Light Grid and Geometry Viewer: lgv

lgv is an OpenGL-based program for visualizing molecular orbitals and densities, density differences and spin densities, molecular structures (which can be manipulated on the screen), and selected molecular properties. The code is the next generation of gv (not to be confused with ghostview) and LUSCUS. Thus, the ‘l’ in lgv can also be understood as luscus-featured gv code.

lgv can operate with different kinds of files:

grid files (usually with extension .grid) generated by the program GRID_IT from the MOLCAS package
XYZ files
molden files, generated by MOLCAS
CIF files (Crystallographic Information Files)
MOLCAS SEWARD/GATEWAY input files (auto-detected by &GATEWAY or &SEWARD marker; coordinates are converted to XYZ internally)

If a file name is specified on the command line, lgv will determine the file type and switch to the appropriate mode. If no file is specified, lgv will search the current directory for files of a known type.

Command-line parameters

Command	Purpose
filename	Name of a grid file, XYZ file, molden file, CIF file, or MOLCAS SEWARD/GATEWAY input file. If omitted, the program tries to find the first relevant file in the current directory.
`-h`	Display help information.
`-n filename`	Create an empty XYZ file.
`-d real`	Set an initial size for the molecule.
`-f filename`	Set the basename of output files (.xyz, .png, .eps, .pov). By default the basename is taken from the filename.
`-s integer`	Set the initial screen size.
`-z`	Force coordinate-editing mode (is_coord=2), even if the file has no unit cell. Useful for XYZ files where auto-detection selects the wrong mode.
`-m`	Start in animation mode (same as pressing `m` key on startup).
`-w`	Draw isosurface as wireframe instead of solid.
`-v`	Load saved viewpoint from `.lgv-config/.ViewPoint` on startup. Falls back to `$HOME/.lgv-config/.ViewPoint` if not found locally. Computes an automatic best viewpoint if neither file exists.
`-q`	Batch/headless mode: render and save PNG image(s), then exit. No window is opened. Typically used with the OSMesa build and the `-o` flag. Example: `lgv -q -o all molecule.lus`
`-S`	Reset saved settings: delete the local `.lgv-config/lgv.rc` file and exit. Run lgv again to start with defaults. Other configuration files (`atoms.rc`, `lgv.keys`, `lgv.frag`) are not affected.
`--record filename`	Record all keyboard, mouse, and menu events to filename for later playback. See the Record/Playback section below.
`--play filename`	Play back a previously recorded session from filename. The file may also contain script commands (`speed`, `wait`, `open`, `status`, `echo`). See the Record/Playback section below.

The following parameters are meaningful only when displaying grid files:

Command	Purpose
`-l real`	Set the initial isolevel value.
`-i real`	Set the increment used for changing the isovalue.
`-t real`	Set transparency level (between 0.0 and 1.0) for isosurfaces.
`-b color`	Set the initial background color (white\|gray\|black).
`-o integer`	Set the initial orbital number (by default: display density).
filename2	Name of the second grid file used to display a density difference.
`-a real`	Weight of the second grid. The default is −1 (density difference).
`--minus`	Shorthand for `-a -1` (density difference, grid1 − grid2).
`--plus`	Shorthand for `-a 1` (sum of two grids).
`--same-space`	Allow two grids sharing the same coordinate space but with different mesh resolutions to be combined. Grid1 is trilinearly resampled onto grid2’s mesh. Without this flag the program aborts if grid sizes differ.
`--align`	Combine two grids whose atoms are in the same order but at slightly different positions (e.g. two steps of a geometry optimisation). A Kabsch rigid-body alignment (optimal rotation + translation) is computed and used to resample grid2 onto grid1’s frame. The program aborts if any atom displacement exceeds the tolerance (default 2 Å; see `--align-tol`). The alignment RMSD is printed to stderr.
`--align-tol real`	Maximum allowed atom displacement in Ångström when using `--align`. Default is 2.0. Set to 0 to skip the check.
`--out filename`	Specify the output file name for a grid constructed with the `-a` option.
`--version`	Print the version number.
`-o N \| all \| list`	Select which orbital(s) to display or export in batch mode. `-o 3` selects orbital 3 (1-based), `-o all` selects all orbitals, `-o 1,3,5` selects a comma-separated list. In batch mode (`-q`) each orbital is saved as a separate PNG.
`--findsym`	Run the built-in `findsym` symmetry utility and exit. Only available in builds compiled with `USE_FINDSYM`.

Configuration

For advanced configuration, save the current state with the F9 key and edit the ASCII-formatted configuration files.

Configuration directories — priority order:

Local: .lgv-config/ in the current working directory. Created by F9. Takes priority over the global directory. Reset lgv.rc with lgv -S.
Global: $HOME/.lgv-config/ (or %USERPROFILE%\.lgv-config\ on Windows). Used as a fallback when no local configuration exists. Create it by running F9 once, then copying .lgv-config/ to your home directory.
Built-in defaults — used when neither directory is present.

F9 always saves to the local .lgv-config/ directory, leaving the global directory unchanged.

The configuration files are:

lgv.rc — settings: colors, transparency, atom/bond sizes, screen size, font mode. Reset with lgv -S.
atoms.rc — per-element van der Waals radii, CPK colors, and valency limits. Each element stores two valency values: one for molecules and one for periodic/crystal structures. lgv selects the appropriate limit automatically.
lgv.keys — key remapping table (native builds only). Format: new_key = existing_key, one entry per line; # introduces a comment. Supported key names: F1–F12, Insert, Home, End, PageUp, PageDown, arrow keys, Ctrl+x, or any single printable character. Example: Ctrl+1 = F1 Ctrl+2 = F2 … Ctrl+0 = F10
lgv.frag — saved molecular fragment library (used by F3 → fragment menu).

Mouse and keyboard overview

The main controls are available through the mouse: use the left mouse button to rotate, and the right mouse button to open the on-screen menu. The middle mouse button removes the current atom selection, or cycles the orbital type in grid mode. Menu operations can also be performed with hot keys. Behavior depends on the type of file being visualized.

As a general rule, plus/minus changes a value, while PageUp/PageDown changes a property of the selected item.

Built-in key aliases (work on all platforms without any configuration):

Ctrl+1…Ctrl+9 = F1…F9; Ctrl+0 = F10.
[ = PageUp; ] = PageDown.
The Insert key (missing on Mac) is emulated by the I key.

Additional mappings can be added in lgv.keys.

Note for Mac users: F-keys require the fn modifier by default; use the built-in Ctrl+n aliases or lgv.keys to avoid this. PageUp/PageDown may not fire on Mac keyboards; use [/] instead.

General hot keys

Key	Purpose
`F1`	Display context-dependent help (list of hot keys for the current mode). Press F1 again to scroll to additional pages.
`Escape`	Leave the current editing mode.
`Home`	Move the molecule to the center of the screen.
`Up/Down/Left/Right`	Move the picture on the screen (hold Shift for larger steps).
`z/Z`	Zoom the grid or molecule.
`F11`	Toggle fullscreen/windowed mode.
`F2`	Save INPORB file (lus/grid mode) or XYZ coordinates (all other modes); in lus/grid mode Shift-F2 saves atoms as a new XYZ file.
`F5`	Save screenshot as PNG (`filename000.png`).
`Shift+F5`	Save screenshot in PostScript format (`filename000.eps`).
`p`	Save a POV-Ray file.
`P`	Print screen in PostScript (level 2) format.
`W`	Cycle atom shape style (spheres → sticks → ball-and-stick → flat discs).
`A`	Cycle atom surface texture style (6 styles, wraps around).
`G`	Switch between grey-scale and colored picture.
`m`	Start/stop animation.
`l`	Switch to/from the mode for moving the light position with the mouse.
`F9`	Save current settings to `.lgv-config/` in the current working directory (creates the directory if needed).
`Shift+F9`	Edit colors for background, labels, orbitals and extra planes.
`r/R/g/G/b/B`	Interactively change RGB code for background, labels, and orbitals (selected by Shift-F9).
`v/V`	v — save viewpoint to `.lgv-config/.ViewPoint`. V — restore viewpoint (falls back to `$HOME/.lgv-config/.ViewPoint`).
`F10`	Exit (with possible backup of edited files).
`Ctrl-Q`	Quit.
`F`	Cycle font rendering mode: GLUT bitmap → stb_easy_font → TrueType. (Not available in the WebAssembly build.)
`y/Y`	Decrease/increase drawing quality (sphere tessellation).
`Ctrl-A`	Toggle alternate modifier flag (use if Shift or Ctrl appears stuck).

Hot keys in Grid mode

Key	Purpose
`PageUp/PageDown`	Display next/previous orbital. In multiview mode (F3), use magnify glass.
`Home`	Jump to the HOMO (last orbital with non-zero occupation).
`+/-`	Increase/decrease the isosurface value.
`t/T`	Change transparency level.
`F4`	Enter an isovalue, orbital number (# n m), or create a filter. See the tutorial for more information.
`Space`	Change the type of the current orbital (by loop).
`f/i/1/2/3/s/d`	Change the type of the current orbital to frozen, inactive, RAS1, RAS2, RAS3, secondary, or deleted.
`F3`	Switch to/from multiview mode. Orbital type is shown by different backgrounds.
`F2`	Save INPORB file (`filename.GvOrb`); Shift-F2 saves atom coordinates as a new XYZ file.
`Delete`	Hide the orbital from the list.
`Insert`	Restore all hidden orbitals.

When lgv is used to display a molecule, you can select an atom, a bond, an angle, or a dihedral angle by clicking on an atom with the left mouse button. The first selected atom is shown with a blue net; the remaining selected atoms are shown with a magenta net. In addition to selecting atoms (up to 4), you can highlight a group of atoms with the mouse (hold Shift) or with the keyboard (F7). To remove the current selection, press the middle mouse button or Space.

lgv can read an extended XYZ-file syntax and draw additional elements: axes, polygons, etc.

Hot keys when atoms are loaded (XYZ, Molden, or lus file)

Key	Purpose
`F2`	Save coordinates as a new file (`filename000.xyz`, `filename001.xyz`, …).
`Shift-F2`	Save coordinates (overwrite the file).
`F12`	Save coordinates in the current screen orientation.
`F3`	Open the fragment picker. Fragments are grouped into categories: Fragments (with Q anchor), Molecules (standalone), Clusters, and Periodic (with lattice vectors). Click an icon to insert.

Mouse controls when atoms are loaded

Action	Purpose
Left click	Select an atom.
Left click + Shift	Highlight an atom.
Drag + Shift, then click	Highlight atoms in the rectangular area.

Hot keys when no atoms are selected

Key	Purpose
`Insert` or `F11`	Add an atom or the last inserted fragment.
`Delete`	Delete all dummy atoms (`Z` or `Bq`).
`Backspace`	Undo the last geometry change.
`+/-`	Change the size of atoms and bonds.
`Home`	Move the molecule to the center of the screen.
`Shift+PageUp/Down`	Translate the molecule along the screen Z axis.
`*`	Reverse the selection.
`S`	If several atoms are highlighted, sort them and place them at the beginning of the XYZ file.
`F7` or `a`	Mark hydrogen atoms in the molecule.
`F8`	Analyze molecule symmetry and display symmetry elements.
`O`	Toggle bond-order detection: Auto (double and triple bonds detected) vs Single only.
`End`	Add dummy atoms (reference points, symbol `Z` or `Bq`) on the axes. Dummy atoms are invisible and excluded from bounding box and center-of-mass. Use `PageUp`/`PageDown` to move a Z marker out of the molecular plane.
`E`	Rotate the highlighted atom group around its centroid to minimize pairwise Coulomb energy with the rest of the molecule (electrostatic orientation). Charges: H=+1, C=+4, N=+3, O=−2, F/Cl/Br/I=−1.
`F6`	Enable watch mode: automatically reload the current file whenever it changes on disk. Shift-F6 disables watch mode.
`M`	Run MOPAC geometry optimization. Requires `$MOPAC` environment variable. (Not available in the WebAssembly build.)
`k / K`	Dump SLAPAF constraint indices (k) or plain atom indices (K) to the status line.
`d`	Dump all current atom coordinates to the console (stdout).

Hot keys for periodic structures (no atoms selected)

Key	Purpose
`u`	Toggle border atoms (duplicate atoms near fractional coordinate 0 onto the opposite face). Only active when the file has unit cell vectors.
`1 / 2 / 3`	Select lattice vector a, b, or c as the active translation axis. Once selected, use `F8`/`Shift-F8` to translate along it.
`F8 / Shift-F8`	Translate the structure one step forward/backward along the active lattice axis (after selecting it with 1/2/3).
`C`	Generate concentric-shell clusters. Written to `_clusters.molden` with the largest cluster first. Cell axes are removed after generation.

Hot keys in Selection mode (1 atom selected)

Key	Purpose
`Space`	Remove selection.
`Delete`	Delete selected atom.
`Insert` or `F11`	Add an atom (or last selected fragment) near the selected atom.
`PageUp/PageDown`	Change the selected atom to one from the list (H,C,N,O,F,S,Cl). If the selected atom is a `Z` dummy marker, moves it perpendicular to the molecular plane (or axis for linear molecules) — 0.5 Å per keypress.
`F4` or `=`	Invoke an edit box to type an element name for the selected atom.
`F3`	Open the fragment picker and insert the chosen fragment near the selected atom. Once a fragment has been picked, Insert re-inserts it without reopening the picker.
`F7`	Mark atoms connected to the selected atom.
`a`	Mark all atoms that are the same element as the selected atom.
`F8`	Apply inversion symmetry around selected atom.
`Home`	Place the origin at the position of the selected atom.
`+/-`	Change the colour saturation of selected/highlighted atoms. `-` makes the atom pale; `+` makes it vivid. Up to three levels in each direction. Stored in the XYZ file as a suffix: `C-`, `C--`, `C---` for pale; `C+`, `C++`, `C+++` for vivid.

Hot keys in Selection mode for bond (2 atoms selected)

Key	Purpose
`Space`	Remove selection.
`+/-`	Change the distance between atoms (the first selected atom, blue, moves).
`F4` or `=`	Invoke an edit box to type the interatomic distance.
`Insert`	Create a bond between selected atoms.
`Delete`	Delete the bond between selected atoms.
`PageUp/PageDown`	Change the type of the bond between atoms.
`F6`	Watch the value of the selected bond.
`F7`	Mark all connected atoms around the first atom in the selected bond into a group.
`F8`	Apply translation or C_n rotation by the axis specified by selected atoms.
`S`	Change the order of selected atoms.

Hot keys in Selection mode for angle (3 atoms selected)

Key	Purpose
`Space`	Remove selection.
`+/-`	Change the angle between selected atoms (the first selected atom, blue, moves).
`F4` or `=`	Invoke an edit box to type an angle value.
`PageUp/PageDown`	Change the angle to standard angle values (by loop).
`F6`	Watch the value of the selected angle.
`F8`	Apply mirror symmetry around the plane specified by the selected atoms.
`3`	Draw a triangle between points.
`4`	Draw a plane.
`\|`	Cut the structure by the plane defined by the 3 selected atoms.

Hot keys in Selection mode for dihedral angle (4 atoms selected)

Key	Purpose
`Space`	Remove selection.
`+/-`	Change the dihedral angle (the first selected atom, blue, moves).
`F4` or `=`	Invoke an edit box to type a dihedral angle value.
`F6`	Watch the value of the selected angle.
`F7`	Mark atoms on the other side of the plane defined by selected atoms 2–3–4, relative to atom 1.
`6`	Draw a cell using selected atoms as axis definition. The first atom indicates the origin.
`F7+Shift`	Use selected atoms as a cell and highlight atoms outside it.

Hot keys in Molden mode for an orbital file

Key	Purpose
`PageUp/PageDown` or `c`	Toggle Mulliken charge labels on/off.

Hot keys in Molden mode for a frequency file

Key	Purpose
`PageUp/PageDown`	Load next/previous vibration mode.
`F3`	Draw graphical information in a separate window.
`+/-`	Change the speed of vibrations.
`a / A`	Decrease / increase the vibration amplitude.

Hot keys in Molden mode for a geometry file

Key	Purpose
`PageUp/PageDown`	Load next/previous geometry.
`Home`	Show initial structure.
`End`	Show the resulting structure.
`n`	Animate the geometry sequence (play through all frames).
`F3`	Draw graphical information in a separate window.
`F2`	Save the current geometry frame as a new XYZ file and reopen it for normal editing.

Building lgv from source

lgv is built from source with a standard C compiler (GCC or Clang) and requires OpenGL, GLU, and freeglut development libraries. Three STB single-header libraries (stb_image_write.h, stb_truetype.h, stb_easy_font.h) are downloaded automatically by make if not present (curl or wget required).

Linux (Debian / Ubuntu):

sudo apt install freeglut3-dev libglu1-mesa-dev fonts-dejavu
make

macOS (Homebrew):

brew install freeglut
make

Windows (MSYS2 / MinGW64):

pacman -S mingw-w64-x86_64-freeglut
make

Cross-compile Linux → Windows:

sudo apt install gcc-mingw-w64-x86-64
make windows

(set FREEGLUT_PREFIX if freeglut is not in the default MinGW sysroot)

For headless / server-side rendering without a display see the OSMesa build section below. For in-browser use see the WebAssembly build section below.

Batch Export and Headless Rendering (OSMesa build)

For server-side or automated rendering without a display, lgv can be compiled against the OSMesa off-screen rendering library:

make osmesa    # requires libosmesa6-dev

The OSMesa build renders entirely in memory; no X11 display, GPU, or xvfb is needed. Combined with the -q flag, it exports PNG images and exits:

lgv -q -o all -v molecule.lus

This exports every orbital to separate PNG files named molecule_MO001.png, molecule_MO002.png, etc. The -v flag applies an automatic best viewpoint. The -o flag accepts all, a single number, or a comma-separated list.

WebAssembly / Browser Build (Emscripten)

lgv can be compiled to WebAssembly for in-browser visualization:

make -f Makefile.emscripten    # requires Emscripten SDK

The browser build provides the same core visualization features as the native build. Grid density differences (Diff menu in the toolbar) are fully supported.

Editing operations are accessible via the toolbar dropdowns:

The Actions XYZ menu provides: Help (F1), Clear selection (Space), Cancel/reset (Esc), Undo (Backspace), Fragment picker (F3), Insert atom/fragment (Ins), Delete selected atom (Del), Watch selected atoms (F6), Apply symmetry (F8).
The Options menu includes Bond order: Auto/Single only and Bond style: 3D/Billboard in addition to the usual show/hide toggles.

The following features are not available in the WebAssembly version:

MOPAC geometry optimization (key M) — requires a local binary.
Sub-window multiview panels — the browser uses canvas overlays instead.
Font mode cycling (key F) — font is fixed.
Key remapping via lgv.keys file.
Record/playback (--record / --play) — file access is sandboxed.