Graphical Viewer

3.1 Launching

Three ways to launch the viewer:

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

# Method 2: Via CLI wrapper (requires CLI installation)
orbitron view fixtures/benzene.xyz

# Method 3: 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 the binaries on your PATH and invoke orbitron-viewer … or orbitron view … from any terminal.

The orbitron-viewer binary itself takes only a file path, plus -h/--help and -V/--version. The launch flags belong to orbitron view (pass them after the command):

• --select "nearest_atoms(1, 5)" highlights atoms on load (atom ids are 1-based).
• --freq chooses vibrational data when both optimization and frequency results exist.
• --tui launches the terminal viewer instead of the GUI.
• --blank opens a new, empty viewer window (skips file loading).

You can also drag-and-drop supported files into the window or use File → Open… (⌘ Cmd+O on macOS, Ctrl+O elsewhere). For VASP runs, open any canonical file directly — vasprun.xml, POSCAR, CONTCAR, OUTCAR, INCAR, KPOINTS, POTCAR, DOSCAR, EIGENVAL, PROCAR, CHGCAR/CHG/PARCHG, XDATCAR, or DYNMAT — and Orbitron auto-switches to Analysis → Sources showing every companion file in the same directory. 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 forces (D4 force arrows), and per-atom magnetic moments (D5 magmom halo) 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 status bar and progress overlays for updates.

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

• Viewport: Left drag orbits, right 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. Hold Shift while dragging to translate faster; adjust sensitivity in View → Camera.
• Toolbar & status bar: Toggle via View → Panels. 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 (labels, unit cell, cartoon), 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 status bar surfaces status text, FPS, and active measurement.
• 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, Compare, and Scene; in edit mode they are Geometry, Measurements, Appearance, and Scene. Press H or use Help → Keyboard Controls to open the help table; Ctrl+Shift+H clears analysis overlays.
• Task sidebar: Appears automatically for Gaussian/NWChem files, letting you load optimization stages, frequency data, or task-specific geometries without reloading the file.
• 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, status bar, 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:195-202

3.3 Keyboard reference

macOS: the application shortcuts below — Open, saved-session Open, New, Save, 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
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” is available in the View → Selection menu but does not have a keyboard shortcut. The A key is mapped to angle measurement mode instead.

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.

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. The navigator can locate unresolved residues even though they have no atoms to select.
• 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 mononuclear centres, their named donors, distances, and Orbitron’s closest supported coordination geometry.

Steric clashes scans the active alternate-location view and lists each nonbonded pair closer than 80% of its summed van der Waals radii. Bonded and 1-3 pairs are excluded. 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. Results run from greatest overlap to least. Select pair replaces the selection with those two atoms, while Add pair extends the current selection.

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 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 side-chain atoms compares coordinate-bearing amino acids with the expected non-hydrogen side-chain atoms for their residue template. The summary reports affected residue conformers and missing atoms; each row names the absent atoms. Select residue and Add residue act on the atoms that are present, which makes the incomplete site visible in the 3D scene.

The check requires a retained CA atom, so a fully unresolved sequence entry or an isolated coordinating atom named as part of an amino acid is not reported as a repairable side chain. Missing backbone atoms and 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 side-chain 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 — Right-drag to draw a rectangle; all atoms inside the box are selected
3. Lasso — Right-drag to draw a freeform polygon; all atoms inside the lasso are selected

Box and Lasso apply in edit mode (Ctrl+E), where Shift+S also cycles the tool. 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) — edit mode only

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
• Status bar 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 Style button (Ball & Stick / Space Fill / Atoms Only).
• Toggle atom labels, indices, and bonds from the Appearance panel (atom labels are off by default).
• A PDB or mmCIF structure with alternate coordinates gains Appearance → Alternate Locations. 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.
• Theme and colorblind palette toggles update both egui and renderer (render::set_colorblind_safe).
• Overlay Manager: Open the rail’s 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. Dataset cards also provide per-lobe checkboxes and an Export OBJ… action that writes positive/negative meshes alongside an .mtl file carrying their colours and transparency.
• Annotations: Add text labels and arrows as scene overlays for presentations and documentation. See §3.6 for detailed workflow documentation. Annotations render in export previews and final image exports.
• 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 pencil-thin 0.010 Å bond default, 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: Light gray

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.12 Å (varies by preset) - 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: 1.0

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.15 Å - 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.4 Å

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.2 Å

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 Technical mode) - Interacts with lighting preset (key/fill/rim intensities)

Line-only Mode: Checkbox (enabled in Technical style) - 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 ~1.0) - 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 ~1.0) - Thickness multiplier for triple bonds (order = 3)

Aromatic Thickness: 0.5–1.5 (slider, default ~0.8) - 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.0) - 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.2) - 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 some styles (e.g., Technical line mode)

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 some styles

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: viewer/core/src/ui_state/appearance/enums.rs (BondCapStyle, BondColorMode, BondMultiBondLayout)
• Render thickness calculation: viewer/core/src/render_styles.rs (order_thickness, applied in apply_theme_styles)
• 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	✓	✓	✓	✗ (line mode)
Taper	✓	✓	✓	✗ (line mode)
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 — 4960×7016 (A0 @300 DPI), opaque PNG, Adobe RGB, 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 status bar 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–12,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 status bar)

Color Profiles: - sRGB (default) — Standard profile for web and screen display - Adobe RGB (wide gamut) — Wider color gamut for print workflows, uses gamma 2.2 encoding - Grayscale Safe — Converts to Rec.709 luminance for monochrome outputs

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 status bar 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 status bar 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 preset(s) to <folder>" - On failure: "Exported N preset(s) to <folder>; failed M preset(s): <names>"

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 (§7.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.

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.6 Analysis panels

• Overview: Shows molecular identity and the permanent dipole, when parsed, as a Debye magnitude plus x/y/z components in the source coordinate system.

• Tasks: Lists stages for Gaussian (GaussianRunSummary), NWChem (NwchemRunSummary), ORCA, DIRAC, QE, Molpro, and Molcas/OpenMolcas runs under per-application headers. Expand a task/stage card to inspect method, basis, implicit solvation, energies, thermochemistry, SCF convergence, and any available diagnostics; use the Load… button to make a 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. Progress and cancellation controls appear at the bottom of the panel.

  • NWChem Task Status Indicators: Each NWChem task displays a colored status circle indicating its completion state:
    • Green circle: Task completed successfully with all expected data
    • Yellow circle: Task incomplete (terminated early but contains partial usable data)
    • Red circle: Task failed (no usable data extracted)
    • Gray circle: Status unknown (unable to determine outcome)
  • 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 shows all tasks with their status indicators so you can manually select any task with usable data. Incomplete tasks with frames or frequency modes can still be loaded by clicking them—Orbitron will load whatever data is available.

• Sources: Companion-file overview for multi-file formats. 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 + .log + .molden + .cube), Molcas (.out + .input + .opt.xyz + the orbital family (.ScfOrb, .RasOrb, .GssOrb, .LprOrb, .Mp2Orb) plus .molden 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.

  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 data is parsed but a dedicated QE Spectra panel that plots it is future work.

  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). The IR/Raman spectrum has a Pop out button that opens it in a resizable window with Save PNG and Export CSV.

• 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).
  • 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.
  • 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 Å; Replace 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 Mulliken, Löwdin, Natural (NBO), and APT charges (each emitted by the population data the scene’s parser found).
  • Orbitals tab → “Show as halo” on any MO row colors atoms by their contribution to that orbital.
  • NBO tab → “Show as halo” on the selected NBO orbital colors atoms by NBO contribution (coefficients from the loaded archive).
  • 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 / APT). 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. “Generate Mesh” renders the orbital as a 3D isosurface; “Show as halo” colors atoms by per-atom contribution to the orbital.

• Slice (appears when the scene carries a basis set): a 2D real-space cross-section of a molecular orbital (signed) or the electron density, drawn as a contour heatmap on a plane through three picked atoms. Pick the three atoms in the viewport to define the cutting plane, choose Orbital vs Density, then select the MO; the in-plane atoms and iso-contour lines are overlaid on the field. The field re-evaluates only when the scene, plane, MO, or resolution changes.

• 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), and DIRAC relativistic response. 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.

• Bands & DOS (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. 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: viewer/core/src/ui_state/atom_color_scheme.rs
  • 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: viewer/core/src/ui_state/analysis_state.rs::signed_contributions_for_mo
  • NBO contribution math: io/pipelines/src/formats/nbo/.../coefficients.rs::signed_atom_contributions_for
  • Surfaces panel: ui/shell/src/panels/analysis/orbital_surfaces/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 at the bottom of the rail’s Scene section, below the scene-info and properties content. - 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) - New annotations are automatically selected and visible - 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) - Annotations use normalized viewport coordinates (0.0–1.0), so they stay positioned relative to the viewport when resizing - 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" - 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) - 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: - 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. Select each annotation and customize text, color, size, and boldness in the panel 5. Toggle visibility checkboxes to show/hide specific layers 6. Disable Annotation mode when done positioning 7. Export the image with annotations included - VASP: When a VASP scene is loaded the VASP tab shows a Run Overview (system, Fermi level, band gap, magnetisation, free / 0 K energy, spin channels, DOS grid, k-path length) plus interactive total-DOS and band-edge plots — each with a Pop out button that opens a larger resizable window with Save PNG and Export CSV — inline CSV export buttons, and an attachments ledger of the companion files Orbitron has parsed. When per-atom data from sibling OUTCAR or ACF.dat is present, a Per-atom overlays section appears at the bottom with: - Magnetic moment → Show as halo (spin-polarized runs only): atoms colored by the per-atom moment’s tot column from OUTCAR’s magnetization (x) block. Positive (spin-up) red, negative (spin-down) blue. - Bader charges → Show as halo (when an ACF.dat from the Henkelman bader tool sits next to the run): atoms colored by net charge Z − bader_population. Same red-positive / blue-negative convention as the other charge schemes. - Forces → Show arrows (any run with OUTCAR or vasprun.xml forces): per-atom arrows render as cylinder shaft + thicker head, colored teal → orange by |F| magnitude. The Arrow scale (Å per eV/Å) drag-value tunes visual length. Useful for diagnosing relaxation hotspots. - Periodic bonds and ghosts: 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. 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. - Show periodic image atoms (ghosts) — the 26 surrounding image cells at reduced opacity, with a Ghost opacity slider. Off by default; it is a lot of geometry and it is context rather than structure.

Both are display only. Neither 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. - 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. - Find primitive cell, Supercell…, Cell parameters…, Niggli reduce…, Apply symmetry…, 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 only for now (variable-cell NPT runs use the first-frame lattice). - 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

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 three 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
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.	A drawn or hand-built sketch whose angles are wrong.
Symmetrize Geometry	Snaps atoms onto the detected point group.	A nearly-symmetric structure you want exactly symmetric.

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. 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.

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 Geometry is in both the Edit menu and the rail’s Geometry section, labelled with the detected group (Symmetrize Geometry (D₃d)). It is disabled when the group is C₁ or the molecule is too large to detect.

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) 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.

Snap Coordination Sphere moves a selected metal’s donors onto its ideal geometry, keeping the metal and every bond length where they are.

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.
• 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.

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 planar, 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)

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 Fragment Palette 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 have atoms selected, the fragment palette automatically suggests a default fragment based on the selected element: - Carbon (C, element 6) → defaults to Methyl - Oxygen (O, element 8) → defaults to Hydroxyl

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… (Alt+C, requires atoms to be selected) 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 element to {symbol}” - 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, status bar 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 Edit Panel 2. Click Choose… to open the “Placement Element” dialog 3. Click the N (nitrogen) button in the periodic table 4. Dialog closes, Edit Panel shows “Element: N (7)” 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:65 (render_periodic_table) - Window handler: ui/shell/src/viewer_loop/change_element/window.rs:12

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 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 side-chain 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 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).
• Status toasts appear in the lower-right corner for confirmations (exports, measurements, theme toggles, etc.). The status text in the title bar can be toggled with T.
• Press P to open the diagnostics overlay (egui window) that shows FPS and background loader progress. The overlay can be closed with P again or via the button inside the panel.
• Toggle diagnostic information via the status bar menu to display camera data and loader statuses.

3.9 Overlay Manager

The Overlay Manager (the 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 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. File picker opens supporting: - Geometry: XYZ, PDB, CIF formats - Volumetric: CUBE, XSF files 3. Selected files load in the background (large volumetric files show progress in status bar) 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 Output and Editable scenes exist (e.g., after loading a computational chemistry output file with editable geometries): - 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 (Kabsch algorithm) 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., “RMSD: 0.42 Å, 18 atoms matched”) or errors

Alignment Algorithm: - Uses Kabsch algorithm for optimal rigid-body superposition - 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 selection to align” (Selection scope but no atoms selected) - “Fewer than 3 atoms matched” (insufficient atoms for rotation alignment) - “No matched atoms” (no common IDs found)

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) - Export OBJ… (per-overlay action on volumetric cards): Exports positive/negative mesh isosurfaces with .mtl material file

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 - Status bar and toasts report when background jobs queue/finish

Implementation References: - Panel rendering: ui/shell/src/panels/overlays.rs:49 - 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 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 Gaussian optimization output (creates Output + Editable scenes) 2. Open the 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 from the toolbar (Output ↔︎ Editable — e.g. entering/exiting edit mode)

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)

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 View → 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 rig whose up direction is fixed to world up, so this sets the viewing direction but not the roll. 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): Set target to selection center, adjust distance to fit selected atoms, then apply preset - 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, distance, target) is saved when you use Ctrl+S to save a session. 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
}

All fields are optional and default to: - 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)

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)
{
  "position": [3.0, 4.0, 5.0],
  "target": [1.5, 2.0, 0.0],
  "distance": 3.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 to use default position
orbitron render molecule.xyz -o default_view.png

Creating Custom Camera JSON: 1. Open your molecule in the viewer 2. Adjust the camera to the desired position using mouse controls 3. Note the camera coordinates (currently no GUI export feature—manual creation required) 4. Create a JSON file with the position, target, and distance values 5. Use the JSON file with orbitron render --camera <path>

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:80 (CameraState struct)
• CLI camera config: automation/cli/src/handlers/commands/convert.rs:14 (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:24 (AnnotationItem)
• Overlay type: viewer/core/src/ui_state/overlay_state.rs:23 (OverlayKind)