Graphical Viewer

3.1 Launching

Ways to launch the desktop viewer:

# Method 1: Direct binary (after installing from release)
orbitron-viewer fixtures/benzene.xyz

# Method 2: From source during development
cargo run --release -p orbitron-ui-shell --bin orbitron-viewer -- fixtures/benzene.xyz

• Desktop app: on macOS double-click Orbitron Viewer.app. On Windows/Linux launch the orbitron-viewer binary from the release.
• Command-line launch: put orbitron-viewer on your PATH and invoke it from any terminal.

orbitron is a separate command-line program and does not link the desktop viewer. orbitron view fixtures/benzene.xyz on its own only prints a text summary of the file; add --tui for an interactive view in the terminal instead — see Terminal UI.

Several outputs open as one calculation. File → Open Several as One Calculation…, then select the files in the order they were run: a job resubmitted after walltime, or unrelated runs looked at together. One member is shown and the Analysis → Tasks pane lists every task across every file, naming which file each came from; clicking a file shows its structure. Nothing merges the structures — two members of a restart chain hold the same molecule at different points. See Several Files, One Calculation.

A saved session opens the same way a structure does. Naming an .orbpack session — or the .json an older one was written as — restores the whole figure: groups, camera, appearance, overlays, the lot. Until 2026-09-05 it brought back only the atoms, and the presentation came back only through File > Open session. An .orbpack that is a data bundle rather than a saved session still opens as a plain scene, which is what it is.

The orbitron-viewer binary itself takes a file path, --xyz-unit <angstrom|bohr> (the coordinate unit to assume for a plain XYZ file), -h/--help, and -V/--version. It also reads two environment variables: ORBITRON_SYNC_LOAD=1 loads the file before the window appears rather than in the background, and RUST_LOG=debug turns on debug-level tracing.

orbitron view has its own flags, but none of them launch the desktop GUI — orbitron does not link it:

• --select "nearest_atoms(1, 5)" highlights atoms on load and prints the match (atom ids are 1-based).
• --freq chooses vibrational data when both optimization and frequency results exist.
• --tui launches the terminal viewer in place of the plain-text summary; see Terminal UI.
• --blank starts from an empty scene instead of loading a file. Without --tui this only prints text, with no visible viewer; combined with --tui it is refused (“–blank is not currently supported with the TUI viewer”).

You can also drag-and-drop supported files into the window or use File → Open… (⌘ Cmd+O on macOS, Ctrl+O elsewhere); File → Recent lists the last eight files opened. On macOS, double-clicking a structure, wavefunction or volume file in Finder opens it too, and Open With offers Orbitron for .out, .log, .xml, .h5 and .map, which other programs also write. For VASP runs, open any canonical file directly — vasprun.xml, POSCAR, CONTCAR, OUTCAR, OSZICAR, INCAR, KPOINTS, POTCAR, DOSCAR, EIGENVAL, PROCAR, IBZKPT, CHGCAR/CHG/PARCHG, XDATCAR, or DYNMAT — and Orbitron auto-switches to Analysis → Sources showing every companion file in the same directory. The same auto-switch happens for NWChem, Gaussian, Molpro, Molcas, DIRAC, and ORCA output, which ship the same way: one .out/.log beside a constellation of input, orbital, cube, and checkpoint files. POSCAR/CONTCAR atoms come from the file directly; older VASP-4.x POSCARs that omit the species line fall back to a sibling POTCAR for element identity. Sidecar data such as DOSCAR, PROCAR, and OUTCAR is parsed eagerly the moment the scene loads, so density-of-states, band plots, per-atom force arrows, and per-atom magnetic-moment halos are populated without additional clicks. If a bader analysis has produced an ACF.dat next to the run, per-atom Bader net charges are auto-loaded as well. CSV summaries (*_dos.csv, *_band_envelope.csv) regenerate alongside the run when DOS/band data updates. Loading, export, and task downloads run asynchronously; watch the footer’s status message and the progress overlays for updates.

Opening a GROMACS .xtc trajectory takes two steps, because the format stores coordinates and nothing else. A Choose topology for GROMACS XTC dialog asks for the matching .gro/.pdb/.tpr, then a prompt asks how strictly to pair the two: Verify coordinates checks the topology against frame 1, and Confirm atom order skips that check for a topology taken from another frame whose atom order you already know matches. See GROMACS & MD for the full workflow.

The legacy .zip/.tar.gz/.tgz archive-import flow was retired in favour of opening one VASP file and using the Sources sub-tab to load companions. If you have older archives, extract them locally and open vasprun.xml (or any other primary file) directly.

3.2 Interface tour

The window is one 3D viewport with chrome around it. A menu bar runs across the top (File, Edit, View, Help; on macOS in the system menu bar rather than in the window). Below it sits the toolbar, a single horizontal strip of mode switches, tools and menus. Down the left side is the unified rail, a resizable accordion that holds every panel — Analysis, Measurements, Appearance, Overlays & Compare, Scene — and it is the only rail there is: nothing docks on the right. Everything else is the viewport. Along the bottom is the footer, with its status message, frame rate and collapsible console. The rail, toolbar and footer hide independently from View → Panels, and Presentation Mode hides most of them at once.

The Orbitron viewer window with a Gaussian optimisation log of benzene open: the menu bar and toolbar across the top, the mode hint line under the toolbar, the unified rail down the left with the Analysis section expanded on Overview, the 3D viewport, and the footer along the bottom, each labelled

Figure 1: The pieces named throughout this chapter, with a benzene geometry optimisation open. The line under the toolbar is the toolbar’s own mode hint; the footer holds the console toggle, the status message and the frame rate.

• Viewport: Left drag orbits, Shift+left drag or middle drag pans, scroll or pinch zooms. The scroll step is proportional to the current camera distance (roughly 9.5% per notch at any scale), so backing out of a slab or protein takes as few notches as backing out of a small molecule. Adjust pan sensitivity in View → Camera.
• Toolbar & footer: View → Panels carries Unified Panel, Toolbar and Footer checkboxes, each hiding its own piece of chrome. The toolbar carries the View/Edit mode switch, the Select/Measure tool pair with their sub-rows (Click / Box / Lasso for selection, Distance / Angle / Dihedral while measuring), the current selection count and a Clear button, a render-style menu, an Overlays menu, and a View block: Frame Sel, Center, Reset View, and − / + zoom buttons. Reset View restores the default orientation and re-fits the scene, so it works on a single atom and a large cell alike. The footer holds the console toggle, the last status message and the frame rate; the line under the toolbar tells you what a click does in the current mode.
• Unified panel (left rail): A resizable accordion rather than a tab strip. In view mode the sections are Analysis (only when the file carries analysis data), Measurements, Appearance, Overlays & Compare, and Scene; in edit mode they are Geometry, Measurements, Appearance, and Scene (there is no Overlays & Compare section while editing). Press H or use Help → Keyboard Controls to open the help table; Ctrl+Shift+H clears analysis overlays. The Help menu also carries Editing Quickstart and Open Crash Reports Folder.
• Molecular identifiers: View → Tools → Molecular Identifiers… opens a window naming the current scene as a SMILES string, an InChI, and an InChIKey, each with a Copy button. Disable stereo (SNon) recomputes the InChI without stereo layers, which is what you want when the geometry came from a drawing rather than from a structure. The three are derived from the scene, so they follow whatever you have edited.
• The Overlays menu holds four checkboxes: Structure, Labels, Unit Cell, Cartoon. Structure is the atoms and bonds themselves — turning it off is what makes a cartoon-only view reachable, which is how a protein is normally looked at. Unit Cell and Cartoon grey out, with a tooltip saying why, for a scene with no cell or no protein chains.
• Where the tasks are: there is no separate task sidebar. Stages of a multi-task run are the Tasks sub-tab of the rail’s Analysis section, and they appear for every program Orbitron recognises, not only Gaussian and NWChem. From there you can load a completed optimization, frequency calculation, or task-specific geometry without reloading the file. Opening a QC output focuses Analysis → Overview; use Tasks for stages and Sources for companion files.
• Presentation mode: View → Presentation Mode optimizes the UI for live presentations, screen recordings, and demos by removing visual clutter and enhancing readability:
  • Hides UI chrome: Toolbar and unified side panel are automatically hidden
  • Enlarges labels: Atom label font size increased by 20% (clamped to 8.0–64.0 points)
  • Enhances outlines: Label outline width increased by 10% for better contrast
  • The 3D viewport expands to fill the entire window, maximizing screen real estate for the molecular structure
  • Toggle the checkbox again (or via View → Presentation Mode) to restore normal UI visibility
  • Presentation mode state persists in saved sessions (serialized with RuntimeUiState)
  • Use cases: Live demos at conferences, screen recordings for tutorials, clean screenshots for publications
  • Implementation: ui/shell/src/viewer_loop/runtime/redraw/setup.rs (the presentation_mode branch)

Idle companions

Leave the desktop viewer alone for a while and pixel cats wander into the 3D viewport. They come only when a structure is loaded and nothing is loading or running in the background, and they start after the delay set in View → Idle Companions → Start after (1 to 60 minutes, 5 by default). The coats are black, orange, orange-and-white tabby and calico.

• A cat stops at a random spot to sit, groom, lie down or curl up asleep, and sometimes stretches or pounces.
• Some walk up to the molecule and bat it, which slides it, or head-bump it, which turns it. Only the camera moves: the structure is never edited, and a slide never carries the molecule more than a quarter of the viewport width.
• Two cats that meet touch noses. About a third arrive with a kitten that follows its mother around. On a small molecule a cat may jump up and nap on top of it.
• Small emotes show what a cat is doing: z’s while it sleeps, ! when it is startled, a heart after a head-bump.

Any mouse or keyboard input puts the camera back exactly where it was and the cats run off. Uncheck View → Idle Companions → Show cats when idle to turn them off; Cats sets how many come (1 to 6, kittens not counted). The settings are saved in the user configuration under [idle_companions] (enabled, delay_seconds, cat_count). The cats are desktop-only and never appear in exports or web views.

3.3 Keyboard reference

macOS: the application shortcuts below — Open, saved-session Open, New, Save, Select All, Edit mode, Quit, Undo/Redo, clear-overlays, and the command palette — use ⌘ Cmd in place of Ctrl. Orbitron binds these to the platform command modifier (Cmd on macOS, Ctrl on Windows/Linux). The single-letter shortcuts take no modifier.

Keys	Action
1 / 2 / 3	Camera presets (Front / Side / Top)
F	Frame current selection
Ctrl+A	Select all atoms
Esc	Clear selection
Shift+S	Cycle selection tool (Click → Box → Lasso)
Z / X	Selection history back / forward
Ctrl+Z	Undo edit operation
Ctrl+Y / Ctrl+Shift+Z	Redo edit operation (both conventions work)
Delete / Backspace	Delete selected atoms (edit mode)
Ctrl+Shift+H	Clear MO/charge/NBO overlays
Ctrl+O	Open file dialog
Ctrl+Shift+O	Open saved session
Ctrl+N	New blank session
Ctrl+S	Save session
Ctrl+E	Toggle edit mode
Ctrl+Q	Exit application
Ctrl+K	Open command palette
M	Cycle render mode
L	Toggle light/dark theme
B	Toggle colorblind palette
Shift+B	Cycle NBO highlight set
P	Toggle diagnostics overlay (FPS/background status)
T	Toggle status text in window title (Shift+T highlights top charges)
I	Print selection summary to console
D / A / G	Distance / angle / dihedral measurement modes
V	Exit measurement mode
C	Clear measurement atom buffer
Shift+O	Cycle through frontier orbitals when orbital data is present
H	Show keyboard help overlay

Note: Select All takes the command modifier (Ctrl+A, ⌘ Cmd+A on macOS) and is also in the View → Selection menu. A bare A is angle measurement mode.

The shortcuts without a modifier (the letters, the camera digits, Delete) act only while the pointer is over the 3D view. Over a panel, plot or window a stray keystroke does nothing, so a key pressed after a click that missed a text field cannot switch the measurement mode or the theme. Esc and the Ctrl/⌘ Cmd shortcuts work wherever the pointer is.

Ctrl+K opens the command palette, a fuzzy-search launcher over the menu and edit actions: type a few letters of a command and press Enter to run the best match. Starting the query with = switches it to a selection query and runs the expression against the scene instead (=element O, =within_atom(1, 3.5)), so a picking expression needs no panel. The footer states both: “Enter to run · = for a selection query · Esc to close”.

3.4 Selection and measurement workflow

3.4.1 Selection Tools

There is no Selection panel. Its controls now sit in three places: the everyday ones on the toolbar, the label override in Appearance, and the set operations in the View → Selection menu.

A selected atom keeps its element colour and takes a rim in the highlight colour, so a selected residue still shows which atoms are carbon, nitrogen and oxygen. An atom that already carries an analysis halo (a charge, an orbital’s share, a frozen atom) is painted in the highlight colour instead, so neither reading is lost.

Basic Selection: - Left-click or right-click an atom to select it - Right-click a selected atom to deselect - Right-click empty space to clear selection - Ctrl+click toggles an atom in or out of the selection. This, not Shift, is how you build up a multi-atom pick by clicking: Shift+left-drag pans the camera, so Shift is not available for clicks. - Ctrl+drag / Shift+drag during a box or lasso drag toggles / adds the dragged atoms instead of replacing the selection - Keyboard: Esc clears selection, Z/X step back and forward through the pick history

Sequence and residue selection:

For a PDB or mmCIF structure, open Scene → Sequence / Residues. Each protein or nucleic-acid residue appears as a compact button such as T1 or G42; the hover text gives the full residue name, atom count, mmCIF label numbering, alternate-location names, and any source chemical-component name, type, formula, mass, or standard parent. Ligands, solvent, ions, and unrecognised non-polymer residues stay separate under Other components. Dimmed, italic residues are present in the file’s declared polymer sequence but have no coordinates in the current model. They cannot be selected because there are no scene atoms to select.

• Click a residue to replace the atom selection with that residue.
• Ctrl/Cmd-click toggles the residue in or out of the current selection.
• Shift-click selects the range from the last residue clicked, without crossing into another chain. Insertion-coded residues such as 100, 100A, and 100B stay distinct.
• Select chain replaces the selection with every coordinate-bearing atom assigned to that chain, including its ligands, solvent, and ions. Ctrl/Cmd-click adds the chain, or removes it when the whole chain is already selected.
• Enter an author residue identity such as A:42 or H:100A in the Go field. An unqualified identity such as 42A works when it identifies one residue across all chains. Compact button labels such as K134 also work. Go selects the residue’s atoms, as clicking its button does. The navigator can locate unresolved residues even though they have no atoms to select; for one of those it says so instead.
• The search field filters the displayed residues as you type. Plain text searches residue names, author sites, compact labels, chains, and atom names. Use chain:A, res:HIS, site:A42, resid:42A, or atom:NE2 when the field matters, and combine terms with spaces. For example, res:HIS atom:NE2 shows histidines that contain an NE2 atom. Qualified site: and resid: terms are exact; plain terms allow partial matches. Clicking a result selects its complete residue. When you need only the matching atoms, open the command palette and enter a selection query starting with =.
• Viewport selection feeds back into the buttons. A full residue is selected; a partially selected residue uses italic text. The most recently picked 3D atom scrolls its residue into view once, so manual scrolling remains stable afterward.

A residue button selects every retained alternate location for that residue, even when Appearance currently shows only the primary location. Use an altloc selection expression when you need one named conformer.

PDB files supply the declared sequence through SEQRES and exact missing positions through REMARK 465. mmCIF files use _pdbx_poly_seq_scheme and _pdbx_unobs_or_zero_occ_residues. Author chain and residue numbers remain the displayed identity. For modified mmCIF residues, _chem_comp.type determines whether a component belongs to a peptide, DNA, or RNA chain, and _chem_comp.mon_nstd_parent_comp_id supplies a compact sequence code when the parent is a recognized standard residue. Orbitron does not classify peptide-like ligands as polymer residues.

Structure contacts and validation:

The same Sequence / Residues panel contains read-only contact and validation tools. Contacts from selection finds complete partner residues and includes ligand, chain-interface, explicit-hydrogen bond, named salt-bridge, and disulfide checks. Metal sites lists bonded centres with a sphere of their own, their named donors, distances, and Orbitron’s closest supported coordination geometry. For any metal centre, the Coordination readout in the rail’s Scene section adds the oxidation state and d or f count, the valence electron count, a trust grade for the state and a collapsible ligand-field drawing; see Metal-site accuracy for what each one claims and declines. Protein termini lists the observed peptide-fragment ends and reports how many are uncapped; a chain change, a missing residue, or a broken C–N bond all split a fragment, and an ACE or NME cap counts only when the expected bond is present. It reads the active alternate-location view and infers no protonation state.

Steric clashes scans the active alternate-location view and lists each nonbonded pair closer than 80% of its summed van der Waals radii. Bonded, 1-3 and 1-4 pairs are excluded, and so is a metal and a donor atom (N, O, S, P, Se or a halogen) 1.6 Å or more apart, which is a coordination contact, and a pair that need never be present together (below). The panel defaults to heavy atoms; Include H adds explicit hydrogens. Each row gives the two atom and residue identities, actual distance, pair-specific limit, and overlap, and an atom’s occupancy when it is below 1. Results run from greatest overlap to least.

Where two occupancies sum past 1 the atoms must be present together in some of the unit cells, so the clash is real there, and the row shows both occupancies. Where they sum to 1 or less and at least one of the two has no alternate-location label, they need never meet: the pair is left out, as MolProbity’s Probe leaves it out, and the panel says how many were. Select pair replaces the selection with those two atoms, while Add pair extends the current selection.

Impossible bond lengths is the complement of that panel: bonds shorter than 60% of their summed covalent radii, which the clash test cannot see because it excludes bonded pairs. The threshold clears real multiple bonds — a carbon triple bond sits at 79% and a dimetal quadruple bond near 68% — so a row here is a broken structure rather than a tight one. It reads the active alternate-location view like the rest.

These clash values are geometric Orbitron evaluations. They are not energies, probabilities, or facts declared by the source file. Residue-mutation previews use the same rule, include hydrogen, and rank candidate side chains by summed squared overlap.

Backbone validation evaluates complete protein residues against the Richardson Lab Top8000 Ramachandran distributions. The summary reports favored, allowed, outlier, and evaluated counts. Favored rows are hidden by default so unusual residues stay visible; enable Show favored to inspect every result. Each row gives the residue-specific reference class, phi, psi, and percentile-grid score. Select residue replaces the current selection with that complete residue; Add residue extends it.

The Ramachandran plot above the rows draws every evaluated residue at its phi and psi over the favoured (darker blue) and allowed (lighter blue) regions, black when favoured, orange when allowed and red when an outlier. By default every residue sits over the General regions, coloured by its class against its own distribution, so a glycine outside them can still be black; the picker draws one distribution’s regions and only the residues it scores. Hovering a point names the residue and clicking selects it. orbitron plot ramachandran writes the same plot as a figure.

The six reference classes are general, Gly, cis-Pro, trans-Pro, pre-Pro, and Ile/Val. A residue needs N/CA/C atoms and both neighboring peptide residues, so chain ends, gaps, incomplete backbones, ligands, and nucleic acids are excluded from the evaluated count. Periodic structures are unwrapped along the backbone, and hidden alternate locations cannot supply an angle. The categories are Orbitron evaluations based on the bundled Top8000 grids, not validation labels read from the source file.

Missing heavy atoms compares coordinate-bearing amino acids with the expected non-hydrogen atoms for their residue template: the side chain, and the backbone N, CA, C and O. The summary reports affected residue conformers and missing atoms; each row names the absent atoms, backbone first. Select residue and Add residue act on the atoms that are present, which makes the incomplete site visible in the 3D scene.

The check needs at least one backbone atom, so a fully unresolved sequence entry or an isolated coordinating atom named as part of an amino acid is not reported, while a residue modelled as its C and O alone is, with N, CA and its side chain missing. Side-chain repair needs the backbone and refuses such a residue. Hydrogens are outside this check. Common protonation variants use their parent amino-acid template, MSE expects SE in place of Met SD, and SEC is supported. PYL and unrecognised modified residues are omitted because Orbitron has no complete template for them. Alternate conformers are checked separately using the active location view. This panel detects missing atoms but does not reconstruct them.

Side-chain validation evaluates complete rotamer-bearing amino-acid side chains against the Richardson Lab Top8000 percentile grids. Its summary and Show favored control follow the backbone panel. Each row lists the residue, retained alternate location, measured chi angles, percentile-grid score, and favored, allowed, or outlier category. Select residue and Add residue act on that visible conformer.

Ala and Gly have no side-chain rotamer distribution and do not enter the evaluated count. A supported residue with a missing chi-defining atom is also omitted; inspect the separate Missing heavy atoms panel for the absent heavy-atom names. Hidden alternate locations cannot complete a side chain. The categories are Orbitron evaluations, and the panel does not assign a named rotamer.

Each validation panel, including Metal sites, has compact Export CSV… and JSON… controls. An export contains every finding from the active alternate-location view, even when the panel hides favored rows or limits the number shown on screen. Both formats record the scene digest, Orbitron version, source path, structure name, model or trajectory frame when available, biological-assembly view, active alternate-location view, selected one-based atom numbers, and the analysis parameters. JSON keeps numeric values and lists typed. CSV uses one row per finding, repeats the provenance columns on every row, and stores lists as JSON text. A CSV with no findings still writes one provenance row with empty finding fields.

The exported evaluation_source is Orbitron evaluation. It distinguishes derived geometry and reference-library classifications from annotations read from the PDB or mmCIF source. Atom numbers match the one-based numbers shown in the viewer.

Selection Tools (toolbar):

The toolbar’s Select tool has a sub-row for the picking gesture:

1. Click — Single-atom picking (default behavior)
2. Box — Drag to draw a rectangle; all atoms inside the box are selected
3. Lasso — Drag to draw a freeform polygon; all atoms inside the lasso are selected

The two mouse buttons split turning the scene and selecting an area, and the tool says which way round. That is the whole rule:

	Click	Box / Lasso
Left drag	orbit	draw the band
Left click	select an atom	select an atom
Right drag	box-select	orbit
Right click	deselect an atom	deselect an atom
Shift+left drag, middle drag	pan	pan

So a right-drag box-selects without leaving Click mode, and picking Box or Lasso moves the band onto the primary button — which is what a trackpad can comfortably drag — and the camera onto the right. Whichever tool is active, one button always turns the scene: until 2026-09-11 both buttons drew a band under Box and Lasso, which left orbiting unreachable and pan stranded on a middle button a laptop does not have.

While the band is open, Ctrl toggles what it covers and Shift adds to the selection; with neither held it replaces. A band that covers nothing leaves the selection alone rather than clearing it.

A drag that moved the scene is never also a click, so letting go of an orbit over an atom no longer selects it — until 2026-09-11 it did, because the only thing standing between the two was a “is a button down” flag that the release had already cleared. A press that wobbles a few pixels is still a click.

Box and Lasso work in view mode as well as edit mode, and Shift+S cycles the tool in either; it refuses only while a measurement or a placement owns the click. Next to the picker the toolbar shows the count ("12 selected") and a Clear button whenever something is selected.

Editing the selection (toolbar, edit mode):

With edit mode active the toolbar gains a row of actions on the current selection:

• Freeze / Thaw — Hold the selected atoms in place, or release them. Frozen is orthogonal to selection; see §3.7.3
• Element… — Change the element of the selected atoms
• Bond ▾ — Set the bond order between two selected atoms (Single / Double / Triple / Aromatic), or Remove bond. Dative (coordination) bonds are perceived automatically for metal–donor pairs rather than set here; see Data Support §2.6 for what that means on export
• Delete — Delete the selected atoms

The building tools on the same row — Place Atom, Fragment, and the placement chooser — are covered in §3.7.1.

Atom label override: Appearance ▸ Atom Labels, with one atom selected, shows the auto-generated label and a text field for a custom override, plus Reset label for that atom and Reset all for the scene. Overrides persist in saved sessions.

Selection menu:

Set operations live under View → Selection:

• View → Selection → Select All, Clear Selection, Clear Highlights, Invert Selection, Expand to Bonded
• View → Selection → By Element submenu (H, C, N, O, S, P, F, Cl, Br, I)
• View → Selection → Selection Tool (Click, Box, Lasso) — these menu buttons are edit mode only, though the tools themselves are not

Z and X walk the pick history, but the UI has no history list and no Back / Forward / Clear History controls.

3.4.2 Measurement Workflow

Activating Measurement Mode:

• Press D (Distance), A (Angle), or G (Dihedral) to enter measurement mode
• Or use the Measurements panel to select mode: Distance, Angle, Dihedral
• The panel shows: "Active mode: Distance" (or Angle/Dihedral)
• Press Clear button or select the same mode again to exit measurement mode

Making Measurements:

1. Select required atoms by clicking in the viewport:
   • Distance: 2 atoms (start, end)
   • Angle: 3 atoms (start, vertex, end)
   • Dihedral: 4 atoms (atom 1, 2, 3, 4)
2. The panel shows progress: "Selected atoms: 2 / 2" (for distance)
3. When complete, the measurement value appears in the Current measurement section
4. Save adds the measurement to history
5. Clear resets the buffer to start a new measurement
6. Copy copies the measurement to clipboard (tab-separated format)

Measurement History:

• All saved measurements appear in the Session history section
• Each entry shows: Mode, Atoms (e.g., "C1 - O3"), Value (e.g., "1.43 Å")
• Copy all copies the entire history table to clipboard
• Click an entry to highlight those atoms in the viewport
• Remove button deletes individual entries
• History persists in saved sessions

Measurement Overlay:

• The 3D viewport highlights measured atoms with colored markers
• Completed measurements display values as floating labels
• The footer’s status message shows the most recent measurement
• Toast notifications appear when measurements complete (even if panel is hidden)

3.4.3 Applying Measurements (Edit Mode)

When edit mode is active (Ctrl+E), the measurement panel gains geometry editing capabilities:

Target Value Editing:

1. Make or select a measurement (distance/angle/dihedral)
2. In the Current measurement section, the Value column shows:
   • Current computed value: "1.43 Å" (read-only)
   • Arrow: "→"
   • Editable target value (DragValue widget + Slider below)
3. Drag the value or use the slider to set a target
4. The diff appears next to the slider: "(+0.12 Å)" in accent color
5. Apply button becomes enabled (highlighted in cool accent color)
6. Click Apply to run the constraint solver and move atoms
7. Reset restores the target value to the current computed value

Move Controls:

For multi-atom measurements (angle, dihedral), two controls determine which atoms move:

• Move side: Radio buttons for First or Last
  • Distance: Swaps atom order (moves atom 0 or atom 1)
  • Angle: Swaps start ↔︎ end (moves atom 0 or atom 2, vertex stays fixed)
  • Dihedral: Reverses atom order (moves atoms 0-1 or atoms 2-3)
• Move bonded subtree (checkbox):
  • When enabled: Moves the selected atom plus all atoms “downstream” in the bond graph
  • When disabled: Moves only the selected atom
  • Default: enabled

Constraint Solver Behavior:

• Distance: Translates the last atom toward/away from the first atom
• Angle: Rotates the subtree rooted at the third atom around the vertex
• Dihedral: Rotates the fragment beyond the pivot bond (holds anchor side fixed)
• Ring detection: If the target atoms form a ring, the solver aborts with an error message (prevents distorting entire loops)

Apply Workflow Example:

1. Enter edit mode (Ctrl+E)
2. Activate distance measurement mode (D)
3. Click two bonded atoms
4. Drag the target value from 1.43 Å to 1.55 Å
5. Click Apply — the second atom (and its subtree) moves to satisfy the constraint
6. The measurement updates to show the new computed value
7. Repeat or exit edit mode (Edit → Exit Edit Mode… to commit/discard all edits)

Saved Measurement Editing:

• Measurements saved to history can be re-edited:
  • Select the same atoms in the same order
  • The panel detects the existing record and shows "✓ Saved" badge
  • The target value defaults to the previously set target (or current value if not yet edited)
  • Modify and Apply to update the geometry without saving a duplicate measurement

Implementation: ui/shell/src/toolbar/session.rs (selection tools and edit actions), ui/shell/src/panels/measurements/ ## 3.5 Rendering & appearance

• Switch render styles via M or the toolbar Model menu (Ball & Stick / Sticks / Space Fill / Atoms Only). M cycles them in that order.

• Sticks is the licorice representation: bonds at full thickness with each atom drawn as a sphere of exactly the same radius, so the joints are continuous and no atom reads as larger than another. The radius is the one number — it follows the bond thickness slider under Appearance, and the atom size slider deliberately does not apply, because growing the spheres without the sticks puts a bead at every joint and turns the figure back into ball-and-stick. Use it when the point of the figure is connectivity or a backbone trace rather than atomic size.

• Expect to raise the bond thickness. The default, 0.15 Å (the Orbitron Signature preset; Classic uses 0.135 Å), is chosen for ball-and-stick, where the spheres carry the figure and the bonds only connect them. Licorice has nothing but the bonds, so at that setting it draws a very thin wireframe. Appearance → Bonds → Thickness is the single control for how heavy a licorice figure looks, caps included.

• Sticks colours its bonds by atom, including a bond between two atoms of the same element, which the Split bond-colour mode alone does not do. It has to: the cap is the same radius as the stick, so a bond colour that differs from the atom colour reads as a bead at every joint. Setting bond colour mode to Solid under Appearance → Bonds still wins, for a deliberate single-colour trace.

• Per-selection representation and groups live under Appearance → Selection Styling, which is shown for every scene. Cartoon/ribbon geometry and ribbon opacity live under Appearance → Cartoon / Ribbon, which appears only for a file with protein chains. See §3.5.9 — the Model** menu does not offer cartoon, and neither set of controls is with the selection tools.**

• Toggle atom labels, indices, and bonds from the Appearance panel (atom labels are off by default). Labels have a mode: Elements draws the element symbol on every atom, which is what the viewer has always done and is unreadable on a protein — 3,661 labels on a mid-sized one. Selected residues draws one label per residue for the current selection instead, spelled the way a caption spells it (T250, and HEM 501 for anything without a one-letter code), anchored on the alpha carbon where there is one. A representation group can carry the same labels without a selection at all, which is what a saved figure wants; see §3.5.9. Show atom indices (available in Elements mode) has an Index base picker beside it, 0-based or 1-based. Set it to 1-based if you are reading indices off the viewport to write a selection expression: every atom id on this page, in the query DSL and in the CLI, is 1-based.

• A PDB or mmCIF structure with alternate coordinates gains an Alternate Locations block inside the Appearance → Structure collapsible, which appears for scenes carrying protein chains. The default shows blank/shared atoms plus the highest-occupancy location in each residue. Choose All locations or one named location to inspect the retained coordinates. This is a display choice; it does not delete atoms, and saved sessions restore it. The same section carries per-chain visibility (Show all plus a per-chain toggle) and, for a file declaring BIOMT records, a biological-assembly picker.

• Theme and colorblind palette toggles update both egui and renderer (render::set_colorblind_safe).

• Overlay Manager: Open the rail’s Overlays & Compare section to import additional structures (XYZ plus volumetric CUBE datasets). Each entry reports its status, can be toggled individually, and includes a ✖ button to remove it from the session. Large volumetric files load in the background; the status strip and toasts report when jobs queue and finish so the UI stays responsive. Use the checkbox at the top to hide the base scene for comparative viewing. Overlay visibility changes immediately invalidate the render cache so the viewport always reflects the current stack, and saved sessions now restore the entire overlay roster (geometry and volumetrics) on load. The export dialog includes an Export Visible Overlays… action that writes each overlay to disk (geometry overlays as XYZ with transforms applied, volumetric overlays by copying their source CUBE). Volumetric entries now expose a Blend mode selector (alpha or additive) so multi-orbital stacks stay legible without washing out neighbouring lobes.

• Annotations: Add text labels and arrows as scene overlays for presentations and documentation, anchored to the viewport or to the structure itself. See §3.6 for detailed workflow documentation. Annotations render in export previews and final image exports. Thirteen built-in presets. Orbitron – Signature (the default), Ink (the signature drawn rather than lit: matte atoms under a soft light, a dark outline on every atom and bond, and depth cueing, on the same ground), Glow (the signature on a deeper ground, every bond haloed in its own colour and every atom’s rim lit, for title slides), Classic, Publication (light ground, for paper), Presentation (dark ground, heavy lines and large labels, for a projector), Print (white ground, an outline on every atom, no gloss, so the geometry still reads once a figure is printed in black and white), Licorice, Space fill, and four drawn looks:

• Line art: flat pastel discs with white carbon and split bonds, every atom and bond outlined in black, on white. The hand-inked look of an older paper figure.

• Sketch: white outlined circles joined by thin black bonds. Nothing in it competes with a translucent molecular surface drawn around the structure.

• Comic: chunky toon-shaded atoms with heavy outlines on a warm ground, for outreach and informal talks.

• Grayscale: Print with the element colours replaced by their luminance and depth cueing on, for a figure that will only ever be printed in black and white.

Licorice and Space fill are the only ones that change what is drawn: applying them also switches the Style, because for those the representation is the look. Every other preset changes colours, lighting and thicknesses and leaves the Style where you had it. A custom preset you save behaves the same way: it records a theme, and applying it never changes the representation.

Space fill is a CPK figure: the mode draws each atom at its van der Waals radius (Alvarez 2013, carbon 1.77 Å), so the spheres merge into a solid shape. --show surface remains the thing to reach for when you want a molecular surface as a mesh rather than as overlapping spheres.

Three settings carry most of these looks, and each can be used on its own:

• Element colours (Atoms): Standard, Pastel, Grayscale or White. Each recolours atoms that are drawn in their element colour, after the carbon colour has replaced the table’s carbon. An atom coloured by a group, a residue or a property keeps its colour, and a cartoon’s bases and a molecular surface coloured by nearest atom follow the palette the atoms do. The colourblind palette in the View menu replaces element colours outright, so with it on the theme’s palette has nothing to act on.
• Outline width and colour (Bonds): a rim along each bond, as a fraction of its radius, matching the atom outline. Cartoon rungs are not bonds and do not get one.
• Depth cueing (Background): fades the back of the scene toward the background colour, from 0 (off) to 1 (the farthest point takes the background colour). The range is the scene’s bounding sphere along the view axis, so it follows the scene as it is zoomed and turned. A transparent export still fades toward the background’s colour.

These three are drawn by the GPU renderer, so the desktop, the CLI’s render and the web viewer all show them. The SVG export and the CPU fallback renderer already ignore atom outlines and do the same with bond outlines and depth cueing; the palette is applied to the scene data and reaches them too.

• The Appearance panel allows fine control over atom/bond styles, lighting presets, background colour, and custom presets. All sliders feed into a dedicated appearance profile, so swapping presets or restoring a session reapplies every tweak without dragging stray values between projects. Saving a preset persists it between sessions (stored alongside other viewer settings).
  • Styles: Choose Classic/Flat/Presentation/Technical to enable the relevant controls and keep the panel focused.
  • Atoms: Pick sphere/flat/faceted styles, adjust finish/toon steps, add outlines and selection rings, and clamp minimum on-screen size.
  • Bonds: Comprehensive controls for bond geometry, coloring, and effects. See §3.5.1 for detailed documentation of all bond rendering controls.
  • Adjustments apply immediately to the viewer and can be captured inside appearance presets for reuse across projects.
  • When any panel is visible the 3D viewport automatically resizes to the remaining space, so the UI no longer overlays the scene and hit-testing respects the clipped region.
• Typical workflow inside the Appearance panel:
  • Presets: Quickly swap between built-in looks or save your own. A saved preset records every slider in the panel, including the default bond thickness (0.15 Å in the default Orbitron Signature preset), so you can jump between project-specific styles.
  • Atoms: Scale van der Waals radii, recolour highlight selections, and tweak label size/colour for presentations. The atom scale slider is linear, letting you exaggerate radii without touching bond geometry.
  • Bonds: Use detailed controls to customize bond appearance including thickness, multi-order layouts, caps/taper, and accent effects. See §3.5.1 for complete reference.
  • Lighting & Background: Switch between lighting presets (key/fill/rim combinations) or customise direction vectors and intensities. Background colour updates both the renderer clear colour and UI theme tint for consistent screenshots.

3.5.1 Bond Rendering Controls (Appearance Panel)

The Bonds section in the Appearance panel provides granular control over bond geometry, shading, and visual effects. All controls update the viewport in real-time and are saved in appearance presets.

Location: Appearance panel → Bonds section (collapsible group)

Bond Color Controls

Base Colour: - Color picker: RGBA premultiplied color editor - Sets the default tint for non-highlighted bonds - Applies when bond color mode is “Solid” - Default: steel blue ([0.46, 0.57, 0.70, 1.0] in the default Orbitron Signature preset)

Show bonds checkbox: - Toggle global bond visibility on/off - Lives here in Appearance → Bonds (no menu or keyboard shortcut) - Hidden bonds do not render but still exist in scene data

Color Mode dropdown: Three options for hetero-bond (different elements) coloring: - Solid (uniform): All bonds use base bond color - Split (default): Bond splits at midpoint, each half colored by atom element - Gradient: Smooth color blend from one atom to the other

Availability varies by appearance style (Classic/Flat/Presentation/Technical).

Bond Core Controls

Thickness (Å): 0.001–0.45 (slider) - Base radius of bond cylinders in Ångströms - Default: 0.15 Å (the Orbitron Signature preset, which is the default theme; Classic uses 0.135 Å, DEFAULT_BOND_THICKNESS); appearance presets may set their own — Publication uses 0.16 Å, Presentation 0.20 Å, and Licorice 0.34 Å because there are no spheres to carry the figure - Extremely thin bonds (0.001) create wireframe look - Thick bonds (0.45) approach space-filling representation - Clamped during rendering: clamp(0.001, 2.0)

Inactive Opacity: 0.1–1.0 (slider) - Alpha transparency for non-selected/non-highlighted bonds - 1.0 = fully opaque, 0.1 = nearly transparent - Useful for focusing attention on selected atoms/bonds - Default: 0.85

Highlight Scale: 1.0–2.0 (slider) - Multiplier for bond thickness when highlighted/selected - 1.0 = no change, 2.0 = double thickness - Applies to selection highlight and hover state - Default: ~1.2

Lane Spacing (Å): 0.05–0.4 (slider) - Distance between parallel lanes in multi-order bonds (double/triple) - Measured in Ångströms between lane centerlines - Smaller values → tighter bundles, larger values → spread lanes - Default: 0.2 Å - Interacts with bond order spacing multipliers (see Order Controls)

Dash Length (Å): 0.0–1.0 (slider) - Length of solid segments in dashed bonds (aromatic/resonance) - 0.0 = no dashing (solid), 1.0 = long dashes - Used for visual differentiation of delocalized bonds - Default: 0.22 Å

Dash Gap (Å): 0.0–1.0 (slider) - Length of gaps between dashed segments - 0.0 = no gaps (solid), 1.0 = wide gaps - Combined with dash length to control dash frequency - Default: 0.18 Å

Desaturation: 0.0–1.0 (slider) - Color desaturation for inactive (non-highlighted) bonds - 0.0 = full color, 1.0 = grayscale - Applies before opacity adjustment - Useful for making selection stand out with vibrant color

Glossiness: 0.0–1.0 (slider) - Specular reflection intensity (sheen/shine) - 0.0 = matte (diffuse only), 1.0 = glossy/reflective - Availability depends on appearance style (disabled in Flat and Technical) - Interacts with lighting preset (key/fill/rim intensities)

Line-only Mode: Checkbox (available in Classic, Flat, and Technical styles) - Renders bonds as simple lines instead of cylinders - Ignores thickness, caps, taper, and glossiness - Extremely fast rendering for large structures - Checkbox availability varies by style

Order Controls

Multipliers applied per bond order to base thickness and spacing. Final thickness = bond_thickness × order_thickness, final spacing = bond_lane_spacing × order_spacing.

Double Thickness: 0.5–1.5 (slider, default 0.95) - Thickness multiplier for double bonds (order = 2) - 1.0 = same as single bond thickness - <1.0 = thinner double bonds, >1.0 = thicker

Triple Thickness: 0.5–1.5 (slider, default 0.9) - Thickness multiplier for triple bonds (order = 3)

Aromatic Thickness: 0.5–1.5 (slider, default 0.85) - Thickness multiplier for aromatic bonds (order = aromatic) - Often set thinner than single bonds for visual distinction

Double Spacing: 0.6–1.6 (slider, default ~1.0) - Spacing multiplier for double bonds - Final spacing = bond_lane_spacing × bond_spacing_double - 1.0 = use base lane spacing, 1.5 = 50% wider

Triple Spacing: 0.6–1.6 (slider, default 1.05) - Spacing multiplier for triple bonds - Three lanes: center lane at bond axis, outer lanes offset by ±spacing

Aromatic Spacing: 0.6–1.6 (slider, default 1.0) - Spacing multiplier for aromatic bonds - Often set wider than single for dashed lane visibility

Geometry Details

Cap Style: Dropdown (3 options) - Rounded (default): Smooth hemispherical caps at bond ends - Flat: Perpendicular plane cut at bond ends - Chamfer: Beveled/angled caps - Availability: disabled in the Flat style

Taper: 0.0–0.6 (slider) - Conical taper from bond center to ends - 0.0 = uniform cylinder, 0.6 = strong taper (cone-like) - Taper amount is proportion of radius reduction at ends - Creates depth cues for overlapping bonds - Availability: disabled in the Flat style

Multi-bond Layout: Dropdown (2 options) - Parallel (default): Multi-order lanes run parallel to bond axis - Double: two parallel cylinders offset perpendicular to axis - Triple: three parallel cylinders (center + two offset) - V-Spread: Lanes diverge from atom centers in V-shape - Controlled by V-spread (deg) slider (see below) - Creates wider visual separation at atom sites

V-spread (degrees): 0.0–20.0 (slider, only enabled when Multi-bond Layout = VSpread) - Angular spread of multi-bond lanes from atom centers - 0° = parallel (equivalent to Parallel layout) - 20° = maximum divergence (wide V) - Each lane tilts outward by half the spread angle

Halos & Orbits (Accent Effects)

Halo Glow: Soft additive glow layered on top of bond geometry.

• Enabled checkbox: Toggle halo effect on/off
• Intensity: 0.0–1.0 (slider) — Glow brightness/alpha
• Radius scale: 0.8–2.0 (slider) — Halo size relative to bond thickness
  • 1.0 = same radius as bond, 2.0 = double radius
• Halo colour: RGBA color picker for glow tint
• Availability: disabled in some appearance styles

Orbit Bands: Periodic intensity bands along bond length (stylistic accent).

• Enabled checkbox: Toggle orbit bands on/off
• Intensity: 0.0–1.0 (slider) — Band contrast/visibility
• Frequency: 0.0–8.0 (slider) — Number of bands per Ångström
  • 0.0 = solid (no bands), 8.0 = rapid oscillation
• Offset: 0.0–1.0 (slider) — Phase shift of band pattern
  • Animating offset creates “traveling wave” effect
• Availability: disabled in some appearance styles

Workflow Example

Creating publication-quality stick bonds: 1. Open Appearance panel → Bonds section 2. Set Thickness = 0.08 Å (thin sticks) 3. Set Color Mode = Split (element colors) 4. Set Cap Style = Rounded (smooth ends) 5. Set Glossiness = 0.3 (subtle sheen) 6. Set Inactive Opacity = 0.6 (mute background) 7. Adjust Double/Triple Spacing = 1.2 (wider multi-bonds) 8. Save as custom preset: Appearance → Presets → Save As → “Publication Sticks”

Wireframe mode for large structures: 1. Set Thickness = 0.001 Å (pencil-thin) 2. Enable Line-only checkbox (if available in current style) 3. Set Color Mode = Solid 4. Set Base Colour = dark gray or black

Highlighting aromatic systems: 1. Set Aromatic Thickness = 0.7 (thinner than single bonds) 2. Set Aromatic Spacing = 1.4 (wider lane spacing) 3. Set Dash Length = 0.5 Å, Dash Gap = 0.25 Å (clear dashes) 4. Enable Halo Glow with cyan color + 0.5 intensity

Implementation References

• Panel UI: ui/shell/src/panels/appearance/bonds.rs (bonds_section)
• Enum definitions: core/appearance/src/enums.rs (BondCapStyle, BondColorMode, BondMultiBondLayout)
• Render thickness calculation: core/appearance/src/render_styles.rs (apply_theme_styles, which picks the per-order multiplier into a local order_thickness)
• Cache key hashing: ui/shell/src/render_cache/hashing.rs (hash_theme — all thickness/spacing values contribute to cache invalidation)

Style Availability Matrix

Controls disabled in certain appearance styles:

Control	Classic	Flat	Presentation	Technical
Bond color mode	✓	✓	✓	✓
Glossiness	✓	✗	✓	✗
Line-only mode	✓	✓	✗	✓
Cap style	✓	✗	✓	✓
Taper	✓	✗	✓	✓
Halo glow	✓	✗	✓	✗
Orbit bands	✓	✗	✗	✗

Check style_availability() helper for runtime availability flags per style.

• Export Dialog: Open via File → Export → Export Image… to configure and preview image exports. The dialog provides a two-column layout: left panel for settings/presets, right panel for live preview.

3.5.2 Built-in Export Presets

Three publication-ready presets optimized for common use cases:

• Slide HD — 1920×1080 @120 DPI, transparent PNG, sRGB, OrbitronSignature theme
• Poster A0 — 9933×14043 (A0 @300 DPI), opaque PNG, sRGB, safe margin enabled
• Nature 1-col — 2008×2835 (85×120 mm @600 DPI), opaque PNG, sRGB, safe margin + rule-of-thirds enabled

Select a preset from the dropdown to apply all its settings. The preview updates immediately to show the final output appearance.

3.5.3 Image Settings

Format: - PNG (with alpha transparency) - TIFF (16-bit depth) - JPEG (no transparency support) - SVG, PDF, EPS — true vector geometry for ball-and-stick scenes: atoms become circles and bonds become line segments, so a figure stays sharp at any print size. Anything drawn on top of the render rather than by it — isosurfaces and other meshes, atom labels, measurements, annotations, post-processing, composition guides, a non-sRGB colour profile — cannot be expressed as shapes, so those exports fall back to an embedded raster image and the footer says which feature caused it. Vector output uses flat fills rather than shaded spheres, so a pale atom on a pale background reads as an outline.

Resolution: - Width/Height: 64–20,000 pixels (drag values or use presets: HD/Full HD/4K UHD/Square) - DPI: 72–600 (affects print sizing metadata)

Transparency: - Available for PNG, TIFF, SVG only - JPEG exports will fail if transparency is enabled (error message shown in the footer)

Color Profiles: - sRGB (default) — Standard profile for web and screen display; PNG exports carry sRGB and DPI metadata - Grayscale Safe — Converts to Rec.709 luminance for monochrome outputs

A third value, Adobe RGB, exists only so that presets saved when it was offered still load. The combo box no longer lists it, and an export that carries it is refused with “Adobe RGB export needs an embedded ICC profile, which Orbitron does not ship yet.” Choose sRGB or Grayscale on such a preset before exporting.

3.5.4 Animation

Open the Animation collapsing section to export a moving figure. Frame size, theme, transparency and post-processing all come from the Image Settings above, so an animation frame looks exactly like the still export beside it.

Animate: - Vibrational mode — sweeps the mode selected in Analysis → Vibrations through one full period, using that panel’s amplitude and its raw/projected choice. The loop closes seamlessly. - Trajectory — plays back the loaded optimisation or MD frames. When the trajectory has more frames than the frame count, it is sampled evenly with both endpoints kept, and the footer reports how many of how many were used. - Camera orbit — spins the camera one full turn about the scene, geometry unchanged. The axis is whatever points up on screen, so a tilted view turns rather than tipping over.

Output: - Animated GIF — a single looping file that plays anywhere. GIF allows 256 colours per frame, so a shaded render will band and dither. - PNG frame sequence — lossless numbered frames (frame-0000.png, …) in a folder you choose. Use this for a publication-quality movie; the footer prints the ffmpeg command that turns the folder into an MP4. Orbitron does not run ffmpeg itself and does not require it to be installed.

Frames (2–600) and FPS (1–60) set the length; the panel shows the resulting duration. Frame size drives render time far more than frame count does.

3.5.5 Advanced Image Options

Open the Advanced Image Options collapsing section for post-processing, composition guides, and batch export.

Post-Processing:

Enable the checkbox to apply real-time adjustments (reflected in preview and final export):

• Exposure — -2.0 to +2.0 stops (brightness adjustment)
• Contrast — 0.5 to 1.5 (midpoint at 1.0)
• Saturation — 0.0 to 1.5 (0=grayscale, 1.0=original, >1.0=enhanced)
• Vignette — 0.0 to 1.0 (edge darkening effect)
• Grain — 0.0 to 0.2 (film grain texture)
• Bloom — 0.0 to 1.0 (glow strength)
  • Bloom Threshold — 0.0 to 1.0 (brightness threshold for glow)
• Sharpen — 0.0 to 1.0 (clarity/detail enhancement)

All post-processing controls use sliders with clamped ranges. Changes apply immediately to the preview.

Composition Guides:

• Safe Margin — Overlay a padding rectangle (1–20% configurable) to ensure critical content stays within print bleed zones
• Rule of Thirds — Overlay a 3×3 grid to aid in compositional alignment

Guides appear in the preview but are not rendered in the final export.

Custom Presets:

1. Configure desired settings (resolution, format, post-processing, etc.)
2. Enter a name in the “Name” field
3. Click Save preset to persist the configuration
4. Saved presets appear in the list below with:
   • Click to apply — Load preset settings
   • ✕ button — Remove preset

Presets are stored in the viewer’s session state and persist across restarts. Saving a preset with an existing name (case-insensitive) updates that preset and preserves its batch queue selection status.

3.5.6 Batch Export

Export multiple presets in one operation:

1. Open Advanced Image Options
2. Check the Batch Export Queue checkboxes next to built-in presets (Slide HD, Poster A0, Nature 1-col) or custom presets
3. The status line shows: Batch queue: X built-in / Y custom
4. Click Batch Export Presets… (enabled only when queue has ≥1 preset)
5. Select an output folder
6. Orbitron renders all queued presets sequentially to the folder

Output Naming: - Files named using preset slug (e.g., slide_hd.png, poster_a0.png, my_preset.png) - Duplicate slugs get numeric suffixes (preset-2.png, preset-3.png)

Status Reporting: - On success: "Exported N presets to <folder>" (1 preset for one) - On failure: "Exported N presets to <folder>; failed M presets: <name> (<error>), ..."

Each preset in the batch uses its own format extension (PNG/TIFF/JPEG/SVG/PDF/EPS).

3.5.7 Additional Export Tools

The File → Export menu writes the scene itself, rather than a picture of it:

Entry	Writes
Export Image…	Opens the export dialog (§3.5.2–§3.5.6): images, video, and the geometry exports below
Export XYZ…	All atoms, plus visible geometry overlays
Export PDB…	All atoms, plus visible geometry overlays
Export GROMACS GRO…	Base-scene coordinates, residue identity, complete velocities, and periodic box. Topology, bonds, charges, and overlays do not fit and are reported.
Export POSCAR…	VASP structure. Frozen atoms (§3.7.3) come out as Selective dynamics F F F
Export Molfile…	Connectivity as an MDL Molfile. V3000 is written automatically when the structure will not fit a V2000 counts line; dative bonds use V3000 type 9 (see Data Support §2.6)
Export Web View…	A self-contained HTML page with the WASM viewer embedded (see Web Embedding)
Export Bundle…	A single-file .orbpack session bundle (see Bundles)
Export / Import Appearance Bundle…	Render style, colors and overlay settings as JSON, without the structure

The export dialog also provides:

• Export Scene — Write all atoms to XYZ using current scene snapshot (button shows default filename based on loaded file)
• Export Selection — Write only highlighted atoms to XYZ (disabled if selection is empty, shows atom count)
• Export Visible Overlays… — Write each visible overlay to individual files (geometry overlays as XYZ, volumetric overlays as CUBE copies) into a chosen folder
• Save run bundle…: Package a VASP or Quantum ESPRESSO calculation into a structured .orbitron directory (same as orbitron pack periodic; pack vasp remains an alias):
  • orbitron.json canonical metadata
  • Spin-resolved DOS and band-envelope CSVs
  • Quick-look PNG plots for DOS and band envelopes
  • Optional source files from the run
  • Optional VASP volumetric fields (CHGCAR, LOCPOT, AECCAR, PARCHG)
  • Manifest with SHA-256 hashes and export metadata
  • Checkboxes: Include raw files, Include volumetric, Overwrite (force-remove existing bundle)
• Save DOS CSV / Save band envelope CSV: Export the active periodic electronic-structure data to CSV when usable DOS or band arrays are present

Theme Preset:

Export settings include a theme_preset field (currently internal, not exposed in UI): - None (default) — Use active viewer theme - OrbitronSignature — Apply Orbitron’s signature theme for consistent branding across exports

Built-in presets use OrbitronSignature by default.

Notes: - Scene annotations are included in export previews and final renders (ui/shell/src/export/rendering/raster/overlays.rs, overlay_annotations) - The status ribbon indicates when current settings differ from the applied preset - The left column is resizable and scrollable for compact display - See Developer Guide (§8.2 UI State & Panels) for implementation details on how theme changes propagate through UiState - Orbital and NBO panels let you load CUBE files, adjust isovalues, recolour lobes, and export meshes. Mesh generation times and triangle counts are reported via the panel (OrbitalMeshStats).

3.5.8 Molecular diagrams and crystal projections

Appearance → 2D Diagram lays out a non-periodic molecular connection table as a skeletal or Orbitron-style drawing. In Edit mode, atom placement, element changes, bond-order changes, deletion, undo, and redo operate on the same scene as the 3D viewer. Dragging an atom outside Edit mode only adjusts the drawing. Leaving diagram mode returns to 3D and relaxes the chemistry changed in the drawing while keeping manual layout nudges out of the molecular coordinates. Clear labels, on by default, turns a coordination complex’s ligands in a skeletal drawing until the element labels no longer overlap, as orbitron.diagram and orbitron render --diagram do, at the same label size, so the three draw the same picture. Identifier reading, also on by default, draws the charges and bond orders orbitron identify names (the ionic model’s reading, with the file’s own explicit chemistry kept) rather than the file as loaded, again as the CLI and Python do; a coordinate file states neither, so drawn as loaded a complex shows no charges. The Orbitron style, the 3D render flattened, draws the same reading: the charges on its atoms’ symbols and the donor bonds dashed. Edit mode always draws the scene being edited.

A periodic scene uses Appearance → Crystal / Unit Cell → Crystal Projection instead. Choose a, b, or c to look down that lattice vector with an orthographic camera, then choose Use flat style for disc atoms and line bonds. Editing acts on primary-cell atoms; dashed bonds to periodic images are display only. Orbitron does not offer a molecular diagram for a crystal because flattening one cell would present a lattice fragment as a complete molecule.

3.5.9 Cartoon, ribbons, and figure authoring

A publication figure of a binding site is made from two sections. Appearance → Selection Styling scopes a representation to part of a structure and is shown for every scene; Appearance → Cartoon / Ribbon holds the ribbon geometry and its opacity, and appears only when the file has protein chains.

Turning the ribbon on. Tick Enabled, or use the Overlays menu in the toolbar. Note that the toolbar’s Model menu (Ball & Stick / Sticks / Space Fill / Atoms Only) does not offer cartoon — cartoon is a separate layer that draws alongside atoms rather than instead of them. The three buttons Cartoon only, Cartoon + atoms and Atoms only set both at once.

View → Cartoon mirrors the two toggles and adds two settings of its own. Preset picks Classic — the baseline defaults, and what you want while working — or High Quality, which raises the sampling and facet counts and is worth switching to just before a screenshot. Auto View On Load decides whether Orbitron turns cartoons on by itself for a PDB or mmCIF carrying secondary structure or nucleic acids; turn it off if you would rather open every structure as atoms and decide yourself. The same submenu holds Show H-Bonds, which draws approximate backbone hydrogen bonds as dashed cylinders.

What the ribbon draws follows PyMOL’s cartoon. A helix or strand ends flat at its last residue, and a strand in an arrow over its last residue. Residues whose backbones are bonded are joined whatever their numbers say, so an insertion code does not break the ribbon. Where the backbone does break, a gap of up to ten residue numbers in one protein chain is bridged with a dashed tube, and a larger gap, or any in a nucleic acid, ends the ribbon. A nucleotide’s sugar and base are drawn as plates, both of a purine’s rings among them.

Selecting by expression. Press Cmd+K (Ctrl+K on Windows and Linux) to open the command palette, then start the line with = to run a selection query in the same language the CLI’s orbitron select uses. For example:

=resname HEM or (within 4.5 of resname HEM and not resname HOH)

selects a heme and its binding pocket while leaving the solvent out. The title bar reports how many atoms matched. This is currently the only way to select by expression in the viewer, and a click in the viewport replaces the selection, so build the selection last, or rebuild it if you click the structure.

Scoping a representation to that selection. Two controls under Selection Styling take a selection directly:

• Atoms for selection only draws atoms and bonds for the selected atoms and nobody else, with the ribbon still covering the whole chain. This is the quickest route to “ribbon everywhere, sticks at the active site”.
• Focus on selection (dim others) keeps everything visible but pushes the unselected atoms back.

Groups, under Appearance → Selection Styling, make the arrangement durable. With a selection active, Add from selection captures it as a named group carrying its own:

• visibility checkbox and opacity slider,
• Show as representation — Default, Cartoon, Ball & stick, Sticks, Spheres or Hidden — independent of the global style, so one group can be sticks while the rest of the scene stays ribbon,
• solid colour override, or a per-group cartoon colour mode,
• a Label residues checkbox, which names this group’s residues the way a caption does (W505, HEM 501) whatever the selection is doing,
• a Polar contacts checkbox, which draws dashed lines to this group’s hydrogen-bonding partners,
• a Live (expr) toggle. A group is otherwise a frozen set of atoms captured when you created it; a live group re-evaluates its expression against the scene each frame, so it follows edits.

Groups are saved with the session. They are not part of an appearance preset: a preset carries a theme (and, for the two representation presets below, a render mode), never a set of atoms.

Selection Styling is not just for proteins

Groups, Atoms for selection only and Focus on selection (dim others) live in their own Appearance → Selection Styling section, and that section is shown for every scene. Until 2026-09-04 they sat inside Cartoon / Ribbon, which appears only when the file has protein chains — so for a metal complex, an organic molecule or a slab, the whole system worked in the renderer, saved into sessions and travelled to an exported page, while being unreachable from the UI. Nothing about groups needs a protein.

Building a selection larger than a few clicks is worth knowing separately: press Cmd/Ctrl+K and prefix the query with = to run a selection-DSL expression, such as =within 4.5 of resname HEM. Note that clicking in the viewport replaces the selection, so capture the group before you click away.

Ribbon opacity. The Surface sub-section carries the ribbon’s material: Opacity, Sheen, Rim light, and a constant-width Outline. Dropping opacity below 1 turns the ribbon into a pale backdrop that an active site in sticks reads through, which is the conventional way a binding-site figure is drawn. It applies to the nucleic overlays as well, so a protein–nucleic complex stays consistent, and it composes with a nucleic ring’s own transparency rather than overriding it.

A worked example. The figure of a P450 active site — ribbon behind, heme and pocket residues in sticks:

Orbitron rendering of a haem binding pocket: a pale green ribbon behind the haem drawn in sticks, its iron as a copper sphere, and cyan dashed polar contacts to the surrounding residues and waters

Figure 2: What the five steps below produce: one group in sticks at the site, one group in cartoon everywhere else, and polar contacts on the first.

1. Open the structure and tick Enabled under Cartoon / Ribbon.
2. Cmd+K, then =resname HEM or (within 4.5 of resname HEM and not resname HOH).
3. Open Groups → Add from selection, set Show as to Sticks, and tick Label residues and Polar contacts.
4. Cmd+K again with the complement, =not (resname HEM or (within 4.5 of resname HEM and not resname HOH)), then Add from selection with Show as set to Cartoon. That second group is what leaves the ribbon covering the whole chain while atoms are drawn only at the site.
5. Open Surface and pull Opacity down to about 0.3.

Every step above is a property of a group, so the figure survives clicking in the viewport and reopens intact from a saved session. Atoms for selection only reaches the same picture in one tick and is the better tool while you are looking around, but it follows the live selection: the next click puts every atom back.

Hydrogen bonds in the figure. Tick Polar contacts on a group and every N/O pair within 3.5 A of one of its atoms is drawn as a cyan dashed line. On a binding site that is the picture people mean: the substrate carboxylate to its arginine, a side-chain hydroxyl to the ligand, the ordered waters.

Two things about it are worth knowing rather than discovering:

• It is a contact, not a proven bond. A crystal structure has no hydrogens, so there is no D-H-A angle to test and no way to tell a carbonyl oxygen from a hydroxyl one — every bond in a PDB without CONECT records reads as single. What is drawn is the conventional heavy-atom criterion, which is what PyMOL and ChimeraX call a polar contact too. Two carbonyls pointing at each other are reported; a person reads the figure. Where a structure does carry explicit hydrogens, Scene > Contacts from selection runs the strict detector, which tests the angle and will not report those.
• Contacts to atoms that are not drawn are left out, so a dash never ends in empty space. In the ribbon-plus-active-site construction that means contacts appear among the residues drawn as sticks — which is the reason to draw them as sticks.

Separately, Appearance > Cartoon / Ribbon > Show H-bonds draws the backbone hydrogen bonds that hold the secondary structure together, as part of the ribbon. It only ever fires for residues in a helix or a sheet, so it shows nothing for a loop, a side chain, a ligand or a water: it decorates the fold, where Polar contacts describes a site.

Labelling the residues in the figure. Tick Show labels under Appearance → Atom Labels, then choose where the names come from:

• A group’s own labels. Tick Label residues on the group. This is the one to use for a figure: the labels belong to the group, so they stay through the next viewport click and come back when the session is reopened.
• The live selection. Set the label mode to Selected residues, and the Cmd+K query that picked the active site also decides what is named. Good for looking around, but the labels go when the selection does.

The two add together, so a group can name the active site while you inspect something else. Elements, the default mode, is the old behaviour: one element symbol per atom.

The same figure from the command line, including the labels, is in the CLI guide (§4.3.1) — the flags there mirror these controls, so a figure built here can be regenerated in a script.

3.6 Analysis panels

Analysis is a section of the left rail with a single dropdown across the top that picks the view, its entries grouped under Run, Geometry & dynamics, Electronic structure and Periodic electronic structure. The view set is conditional on what the file carries. An entry is offered only when the scene holds the data behind it, so two files rarely show the same list. Overview and Surfaces are always there; Tasks needs parsed task summaries, Orbitals needs molecular orbitals, Vibrations needs frequencies, Excited States needs an excitation spectrum, Periodic needs a periodic run that produced bands or a DOS, and Charges needs per-atom populations. The 2D slice is a section inside Surfaces rather than a tab, and it needs the file to carry a basis set. If a tab named below is not on screen, the file does not have what it reads, and no setting will bring it back.

The Analysis section of the rail with its view picker open for a Gaussian optimisation stage: Overview, Tasks and Sources under Run, Optimization under Geometry & dynamics, and Orbitals, Surfaces and Charges under Electronic structure

Figure 3: The Analysis view picker for a Gaussian optimisation stage. A frequency stage adds Vibrations; a plain XYZ offers only Overview and Surfaces.

• Overview: Leads with the active task: the program, the kind of calculation, method and basis (and solvent, when there is one), a converged / failed / incomplete tag, the final energy, and a Tasks… button that jumps to the Tasks view. Below it come the ground-state <S²> when the run printed one and the permanent dipole, when parsed, as a Debye magnitude plus x/y/z components in the source coordinate system.

  • Show vector draws the printed Cartesian dipole as an arrow, with the arrowhead pointing from negative toward positive charge and the arrow’s midpoint moved onto the centre of mass so it reads against the molecule. Scale (Å/D) beside it is an absolute conversion — Ångströms drawn per Debye — not the relative multiplier the force arrows use, so two scenes at the same scale are directly comparable. The checkbox is disabled for a dipole that is effectively zero, and the panel says so rather than drawing nothing without explanation.
  • Two warnings sit under it when they apply. For a charged system the vector depends on the calculation’s origin, so its direction is a property of the input file as much as of the molecule. And for a periodic cell, what is drawn is a molecular dipole, not the cell’s polarization — those are different quantities, and the Berry-phase one is not this.
  • Force vectors appear here, under Forces, when a QMCPACK deck carried an ACForce estimator. The QMCPACK estimate checkbox draws one arrow per atom, starting at the atom’s surface along its force. Lengths are relative: the largest force in the run draws at about one bond, and the scale beside the checkbox multiplies that. So the arrows compare within a scene and not between two — which is the right trade for a quantity whose magnitudes carry a systematic error, and it is what keeps them visible whether the geometry is converged or not. (VASP forces are a separate overlay with their own checkbox in the same group, VASP final step, scaled by the same rule and coloured by magnitude; see below.)
  • A QMC force is a Monte Carlo estimate, so it comes with an error bar and a force the run did not resolve from two standard errors of zero is drawn dashed. The test is on the vector’s magnitude against the error propagated onto it, so a force is dashed as a whole rather than per component, and one missing component error makes the whole vector unresolved. A dashed arrow means the run could not distinguish that force from no force; it is not a smaller arrow, it is a different claim.
  • QMCPACK 4.4 forces additionally carry a systematic error this project measured and could not explain (0.02–0.06 Ha/bohr against a finite-difference-verified analytic reference; see the CLI guide’s §4.1.5 callout). Read the directions, not the lengths.

  

  Force arrows on a QMCPACK water molecule: two solid shafts for forces the run resolved from zero and a short dashed shaft on a hydrogen whose force it did not

  Figure 4: Solid means the run resolved that force from zero; dashed means it did not. Lengths are relative to the largest force in the run, so the dashed arrow is short because that force is small; the arrow scale was raised to 2.2 to give its shaft room to show the dashes.

  • The arrows travel with the figure. They are captured alongside the cell overlays and the dipole arrow, so File → Export → Web View ships them into the embedded viewer and a saved .orbpack restores them with the rest of the presentation. Whichever way the figure leaves Orbitron, the dashed ones stay dashed.

• Tasks: Lists stages under per-application headings. Ten programs are recognised by name — Gaussian (GaussianRunSummary), NWChem (NwchemRunSummary), ORCA, DIRAC, QE, Molpro, Molcas/OpenMolcas, VASP, QMCPACK, and CP2K — and every one of them gets a heading. Six have a dedicated summary panel; ORCA, VASP, QMCPACK, and CP2K render generic task cards instead, which carry the method, basis, solvation, outcome and energy but not a package-specific breakdown. Expand a task/stage card to inspect method, basis, implicit solvation, energies, thermochemistry, SCF convergence, and any available diagnostics; use Select task to make a completed Gaussian/NWChem/Molpro task the active scene. SCF histories keep optimisation cycles separate and plot iteration energies when the program printed them. Molpro tasks map directly onto electronic-structure and driver programs (RHF/DFT, UCCSD/UCCSD(T), MULTI, RS2C, OPTG, FREQUENCIES) while SEWARD/integrals stay behind the scenes to feed geometry and basis data; the Molcas section renders one card per module (SCF, RASSCF, CASPT2, OPT/FREQ, etc.) and surfaces optimisation energy profiles, frequency mode counts, and RASSCF/CASPT2 active-space/spin/symmetry diagnostics derived from extras.molcas; a frequency run’s thermochemistry (its 298.15 K table) is on the MCLR card that printed it. Progress and cancellation controls appear at the bottom of the panel.

  • NWChem completion is two levels of information: the source in Overview says whether the whole output reached a terminal marker. A red Run incomplete source can still contain a completed earlier optimization. Separately, every NWChem task has its own outcome. Orbitron auto-selects the best completed task (last optimization, then frequency, then single point); incomplete or failed cards retain their extracted summary but say why they are Unavailable instead of attempting a partial task load.
  • QMCPACK statistics are inside the task card rather than in a tab of their own, because a QMC number without its error bar is not a result. The card opens with the number of blocks per series, then one line per trace reading mean ± blocked error (N× correlated). A run too short for the blocking curve to flatten gets no error bar and says so — that is the answer, not a missing feature. A trace whose two halves differ by more than a couple of sigma is flagged as drifting, meaning the walk had not settled and the mean is not a result however tight its bar.
    • Below the table, a selector picks which trace to plot (defaulting to LocalEnergy, since that is the number being quoted) and draws two plots. The block trace shows the series against block index with its mean and ±1σ band; a trace that sits outside its own band for long stretches has not equilibrated, which the error bar alone never says. The blocking curve shows the standard error against blocking level with each level’s own uncertainty as a bar, and marks the level that was actually taken. A curve still climbing at the marked level means the quoted error is too small.
    • Natural orbital occupations from a QMCPACK run are a CLI-only report (orbitron analyze); the viewer does not show them.
  • Smart Auto-Selection: When opening an NWChem file, Orbitron automatically selects and loads the best complete task using this priority order: (1) last complete optimization, (2) last complete frequency analysis, (3) last complete single-point energy calculation. If no tasks completed successfully, a toast notification appears: “All NWChem tasks are incomplete or failed. See Analysis → Overview.” The Analysis tab still shows every task, including incomplete ones, with the reason it cannot be loaded.

• Sources: Provenance for any scene opened from a file on disk (and for the members of a study), and a companion-file overview for multi-file formats. Even an MD trajectory states which coordinate and topology files it came from. Companion-file coverage: NBO7 (.47 archive + .31–.46 plot files), VASP (full run directory), NWChem (.out + .nw + .movecs + .hess + .zmat + .cube + .civecs), ORCA (.out + .inp + converted .molden.input + .gbw + .hess + _trj.xyz + .engrad), Gaussian (.log/.out + .gjf/.com + .fchk/.chk + .cube), Molpro (.out + .inp/.com + .xml and its .xml-sidecar, which carry the orbitals through i shells, + .log + .molden + .cube), Molcas (.out + .input + .opt.xyz + the orbital family (.ScfOrb, .RasOrb, .GssOrb, .LprOrb, .Mp2Orb) plus .molden, the HDF5 orbitals (.scf.h5, .rasscf.h5) and status), DIRAC (.out + .inp + .mol + .h5), and Quantum ESPRESSO (.out + .in + .xml + .UPF + .dos + .pdos_tot + .pdos_atm#* + .bands + .bands.gnu + .xsf). The panel scans the active scene’s directory and groups discovered roles into Required, Optional / advanced, and Plot data sections. Each row shows one of three states:

  • ✓ Loaded — file is the active scene or has been parsed into the workspace; ↻ Reload re-reads from disk.
  • ◯ Detected — sibling found on disk but not yet loaded; Load stages it into the workspace (or, for VASP volumetric/trajectory and cube files, routes through the appropriate loader). For POSCAR ↔︎ CONTCAR pairs an additional Compare button pushes the file as a scene overlay so initial vs. relaxed geometries render simultaneously.
  • ○ not loaded — no sibling found; Add file… opens a file dialog filtered to the role’s filename pattern. Sibling matching is mode-aware: NBO and the QC formats use stem-matching (water.out → water.fchk) so neighbouring runs in the same fixtures dir don’t cross-pollinate; VASP uses exact-filename matching (every VASP file has a canonical name). Stem matching also accepts extended-stem siblings — Molcas writes <stem>.scf.molden, <stem>.rasscf.molden, etc., and these auto-detect against an <stem>.out primary because the dot-prefixed extension protects against cross-run matches. NWChem deep-load actions (introduced 2026-05-09):
    • Hessian (.hess) — Loads NWChem’s Cartesian Hessian, mass-weights it against atomic masses, projects out 5–6 rigid-body modes, and diagonalises in pure Rust to synthesise vibrational modes. Auto-switches to the Vibrations tab. Useful when the freq calculation was a follow-up job whose .out you don’t have open. Frequencies are in cm⁻¹; near-zero modes correspond to the projected-out trans/rot residue.
    • MO coefficients (.movecs) — Loads NWChem’s Fortran-binary MO file (full nbf × nmo, unlike the truncated coefficient table in the .out). Auto-switches to the Orbitals tab and populates the parent scene’s electronic structure. When the .out already provided the basis-set definition, the coefficients also flow through to the Surfaces tab so MOs render as 3D isosurfaces — pick one or more orbitals, click Compute selected, and the meshes appear without needing a precomputed cube file. Cartesian d and f shells are reordered from NWChem’s alphabetical column convention to the Gaussian-style convention the surface evaluator expects, so heavy-element runs (uranium with ECP60 + f-shells) render correctly.
    • Input deck (.nw) — Toasts a one-line summary of the deck (charge, multiplicity, basis libraries, ECP usage, xc functional, task list). Doesn’t swap the active scene when one is already loaded.

  Molcas / Molpro deep-load actions (introduced 2026-05-09):

  • MOLDEN snapshots (.molden) — MOLDEN is a portable text format that ships geometry, basis-set definition, and MO coefficients in a single file. Loading one immediately populates the Surfaces tab — no separate basis or movecs companion needed. Common Molcas flavors (*.scf.molden, *.rasscf.molden, *.guessorb.molden, *.mp2.molden) auto-detect against the .out primary thanks to extended-stem matching. Spherical d ([5D]) flows through the existing 5D→6D pure-spherical mapping. Cartesian d / f rendering matches the FCHK convention so any package emitting MOLDEN works out of the box.

  DIRAC deep-load actions (introduced 2026-05-09):

  • HDF5 checkpoint (.h5) — Loads DIRAC’s structured HDF5 dump (eigenvalues, occupations, MO coefficients, AO basis on /input/aobasis/1). Builds MolecularOrbital records on the active scene’s electronic structure with positron tags applied to the lower half of the 4-component spectrum (energies < −1000 Ha, near −2c²). The Large-component AO basis is reconstructed into a GaussianBasisSet so the Surfaces tab can compute relativistic MO isosurfaces from the same scene. Handles nz = 1 (real / scalar-relativistic), nz = 2 (Kramers-restricted), and nz = 4 (full quaternion 4-component) checkpoints — for nz ≥ 2 the dominant-z slice is selected per MO so β-spinor-dominant orbitals (which leave z=0 near zero) are recovered correctly. Isosurfaces need a run without symmetry (.NOSYM, or a .mol file without symmetry): with symmetry DIRAC stores the coefficients in its symmetry-adapted basis, which cannot be read shell by shell, so such a checkpoint loads its energies and coefficients but no orbital basis, and the status line says so. The checkpoint must belong to the open scene: same atoms, within 1e-3 Å.

  Quantum ESPRESSO deep-load actions (introduced 2026-05-10):

  • Input deck (.in) — Parses &CONTROL / &SYSTEM namelists and the free-form ATOMIC_SPECIES / ATOMIC_POSITIONS / CELL_PARAMETERS blocks. Derives the lattice from ibrav (0–14) + celldm or from the explicit CELL_PARAMETERS block, depending on ibrav=0. Loads the geometry as the active scene — useful for previewing structures before running pw.x.
  • Structured XML (<prefix>.xml / data-file-schema.xml) — Parses QE’s version-stable XML. Pulls the final relaxed structure plus eigenvalues / occupations / Fermi level / total energy / convergence flags from the <output> block. Builds a SceneGraph from the geometry.
  • XSF / Cube-as-xsf (.xsf) — Handles both proper XSF (CRYSTAL / MOLECULE / ATOMS keywords) and QE’s “Cube-as-xsf” format (pp.x output_format=6 writes Gaussian Cube content with an .xsf extension). The latter routes through the existing cube parser so pp.x densities feed the orbital-dataset registry.
  • DOS / PDOS / bands (.dos, .pdos_*, .bands, .bands.gnu) — Loading any of these toasts a one-line parse summary (point count, energy range, EFermi for DOS) and marks the role Loaded. The file is parsed for that summary only. Analysis → Periodic draws a QE run’s bands from the run’s own output, and its DOS and projected DOS from the projwfc.x files beside that output, read when the pw.x output is opened rather than from a file loaded here.

  NWChem .civecs and Natural Transition Orbitals (introduced 2026-05-09):

  • Loading a .civecs_singlet / .civecs_triplet file (NWChem’s TDDFT / TDA / EOM excited-state amplitudes) parses every state’s X amplitudes, computes Natural Transition Orbitals via SVD, and appends the dominant particle / hole NTO pairs to the active scene’s electronic_structure.molecular_orbitals with high vector_numbers (≥100 000) so they sort to the bottom of the Orbitals list. Surfaces can render them like any other MO. Requires the parent scene already to carry SCF MOs (.out + .movecs loaded first).

• Vibrations: Playback vibrational modes. Raw/projection toggles, amplitude, speed, and autoplay live in the shared analysis state, so switching tasks or loading sessions keeps the expected playback posture but automatically clears stale meshes when the source data changes. ⟲ Reset to Equilibrium — and toggling auto-play off — snaps the geometry back to the equilibrium structure; Show vectors draws static per-atom displacement arrows on that equilibrium geometry (not on the animated frame), and Vector Length scales them independently of the playback amplitude. They are hidden while a mode is playing: the arrows are anchored to the equilibrium geometry and the atoms are not, so showing both makes the molecule come away from its own vectors, and the animation says what the arrows say. Arrow appearance sets thickness and an optional colour override, shared with the force and dipole arrows. Lengths are relative to the mode: its largest displacement draws at about one bond and every other atom in proportion, so a mode is legible whatever its eigenvector normalisation, and lengths compare within a mode rather than between two. The arrows are scene geometry, so they appear in exported images, in vector output, and in an exported web view. The IR/Raman spectrum has a Pop out button that opens it in a resizable window with Save PNG and Export CSV. An NWChem Raman task brings its own sampled curve; a Gaussian freq=raman job carries Raman activities on its modes beside the IR intensities, and the panel offers Dataset: IR | Raman to switch between them, the Raman curve broadened from the activities with the same line shape and width as the IR one, as orbitron plot spectrum --raman draws it. A Gaussian Freq=Anharm job’s IR spectrum can be drawn at its anharmonic fundamentals with their anharmonic intensities (Anharmonic fundamentals, offered when every mode has one), as plot spectrum --anharmonic draws it; the modes listed and played stay harmonic.

• Orbitals: Lists every parsed molecular orbital with energy, occupancy, and symmetry label. HOMO/LUMO are highlighted; the panel shows the gap in Hartree and eV. Each MO row expands to:

  • A Show as halo button that colors every atom by its contribution (Σ|c|², signed by dominant lobe) to that orbital — see “Atom Coloring halo overlay” below.
  • Top-N coefficient inspector (configurable per panel: 1–200): the largest contributors with the bfn index, signed coefficient (color-tinted by sign), and atom-orbital label.
  • Filter atoms textbox: case-insensitive substring match against the AO label (e.g. "O", "1 N", "px").
  • Copy button: emits the visible contributors as TSV for paste into a spreadsheet/report.

• Surfaces (unified isosurface view, replaces the legacy “Volumetrics” tab): one place to render 3D orbital meshes from any source the scene holds. For an NWChem scene whose .out carried the basis but not full coefficients, opening this tab auto-loads a detected sibling .movecs so the orbital rows and isosurfaces become available without a manual trip to Sources.

  • Sources automatically populated from the loaded scene:
    • Volume datasets loaded via Add volume…: CUBE, XSF, MRC2014, and CCP4 maps.
    • Molecular orbitals computed on-the-fly from the scene’s basis set (FCHK / NWChem / Gaussian / Molcas with parsed coefficients). α/β rows are interleaved by vector number.
    • NBO orbitals from a loaded NBO archive (every family in the workspace’s .31–.40 files: AO, NAO, NHO, NBO, NLMO, MO, plus pre-orthogonal variants).
    • Molecular surfaces added with Add molecular surface. Unlike every row above, these come from the atoms rather than from anything in the file, so they are the one thing this tab can offer a scene with no wavefunction at all — a plain PDB included. Pick solvent-excluded (the default, and the picture a paper usually shows), solvent-accessible, or plain van der Waals; set the probe radius, the grid spacing, and which radius table; and optionally narrow the surface to a selection. The row reports what was built — atom count, the grid actually used, triangle count and area — and says so when the grid had to be coarsened to fit the voxel budget or when the result turned out to be more than one closed shell. Neither is visible in the picture, and both change what the figure is claiming. For the solvent-accessible and van der Waals surfaces, which are unions of the atoms’ spheres, the area is integrated over the spheres, with the mesh’s own beside it: a mesh cuts across the creases where spheres meet and comes out a few percent short, by less on a finer grid. The integrated area does not depend on the grid and agrees with Zeo++ to within 1% on two zeolites. It is not given when Show leaves pieces out, and the solvent-excluded surface, not a union of spheres, has only the mesh’s. The surface covers whatever the viewer is drawing, so hiding a representation group hides its surface and marks the mesh stale. Cell applies a periodic scene’s cell: under it, the surface is that of everything in the cell, cut at the cell’s faces, so a slab shows its two faces and a framework its pores, and the row reports the area and the enclosed volume per cell. Being open, such a surface is drawn from both sides, so a slab’s far face shows when you look along the cell. Auto does this where the structure’s bonds run through the cell, and not for a molecular crystal or a protein whose cell only says how it packs. A surface cut at the cell has no closed pieces, so its space is sorted instead: a region closed within a cell is a cavity, and the row names the cavities, with their volume per cell, and the space that runs through the lattice as channels, layers or a network. For the solvent-excluded surface the space is sorted by where the probe’s centre can go, so two cages whose probe spheres meet in a window too narrow for the probe stay two cavities. On a trajectory the surface is computed for the frame the slider stops on: frames passed while dragging are shown without it, each frame computed is kept (the last 32), and stepping back to one draws it again at once. A surface is never drawn over atoms it was not computed for; an orbital’s isosurface likewise disappears while the atoms are elsewhere (another frame, a vibration being animated) and returns with them. Show chooses which pieces to draw: a buried void is a second closed shell wound the other way, and drawing only those is how to look inside without cutting. Colour by paints the nearest atom’s element, its partial charge, the electrostatic potential of the partial charges, or the hydrophobicity of the residue it belongs to. The potential is 332.0637 Σ qᵢ/rᵢ kcal/mol at each point, red negative and blue positive as in GaussView and ChimeraX, the convention the charge mode follows too; the row names the charges it used and the range the colours span (the 97th percentile of the magnitudes, by default), and Fixed range pins that range so two figures compare. It needs an isolated structure, since a lattice sum of point potentials needs an Ewald sum. Charge and potential need a scene carrying a population analysis, and the row says so if it falls back. Hydrophobicity offers both published scales — Kyte–Doolittle and Eisenberg — because they disagree about more than magnitude, and residues neither tabulates are drawn grey rather than given a number.
  • Multi-orbital workflow: check any combination of rows, click “Compute selected” once to render them all together. Each surface gets a color from a rotating ColorBrewer Set2 palette; user can override per row.
  • Per-row controls: isovalue (log-scale slider), positive/negative color pickers, optional negative contour for volumetric data, and opacity. Experimental and ordinary density maps start positive-only; orbitals and other signed fields retain both contours. Mesh-status badges show “cached” / “(will compute)” so stale meshes are obvious.
  • Drawing as a wireframe: every row’s Draw as also offers Wireframe: the surface’s triangle edges as one-pixel lines in its own colours (lobe colours, element or charge colours, or a colouring grid), so the atoms inside show through. It is the same mesh, so its isovalue and settings apply as for the filled surface. It travels with a session and a bundle; canonical export --wireframe and render --surface-wireframe record and draw it from the command line.
  • Drawing as points: every row’s Draw as offers Points. For an orbital, NBO, spin-density or volume row, that is a cloud of points scattered in proportion to the field instead of an isosurface: its square for an orbital, with the two phases in the two lobe colours, and its magnitude for a density. This is the textbook picture of where an electron is. The count is adjustable (20,000 by default), the isovalue does not apply, and the same cloud is drawn every time, so a figure reproduces. Each point’s size follows the spacing between points, so a cloud looks equally dense at its fitted view whatever the molecule’s size or the count. A scene orbital or an NBO is evaluated onto the grid orbitron cube writes. For a molecular surface, Points spreads the points evenly over the surface by area, each in the surface’s colour where it lies, which is PyMOL’s dot surface. The style travels with a session and a bundle; canonical export --dots and render --surface-dots record and draw it from the command line. A cloud coloured by another grid crowds its points at the nuclei, where a potential spikes, so it starts with a fixed range of ±0.05 (a potential cube’s usual atomic units) rather than one taken from the points.
  • Drawing as fog: an orbital, NBO, spin-density, promolecule or volume row’s Draw as also offers Fog: the whole grid drawn as a glowing fog, ray-marched on the GPU, rather than one isosurface of it. The fog is at full strength where the field’s magnitude reaches the row’s isovalue and fades below it, in proportion to the field for a density and to its square for an orbital (as a point cloud places its points), with the two signs in the two lobe colours. Lowering the isovalue thickens it. Opacity sets how much light it absorbs, per Ångström rather than per grid step, so the same settings look the same on a coarse grid and a fine one. Atoms inside the fog are seen through the fog in front of them. A molecular surface has no field behind it and does not offer fog, and fog has no surface to colour by another grid. The style travels with a bundle; canonical export --volume records it, and render and the web viewer draw it.
  • Promolecule density: every structure, a plain XYZ or PDB included, has a Promolecule density (free atoms) row: the free atoms’ densities from Slater’s rules, summed, in e/bohr³, drawn as points by default. It needs no wavefunction, so it is the electron cloud a structure file can show; it shows the molecule’s size and shape and none of its bonding, since free atoms are all it is made of. Each atom integrates to its atomic number. Subshells fill in Madelung order, so the few elements whose ground state breaks it (Cr, Cu, Pd among them) are drawn with the Madelung configuration. orbitron cube --promolecule writes the same grid.
  • Colouring by another grid: with two grids loaded, a volume row’s Colour by samples the other one at each point of its surface, red where it is negative, white at zero and blue where it is positive. A potential cube over a density isosurface at 0.001 au is the usual electrostatic-potential figure. The row reports the range the colours span in that grid’s units: by default the 97th percentile of the magnitudes on the surface, so a potential’s spike at a nucleus saturates rather than washing out the rest (which matters for a point cloud, whose points crowd the nuclei). Fixed range pins it. Points of the surface outside the colouring grid are grey. The colouring travels with a session and a bundle, and the CLI and the web viewer draw it too.
  • Local map clipping: when atoms are selected, a volume row offers Clip to selection with 4 Å default padding. The captured Cartesian bounds stay fixed while the live selection changes. Padding is adjustable from 0 to 20 Å; Update from selection captures a new region and Show full map removes it. The crop runs before the surface memory gate, decimation, and marching cubes, but after the full map has been parsed and retained.
  • Auto-rebind: toggling a row’s render checkbox after a mesh has been computed shows/hides it instantly without recomputing — cached meshes are kept until “Clear all surfaces”.
  • Mesh generation: marching cubes for cube datasets, basis-set sampling for FCHK/MO orbitals (uses the same convert_fchk_basis path the NBO mesh button used). Statistics (triangle counts, generation time) shown per row.
  • Volumetric data types recognized across CUBE, XSF, MRC2014, and CCP4 sources:
    • HOMO: Blue positive lobes (RGB: 0.20, 0.52, 0.94), orange negative lobes (RGB: 0.96, 0.40, 0.26), isovalue ±0.02 Å⁻³
    • LUMO: Green positive lobes, magenta negative lobes, isovalue ±0.02 Å⁻³
    • Spin Density: Red positive (alpha excess) lobes, blue negative (beta excess), isovalue ±0.001 Å⁻³
    • Density: Light gray positive, dark gray negative, isovalue ±1.0e-4 Å⁻³
    • Potential: Yellow positive, light blue negative, isovalue ±0.001 Å⁻³
    • Transition Density: TD-DFT excited-state densities; same controls as MO/Density.
    • Experimental Density: cryo-EM or crystallographic map density, positive-only by default at the header-derived recommended contour. Enable Negative contour for signed difference maps.

• Atom Coloring halo overlay (per-atom rim glow drawn on every atom; element colors stay intact): red rim = positive value, blue rim = negative, intensity proportional to magnitude. Magnitude ≠ 0 atoms get tinted at the silhouette so the sign and magnitude both read at a glance. Activate from the natural tab for whichever data you’re visualizing:

  • Charges tab → “Show as halo” buttons for every scheme the scene’s parser found: Mulliken, Löwdin, Natural (NBO), Hirshfeld, Atomic sphere, Bader, and APT. Where the population also carries spin density, a second button colours by the signed spin population instead, so a spin-polarised run reads as moment rather than charge.
  • Orbitals tab → “Show as halo” on any MO row colors atoms by their contribution to that orbital.
  • Surfaces tab → “Show as halo” on an NBO row colors atoms by NBO contribution (coefficients from the loaded archive).
  • Periodic → Band edges → “Halo VBM” / “Halo CBM” colors each atom by how much of that band-edge state sits on it (shown only when the run carries projections).
  • Halo appearance expander (collapsed by default at the bottom of any tab where a halo is active): positive/negative color pickers + max-opacity slider + range readout. Customize once and the colors persist across schemes.
  • Only one scheme is active at a time — picking a new one replaces the halo. Click the “Disable halo” button to clear.

• Charges tab lists every per-atom population the parser recovered, organized by scheme: Mulliken, Löwdin, Natural, Hirshfeld, Atomic sphere, Bader, and APT. Hirshfeld sits beside the basis-partitioned three deliberately: a plane-wave or very large basis run reports it instead of a meaningful Mulliken, and comparing the two is the useful reading. Atomic sphere and Bader arrive from a periodic run: atomic-sphere charges and moments from OUTCAR, Bader charges from an ACF.dat written beside it. Each block is a sortable table with charges, shell decomposition (when available), and a “Show as halo” / “Disable halo” button. Click an atom row to focus the camera; hover to highlight in the 3D view.

  • APT charges appear when Gaussian frequency jobs include them (derived from dipole derivatives — typically much larger magnitudes than Mulliken on the same atoms, e.g. APT(O) = −1.08 vs Mulliken(O) = −0.78 for water). Listed alongside the SCF charges, same “Show as halo” workflow.

• Computed bond orders appear below the population tables for Gaussian Wiberg, NWChem or ORCA Mayer, Molcas/OpenMolcas natural, and standalone NBO Wiberg results. They remain analysis data rather than replacing scene connectivity. Each table states whether the source supplied a complete pair matrix or only values above a print threshold, and keeps three-center terms separate.

• NBO tab (when an NBO archive is loaded — .47 plus .31–.46 companion files): lists orbitals per family (AO/NAO/NHO/NBO/NLMO/PNAO/PNHO/PNBO/PNLMO/MO) with occupancy and labels. The tab is read-only: mesh rendering and the halo overlay live in Surfaces, where each NBO row has its own Show as halo button and Compute selected builds the isosurfaces. Use the family filter there to narrow to one set.

• Slice (a section inside Surfaces, shown when the scene carries a basis set): a 2D real-space cross-section of a molecular orbital (signed), the electron density, or the spin density ρα − ρβ (signed, red where alpha is in excess), drawn as a contour heatmap on a plane through three picked atoms. Choose Orbital, Density or Spin density and, for an orbital, select the MO. The spin density needs an open-shell calculation; for a restricted open-shell one it is the density of the singly occupied orbitals. An open-shell scene also lists Spin density (ρα − ρβ) among the Surfaces tab’s scene orbitals: an isosurface at 0.002 e/bohr³ by default, red where alpha is in excess and blue where beta is. Then define the plane: selecting three atoms in the viewport is not enough on its own — press Set plane from selection (n), which counts the current selection in its label and enables at three or more. Until you do, the panel shows a hint and draws nothing. Clear plane beside it drops the plane again. The in-plane atoms and iso-contour lines are overlaid on the field, which re-evaluates only when the scene, plane, MO, or one of the settings changes.

  Three settings shape the picture: resolution (32–160 grid points per side — raise it for a publication crop, lower it while hunting for the right plane), padding Å (0.5–5.0, how far the plane extends past the three atoms), and, when contours is ticked, levels (1–12 iso-contour lines).

• Magnetism (appears when an OpenMolcas run carries a SINGLE_ANISO analysis): each pseudospin multiplet’s energy, g tensor, the angle of its main axis to the ground one and its main M_J, the ground multiplet’s crystal-field parameters, and the powder χT curve. orbitron analyze magnetism prints the same.

• Excited States (appears when the run carries a vertical excitation spectrum): the state table plus a broadened UV-Vis curve. Sources are Gaussian TD-DFT (per Link1 stage), NWChem’s TDDFT root table, Molcas RASSI (spin-free and spin-orbit), DIRAC relativistic response, and ORCA (TD-DFT/TDA singlets and triplets, EOM-CCSD, CASSCF and MRCI states). The Axis toggle switches between eV and nm, Envelope picks the broadening (Gaussian or Lorentzian) and FWHM its width, and the spectrum exports as PNG or CSV. A state links through to its Natural Transition Orbitals where the scene carries them, and says why when it cannot.

• Trajectory (labelled Optimization, Reaction Path, or Model Ensemble when the run says which it is): steps through the loaded frames. Prev / Next walk one at a time, TS and Min jump to the transition state and the minimum, and the energy of the current frame is shown beside them. Two blocks below that matter for periodic and MD data:

  • Periodic-boundary view — As stored leaves coordinates as the file wrote them, Whole molecules keeps each molecule intact across a cell face, and No-jump / unwrapped stops an atom teleporting when it crosses the boundary. Pick the last one before measuring diffusion; pick the middle one before looking at a solvated molecule. A no-jump frame depends on every frame before it, so stepping back, or jumping ahead of what has been shown, replays the frames from the first. Where that is estimated at over a second, from how long this view last took a frame, the replay runs in the background: the panel shows how many of the frames have been replayed and a Cancel seek button, the window stays live, and a frame asked for meanwhile is reached once the replay is done. Cancelling leaves the frame that was shown. While the slider is dragged the frame is held until it is released.
  • Centering / alignment — Center current selection holds your selection at the middle of the cell for every frame, and Fit to current frame removes rigid-body drift by aligning each frame onto the one on screen.

  The same tab carries an MD analysis plots collapsible: choose a frame range and which series to compute (RMSD against a reference frame, RMSF, radius of gyration, residue and interface contacts, hydrogen bonds, and your saved measurements), then Run analysis. It runs in the background with a progress bar and a Cancel analysis button, and the button reads Recompute once results exist. See GROMACS & MD.

• Periodic (any periodic run that produced them, not just VASP): band structure and density of states on a shared energy axis, with the band gap (value, direct/indirect, and the k-points it occurs at), band edges relative to E_F painted by what they are made of, and per-element/per-shell projected DOS: each curve plot pdos draws, ticked one at a time under Projected and kept within 15 eV of E_F. A run that gives discrete projected states rather than curves, as CP2K’s .pdos companions do, has them broadened as the CLI broadens them, the total DOS with them. High-symmetry corner labels come from the run’s own k-path input, such as a KPOINTS header comment for VASP, so a run without a line-mode path gets unlabelled corners rather than guesses. Each plot has a Pop out button, and PNG/CSV export for both the bands and the DOS. Open 3D k-space view… draws the exact first Brillouin zone of the calculation cell, folded samples, and boundary-split path runs, with SVG and PNG export.

  Two traps worth knowing, both of which produce a plausible-looking figure: a uniform mesh is not a k-path, and plotting one walks the points in grid storage order, which looks like a jagged band structure (the panel classifies mesh vs path and drops corner labels for a mesh). And high-energy PDOS is not trustworthy — the underlying numbers go unphysical far above E_F, so the figures window to E_F ± 15 eV.

• Charge / halo session persistence:

  • Surface row state, halo scheme + colors + opacity, and per-row settings save with sessions. Generated GPU meshes are rebuilt after load.
  • Loaded NBO archive metadata persists; coefficients re-read from the file paths recorded in the session.
  • Live volumetric grids and their contour, signed-contour, color, opacity, and visibility settings are embedded in the session. The original CUBE, XSF, MRC2014, or CCP4 file is not required to reopen the surface.

• Implementation references:

  • Atom Coloring scheme + halo state: core/appearance/src/halo_scheme.rs (AtomColorScheme)
  • Population parsers: io/pipelines/src/formats/{nwchem,gaussian,molcas,molpro}/...
  • Halo overlay shader path: core/render/src/renderer/shaders/atom.wgsl (search for halo.a > 0.0001)
  • MO contribution math: core/appearance/src/halo_values.rs::signed_contributions_for_mo
  • NBO contribution math: io/pipelines/src/formats/nbo/nbo/workspace/coefficients.rs::signed_atom_contributions_for
  • Surfaces panel: ui/shell/src/panels/analysis/surfaces_tab/mod.rs
  • Halo appearance helper: ui/shell/src/panels/analysis/halo_appearance.rs
  • CUBE parsing: io/pipelines/src/formats/cube/data_structures.rs (CubeDataType enum)
  • Spin density detection: io/pipelines/src/formats/cube/metadata.rs (filename/title parsing)

The focused cross-frontend reference is Analysis Results. - Annotations: Add text labels and arrows as a scene overlay for presentations, documentation, or highlighting features of interest. Annotations are managed in the rail’s Scene section, directly below the scene-info card and above the properties and sequence content: they are the interactive controls in that section, so they sit ahead of the properties and residue listings. - Creating Annotations: - Click + Text to add a text label at the center of the viewport (default: “Label”) - Click + Arrow to add an arrow from left to right (horizontal by default) - Click + Leader to add a label joined by a plain line to the thing it names. A leader is not an arrow: an arrow says “look that way” and a leader says “this word names that thing”, so it ends in a short tick rather than a head. Its editor names the ends Points at and Label rather than head and tail, and the line leaves the edge of the text rather than its centre, so it never runs through the word. Anchor Points at to an atom or a selection centroid and it follows the camera. - Click + Measurement to caption a distance, angle or dihedral that the viewer reads from the structure rather than one you type. Take the measurement first (Measure in the toolbar); the button binds to the most recent one and the editor’s Reads picker changes which. Its text field becomes a prefix, so “Zn-His94” plus the live value reads as one caption. The number is recomputed from the frame being drawn, so it follows a trajectory, an edit or a superposition, and an endpoint that is not currently drawn produces no caption at all rather than a value from an atom the reader cannot see. Same reasoning as the scale bar: a caption that says 2.05 Å beside a bond of some other length is the one way a measurement label can lie, and not letting anyone type the number is the only way to prevent it. - Click + Box to mark a region: a rectangle with a light wash inside it, for an inset boundary, a binding pocket, or the part of a figure a panel enlarges. Its two anchors are opposite corners, and either can be pinned to an atom or a selection centroid — anchor both to atoms and the box tracks the pocket as the camera turns, anchor both to the screen and it stays put on the glass. The wash keeps a fraction of the item’s own colour and alpha, so the structure stays readable through it. - Click + Circle for an ellipse drawn in the box between two corners, washed and outlined as a box is: a metal centre, a ring, a pocket. Its corners anchor like a box’s, so the two can change kind and keep them. - Click + Bracket for a square bracket from one end to the other, its arms turned to the left of that direction as you look at the screen (drawn downwards it is ]), with an optional Label on its open side: these residues, this chain, this ligand. Swap its ends to turn it round. - Click + Highlight for a translucent band with no outline, a marker pen over the part of the figure a sentence is about. It is washed more strongly than a box, since the wash is all it has. - Click + Scale bar to add a bar of known length with the distance written on it. Its length and label are measured from the camera each frame, not typed: there is no text field, because a bar that says “10 Å” while being some other length is the one way a scale bar can lie. The bar picks a round number — 1, 2 or 5 times a power of ten — that fits a fifth of the viewport, so it changes as you zoom.

  ::: {.callout-warning}
  ## A scale bar in a perspective view is only true at one depth
  Under a perspective projection, things nearer the camera cover more
  pixels per Ångström than things further away, so no single bar can be
  true for the whole picture. Orbitron measures at the point the camera
  looks at — the scene centre for a fitted camera — which is the best
  single answer, not a complete one.

  For a figure that carries a scale bar, switch to **orthographic** under
  *Appearance → Camera*. There the scale is constant and the bar is true
  everywhere in the frame.
  :::
- New annotations are automatically selected and visible
- With no annotations the section is just its heading and the nine add buttons (**+ Measurement** stays disabled until a measurement exists); the rest of the controls appear once there is something to control

• Annotation Mode:

  • Toggle Annotation mode checkbox to enable direct manipulation in the viewport
  • When active, a “Annotation mode” indicator appears in the bottom-right corner of the viewport
  • Text labels: Click and drag the text to reposition it anywhere on screen
  • Arrows: Click and drag the start or end handle (white squares with stroke) to adjust arrow position and direction
  • Click any annotation in the viewport to select it (updates the panel’s “Selected” section)
  • A dragged end snaps to the vertical and horizontal lines through every other annotation’s ends and through the viewport’s centre when it comes within six points of one, each axis on its own, and a blue guide shows the line while you hold it. Hold Alt to drag freely
  • Handles are drawn 7 to 9 points across, and grab four points beyond what is drawn
  • Dragging a screen-anchored annotation moves it outright; dragging an anchored one moves its offset, so it keeps following the atom it names

• Anchoring — the difference between an annotation and a caption:

  • By default an annotation sits in normalized viewport coordinates (0.0–1.0). That is right for a caption in the corner: it stays put when the camera moves, and keeps its relative place when the window is resized.
  • It is wrong for anything that points at something. A spot on the glass does not rotate with the molecule, so an arrow aimed at a binding pocket ends up over the wrong helix as soon as you turn the structure, and the figure is wrong in a way that still looks fine.
  • Select the atoms it should name, then set the anchor picker in the Selected section. Four choices:
    • screen — fixed to the viewport, where it is now. This is the default and the right one for a caption. Choosing it from one of the others drops the anchor and leaves the annotation where it currently appears, rather than teleporting it back to the middle.
    • selected atom — follows the first selected atom, projected through the camera each frame, so it survives a rotation, a zoom, a pan, and a trajectory frame.
    • centre of selected atoms — follows the centre of the selected atoms, a residue or a ligand, through a rotation and a trajectory frame alike: the mean of those of them that are drawn, and nothing at all when none is.
    • centre of selection, fixed — a fixed point in the scene at the centre of the selected atoms, for a pocket or the mouth of a channel: a place rather than a set of atoms, so it follows the camera but not a trajectory.
  • A text label has one endpoint and so one Anchor row. An arrow has two, and they anchor independently: Head is the end that points at something and is usually the one to anchor, Tail is where the arrow comes from and is often better left on the glass, off to one side of the figure.
  • An anchored annotation whose atom is not drawn — hidden by a representation group, or absent from the current frame — draws nothing rather than being parked at a default position. Exports behave the same way.

• Layer Management:

  • The Layers list shows all annotations with type labels:
    • Text annotations show: "Text: <content>" (or just "Text" if empty)
    • Arrow annotations show: "Arrow"
    • Leader annotations show: "Leader: <content>" (or just "Leader" if empty)
    • Measurement annotations show: "Measurement: <prefix>" (or just "Measurement")
    • Box, circle, highlight and scale-bar annotations show: "Box", "Circle", "Highlight" and "Scale bar"; a bracket shows "Bracket: <label>"
  • The list is the drawing order, first at the bottom, in the viewport, an exported image and a saved session: ⏶ draws an annotation over the next one and ⏷ under the previous one
  • Checkbox next to each layer toggles visibility (hidden annotations are not rendered)
  • Click a layer name to select it for editing
  • Remove button deletes the annotation from the scene

• Editing Selected Annotation:

  • The Selected section appears below the layer list when an annotation is selected
  • Text annotations:
    • Text field: Edit the label content (single-line text input)
    • Font: Choose Sans (proportional) or Mono (monospace)
  • Arrow annotations:
    • Label shows “Arrow” (no editable text content)
  • Anchor rows: one Anchor row for text; Head and Tail rows for an arrow. Each is a picker offering the four anchors described below, screen, selected atom, centre of selected atoms and centre of selection, fixed; all but screen are enabled once atoms are selected
  • Common properties (both types):
    • Size: 8.0–36.0 points (font size for text, arrow thickness/head size for arrows)
    • Boldness: 0.6–2.0 multiplier (values >1.0 apply multi-pass rendering offsets for boldness effect)
    • Color: RGBA color picker (default: orange [0.91, 0.55, 0.28, 1.0])

• Rendering Details:

  • A text or leader label may span several lines: press Return in the text field. The viewport and the raster exporter both break the line and centre the block on the anchor. The web export does not — its text shaper walks characters and has no notion of a line — so a multi-line caption arrives there as one line with the break read as a space, which is a readable degradation rather than a stray glyph.
  • Annotations render as an egui overlay on top of the 3D viewport (ui/shell/src/viewer_loop/annotation_overlay.rs)
  • Text labels are centered on their anchor point
  • Arrows draw a line segment with an arrowhead at the end point
  • Arrow thickness scales with size: (size × 0.12) × boldness, clamped to 1.0–3.0 pixels
  • Arrowhead size is size × 0.7
  • Boldness for text >1.05 renders the text multiple times with pixel offsets for a thicker appearance

• Export Integration:

  • Annotations are included in export previews and final image exports
  • Use annotations to label molecular features, highlight bond angles, or add captions for publication figures
  • Annotations persist in saved sessions (serialized with AnnotationState)

• Typical Workflow:

  1. Add one or more text/arrow annotations
  2. Enable Annotation mode
  3. Drag annotations to desired positions in the viewport
  4. For anything that points at the structure, select the atom or residue it names and set its anchor to selected atom or centre of selected atoms, then pose the camera — the annotation travels with it
  5. Select each annotation and customize text, color, size, and boldness in the panel
  6. Toggle visibility checkboxes to show/hide specific layers
  7. Disable Annotation mode when done positioning
  8. Export the image with annotations included

• VASP: VASP has no view of its own. What is genuinely VASP-specific is under VASP run data in Sources: an Attachments ledger of the companion files Orbitron has parsed and any recent warnings from the run. Its forces are in Overview, under Forces → VASP final step (any run with OUTCAR or vasprun.xml forces): per-atom arrows render as a shaft with a tapered head, colored teal → orange by |F| magnitude. Lengths are relative, the same rule the QMCPACK force overlay uses: the largest force in the run draws at about one bond and the rest in proportion, so the arrows stay visible whether the geometry is fresh or nearly converged. The Scale (×) drag-value multiplies that, and Arrow appearance sets thickness and an optional colour override — turning the override on replaces the magnitude ramp with a flat colour, which is a trade of the magnitude cue for a figure-ready one. Useful for diagnosing relaxation hotspots.

  The rest moved to the tabs that hold it for every package. Band structure, density of states, the band gap and the band-edge halos are in Periodic; the per-atom scalars (atomic-sphere charge and magnetic moment from OUTCAR, Bader charges from a sibling ACF.dat) are population analyses and sit in the Charges tab beside Mulliken and the rest.

• Periodic bonds and boundary: Appearance → Crystal / Unit Cell → Periodic Bonds controls what a crystal shows of its surroundings.

  • Show periodic bonds — bonds that leave a cell face and connect to the neighbouring image, drawn translucent so they read differently from in-cell bonds. On by default, because a crystal that hides them looks like a handful of disconnected fragments: every atom near a face is missing neighbours that are physically there. Each one also draws the atom it lands on, faded, so the bond ends on a neighbour rather than in empty space — a cell’s worth of dashes stopping at nothing reads as a broken structure rather than as a continuing lattice. It draws nothing for a scene with no unit cell, so it costs a molecule nothing. This is also what the geometry commands refuse over (§3.7.4), so leaving it on means the bonds they name are ones you can see.

  • Image atom opacity — how faint the atom each cross-face bond lands on is drawn. There was a Show periodic image atoms (ghosts) checkbox here until 2026-09-12 that replicated every atom into all 26 surrounding cells; it connected none of them, so it read as a haze around the cell rather than as more crystal, and it multiplied the drawn atoms by 27 — enough that switching it on needed a capacity confirmation. Boundary does that job and draws the bonds, so only the opacity survives.

  • Whole molecules: draw each molecule whole rather than wrapped into the cell. Only the drawing moves; coordinates, analyses and exports keep the file’s, and an extended solid is always drawn as stored.

  • Reset boundary: appears once the boundary differs from the default, and puts it back to 0 to 1 on every axis.

  The periodic-bond, image-atom and boundary settings are display only. None of them changes the scene’s own bond list, its formula, or what gets exported — a crystal’s bonds() is not periodic, and cannot be, because a bond record has nowhere to put a lattice image.

• The rest of Crystal / Unit Cell. The panel has ten framed groups, each under its own heading and none collapsible; Crystal Projection (§3.5.8) and Periodic Bonds above are two of them. The other eight are figure controls for a crystal. Boundary and Show only asymmetric unit, described below, are not groups of their own: they sit inside Periodic Bonds, with Image atom opacity.

  • Edge Appearance — line style and weight for the cell box, in the viewport and in exports.

  • Hidden Edges — dim or dash the back-facing edges of the box, which is what makes a cell read as a box rather than a cage in a publication figure.

  • Axis Labels — coloured a/b/c arrows at the cell origin, red/green/blue per the VESTA convention.

  • Miller Plane (hkl) — outlines the (hkl) lattice plane through the origin and reports its d-spacing. Use it to check a slab orientation before cleaving one (§3.6, Edit → Cell).

  • Origin & Grid — an origin cross-hair and a reference grid inside the cell.

  • Reciprocal Lattice — the b₁/b₂/b₃ basis and its primitive cell, scaled to sit inside the real-space cell so the two can be compared in one picture.

  • Boundary — how much of the lattice to draw, as a fractional range per axis. 0 to 1 is the cell the file gives, 0 to 2 along a is two cells of it, and -0.5 to 1.5 is a cell with half of each neighbour either side. Fractional rather than a replication count because half a cell is a thing you want to show and an integer cannot say it; a range narrower than the cell drops what it excludes, which an integer cannot say either.

    This draws, it does not edit. Edit → Cell → Supercell… rewrites the scene — new atoms, a new cell, an undo entry — which is what you want before a calculation. A boundary costs nothing to undo and leaves the structure alone.

    The cells it adds are bonded, to each other as well as internally: a contact that leaves a cell face becomes an ordinary bond once the neighbour is drawn, rather than a dash into empty space. That is what separates a boundary from the periodic-image replication it replaced, which drew atoms and connected none of them. The replicas are images, so picking and measurement skip them, and only the primary cell stays selectable.

    The range is half open — the low bound is included and the high one is not — so an atom on a cell face is drawn once rather than once per touching cell, and 0 to 1 is exactly the scene you started with.

    Reset View frames the range rather than the cell, so widening it and refitting shows the whole block. A very large range is capped rather than refused: ten cells on three axes is a thousand of them, past what the browser will render at all, so the figure comes back smaller than asked instead of not at all.

  • Show only asymmetric unit — draw the atoms the file states and hide the copies symmetry generated to fill the cell. A CIF gives an asymmetric unit and the operations that expand it; spinel’s three lines become fifty-six atoms, and this shows the three. Off by default, because the filled cell is what the structure is. The checkbox appears only for a structure that was actually expanded — a P1 cell or an XYZ file has no copies to hide.

    The mark is a per-atom property carrying the index of the operation that made each copy, so it is also reachable from the selection language: property("cif:symmetry_image") > 0.5 is everything symmetry added, and not property("cif:symmetry_image") > 0.5 is the asymmetric unit. Selecting one index singles out a particular image.

  • Thermal Ellipsoids — each atom’s anisotropic displacement drawn as the surface it lies inside with the chosen Probability (50% is the published default), with its three Principal ellipses. An isotropic atom other than hydrogen becomes the sphere its U_iso describes. The tensors come from a CIF’s _atom_site_aniso_U (or _B) loop, an mmCIF’s _atom_site_anisotrop, or a PDB file’s ANISOU records; a CIF’s crystal-axis values are converted to Cartesian on reading and rotated onto every symmetry copy. A tensor that is not positive definite is a refinement fault rather than a shape, and the section counts those atoms and leaves them as spheres.

  • Coordination Polyhedra — solid shaded polyhedra around the cations of a structure, built as the convex hull of each coordination sphere and drawn with its edges outlined. The colour and opacity are Polyhedron colour; translucency is what lets the atoms inside show through and what keeps a stack of octahedra legible.

    Which atoms get one is decided by electronegativity: an atom is a centre when every one of its neighbours is more electronegative than it is, which is what makes it the cation of a coordination sphere. That gets magnesium and aluminium in spinel and silicon in a silicate, and leaves the oxygens as corners in both. An element among its own kind is not a centre, so a covalent network like diamond draws nothing. Set Centres (it reads all cations while empty) to a selection expression — element Al, element Al or element Mg — to choose them yourself instead.

    Until 2026-09-12 this joined every pair of neighbours rather than computing a hull, so an octahedron carried fifteen edges instead of twelve with three of them running through the middle of the solid, and the neighbour-count threshold made a centre of every oxygen as well. A spinel cell came out as a thicket of wires spanning the box rather than a framework of octahedra.

• VASP cell + structure tools: Beyond the panels, several VASP-relevant edit commands live under Edit → Cell (require Edit mode):

  • Convert to conventional cell — for centred Bravais types (cF/cI/oF/oI/tI/hR), expands the primitive cell to the standard conventional one. For example, an FCC POSCAR with 1 Si in a 60° rhombohedral primitive becomes 4 Si in a 3.9 Å cubic cell.
  • Cleave (hkl) slab… — h/k/l + fractional thickness + vacuum (Å) + search range. Re-orients the cell so two lattice vectors lie in the (hkl) plane and the third is perpendicular, replicates atoms across the slab, and pads with vacuum. Useful for surface-science prep.
  • Cleave slab… — the simpler neighbour of the above: cut perpendicular to a chosen cell axis, with a fractional thickness and vacuum, when the surface you want is already a cell face.
  • Apply symmetry… — paste one symmetry operation per line, in fractional coordinates, then Expand asymmetric unit, Reduce to asymmetric unit (the inverse, for cleaning up a P1-expanded CIF), or Expand selection by symmetry. Expansion drops bonds; re-run inference afterwards.
  • Find primitive cell, Supercell…, Cell parameters…, Niggli reduce…, Wrap atoms to cell — general crystallographic edit operations that work for any periodic scene.

• VASP volumetric data: Click Load on the CHGCAR / CHG / PARCHG row in Sources to register the volumetric grid as an isosurface dataset and switch to the Surfaces tab. Spin-polarized runs split into two datasets (<file> total and <file> spin density (↑−↓)), each renderable as an independent isosurface with its own isovalue and colors.

• VASP trajectories: Click Load on the XDATCAR row to ingest the multi-frame MD/relaxation trajectory and unlock the frame slider. Constant-cell MD writes one header at the head of the file; a variable-cell run repeats the full header before a later configuration, and Orbitron retains that lattice for the frames that follow it.

• Fragments: When edit mode is active, you can attach pre-built molecular fragments from the built-in library. See §3.7.9 for detailed workflow.

3.7 Edit mode

Edit mode turns the viewer into a molecular builder. Toggle it with Ctrl+E or the toolbar’s View/Edit switch: the selection outline turns orange, the toolbar swaps its view controls for building tools, and the left rail’s sections change to Geometry, Measurements, Appearance, and Scene.

Every edit goes on an undo stack (Ctrl+Z / Ctrl+Shift+Z, or the toolbar’s Undo (n) / Redo (n) buttons, which show the stack depth). Revert reloads the original file. Leaving edit mode opens a commit/discard/cancel dialog rather than deciding for you.

Undo history retains at most 100 commands and 512 MiB of command snapshots. Ordinary atom and bond edits usually retain only small identifiers and values; whole-cell transforms may retain a complete pre-edit scene. If either limit removes older entries, the edit-status strip reports the exact number of undo steps that are no longer available. Those edits remain unsaved and are still included when you Commit or Discard the edit session.

Before a full-scene cell edit starts, Orbitron estimates the additional memory needed for the published scene, the new undo record, and the command’s peak working buffers. This applies to supercells, symmetry expansion and reduction, cell-basis changes, slab cleaving, cell-parameter changes, and wrap-to-cell. A tight estimate opens the same resource confirmation used for other heavy operations. Existing undo history is already resident and is reflected in the available-memory reading, so it is not charged a second time.

Analysis belongs to the geometry it was computed for

Once a loaded structure has been edited, the toolbar shows an Orig / Edited pair. Orbitals, charges, and every other analysis quantity were computed for the geometry in the file, so they are only valid on Orig. Edited shows your structure; the analysis overlays on it are stale by construction. The two views share one scene — switching does not lose your edits.

Building from nothing works too: File → New Session (or the welcome card’s New) gives an empty scene, and Add Atom places the first atom without needing a selection it could not have.

3.7.1 The edit toolbar

The toolbar in edit mode with two atoms selected: the View and Edit switch, Select and Measure, Place Atom, Fragment, the element chooser, Thaw, Element, Bond, Charge and Delete, the Click, Box and Lasso row with the selection count and Clear, and the Original and Edited switch with Undo and Redo and their depths

Figure 5: Edit mode with two atoms selected and one edit made, a freeze, so that button now reads Thaw and Undo shows a depth of 1. The selection is what enables Bond and Charge. The controls are described in the table below.

With edit mode active the toolbar carries, left to right:

Control	What it does
Place Atom	Toggles click-to-place. Click in the viewport to drop what the chooser is set to; stays armed until you click it again or press Esc.
Fragment / Fragment ▾	Toggles fragment placement, and picks which fragment (§3.7.9).
Chooser (C ▾, C·tet ▾, ring C6 ▾)	Opens the placement dialog — element, shape, ring size, attachment site (§3.7.2). The button label tells you what a click will drop.
Freeze / Thaw	Holds the selected atoms in place, or releases them (§3.7.3).
Element…	Changes the element of the selected atoms (§3.7.10).
Bond ▾	Between exactly two selected atoms: Single, Double, Triple, Aromatic, Remove bond.
Charge ▾	Formal charge on the selected atoms, +3 through −3 (§3.7.5).
Delete	Deletes the selected atoms.
Undo (n) / Redo (n) / Revert	Edit history, with stack depths.
Orig / Edited	Which geometry to draw, once the scene has been edited.

The selection tools (Click / Box / Lasso), the selection count, and Clear stay where they are in view mode. Shift+S cycles the selection tool.

Freeze sits between the chooser and Element…, deliberately away from Delete — the two are one misclick apart in intent and very far apart in consequence.

3.7.2 Placing atoms, shapes, and rings

Place Atom does not only place atoms. The chooser button beside it opens a dialog with three exclusive choices for what a viewport click drops:

• single atom — one atom of the chosen element, the classic behaviour.
• A shape — that element as a centre, capped with hydrogens on one of nine geometries: linear, bent, trigonal planar, pyramidal, tetrahedral, square planar, trigonal bipyramidal, square pyramidal, octahedral. Clicking empty space drops the whole capped centre.
• A ring — cyclo-C₃ through cyclo-C₈, as carbon with its hydrogens.

Rings are generated, not transcribed from a coordinate table: a regular polygon whose edge is one bond, puckered, capped, and then run through the same solver Clean Geometry uses. A placed C₆ therefore comes out as chair cyclohexane (the symmetry panel reads D₃d, where a flat hexagon would read D₆h). Rings are carbon-only — change elements afterwards.

Growing in place of a hydrogen. With a shape armed, clicking an existing hydrogen replaces that cap with the new centre rather than dropping a molecule in front of it. The new group is staggered against the anchor’s existing substituents, so growing carbon twice from methane gives you staggered ethane (D₃d) and then propane (C₂ᵥ). Only hydrogens qualify: clicking a heavy atom could mean bond-to, replace, or place-past, and guessing between those is how a builder stops being predictable.

Choosing the attachment site. For the two five-coordinate shapes the vertices are not equivalent, so the dialog adds a Grow onto its: row — equatorial or axial for trigonal bipyramidal, basal or apical for square pyramidal. Every other shape here has a point group that acts transitively on its vertices (a tetrahedron’s four positions are one position), so no choice is offered. The row only affects growing onto an existing atom; placing on empty space spends no position.

3.7.3 Freezing atoms

Frozen is orthogonal to selection: the selection says what a command acts on, frozen says what may never move. Every geometry command below respects it.

• Freeze / Thaw in the toolbar act on the selection. The button reads Thaw only when every selected atom is already frozen, so a mixed selection offers to freeze the rest.
• Edit → Freeze Selected / Thaw Selected / Thaw All do the same from the menu. Thaw All also releases atoms that arrived frozen from a file.
• Frozen atoms carry a cyan rim while edit mode is active. It overrides an analysis halo where they collide, and disappears in view mode so a structure being read is not repainted by a flag from its file.
• The rail’s Scene section shows a Frozen: count, because the halo only tells you about atoms currently on screen.

Frozen state survives export where the format can carry it: File → Export → Export POSCAR… writes frozen atoms out as VASP Selective dynamics F F F.

3.7.4 The four geometry commands

They are genuinely different operations, and picking the wrong one is the most common way to damage a structure.

Command	What it does	When
Fix Geometry	Clean, then Relax, in that order.	You have not yet had to learn the difference between the two, and just want the structure fixed.
Relax Geometry	Settles the structure under the UFF force field. Entrenches whatever geometry is there — it finds the nearest local minimum.	A structure that is roughly right and needs tidying; anything where torsions matter.
Clean Geometry	Moves the structure onto what the connectivity implies — angles, coordination spheres, point group — while keeping the conformer. Does not touch torsions, except to flatten a double bond outside a ring, cis or trans as it already is.	A drawn or hand-built sketch whose angles are wrong.
Symmetrize Geometry	Snaps atoms onto the detected point group, and offers the groups reachable at a looser tolerance. It is offered once the Scene section has run point-group detection; until then the menu entry is greyed out.	A nearly-symmetric structure you want exactly symmetric. It fixes symmetry, not angles.

A chloromethane drawn flat by hand, with H-C-Cl angles near 80 degrees, shown as the input and after Clean, Relax and Symmetrize, all from the same camera

Figure 6: One input, three commands. Clean and Relax both bring the carbon to a tetrahedral centre on this small molecule: Clean from what the bonding implies, keeping the drawn conformer, and Relax by minimising the UFF energy. Symmetrize onto C_3v makes the sketch exactly symmetric and leaves the flattened pyramid as it was: it settles symmetry, not angles.

Fix Geometry (Edit → Fix Geometry, or Fix Geometry (Selected) with a selection) is the entry that does not require knowing which of Clean and Relax repairs and which entrenches. It runs Clean and then Relax: the repair first, against what the bonding implies, and the settle afterwards. Running them the other way round settles the structure into whatever shape it arrived with, which is why the order is fixed rather than offered.

Relax Geometry (Edit → Relax Geometry) offers Relax Selected and Relax All, with iteration counts in the same submenu (default 12 for a selection, 20 for the whole scene). It runs all five UFF terms — bond stretch, angle bend, torsion, inversion, van der Waals — from orbitron-forcefield. For a periodic scene, every term carries its lattice image and the cell remains fixed. By default each metal whose coordination sphere is its own is held with its donors while the rest settles, including each metal in its own pocket of a ligand that holds two; metals that share a bridging donor are not. Allow metal coordination spheres to move is an explicit override: leave it off for a frozen slab and movable adsorbate; turn it on only when UFF’s approximate periodic metal or ionic framework geometry is the intended result.

Relax is periodic; Clean is not

Relax uses a fixed-cell periodic UFF system. It includes cross-face and self-image bonds, periodic atom typing, image-specific bonded exclusions and van der Waals image shells. Frozen atoms and selection scope keep their usual meaning. A singular cell is refused explicitly.

UFF remains an approximate force field. Orbitron therefore refuses to move a periodic metal or ionic framework by default. Freeze the framework to relax an adsorbate, or enable Allow metal coordination spheres to move as an explicit scientific override.

Clean still reasons from the scene’s ordinary connection table, which has no lattice-image field. It refuses when an atom it would move is bonded through a face. A molecule in a vacuum box and a repair away from a frozen periodic fragment continue normally.

How accurate are these, and how is that known?

Every figure below comes from comparing against something Orbitron had no hand in: experimental aqua-ion distances, Alvarez’s published shape measures, or tmQM — 108,541 transition-metal complexes taken from the Cambridge Structural Database and optimised at TPSSh. That matters more than the numbers themselves. A geometry tool checked only against its own conventions will agree with itself however wrong it is.

Metal–donor distances are the best-supported part. The table Clean and the coordination-sphere builder place donors at is Shannon ionic radii plus measured donor radii, and it sits within 0.033 Å of experimental aqua-ion distances across fourteen ions. Use it as the reference it is. The halide radii were fitted on the CSD’s terminal metal–halide contacts, and built metal–halide bonds land a median 0.033 Å from the CSD median over the 80 metal, state, coordination-number and halide groups of at least 10 contacts from 3 entries. That is the fit’s own data, not a held-out check. A mercury(II) halide takes mercury’s two-coordinate radius at any coordination number, since the heavier halides do not follow Shannon’s steps for it.

Nitrogen’s radius was refitted on crystals in the same way, and it depends on the metal: 1.43 Å on groups 4 to 12 and 1.48 Å on everything else, group 3, the f block, the main group and the s block included. One value could not serve both: the single 1.45 used until 2026-10-20 built the d block long and the rest short, and the earlier 1.55, from GFN2-xTB complexes whose nitrogens were mostly tertiary amines, placed N donors 0.05 to 0.15 Å long by block. Fitted and held out by element, the split takes the median M–N error per CSD contact from 0.070 to 0.061 Å. Two known costs: nitrogen on a d-block ion at +4 or above is placed about 0.02 Å shorter where it was already short (on an oxo centre it has its own floor, below), and Tl(I)–N is placed long because Shannon has no Tl(I) radius below six-coordinate. The builder places each donor at its own element’s distance, a chelate’s included; until 2026-10-19 it placed every donor of a ligand at the ligand’s mean, which pulled the nitrogen of a mixed N/O chelate inside its template. Nitrogen is not told apart by donor class: tertiary amines sit about 0.07 Å beyond a pyridine on the same ion, and a separate radius for them was measured and held. Sulfur splits at the same boundary, 1.70 Å on groups 4 to 12 and 1.79 Å elsewhere: the single 1.79, fitted on GFN2-xTB complexes, built d-block sulfur about 0.09 Å long, and held out by element the split takes the median M–S error per CSD contact from 0.106 to 0.051 Å. A sulfur that is not bonded to the metal, such as a chelating sulfonate’s, is still kept out at the 1.79 distance, and the crystals put it beyond that. One class of sulfur is told apart by its bonds: an S-bound sulfoxide (a sulfur with three neighbours, one of them oxygen, as in DMSO) sits 0.09 Å nearer the metal than other sulfur, as its crystals do. And two ions take their own sulfur distance: mercury(II)’s and silver(I)’s sulfurs sit 0.14 and 0.12 Å nearer than the sum. The equatorial donors of a uranyl or another actinyl sit 0.25 Å beyond the plain sum, because the actinide’s Shannon radius averages in the two short M=O bonds.

Coordination templates hold at every coordination number. Snapping a real crystal structure’s donors onto Orbitron’s nearest reference polyhedron moves the angles by a median 0.155 rad over 34,960 sites, 87% of them inside 0.3 rad and 98% inside 0.5, and the figure is flat from four-coordinate through twelve. An earlier reading of the same data suggested templates fell apart above eight; that was η⁵ and η⁶ ring carbons counted as separate donors, and it is why a ring bound through its face now counts as the one site it occupies. A ferrocene reads as two-coordinate rather than ten, which is what it is.

Relax is UFF, and UFF is crude at a metal. Settling 1,387 high-coordinate crystal structures moves metal–donor distances a median 0.134 Å and the sphere angles 0.197 rad. UFF’s metal–donor equilibrium runs about 0.14 Å short of the distance table above, and it has almost no angular preference at a metal, so donors hold their distance and slide. This is why Relax refuses a periodic metal framework without an explicit override, and why a coordination sphere that matters should be checked rather than assumed after relaxing. Where a metal’s oxidation state is set, Relax and Clean hold an oxo group at the measured M=O length rather than a donor distance, whether it is drawn as a double bond or is an oxygen bonded to the metal alone at an oxo distance: a uranyl’s U=O was relaxing to 2.08 Å and a vanadyl’s V=O to 1.88, and Clean was setting U=O to 2.15. On an oxo centre the builder, Relax and Clean hold every other donor no closer than the CSD’s median single bond to oxygen on that element’s oxo complexes, shifted by the donor’s radius less oxygen’s, and a nitrogen at the CSD’s median cis N there, which sits 0.12 to 0.23 Å beyond the oxygen rather than the 0.09 the radii give. A donor trans to an oxo group sits further out by the oxo’s trans influence, measured per element on the CSD: a nitrogen 0.14 to 0.21 Å, an oxygen up to 0.41 on vanadium.

Adding the UFF4MOF extension, which supplies the eight-coordinate types Rappé’s table lacks for every lanthanide and for uranium, was measured making this slightly worse — 0.144 Å against 0.134 — so Orbitron carries those parameters and does not assign them. It does assign UFF4MOF’s square-planar copper: Rappé’s only copper is tetrahedral, and a square-planar Cu(II) relaxed with it twisted toward a tetrahedron (a median 0.53 rad of angle drift over 28 crystal structures, 0.07 with the square-planar type). See core/forcefield/src/uff4mof.rs.

What the repair is and is not for. Forty rebuilt complexes and their originals were optimised at GFN2-xTB from both starting points. On energy it is a coin flip — 18 against 15 with a median difference of 0.03 kcal/mol — and the original converges in fewer cycles, 68 against 98, because it was made with a related force field and starts nearer the answer. The two never reach the same minimum: 5.2 Å apart on average, and not one pair of forty inside 0.5 Å.

So repairing a coordination sphere does not give an optimiser a better place to start; it gives it a different one. What the repair is for is the class of problem an energy comparison cannot see, because both structures in it are already chemically valid: an atom collapsed inside the metal, a carboxylate protonated into a carboxylic acid, a donor that never reached the metal. Those make a calculation wrong rather than slow. Full method and caveats in notes/archive/xtb-starting-geometry-validation.md.

A clean coordination sphere means recognisable, not correct

The sphere verdicts — clean, drifted, no clear match — measure how far a sphere sits from a reference polyhedron. Real spheres sit 0.13 to 0.29 rad from one even when they are perfectly good, so clean is a statement about shape and not about correctness. A structure can be called clean and still have a donor at the wrong distance, and 8% of real crystal spheres match no reference shape closely enough to snap to at all.

For the same reason, the shape measure is no use as a self-check on a built sphere: the builder places donors on a polyhedron’s vertices, so scoring the result against that polyhedron restates the construction. Distances and ligand-bond lengths are the checks that carry information there.

Clean Geometry (Edit → Clean Geometry) offers Clean Selected (the selected metals’ coordination spheres) and Clean All (the whole scene, then a point-group fit). Which repairs it is allowed to make are checkboxes in the same submenu, because “clean” means different things on a sketch and on a converged structure:

Checkbox	Default	What it does
Bond angles, from bond orders	on	Pulls every angle onto what its bonding implies, keeping the conformer and every bond length. Rings pucker rather than unravel.
… and bond lengths, from covalent radii	off	Corrects lengths in the same solve. Off because a covalent radius is a worse number than a converged bond length.
Coordination spheres	on	Moves each metal’s donors onto its best-fitting shape, keeping bond lengths. A frozen donor holds the whole sphere.
… and metal–oxygen distances	off	Sets each M–O distance to the Shannon ionic radius + 1.40 Å. Metals with no tabulated oxidation state, and non-oxygen donors, are left alone and reported.
Fit to point group	on	Runs last, on the already-repaired coordinates. Whole scene only, and skipped when any atom is frozen.

A flat ring is a symmetric saddle point — the angle solver cannot lift it, and says so rather than pretending. Reach for Relax if you want it puckered.

Symmetrize is in both places, labelled with the detected group. The rail’s Geometry section carries it as a single button, Symmetrize (D₃d); the Edit menu carries it as a submenu, Symmetrize Geometry (D₃d), whose first entry Snap to D₃d does the same thing. Both are disabled when the group is C₁ or the molecule is too large to detect.

The menu offers one thing the button cannot: under Reachable by loosening the tolerance it lists the other point groups the structure would fit if atoms were allowed to move further, each with the tolerance in Ångströms that it needs. Picking one symmetrizes onto that group instead of the detected one. The looser the tolerance, the more it will move.

The rail’s Geometry section also carries its own collapsed Clean geometry… and Relax geometry… blocks, each with the same Selected and All buttons as the Edit menu entries above (Clean Selected is disabled until something is selected); the repair checkboxes stay in the Edit menu.

3.7.5 Charge, hydrogens and bond orders

Formal charge is the toolbar’s Charge ▾, +3 through −3 on the selection. It is not cosmetic — three things downstream read it:

• Valence. The lookup is Z − charge, so N(+) is read as carbon and wants four bonds rather than three, and O(−) is read as fluorine and wants one. Set a nitrogen to +1 and the status line tells you the scene is a hydrogen short.
• Oxidation state, on a metal. Clean’s metal–oxygen repair reads the Shannon ionic radius, and the table has no charge-0 entries at all. Every parser but SDF loads a metal at charge 0, so on a structure from a file that step can only report itself skipped until you set the state. Set a europium to +3 and the same Clean goes from “left distances alone: no ionic radius for that oxidation state” to “set 8 metal–oxygen distances”.
• Identifiers and the diagram, which draw and encode the charge you set.

Hydrogens are not adjusted when you change a charge — see below.

Adjust Hydrogens and Work Out Bond Orders are on demand, never automatic. A builder that silently adds and removes atoms while you work is one whose output you have to re-check after every change.

Adjust Hydrogens (Edit → Adjust Hydrogens → Adjust Selected / Adjust All) fills each atom up to a valence it can hold and removes the hydrogens a promoted bond displaced. New hydrogens land roughly; run Clean Geometry afterwards to settle the angles.

Work Out Bond Orders (Edit → Work Out Bond Orders) assigns orders from valence across the whole scene. It ignores the geometry on purpose: a drawn bond sits at the single-bond length whatever it means, so distance evidence would refuse every promotion. It will also overrule orders you set by hand, which is why it is a deliberate command rather than something that runs on edit. Draw ethene as two carbons and a bond, run it, and the bond becomes a double bond — orbitron identify then reports C=C and the real InChIKey VGGSQFUCUMXWEO-UHFFFAOYSA-N.

These are halves of one answer: finding a double bond changes how many hydrogens its atoms should carry, and so does charging an atom. The usual order is charge, then bond orders, then hydrogens, then Clean.

3.7.6 Metal complexes

Place Metal Complex… (Edit, the rail’s Geometry section, or the button at the foot of the Insert Fragment window) opens a dialog taking an element and an oxidation state, and reports what it will build — for example Fe(3+): octahedral at 6 donors, with the reach to each donor taken from the Shannon ionic radius at that coordination number. Two ways to use it:

• Place aqua ion — every site filled with water.
• Wrap selection (n donors) — select the atoms that coordinate the metal and it places the centre and folds your existing ligands onto its geometry.

Suggest Donors selects the atoms most likely to coordinate a metal. It is a suggestion to correct, not an answer — check it before wrapping.

What the template decides. An element and an oxidation state give a preferred coordination number, a reference shape and a ceiling. Fe(III) prefers six and will not go past six; a lanthanide(III) prefers nine for lanthanum to neodymium and eight after, and will expand further when a chelate demands it (to twelve through gadolinium, ten after), because f-block coordination numbers are set by the ligand rather than the ion. Germanium(IV) and silicon(IV) prefer four and take six (the catecholates, hexafluorosilicate), tellurium(VI) is the octahedral Te(OH)₆, and thorium(IV) may reach twelve. Copper(II) and zinc(II) are the aqua ions of a solution database, octahedral at six (copper’s Jahn-Teller elongation is not in the template shape and relaxation finds it): hexaaquazinc, and the 4+2 octahedron of copper. They were square planar and tetrahedral at four until 2026-10-10, and 46% of the CSD’s mononuclear copper(II) complexes and 42% of its zinc(II) are in fact above four. A four-donor ligand set is filled to six with water, and a pentadentate or hexadentate ligand such as EDTA is built. Yttrium(III), the size of holmium, is built like a lanthanide (eight, up to nine), and scandium(III) prefers six and reaches eight. An actinyl or vanadyl carries an oxo core: its axial oxygens are placed first and the remaining sites arranged around the equator. Vanadium(V), molybdenum(VI) and tungsten(VI) carry a cis-dioxo core: two oxo groups at the template’s angles, taken from the CSD (V: 109 degrees with five donors, 105 with six, V=O 1.625 Å; Mo and W six donors at 105, Mo=O 1.70 and W=O 1.725 Å), and the other donors in the remaining sites. Molybdenum(V), rhenium(V) and technetium(V) carry a single oxo group on an octahedron (a square pyramid for technetium). An arsenic, antimony or bismuth(III), selenium or tellurium(IV), or germanium, tin or lead(II) ion with three to five donors is built in the shape its lone pair leaves: a pyramid with right angles at three, a seesaw at four with its axial bonds longer than its equatorial ones, and at five a square pyramid with the metal in its base and the apex shorter than the base, each split by the CSD’s median for that element ([SbCl₄]⁻ at 2.34 Å equatorial and 2.49 axial). A six-coordinate copper(II) is built as the Jahn-Teller 4+2 octahedron its crystals are, its two axial bonds 0.42 Å longer than its four equatorial ones, and a six-coordinate manganese(III) the same way by 0.20 Å; a chelate’s rings hold some of that back. Clean and Relax keep the elongation, along the axis the structure already has. Reach comes from the Shannon ionic radius at whichever coordination number the sphere ends up at, plus the donor element’s own radius, so an N donor sits further out than an O donor on the same ion and a chloride further still. Where Shannon has no radius at that number (gold(I) at two, tin(II) at two to four, antimony(III) at three and four, a neptunyl(V) at seven and a neptunyl(VI) at eight), or none for the oxidation state at all (ruthenium(II), osmium(II) and (III), rhodium(I), iridium(I), rhenium(I), (II) and (III), manganese(I), technetium(I) and (III)), the radius is one measured on CSD crystal structures. Before that the last group was placed from its charge alone, which put a ruthenium(II)’s nitrogens 0.3 Å too far out. Some are still missing because the crystals do not settle them: thallium(I) below six donors has almost no oxygen or halide contacts and its nitrogens are not a reliable stand-in, plutonium(V) and (VI) above six and americium(V) and (VI) are in too few structures, and silver(I)’s oxygens and halides disagree with each other and with Shannon’s own silver radii.

A carbonyl, an isocyanide or a cyanide bound through carbon takes a distance measured on CSD crystal structures rather than a radius sum, per metal, and a little further out when another carbon is trans to it: W–C 2.04 Å in W(CO)₆, Re–C 1.92 Å trans to a nitrogen in a rhenium(I) tricarbonyl, Fe–C 1.94 Å in a hexacyanoferrate. M–C–O is built straight. The builder, Clean and Relax all read the same table, and given a choice the builder keeps carbonyls and isocyanides out of each other’s trans slots, so three carbonyls with three other monodentates come out fac and two come out cis. A carbonyl or isocyanide on a metal the crystals give no distance for is refused (carbonyl_or_isocyanide); a cyanide there takes oxygen’s distance.

Slots left over are filled with water, which is what an aqueous species actually has and what keeps the built centre at the coordination number its template names rather than under-coordinated.

Placement can refuse, and the message says which. More donors than the template’s ceiling, a ligand whose aromatic rings cannot be resolved to a Kekulé structure, or a result with an atom collapsed onto the metal are all refused rather than returned. The last one matters most: a heavy atom inside the metal looks clean by every other measure — the sphere sits on its template, the ligand bonds are intact, and the metal-donor error reads near zero because the atom lying on the metal is usually a carbon with no tabulated distance to be wrong about. Returning it would hand you a molecule with no way to tell.

A ligand is built as the stereoisomer it is given. Each carbon stereocentre and each double bond outside a ring keeps the configuration of the ligand you supply, and a build that would turn one over is refused (configuration_changed) and tried on other slot arrangements and on their mirror image first, since a chelate of one hand fits the reflection of the slots that fit the other. A carbon counts as a centre when its four neighbours differ anywhere along their branches, or when it is one of a cis/trans pair across a ring (cyclohexane-1,4-diol’s two carbons, but not cyclohexanol’s). A double bond with one end in a conjugated ring (one with a double or aromatic bond of its own; an exocyclic C=O does not make it one) is not checked: which of the ring’s bonds is drawn double is a resonance form, not a configuration.

Donors are held while the ligand settles. Building runs a UFF relaxation with the donors restrained on their slots, because releasing them lets UFF’s shorter metal-donor equilibrium pull an octahedral sphere into a trigonal prism and drag the ligand backbone with it. When a chelate’s bite genuinely cannot span the geometry it was given — EDTA on iron is the standard case — the hold is released and the free result kept only if the sphere is still clean.

Snap Coordination Sphere moves a selected metal’s donors onto its ideal geometry, keeping the metal and every bond length where they are. A sphere between two shapes is left as built, by Snap and by Clean: on the path from one to the other and at least a quarter of the way from each end (a four-coordinate seesaw halfway from the tetrahedron to the square), it is no more one shape than the other, and snapping it to either would be arbitrary.

The Coordination readout in the rail’s Scene section reports each centre without offering a button, because coordination number does not determine geometry at four, five, seven, eight or nine donors and a one-click “fix” would be nudging toward a guess. Each centre reads as one of:

• <shape>, <n> from ideal — sits on a recognised geometry.
• <shape>, distorted (amber) — Snap Coordination Sphere will straighten it.
• <shape>, distorted, between two shapes (amber) — lies in the middle of the path between its two nearest shapes, so Snap and Clean leave it as built; the SHAPE table gives how far along.
• no standard geometry (nearest <shape>) — too far from every reference shape to name. Clean holds this sphere fixed rather than relaxing it.
• no reference geometry — nothing to compare this donor count against.

Hapto ligands. A ligand bound through several contiguous atoms is one site, so Cp₂ZrCl₂ is a four-coordinate metal. A line under the verdict names them, 2 × η5-Cp (also η6-arene, η3-allyl, η2, and so on), named by how many atoms are bound and whether they close a ring, which is what the geometry shows and says nothing of charge or substituents. A sandwich complex is two sites, measured with the metal like any two-coordinate centre, so ferrocene reads linear. orbitron analyze metal-sites lists the same ligands with their atoms.

M···H–C contacts. A line M···H–C: 1 agostic (2.16 Å), 1 anagostic (2.72 Å) counts a centre’s C-H contacts with the nearest of each, named as orbitron analyze metal-sites names them: by Brookhart, Green and Parkin’s windows, and then by the electron count, since a contact in the agostic window is agostic only where the metal has a vacant orbital to take it. On a d8 square planar centre, or one already past 16 electrons, it reads anagostic in the agostic window with the rule that made it so. Where no count was made, the contact is named for its window (agostic-window).

d/f count. A line Fe(II), d6 · bond valence gives the centre’s oxidation state and the d or f electron count it implies in the ionic model (the group less the state: U(VI) is f0, Pt(II) d8). The state is one the file states, the atom’s formal charge, a bond-valence sum consistent over every bond, or the ionic model from the file’s declared total charge, in that order, and the line says which. The state is right for nearly nine complexes in ten against BOS-Lig’s experimental states (88.6% of 1,142). With none of them the line is left out rather than counting from charge zero. A metal whose donors bridge it to another (Zeise’s dimer, a paddlewheel) has no sphere of its own to assess, and is listed as Pt (bridged) with its count. orbitron analyze metal-sites reports the same state and count, from the same code.

Electron count. Under the configuration, the valence electron count in the ionic model, as orbitron analyze metal-sites gives it: 18 electrons, 16 electrons, d8, and so on, amber when it is over 18 or odd on a complex the file declares even-electron. It needs the file’s total charge. Where the count rests on something the geometry does not settle (a contact that may be bound, a π system that reaches past the atoms bound, a nitrosyl bent between 140° and 150°) the line gives both totals (16 or 18 electrons) and why, and where there is nothing to count on (two metals sharing ligands, a metallaborane) it says so. The CLI guide’s analyze metal-sites section has the rules.

Trust in the state. A line Trust in the state: high, moderate, low, not calibrated or as stated grades how far to believe the oxidation state above it: how often a state like it was right for similar complexes in a benchmark of 67,315 CSD structures of the d and f blocks, by metal, the method that gave it, the number and kind of donors, and whether a ligand’s charge is a convention. An organometallic is graded from 27,589 CSD organometallics in the same way. Under the grade the share of those complexes that were right is given with its 95% interval and the size of the closest group, so a high resting on 25 complexes reads differently from one resting on 2,000. not calibrated means no benchmark describes the site (a cluster, a periodic structure, no declared charge, an element with too few complexes). as stated means you or the file gave the state (a stated state or a formal charge), so it is not a grade of whether it is right. A low grade is drawn amber, and each caution is listed beneath in small type. The grade is what was checked, not a probability; hover over it for the convention and the CSD hit rates, and see Metal-site accuracy.

Ligand field. For a centre with one to nine d electrons, a collapsed Ligand field heading opens a drawing of the d levels in a σ-only angular overlap model, with the electrons as arrows and each level’s energy in eσ (an octahedron has Δo = 3 eσ). Where high and low spin differ, buttons pick the filling, and a line gives the d count, the unpaired electrons and the LFSE, with a Jahn–Teller note where it applies. It is a model of the pattern, not a prediction: π effects are left out, eσ is not estimated, and the LFSE is not a computed stabilization energy.

The readout sits directly under the atom and charge counts, not inside the collapsed Scene details, and draws nothing for a structure without a metal centre.

SHAPE table. Under each centre, a collapsed SHAPE table lists every reference shape for that donor count with its continuous shape measure, best first: SHAPE’s ML_n convention, the metal a vertex, which is the number published tables quote and what orbitron analyze metal-sites prints. The verdict line above is calibrated on the donors alone from four donors up (at two and three the metal is a vertex there too), so the two can differ in the first decimal; hovering a code gives the shape’s name and the donors-alone value. Copy puts the table on the clipboard as tab-separated text, both measures included, for a spreadsheet or a paper’s SI.

On a structure with residue annotation — a PDB or mmCIF — each centre is also named by where it sits, and its donors are named the way you would ask about them:

Zn C1 (3-coordinate)
trigonal pyramidal, 0.4 from ideal
via HIS A1 NE, HIS A2 NE, HIS A3 NE

The site (C1, A99) is what tells two zincs in the same protein apart. The donor line appears when at least one donor carries residue annotation, so a metal ligated by three histidines and a crystallographic water still names the histidines. A small-molecule calculation gets no donor line, because there the donors are already visible in the structure.

3.7.7 Cutting a metal site out for a QM calculation

Extract Cluster Model (Edit, with a metal selected) reduces the structure to that metal’s site: what coordinates it stays, everything else goes, and the bonds that were cut are capped with hydrogen. This is the standard preparation step for running DFT on a metalloprotein.

Where it cuts follows one rule. From each donor it grows outward through bonds and stops at an α-carbon, so a coordinating histidine keeps its whole imidazole plus CB — 4-methylimidazole once capped — and a coordinating backbone carbonyl keeps the peptide unit, which caps to formamide. A group with no α-carbon has nothing to cut at and survives entire: a water, a chloride, a heme. Nucleotide sugar carbons stop growth the same way, so a magnesium on a phosphate does not pull in the whole strand.

Two things it does that are easy to miss:

• It takes a distance shell, not just the bond list. Bond inference works from covalent radii and a metal–ligand contact is longer than that: the catalytic water of a zinc protease sits 2.36 Å from its zinc with no bond inferred. A model without that water is the wrong model, so any residue with an atom within 2.8 Å joins regardless.
• The capping hydrogens are frozen. Nothing else is holding the fragments in their crystallographic arrangement once the protein around them is gone, so an unfrozen cluster folds up the moment you relax it.

The report names the residues and gives the formula — GLU A164, HIS A144, HIS A140, HOH A414 — 22 atoms (C11H3N4O3Zn), 3 frozen caps — because those are what you type next to a charge and a multiplicity in an input file, and neither is readable off the result.

A crystallographic file has no hydrogens, so the cluster arrives with only its caps and says so. Run Adjust Hydrogens to protonate it; the protonation states (is that glutamate charged? is that water a hydroxide?) are yours to decide, and nothing here guesses them.

The extraction is destructive and undoable on purpose. The intended loop is extract, look at it, export it, undo, carry on with the structure.

3.7.8 From a flat drawing to 3D

Generate 3D Coordinates (Edit) builds a three-dimensional structure from connectivity alone, adding the hydrogens a connection table leaves implicit. This is the path for an SDF/Molfile that carries a 2D depiction rather than coordinates. Handedness specified by the drawing is kept, and individually inverted stereocentres are repaired rather than the whole structure being re-embedded.

Orbitron can also build from supported SMILES through Edit → SMILES; see §3.7.12. Use File → Export → Export Molfile… to get connectivity back out (V3000 is written automatically when a structure will not fit a V2000 counts line).

3.7.9 Fragment Palette

The Fragment Palette inserts pre-built molecular fragments from a built-in library. Fragments attach via single bonds with automatic hydrogen cleanup at the anchor site.

For carbocycles, prefer the ring sizes in the placement chooser (§3.7.2) — those are generated and solved rather than stored as coordinates, and cover C₃–C₈.

Available Fragments: - Benzene (C₆H₆): the one template that needs no anchor, so it can start an empty session. Every other entry is a substituent, and a substituent with a dangling valence is a radical rather than a molecule. - Methyl (–CH₃): Tetrahedral carbon with three hydrogens (anchor bonds to carbon) - Hydroxyl (–OH): Oxygen with one hydrogen (anchor bonds to oxygen) - Phenyl (–C₆H₅): Planar benzene ring with five hydrogens (anchor bonds to para carbon)

A chelating ligand binds through several atoms, which no one-anchor fragment can. The foot of the Insert Fragment window says how to build one: draw the ligand from SMILES (Edit → SMILES), select its donor atoms, then place the metal on them. Its Place Metal Complex… button closes the palette and opens that dialog (§3.7.6).

Opening the Fragment Palette: 1. Toolbar (recommended): Enable edit mode (Ctrl+E), then click Fragment ▾ 2. Menu: Edit → Advanced → Add Fragment… (requires an anchor atom to be selected)

Insertion Workflow:

Option 1: Fragment placement mode (viewport-based placement) 1. Enable edit mode (Ctrl+E) 2. In the toolbar, click Fragment to enter placement mode 3. Click Fragment ▾ to open the palette, an Insert Fragment window 4. Select a fragment from the scrollable list 5. The palette shows the current anchor selection: - If a single atom is selected: “Anchor atom: {id}” appears - If selection contains multiple atoms: uses the last selection history entry - If no anchor is available: displays a warning (“Select an anchor atom to attach the fragment”) 6. Click Insert Fragment to place the fragment and bond it to the anchor 7. The newly inserted atoms are automatically selected and highlighted

Option 2: Menu-based insertion 1. Enable edit mode and select one anchor atom 2. Open Edit → Advanced → Add Fragment… 3. Select a fragment from the palette 4. Click Insert Fragment

Fragment Behavior: - Anchor cleanup: For the three substituents, Orbitron removes one hydrogen bonded to the anchor atom before placement (FragmentCleanup::RemoveSingleHydrogen). Benzene attaches nothing and cleans up nothing (FragmentCleanup::None) - Positioning: Fragment atoms are placed relative to the anchor position using chemically accurate bond lengths: - C–C single bond: 1.54 Å (methyl) - C–O single bond: 1.43 Å (hydroxyl) - C–C aromatic: 1.40 Å (benzene, phenyl) - Bond order: All fragments attach with single bonds (BondOrder::Single) - Placement origin: Benzene needs no anchor; the substituents require one

Smart Selection: When you open the palette, it picks a default fragment from the element in the placement chooser (the toolbar’s C ▾), not from the selected atom, and only when an anchor atom is selected: - Carbon (C, element 6) → defaults to Methyl - Oxygen (O, element 8) → defaults to Hydroxyl - Any other element leaves the previous choice as it was - With no selection, the palette defaults to Benzene, the one template that needs no anchor

Keyboard Navigation: - Esc: Cancel placement mode or close the palette without inserting

Implementation References: - Fragment library: ui/shell/src/fragments.rs - Palette UI: ui/shell/src/viewer_loop/fragment_palette.rs - Generated rings (the C₃–C₈ alternative): core/edit/src/geometry/ring.rs

Example Use Case: To add a hydroxyl group to a carbon atom: 1. Select the target carbon atom 2. Press Ctrl+E to enter edit mode 3. Click Fragment in the toolbar 4. Click Fragment ▾ to open the palette 5. Select “Hydroxyl (–OH)” from the list 6. Click Insert Fragment 7. The hydroxyl group appears bonded to the carbon, with one hydrogen removed from the carbon automatically

3.7.10 Change Element Dialog

The Change Element dialog lets you modify the atomic number (element type) of selected atoms or set the default element for placement operations. It provides both a visual periodic table grid and a text input for quick symbol/number entry.

Opening the Dialog: 1. Edit Menu: Edit → Change Element… (requires atoms to be selected; the menu shows Alt+C, but no key handler is bound to it) 2. Toolbar: Click Element… (requires atoms to be selected) 3. Placement element: Click the toolbar chooser (C ▾, C·tet ▾, ring C6 ▾)

Dialog Modes:

Mode 1: Change Selected Atoms (Selection Scope) - Requires: Edit mode enabled + one or more atoms selected - Window title: “Change Element” - Applies element change to all currently selected atoms via ChangeElementCommand - Button label: “Apply”

Mode 2: Set Placement Element (PlacementOnly Scope) - Reached from the toolbar chooser - Window title: “Placement Element” - Sets what future placements drop: the element, plus the Shape to build around it and Or drop a ring pickers described in §3.7.2, and the Grow onto its row for the two five-coordinate shapes - Button label: “Set” - Does NOT modify existing selected atoms

Input Methods:

1. Text Input (top of dialog) - Enter element symbol: C, O, Fe, Si (case-insensitive) - Enter atomic number: 6 (carbon), 8 (oxygen), 26 (iron), 1-118 (valid range) - Press Enter or click Apply/Set to confirm - Invalid input displays status message: “Invalid element input”

2. Periodic Table Grid - Layout: 9 rows × 18 columns with row/column headers - Rows: P1-P7 (main periods), Ln (lanthanides), An (actinides) - Columns: Group numbers 1-18 - Cell size: 30×24 pixels, color-coded by element category: - Nonmetals: Light blue (#A6CCEB) - Noble gases: Teal (#A2DACD) - Alkali metals: Peach (#E89E80) - Alkaline earth: Yellow (#ECD07C) - Transition metals: Blue-gray (#A8C5D7) - Post-transition: Green (#A9D2AA) - Metalloids: Tan (#D1C484) - Halogens: Purple (#D6B5E0) - Lanthanides: Brown-orange (#D2A884) - Actinides: Pink (#CD9AAF) - Selection indicator: 1.5px colored stroke around current element - Hover tooltip: Shows full element name, symbol, and atomic number (e.g., “Carbon (C)= 6”) - Click any element button to select it immediately

Dialog Controls: - Apply / Set: Confirms the selection and closes the dialog - In Selection scope: Executes ChangeElementCommand on all selected atoms - In PlacementOnly scope: Updates ui_state.placement.add_atom_element - Cancel: Closes dialog without changes - Enter key: Submits text input value (same as clicking Apply/Set)

Status Messages: - Success (Selection): “Changed N atom(s) to {symbol}” - Success (Placement): “Set placement to {symbol}, {shape}”, where the shape is single atom, a geometry name, or C{n} ring - Error: “Invalid element input” (invalid symbol/number) - Error: “Select atoms to change element” (no selection in Selection scope) - Error: “Enable edit mode to change elements” (Selection scope without edit mode)

Workflow Example (Selection): 1. Select one or more atoms in the viewport 2. Enable edit mode (Ctrl+E) 3. Navigate to Edit → Change Element… 4. Either: - Type “Fe” in the text box and press Enter, OR - Click the Fe (iron) button in the periodic table grid 5. Dialog closes, the footer shows: “Changed 3 atom(s) to Fe” 6. Selected atoms are now iron (atomic number 26)

Workflow Example (Placement): 1. Enable edit mode and click Place Atom in the toolbar 2. Click the chooser beside it (C ▾, or C·tet ▾ / ring C6 ▾ when a shape or ring is armed) to open the “Placement Element” dialog 3. Click the N (nitrogen) button in the periodic table 4. Dialog closes, the status line reads “Set placement to N, single atom” and the chooser button now reads N ▾ 5. Future atom placements will be nitrogen until you change it again

Implementation Details: - Command: ChangeElementCommand::new(atom_ids, atomic_number) (from orbitron-edit) - Text parsing: Tries u8 parse first, then symbol lookup via helpers::atomic_number_from_symbol() (case-insensitive) - Valid range: Atomic numbers 1-118 (hydrogen through oganesson) - Periodic table data: Stored in ui/shell/src/viewer_loop/change_element/data.rs - Rendering: ui/shell/src/viewer_loop/change_element/table.rs (render_periodic_table) - Window handler: ui/shell/src/viewer_loop/change_element/window.rs (handle_change_element_window)

Keyboard Shortcuts: - Enter: Submit text input - Esc: Close dialog (implicit via egui window behavior)

3.7.11 Molecular charge and multiplicity

The Molecular state row at the top of the Edit rail records the intended total charge and spin multiplicity of the structure being built. These values are separate from each atom’s formal charge. The row reports the implied electron count and warns when the multiplicity has the wrong parity or when the sum of atomic formal charges disagrees with the molecular charge.

Changing this state is undoable and participates in the scene digest, session save, bundles, Python API, and export checks. It does not rewrite electronic structure parsed from a calculation. Parsed charge and multiplicity remain evidence about the original calculation, while the editable molecular state describes the current structure.

Adjust Hydrogens checks the proposed formula against this state before it moves or creates atoms. For example, it refuses to turn a declared neutral CH3 doublet into even-electron CH4. XYZ export warns that it loses both charge and multiplicity; PDB, MOL, and SDF warn that they lose the declared molecular charge and multiplicity. Per-atom formal charges remain in formats that support them, but they are not a substitute for the molecular declaration. Scene bytes and .orbpack preserve the complete state. InChI and InChIKey generation use the editable molecular charge after a builder edit while leaving parsed electronic-structure evidence unchanged.

The editor is hidden for periodic scenes. Orbitron does not assign a single molecular charge or spin multiplicity to a periodic cell.

3.7.12 Building from SMILES

Edit → SMILES → Build New… replaces an empty scene with a molecule. Edit → SMILES → Insert Beside Scene… adds a fragment three angstroms to the right of the current scene and keeps the current scene’s molecular state. The dialog generates deterministic 3D coordinates by default; clear Generate 3D coordinates to keep the connection-table layout. Orbitron marks that layout as a 2D depiction, so measurements refuse it until you generate or supply 3D coordinates and MOL/SDF export records it as 2D.

The reader accepts atoms, bracket atoms, isotopes, formal charges, aromatic atoms, branches, ring closures, disconnected components, tetrahedral @/@@, and non-ring alkene //\\ stereochemistry. It adds explicit hydrogens and checks the requested configuration in the generated coordinates. Stereo requires Generate 3D coordinates. Wildcards, atom maps, reactions, SMARTS, CXSMILES, ring-alkene stereo, and non-tetrahedral atom configurations are refused. Bracketed metal ions are accepted, but the built-in 3D coordinates are only a starting geometry and conformer search refuses metal-containing structures.

For scripts, the matching commands are orbitron from-smiles and Scene.from_smiles(); see the CLI and Python guides.

3.7.13 Conformer search

Edit → Generate Conformers… performs deterministic single and combined torsion sampling, relaxes each starting arrangement with UFF, removes duplicates by heavy-atom aligned RMSD, and sorts the retained conformers by UFF energy. The search runs in the background: a small window says it is running and offers Cancel, the rest of the window stays usable, and a search whose structure was edited before it finished is discarded rather than shown. The dialog reports how many rotatable bonds and starting arrangements it evaluated. Selecting a row previews a detached copy: Save, export, edit commands, viewport manipulation, and file drops remain unavailable until the chooser closes. Use this conformer applies the selected coordinates as one undoable edit. Cancel dismisses the preview without changing the scene.

A rotatable bond is terminal only when one end has no other heavy-atom neighbour, so explicit hydrogens do not turn terminal methyl bonds into false rotors. If one side is frozen, Orbitron rotates the movable side around the same bond. Duplicate removal retains the lowest-energy member of each RMSD cluster.

The search requires one connected, non-periodic, non-metal molecule with 1 to 200 atoms, at least one movable atom, and UFF parameters for every atom. It is a bounded rotatable-bond search, not a ring-puckering or macrocycle search. The relative energies are force-field scores in kcal/mol, not quantum-chemical energies.

3.7.14 Mutating an annotated residue

Select one or more atoms belonging to exactly one PDB or mmCIF residue, then use Edit → Mutate Residue…. Choose a target and select Generate rotamer previews. Orbitron replaces the side chain from pinned wwPDB CCD ideal coordinates, measures the retained backbone phi and psi angles, and loads up to 12 candidates from a 20° backbone bin derived from the Richardson Lab Top8000 residue set. The dialog shows the measured angles, selected bin, Top8000 rotamer name, local probability, chi angles, clash count, and geometric overlap score. Selecting a row renders a detached preview. Use this side chain applies that exact candidate as one undoable edit.

The bundled library smooths each bin with its immediate phi/psi neighbours. If the requested bin has too little source support, Orbitron uses the nearest populated bin. A chain end or incomplete backbone uses an explicit backbone-independent fallback and says so in the dialog. Ala, Gly, and Pro have one fixed template geometry because this mutation path does not sample a side-chain chi for them.

Clash-free candidates are ordered by their probability in the selected bin. When a candidate has a clash, geometric overlap takes precedence and library probability breaks ties. Probability is a frequency in the bundled Top8000 derivative. The overlap score is a placement heuristic, not an energy.

The mutation retains residue identity and the N, CA, C, O, and OXT backbone atoms and coordinates that are present. N, CA, and C are required to define the placement frame. The target list contains 19 unambiguous standard residues plus explicit HID, HIE, and HIP histidine states. Plain HIS is refused because its protonation site is ambiguous. HID and HIE are neutral, with one ring proton on ND1 or NE2; HIP is +1, with both ring nitrogens protonated. New side-chain atoms inherit residue identity fields but not occupancy, displacement tensors, or computed atom properties from CA.

Mutation checks the declared molecular charge/multiplicity before applying. If a CYS endpoint is changed to another residue, stale SSBOND metadata for that endpoint is removed and restored by Undo. The command does not optimize the backbone, rebuild missing residues, insert or delete residues, or handle nucleic acids and non-standard residue templates.

3.7.15 Repairing a missing side chain

Use Scene → Sequence / Residues → Missing heavy atoms to find an incomplete coordinate-bearing amino acid, select that residue, enter edit mode, and choose Edit → Repair Missing Side Chain…. Select Generate repair previews to build complete candidates from the same pinned CCD templates and Top8000 rotamers used by residue mutation.

The preview names the missing heavy atoms before and after repair, existing side-chain atoms that will be rebuilt, explicit side-chain hydrogens that will be removed, molecular formal charge, and steric clashes touching the side chain. Each candidate reports its rotamer probability and chi angles, the RMS and largest displacement from existing heavy side-chain coordinates, and its post-repair clash count and overlap score. Clash-free candidates appear first; the default within that group has the smallest retained-atom RMS displacement. These values describe geometry. They are not energies or a substitute for refinement.

Repair keeps N, CA, C, O, and OXT atoms and coordinates fixed. It replaces the complete side chain rather than mixing measured and generated internal coordinates. Generated atoms retain author and mmCIF residue identity but do not copy occupancy, displacement, or computed atom properties from source atoms. Selecting a row renders a detached scene, and Use this reconstructed side chain applies that exact candidate as one undoable edit.

Orbitron requires one incomplete supported standard residue with an unambiguous N/CA/C backbone. Generic HIS, protonation aliases such as ASH or CYM, active disulfides, other bonds from the side chain to an external residue or metal, non-standard residues, and residues with alternate locations are refused. Choose or delete an alternate conformer first. For an ambiguous protonation state, rebuild or normalize the residue explicitly, then use the protonation or disulfide editor. This command does not build missing backbone atoms, loops, or unresolved residues.

3.7.16 Retaining or deleting an alternate location

Select any coordinate-bearing atom in one residue with named alternate locations, enter edit mode, and choose Edit → Edit Alternate Locations…. Choose the residue-local conformer and one explicit operation. Keep only this conformer removes the other named locations in that residue and clears the retained atoms’ alternate-location labels. Delete this conformer removes only the chosen named location and leaves the other labels intact.

Blank-location atoms belong to every conformer and are always preserved. The detached preview lists locations before and after, atom names removed, location labels cleared, incident bonds, and bonds reaching another residue. A cross-residue bond is shown as a warning because deleting its atom also deletes that bond. Both operations affect exactly one author residue; a location with the same name in another residue is untouched. Apply is one stale-safe, undoable edit.

Keeping one conformer preserves its source occupancy instead of rewriting it to 1.0. This retains experimental provenance even though the altloc label is cleared. The Appearance alternate-location control remains a view filter only; it never deletes atoms. Use the editor when the source model itself should be collapsed or pruned, then export PDB or orbpack to retain the edit.

3.7.17 Selecting or removing water and ions

Enter edit mode and choose Edit → Clean Up Water/Ions…. The default matches all recognized water residues. You can instead choose monatomic ions or both classes, then match all residues, residues within a cutoff of the current atom selection, or residues beyond that cutoff. Distance matching uses whole residues and periodic minimum-image geometry when the scene has a periodic cell. Residues containing selected anchor atoms are protected.

The detached viewport preview shows the scene after removal. The dialog reports the exact source component identities, complete-residue and atom counts, formal charge removed, incident bonds, and bonds reaching outside the cleanup set. Select matches closes the preview and highlights the matched source atoms; Remove matches applies one stale-safe, undoable edit.

Water recognition requires a conventional identity (HOH, WAT, H2O, DOD, SOL, common TIP/SPC names), at least one oxygen, and only hydrogen, oxygen, or dummy interaction sites. An ion must be one non-polymer atom, use a metal or halide element, and have a component identity that agrees with that element; common SOD, POT, CAL, CLA, and CES aliases are accepted. Orbitron does not infer that every metal should be discarded. Ion cleanup is an explicit choice and the dialog warns that a matched metal may be structural or catalytic. Inspect the identity list before removal.

3.7.18 Adding an ACE or NME terminal cap

Select any atom in one observed protein-fragment end, then use Edit → Add Terminal Cap…. Choose ACE, N-terminal acetyl or NME, C-terminal methylamide, then select Generate cap preview. The dialog names the protein end and the new cap residue, lists terminal atoms that will be removed, and shows the whole-scene formal charge before and after the edit. The detached cap geometry is rendered behind the dialog. Apply ACE cap or Apply NME cap commits that exact preview as one undoable edit.

Orbitron assigns a blank-insertion-code author residue number before the N end or after the C end, skipping numbers already used in the chain. ACE removes explicit hydrogens bonded to the terminal N and makes that N formally neutral. NME removes OXT and any hydrogen bonded to OXT. The generated cap contains heavy atoms only; run Edit → Adjust Hydrogens afterward when an exported model needs explicit cap hydrogens.

The command requires one N, CA, and C atom in the selected residue. It refuses internal residues, already capped ends, ambiguous alternate backbones, and a declared charge/multiplicity that the edited atom set cannot satisfy. It does not guess protonation, build a missing backbone, or prepare a force-field topology.

3.7.19 Setting an explicit side-chain protonation state

Select any atom in one annotated ASP/ASH, GLU/GLH, CYS/CYM, or LYS/LYN residue, then use Edit → Set Protonation State…. Choose the exact target state and select Generate state preview. ASH and GLH also require an explicit choice of which oxygen carries the hydrogen. Orbitron does not choose a state from pH or infer one from the source residue name.

The dialog shows the source and target component, the selected-residue and whole-scene formal charges before and after the change, and every explicit hydrogen removed or added. The detached result is visible behind the dialog. Apply state commits that exact preview as one undoable edit. Every retained heavy atom keeps its ID and coordinate. The command updates the component name, formal charges, acidic C-O bond orders, and explicit hydrogens at the titratable atoms. Generated hydrogens keep the residue identity but do not copy occupancy, displacement, or computed properties.

The command refuses an incompatible residue family, CYX, a residue with duplicate or missing state atoms, a scene changed since preview, or a target state inconsistent with the declared molecular charge/multiplicity. Tyr, Arg, force-field-specific aliases, and non-standard residues are not supported by this operation. Applying the same named state can still normalize missing or misplaced explicit hydrogens.

PDB export preserves the supported residue name, explicit atoms, and atom formal charges, but PDB export does not write Orbitron connectivity or bond orders. Use an orbpack for an Orbitron-native round trip or Molfile when the edited connection table must survive.

3.7.20 Creating or breaking a disulfide

Select atoms spanning exactly two annotated cysteine residues, then use Edit → Edit Disulfide…. Orbitron chooses Create disulfide when two CYS residues can form a new bridge and Break disulfide when the selected pair already has an SG-SG bond or PDB/mmCIF declaration. You can change the proposed operation before generating the preview.

Creation requires one unambiguous SG atom in each CYS and a minimum-image SG-SG distance from 1.7 through 2.5 Å. Orbitron keeps every heavy-atom ID and coordinate fixed, removes hydrogens bonded to the two sulfurs, makes both SG formal charges neutral, adds one single SG-SG bond, and adds the active PDB SSBOND annotation. Move the sulfurs first if they fall outside the supported range; this command does not pull a distant pair together.

Cleavage accepts CYS or CYX endpoints with an SG-SG bond or declaration. It removes the bridge and active SSBOND annotation, changes CYX endpoints to CYS, and adds one approximate HG to each sulfur. The preview reports both residue sites, the minimum-image distance, SSBOND before and after, hydrogens removed or added, and the whole-scene formal charge. Apply Create disulfide or Apply Break disulfide commits that exact detached preview as one undoable edit.

Imported raw mmCIF _struct_conn rows remain source provenance and are not rewritten. Orbitron updates the live bond and its active SSBOND representation. PDB export writes the active pair as an SSBOND record, but PDB is not a general connection-table format. Use Molfile when explicit connectivity must survive outside Orbitron, or orbpack for the complete Orbitron scene and provenance.

3.8 Background tasks & diagnostics

• File loads, exports, task downloads, and long-running mesh generation run out-of-band. Streaming parsers report bytes consumed against the file size, so large Gaussian, NWChem, XYZ, and other supported loads show real byte progress rather than an activity-only spinner. Formats that must map or copy the complete text report completion at the exact file length. Click the cancel button to abort (wired through CancelHandle). A cube, MRC map or bundle loaded as a volume has its own cancel: the progress overlay’s button stops a cube, map or CHGCAR as it parses and a bundle between its grids. A cube’s and a CHGCAR’s progress bars move as their values are parsed.
• Status toasts appear in the upper-left corner of the 3D view for confirmations (exports, measurements, theme toggles, etc.), at most four at a time; a message raised again while its toast is showing refreshes that toast rather than stacking a copy. The status text in the title bar can be toggled with T.
• Press P to open the diagnostics overlay, a separate borderless always-on-top window titled Diagnostics that shows FPS and background loader progress. The overlay can be closed with P again or with the Hide Overlay button inside it.
• The footer and its console. Along the bottom sits a thin footer strip carrying status text, the frame rate, and a toggle for the console. Expanding the console opens a resizable pane above the strip holding the running log, coloured by severity, with per-level filter buttons and a Clear. Hide the whole footer from View → Panels → Footer.
• If the app crashed last session, the console opens with a red banner saying so. View Report injects the crash report into the log as a block of error entries, so the stack sits inline with whatever was being logged around it; Dismiss clears the banner. Help → Open Crash Reports Folder is where the files themselves live.

3.9 Overlay Manager

The Overlay Manager (the Overlays & Compare section of the unified rail) lets you import and manage additional datasets layered onto the primary scene. Overlays can be geometry (XYZ, PDB, CIF), volumetric fields (CUBE, XSF), or system-managed comparison layers.

Opening the Overlay Manager: - Expand the Overlays & Compare section in the unified rail - The panel shows a list of all loaded overlays plus controls for adding new ones

Adding Overlays: 1. Click Add overlay button 2. The file picker opens with no extension filter, and that is deliberate: .cube and .xsf load as volumetric fields, and anything else Orbitron can open as a scene loads as a geometry overlay. XYZ, PDB and CIF are the common cases, but a Gaussian log or a POSCAR works the same way. 3. Selected files load in the background (large volumetric files show progress in the footer) 4. New overlay appears in the list with status badge

Overlay Entry Controls:

Each overlay card displays: - Checkbox: Toggle visibility on/off (system-managed overlays like Scene Compare cannot be toggled manually) - Name: Display name of the overlay - Kind: Type indicator (e.g., “Scene Geometry”, “Volumetric Field”) - Source: Origin label (file path, “Scene Compare”, etc.) - Status badge: - Pending (gray): Loading in progress - Ready (cyan/blue): Loaded successfully, optionally shows diagnostic info (e.g., “4,321 atoms”) - Failed (orange/red): Error message displayed below - Remove button: Delete overlay from session (disabled for system-managed overlays)

Volumetric Overlay Options: - Blend mode dropdown: Choose rendering blend: - Alpha compositing (default): Standard transparency - Additive (brighten overlaps): Adds color values, useful for multi-orbital stacks to prevent washing out neighboring lobes - Blend mode changes apply immediately to viewport

Transform Controls (collapsible): - Translation (Å): X/Y/Z drag values to shift overlay position (speed: 0.1 Å per drag increment) - Rotation (°): Pitch/Yaw/Roll drag values to rotate overlay (speed: 1° per increment) - Transforms apply to overlay rendering but don’t modify source data - When exporting overlays with Export Visible Overlays…, geometry overlays write with transforms applied

Base Scene Visibility: - Show main scene checkbox: Toggle visibility of the primary loaded structure - Useful for comparative viewing when you want to see only overlays - Hidden base scene still participates in camera focus calculations

Scene Compare (Advanced Feature):

When both an Original and an Edited scene exist (the toolbar’s scene toggle; e.g., after loading a computational chemistry output file and editing its geometry): - Scene Compare group appears at top of Overlay Manager - Show inactive scene as overlay checkbox: Renders the non-active scene as an overlay - Scope dropdown: - All matched atoms: Align using all atoms with matching IDs - Selection only: Align using only currently selected atoms - Ignore H checkbox: Exclude hydrogens (Z=1) from alignment calculations - Translation only checkbox: Align by shifting centroids only (no rotation) - Select Common Atoms button: Finds and selects atoms present in both scenes, sets scope to “Selection only” - Align/Match button: Performs best-fit alignment (Horn’s quaternion method) of overlay to active scene using matched atom IDs - Reset button: Resets overlay transform to identity - Opacity slider: Adjust overlay transparency (0.05–0.9 range) - Feedback message: Shows alignment results (e.g., “Aligned overlay • RMSD 0.4213 Å • 18 pairs”) or errors

Alignment Algorithm: - Uses Horn’s closed-form quaternion method for optimal rigid-body superposition (the same least-squares fit Kabsch’s SVD method gives) - Matches atoms by AtomId (must be identical between scenes) - Ignores hydrogens if Ignore H is enabled - All matched atoms scope: Uses all atoms with matching IDs - Selection only scope: Uses only selected atoms (must be present in both scenes) - Translation only: Computes centroid difference and applies pure shift (no rotation matrix) - Error messages: - “No atoms selected” (Selection scope but no atoms selected) - “Need at least 3 matched atoms to align (found N)” (fewer than three common IDs, including none; this applies in translation-only mode too)

Export Integration: - Export Visible Overlays… (in Export dialog): Writes each visible overlay to individual files - Geometry overlays → XYZ files with transforms applied - Volumetric overlays → CUBE copies (source file copied)

Session Persistence: - Saved sessions restore the entire overlay roster on load - Includes overlay names, transforms, visibility state, blend modes - Volumetric overlays reference source CUBE/XSF paths (must be accessible on reload)

Performance Notes: - Large volumetric files (>100 MB) load asynchronously in background - Overlay visibility changes immediately invalidate render cache - The footer’s status message and toasts report when background jobs queue/finish

Implementation References: - Panel rendering: ui/shell/src/panels/overlays.rs (render_overlay_panel) - Overlay state management: viewer/core/src/ui_state/overlay_state.rs - Scene compare alignment: ui/shell/src/scene_compare.rs - Background loading: ui/shell/src/viewer_loop/background_events/detail.rs

Example Workflow (Volumetric Overlays): 1. Load main scene (e.g., molecule.xyz) 2. Open the Overlays & Compare section 3. Click Add overlay, select orbital_homo.cube 4. Wait for “Ready” status badge 5. Click Add overlay again, select orbital_lumo.cube 6. Adjust blend mode for both to “Additive” 7. Use transform controls to fine-tune alignment if needed 8. Toggle visibility checkboxes to compare orbitals individually

Example Workflow (Scene Compare): 1. Load a Gaussian optimization output and edit its geometry (creates Original + Edited scenes) 2. Open the Overlays & Compare section, enable Show inactive scene as overlay 3. Click Select Common Atoms to highlight atoms present in both geometries 4. Click Align/Match to superimpose geometries 5. Status shows RMSD and atom count 6. Adjust Opacity slider to fade overlay for visual comparison 7. Toggle between geometries by switching the active scene with the toolbar’s Original / Edited buttons

3.10 Camera Presets

Orbitron provides three built-in camera presets for quick navigation between standard viewpoints, plus support for custom camera configurations via JSON files for CLI rendering.

3.10.1 Built-in Presets (Viewer)

Switch between standard orthogonal views using keyboard shortcuts or the View → Camera submenu, where the three preset buttons sit under a “Presets:” label:

Preset	Shortcut	Menu Path	Camera Orientation
Front	1	View → Camera → Front (1)	Yaw: 0°, Pitch: 0°
Side	2	View → Camera → Side (2)	Yaw: 90°, Pitch: 0°
Top	3	View → Camera → Top (3)	Yaw: 0°, Pitch: ~89.4°

Behavior: - Presets change the camera viewing angle (yaw/pitch) only - The camera target point and distance remain unchanged - This allows you to rotate around the current focal point without losing your zoom level or target - Presets work in both normal and edit modes

Camera Orientation Details: - Front: Looking along the positive Z-axis toward the origin (standard molecular view) - Side: Looking along the positive X-axis (90° rotation from Front) - Top: Looking straight down the Y-axis (slightly offset from pure 90° to avoid gimbal lock)

The same submenu carries six framing commands above the presets: Frame Selection (F), Center on Origin, Reset Camera, Center on Selection, Fit All (center and zoom to the whole scene), and Smart Pose, which cycles preset orientations.

3.10.2 Looking down a lattice vector

View → Camera also offers a, b and c under “Down a lattice vector:”. Each turns the camera so that lattice vector points out of the screen and switches to an orthographic projection, so the other two axes lie in the screen plane and the cell outline projects as a clean parallelogram rather than a skewed box.

Orthographic is the point rather than a side effect. Under perspective the far face of the cell draws smaller than the near one, so atoms that are exactly superimposed down the axis do not look superimposed — which is the one thing this view exists to show. Zoom, pan and orbit all still work afterwards; orbiting away simply leaves the crystallographic view, and the projection stays orthographic until you change it in Appearance → Camera.

A scene with no unit cell has no lattice vector to look down, and says so rather than doing nothing.

One limitation. The camera is a yaw/pitch orbit rig with a separate roll about the view direction, and these views set the viewing direction and reset the roll to zero, so they cannot put a chosen axis upright. On a triclinic cell the in-plane orientation is whatever world-up gives rather than b standing upright. The projection is correct either way; only the rotation within the page is arbitrary.

Combining with Other Camera Controls: - Frame selection (F key or the toolbar’s Frame Sel): Set target to selection center, adjust distance to fit selected atoms, and turn the camera to the side with the fewest other atoms in front of them. When every side is blocked, as for a residue buried in a protein, the status message gives the count and names what hides the rest (the cartoon, or the other atoms, which Appearance → Selection Styling → Atoms for selection only removes). It says so only for a selection compact against the scene, its radius a third of the scene’s or less: one spread through the scene, such as all four hemes of haemoglobin, has a share of it in front from any side, and the camera still turns to the clearest one - Lock target to selection: Enable View → Camera → Lock target to selection to keep camera focused on selected atoms while changing presets - Manual camera adjustment: After applying a preset, use mouse drag (orbit) or Shift+drag (pan) to fine-tune the view. Scroll (or the toolbar’s − / +) changes distance by a fixed fraction of the current distance, so the zoom rate feels the same on a small molecule and a large cell - Reset View (toolbar): Restores the default orientation and then re-fits the scene, unlike the presets, which leave target and distance alone

Session Persistence: The current camera state (yaw, pitch, roll, distance and target, with the projection, field of view and orthographic extent) is saved when you use Ctrl+S to save a session. A session saved before roll was recorded reopens upright. When you reopen the session, the camera returns to the saved position regardless of which preset was active.

3.10.3 Custom Camera Configurations (CLI)

The CLI render command accepts a --camera <path.json> option to specify custom camera positions for automated rendering workflows.

JSON Format:

{
  "position": [x, y, z],
  "target": [x, y, z],
  "distance": float,
  "yaw_radians": float,
  "pitch_radians": float,
  "roll_radians": float,
  "fov_degrees": float,
  "projection": "Perspective",
  "ortho_half_extent": float
}

All fields are optional. The three that describe where the camera is:

• position: [0.0, 0.0, 10.0] — Camera location in 3D space (Ångströms)
• target: [0.0, 0.0, 0.0] — Point the camera looks at (Ångströms)
• distance: 10.0 — Distance from target (Ångströms, minimum 0.001)

When position and distance disagree, position wins and the distance is recomputed from the pose. A distance that contradicts the position would put the eye somewhere the file never described, so the pose is treated as the authority. Give distance alone and the camera is placed that far along +Z from the target.

Six more are optional and recorded only when a file states them; a file that omits one leaves the reader’s own default in place:

• yaw_radians, pitch_radians — the orbit angles, for a reader that works in angles rather than in a pose.
• roll_radians, the turn about the view direction, in radians, for a figure that is not upright. Omit it and the camera is not rolled.
• fov_degrees — the lens, which a position and a target cannot express.
• projection — "Perspective" or "Orthographic" (capitalised, as written).
• ortho_half_extent — the half-height of the orthographic frustum, which is what sets the zoom when projection is orthographic.

Example JSON Files:

// cameras/front.json (equivalent to Front preset)
{
  "position": [0.0, 0.0, 10.0],
  "target": [0.0, 0.0, 0.0],
  "distance": 10.0
}

// cameras/side.json (equivalent to Side preset)
{
  "position": [10.0, 0.0, 0.0],
  "target": [0.0, 0.0, 0.0],
  "distance": 10.0
}

// cameras/top.json (equivalent to Top preset)
{
  "position": [0.0, 9.999, 0.01],
  "target": [0.0, 0.0, 0.0],
  "distance": 10.0
}

// cameras/closeup.json (custom close-up view; distance follows from position)
{
  "position": [3.0, 4.0, 5.0],
  "target": [1.5, 2.0, 0.0]
}

Usage with CLI Render:

# Render with front view preset
orbitron render molecule.xyz -o output.png --camera cameras/front.json

# Render with custom camera (only specify what you need to override)
orbitron render molecule.xyz -o closeup.png --camera cameras/closeup.json

# Omit --camera and the camera is framed to fit the scene
orbitron render molecule.xyz -o default_view.png

Reusing a camera from the viewer: you do not need to write the JSON by hand. Pose the molecule in the viewer, then File → Export → Export Appearance Bundle… records the camera along with the theme. orbitron render --appearance <bundle.json> renders from that pose. An explicit --camera still takes precedence over the bundle’s camera. Hand-written camera JSON remains useful for scripted views.

Coordinate System: - X-axis: Right in Front view - Y-axis: Up in Front view - Z-axis: Out toward viewer in Front view - Units: Ångströms (Å) - Origin: Typically the molecular center of mass or geometry center

3.10.4 Implementation References

• Preset enum: ui/shell/src/camera.rs (CameraPreset { Front, Side, Top })
• Preset application: ui/shell/src/camera.rs (apply_preset method)
• Keyboard bindings: ui/shell/src/keyboard.rs (interpret_plain_key: Digit1/2/3 → Front/Side/Top)
• Camera menu: ui/shell/src/menu/camera_menu.rs (the preset buttons, under a “Presets:” label)
• Session state: ui/shell/src/session/types.rs (CameraState struct)
• CLI camera config: automation/cli/src/handlers/commands/convert.rs (read_camera_config)
• CameraConfig struct: core/services/src/renderer/types.rs (definition and defaults)

3.11 Session Files

Orbitron saves a session as a .orbpack bundle: the scene’s data, the view it was posed at, and this window’s own state — camera, selections, measurements, annotations, overlays, export settings, appearance — in one file.

The window state rides as a JSON attachment inside the bundle, in the shape documented below. A session used to be that JSON alone, next to a path to the structure file; moving or deleting that file left a session that restored your panels onto an empty viewport. Sessions written in the old form still open.

3.11.1 Saving and Loading Sessions

Saving: - Keyboard shortcut: Ctrl+S - Menu: File → Save Session - Default filename: session.orbpack - Writes the scene, the view and the window state to one bundle

Loading: - Keyboard shortcut: Ctrl+Shift+O - Menu: File → Open Session… - Restores all saved state from the bundle - The structure comes from the bundle itself, so the original file need not still be there - Also reads a legacy .orbitron.json session, loading its source_path if that file still exists

New Session: - Keyboard shortcut: Ctrl+N - Menu: File → New Session - Resets viewer to default state (clears scene, selections, overlays, etc.)

3.11.2 Session bundle contents

The .orbpack contains a canonical document with the active scene as its primary structure. That structure includes atoms, bonds, cell, parsed results, and the editable molecular charge/multiplicity. The session-specific JSON is an internal attachment beside it.

The attachment preserves the active and inactive Orig/Edited scene branches, active trajectory frame, camera and projection, selection and measurement state, panel state, appearance and lighting, cartoon and visibility flags, groups, overlays, annotations, and export settings. Fields use serde defaults so an older session can acquire sensible values for state introduced later.

It also embeds every live volume dataset and its display settings. Moving the session away from the original CUBE, XSF, MRC2014, or CCP4 source does not remove the grid or change its contour. Recorded source paths and hashes remain useful provenance, but loading the session does not reread those paths.

The undo/redo command history, transient background jobs, generated GPU meshes, and window position are not persisted. Expensive derived objects may be rebuilt from the canonical data after load.

3.11.3 Portability and compatibility

The primary structure is inside a current .orbpack, so the original source file does not need to travel with it. A session may still refer to external overlay or companion files. A missing external file is reported and that item is skipped; the bundled scene and the rest of the window state still restore.

Legacy .orbitron.json files are also accepted. Those files store a source_path rather than a structure, so their source file must still exist. Open a legacy session and save it as .orbpack to make the primary scene self-contained.

Bundle metadata and producer stamps describe the portable container. The session attachment evolves through additive fields with defaults. A newer Orbitron can read old session state; an older build may ignore newer state or fail on a newer bundle schema.

Do not hand-edit a .orbpack: it is a binary container with hashes and typed attachments. The legacy JSON form remains readable for migration, but Orbitron does not write it as the current session format.

3.11.4 Typical Workflows

Workflow 1: Publication Figure Preparation 1. Load molecular structure (Ctrl+O) 2. Adjust camera angle and zoom to desired view 3. Customize appearance (colors, bond styles, lighting) 4. Add annotations (labels, arrows) to highlight features 5. Load overlays if comparing structures 6. Save session (Ctrl+S) as figure1.orbpack 7. Export image with custom preset 8. Later: Reload session to make minor adjustments without re-configuring everything

Workflow 2: Multi-Structure Comparison 1. Load base structure 2. Add overlay structures via Overlay Manager 3. Adjust overlay transforms (translation, rotation) to align features 4. Toggle overlay visibility to compare 5. Save session to preserve overlay configuration 6. Share the session file; include only external overlay or companion files it uses

Workflow 3: Teaching Materials 1. Load example molecule 2. Add annotations explaining key features 3. Set up measurement (bond lengths, angles) 4. Enable presentation mode for clean view 5. Save session for each concept (e.g., lesson1_bond_angles.orbpack) 6. Distribute the .orbpack sessions to students

3.11.5 Implementation References

• Session state types: ui/shell/src/session/types.rs
• Save logic: ui/shell/src/session/save.rs
• Load logic: ui/shell/src/session/load.rs
• Restore logic: ui/shell/src/session/restore.rs
• File dialogs: ui/shell/src/session/dialogs.rs
• Annotation type: viewer/core/src/ui_state/annotation_state.rs (AnnotationItem)
• Overlay type: viewer/core/src/ui_state/overlay_state.rs (OverlayKind)