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.app. On Windows/Linux launch the orbitron-viewer binary shipped with the release bundle.
Command-line launch: add the bin/ folder to your PATH and invoke orbitron-viewer … or orbitron view … from any terminal.

Useful flags (pass them after the command): - --select "nearest_atoms(0, 5)" highlights atoms on load. - --freq chooses vibrational data when both optimization and frequency results exist. - --remote [user@]host:/remote/root pre-configures the remote browser (connection details come from your ~/.ssh/config). - --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. Hold Shift while dragging to translate faster; adjust sensitivity in the Camera menu.
Toolbar & status bar: Toggle via View → Panels. Toolbar actions cover render modes, measurement toggles, and orbitals/NBO shortcuts; selection tools live in the Selection panel and menu. The status bar surfaces status text, FPS, and active measurement.
Unified panel (right side): Tabs for Selection, Measurements, Scene Info, Properties. 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.
Remote browser: File → Open Remote… opens a modal listing directories on the remote host over SSH/SFTP. Opening a file fetches it whole into a temporary location before parsing.
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 (edit mode)
`Z` / `X`	Selection history back / forward
`Ctrl+Z` / `Ctrl+Y`	Undo / redo edit operations
`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 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 & Panel

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 - Shift+click adds to selection - Ctrl+click toggles individual atom - Keyboard: Esc clears selection, Z/X navigate history

Selection Tools (Edit Mode Only):

When edit mode is active (Ctrl+E), the Selection panel exposes three selection tools:

Click — Single-atom picking (default behavior)
Box — Right-drag to draw a rectangle; all atoms inside the box are selected
Lasso — Right-drag to draw a freeform polygon; all atoms inside the lasso are selected

Toggle between tools using the Selection Tool section in the Selection panel, or via Shift+S keyboard shortcut. The active tool is displayed in the panel: "Active: Click", "Active: Box", or "Active: Lasso".

Selection Panel Features:

Open the Selection panel (Unified Panel → Selection tab) to access:

Selection Actions:
- Clear — Remove all highlights
- Select All — Highlight all atoms in the scene
- Invert — Toggle: selected ↔︎ unselected
- Expand — Add all atoms bonded to the current selection
Selection History:
- Orbitron tracks every atom click in a history list
- Back / Forward buttons navigate through history (keyboard: Z / X)
- Clear History removes all history entries
- Click any history entry to jump to that selection
- History shows: "Atom #<id> (<symbol>)" (e.g., "Atom #42 (C)")
By Element:
- Quick-select all atoms of a specific element: H, C, N, O, S, P
- Click element button to select all atoms of that type
Bond Editor (2 atoms selected):
- When exactly 2 atoms are selected and bonded:
  - Order selector: Single / Double / Triple (edit mode only)
  - Delete Bond button removes the bond (edit mode only)
- Order changes take effect immediately when edit mode is active
Atom Label (1 atom selected):
- Shows auto-generated label: "Auto label: C1" (element + index)
- Text field to set custom label override
- Reset label restores auto label for selected atom
- Reset all clears all label overrides in the scene
- Label overrides persist in saved sessions

Selection Menu:

Access additional selection operations via Selection menu: - Selection → Select All, Invert Selection, Expand to Bonded - Selection → By Element submenu (H, C, N, O, etc.) - Selection → Selection Tool submenu (Click, Box, Lasso) — edit mode only

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:

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)
The panel shows progress: "Selected atoms: 2 / 2" (for distance)
When complete, the measurement value appears in the Current measurement section
Save adds the measurement to history
Clear resets the buffer to start a new measurement
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:

Make or select a measurement (distance/angle/dihedral)
In the Current measurement section, the Value column shows:
- Current computed value: "1.43 Å" (read-only)
- Arrow: "→"
- Editable target value (DragValue widget + Slider below)
Drag the value or use the slider to set a target
The diff appears next to the slider: "(+0.12 Å)" in accent color
Apply button becomes enabled (highlighted in cool accent color)
Click Apply to run the constraint solver and move atoms
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:

Enter edit mode (Ctrl+E)
Activate distance measurement mode (D)
Click two bonded atoms
Drag the target value from 1.43 Å to 1.55 Å
Click Apply — the second atom (and its subtree) moves to satisfy the constraint
The measurement updates to show the new computed value
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/panels/selection.rs, ui/shell/src/panels/measurements.rs ### 3.5 Rendering & appearance

Switch render styles via M or the toolbar Style button (Ball & Stick / Space Fill / Wireframe).
Toggle atom labels, indices, and bonds from the Appearance panel (atom labels are off by default).
Theme and colorblind palette toggles update both egui and renderer (render::set_colorblind_safe).
Overlay Manager: Open the Overlays tab 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). When browsing a remote host, the Add CUBE overlay button fetches volumetric datasets and the Add overlay button fetches XYZ/PDB/CIF geometry over SFTP before the layer appears. 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.4.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.4.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.4.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 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.1 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.2 Image Settings

Format: - PNG (with alpha transparency) - TIFF (16-bit depth) - JPEG (no transparency support) - SVG, PDF, EPS (vector formats, beta)

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.3 Advanced Export Tools

Open the Advanced Export Tools 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:

Configure desired settings (resolution, format, post-processing, etc.)
Enter a name in the “Name” field
Click Save preset to persist the configuration
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.4 Batch Export

Export multiple presets in one operation:

Open Advanced Export Tools
Check the Batch Export Queue checkboxes next to built-in presets (Slide HD, Poster A0, Nature 1-col) or custom presets
The status line shows: Batch queue: X built-in / Y custom
Click Batch Export Presets… (enabled only when queue has ≥1 preset)
Select an output folder
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.5 Additional Export Tools

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 VASP bundle… — Package VASP calculation outputs into a structured .orbitron directory (same as orbitron pack vasp CLI command):
- orbitron.json canonical metadata
- Spin-resolved DOS and band-envelope CSVs
- Quick-look PNG plots for DOS and band envelopes
- Optional raw VASP files (OUTCAR, vasprun.xml, DOSCAR, etc.)
- Optional 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 VASP electronic structure data to CSV (enabled only when VASP dataset is loaded and has usable DOS/band data)

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

Tasks: Lists stages for Gaussian (GaussianRunSummary), NWChem (NwchemRunSummary), Molpro, and Molcas/OpenMolcas runs under per-application headers. Expand a task/stage card to inspect method, basis, energies, thermochemistry, and any available diagnostics; use the Load… button to make a Gaussian/NWChem/Molpro task the active scene. 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), 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:
  - Cube / XSF datasets loaded via “Add cube/XSF…”
  - 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 lobe color pickers, opacity. Mesh-status badges show “cached” / “(will compute)” so stale meshes are obvious.
- 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 the cube/xsf parser recognizes (matches presets):
  - 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.
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.
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.
Charge / halo session persistence:
- Surface mesh cache, halo scheme + colors + opacity, and per-row settings save with sessions.
- Loaded NBO archive metadata persists; coefficients re-read from the file paths recorded in the session.
- Volumetric file paths stored relative to the session file when possible.
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)
Annotations: Add text labels and arrows as a scene overlay for presentations, documentation, or highlighting features of interest. Open the Annotations panel (Analysis → Annotations) to manage annotation layers.
- 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.
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.1 for detailed workflow.
Remote: The remote modal caches directory listings and supports navigating into directories, stepping back (..), and downloading files. Downloads resume if the window stays open; closing cancels the transfer.

3.7 Edit mode

Toggle via Ctrl+E or the toolbar Mode toggle. The selection outline turns orange, and edit-specific panels become active. Use Edit → Exit Edit Mode… when you want the commit/discard dialog.
Placement tools:
- Place Atom: toggles click-to-place mode. Click in the viewport to drop atoms; placement stays active until you click Place Atom again or press Esc.
- Place Fragment: toggles fragment placement in the same way (pick a fragment preset first).
- Choose… sets the placement element (periodic table or text input); it does not modify selected atoms.
Selection edits:
- Change Element… applies to the current selection (via Edit menu). Use the periodic table grid or type a symbol/atomic number, then apply.
- Add/delete bonds and set bond order (single/double/triple).
- Delete selected atoms.
Geometry tools:
- Clean geometry (Edit → Clean Geometry → Clean Selected / Clean All) to spring-relax atoms with a lightweight heuristic.
- Translate selected atoms with gizmos; Lock target to selection keeps the camera centre on edited atoms.
Undo/redo stacks are maintained while in edit mode. Attempting to exit shows a dialog (edit_exit_dialog) letting you commit, discard, or cancel.

3.7.1 Fragment Palette

The Fragment Palette lets you insert pre-built molecular fragments from a built-in library into your scene. Fragments are attached via single bonds with automatic hydrogen cleanup at the anchor site.

Available Fragments: - 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. Edit Panel (recommended): Enable edit mode (Ctrl+E), click Place Fragment, then click Choose… to open the palette 2. Menu: Edit → Advanced → Add Fragment… (requires an anchor atom to be selected)

Insertion Workflow:

Option 1: Place Fragment Mode (viewport-based placement) 1. Enable edit mode (Ctrl+E) 2. In the Edit Panel, click Place Fragment to enter placement mode 3. Click Choose… to open the Fragment Palette window 4. Select a fragment from the scrollable list (methyl, hydroxyl, or phenyl) 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: Before placement, Orbitron removes one hydrogen bonded to the anchor atom (FragmentCleanup::RemoveSingleHydrogen) - 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 Å (phenyl) - Bond order: All fragments attach with single bonds (BondOrder::Single) - Placement origin: If no anchor is selected (rare), fragments are placed near the scene center or current focus point

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:10 - Edit panel integration: ui/shell/src/panels/edit.rs:137

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 Place Fragment in the Edit Panel 4. Click Choose… 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.2 Change Element Dialog

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

Opening the Dialog: 1. Edit Menu: Edit → Change Element… (requires atoms to be selected) 2. Edit Panel: Click Change Element… button (requires atoms to be selected) 3. Placement element: Click Choose… in the Edit Panel when Place Atom mode is active

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) - Requires: Place Atom mode active - Window title: “Placement Element” - Sets the default element for future atom placements - 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.8 Background tasks & diagnostics

File loads, exports, task downloads, and long-running mesh generation run out-of-band. A spinner overlay shows progress; 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 (accessible via the Overlays tab in the unified panel) 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: - Click the Overlays tab in the unified right panel - 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

Remote Overlays: When a remote target is configured (File → Configure Remote…): - Add overlay button loads XYZ/PDB/CIF geometry from the remote host over SFTP - Add CUBE overlay button loads volumetric datasets from the remote host over SFTP - Progress shows in status toasts and overlay status badges

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 (.orbitron files) restore 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 - Remote overlays are fetched over SFTP (whole-file) before the layer appears

Implementation References: - Panel rendering: ui/shell/src/panels/overlays.rs:49 - Overlay state management: ui/shell/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 Overlays tab 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 Overlays tab, 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 Remote configuration & browsing (SSH/SFTP)

The Remote Browser opens files on a remote host over SSH/SFTP (see §6 for the model). It supports directory navigation and direct overlay integration; there is no server to run.

3.10.1 Configuration

Opening the settings: - Navigate to File → Configure Remote… (or Preferences → Remote data).

Settings: - Remote target: a scp-style spec [user@]host:/remote/root (e.g. mycluster:/scratch/$USER/runs). - The part before the first : is the SSH destination; a ~/.ssh/config Host alias works. - Port, identity file, ProxyJump, and 2FA all come from your ~/.ssh/config and ssh-agent. - Stored in ~/.config/Orbitron/config.toml (platform-dependent path).

File Loading Limits: - Max file size: Set maximum bytes for local or remote loads (0 = unlimited) - Applies to both GUI viewer and CLI commands - Prevents accidentally queuing multi-gigabyte files

Actions: - Test Connection: Opens the SSH session and lists the remote root, then displays the result. - Save: Persists the target to the config file. - Cancel: Closes dialog without changes

Environment Variable Overrides: ORBITRON_REMOTE overrides the saved target for the current process only. Set it to a scp-style [user@]host:/remote/root spec; connection details (port, identity, jump hosts) come from your ~/.ssh/config. Useful for one-off sessions without touching the persisted profile.

3.10.2 Remote Browser UI

Opening the Browser: - Navigate to File → Open Remote… (enabled only when remote URL is configured) - Window title: “Remote Browser” - Default size: 420×360 pixels (resizable)

Header Controls: - Path display: Shows current directory path (e.g., /structures/organic/, root is /) - Up button: Navigate to parent directory (disabled at root) - Refresh button: Reload current directory listing - Cancel button: Appears when jobs are in flight, cancels active download/listing

File/Directory List: - Scrollable vertical list of entries - Directories: Show name only (e.g., subdir/) - Files: Show name and size (e.g., molecule.xyz (1.2 MB)) - Selection: Click to select (single selection only), current selection highlighted - Double-click behavior: - Directory: Enter directory (triggers listing request) - File: Download and open in viewer (same as clicking Load button)

Footer Buttons: - Load: Download selected file and open in main viewer - Enabled only when file is selected (disabled for directories) - Downloads to temporary file in session-scoped temp directory - Add CUBE/XSF overlay: Fetch the selected volumetric file over SFTP and add it as an overlay - Enabled only when a .cube or .xsf file is selected - Add overlay: Fetch the selected geometry file over SFTP and add it as an overlay - Enabled only when an .xyz, .pdb, or .cif file is selected - Close: Closes browser window

Status Indicators: - Spinner + “Working…”: Active listing or download in progress - Error messages: Red text below header (e.g., “Remote listing failed for ‘/path’: connection refused”) - No configuration warning: “Remote access is not configured. Set ORBITRON_REMOTE (or configure it in Preferences) to enable this feature.”

3.10.3 Navigation Workflow

Directory Navigation: 1. Browser opens at root (/) with initial listing request 2. Double-click directory or select + Load → enters directory 3. Up button → navigates to parent (e.g., /structures/ → /) 4. Refresh button → reloads current directory listing 5. Path breadcrumb shows current location

Cached Listings: - Directory listings are NOT cached (each navigation triggers a fresh SFTP request) - Selection state resets when entering new directory - Error state persists until successful operation or manual Refresh

Navigation Edge Cases: - Up at root: No-op (button still enabled but no path change) - Double-click during download: Action ignored (UI busy) - Navigate while listing: Previous listing request continues in background, new request queued

3.10.4 File Loading

Download to Viewer (Load button): 1. Select a file, click Load. 2. A background thread fetches the file over SFTP into a NamedTempFile. 3. The browser shows a spinner while the fetch is in flight. 4. On completion the temporary file opens in the main viewer. 5. The temp file persists until the session ends.

Files are fetched whole — there is no byte-level progress bar and no incremental/range streaming, because the SSH/SFTP transport reads the complete file before parsing. Format support is identical to local loading: the same loaders run on the downloaded copy.

Overlay loading: - Add CUBE/XSF overlay and Add overlay (geometry) fetch the selected file over SFTP and add it as an overlay layer. The status badge shows “Pending” during the fetch and “Ready” when complete; the source label shows the remote host and path. The overlay descriptor (RemoteOverlayDescriptor) carries the scp-style spec and the remote path segments.

Cancellation: - The Cancel button (shown only while a job is in flight) requests cancellation via an Arc<AtomicBool>. Because a fetch is a single whole-file read, cancellation takes effect at the transfer boundary rather than mid-stream.

3.10.5 Error Handling

Connection and transfer errors surface as red text in the browser header or status bar, carrying the underlying ssh/sftp message — for example “Failed to reach the remote target” when the SSH handshake fails, or an SFTP “No such file” when a path is wrong. The first access opens the SSH session, so a key passphrase or 2FA prompt appears at that point (in the terminal Orbitron was launched from).

Invalid selections: - Load directory: “Cannot load a directory — select a file instead.” - Add overlay (wrong extension): “Selected file is not a .cube or .xsf volumetric dataset.” or “Geometry streaming currently supports XYZ, PDB, or CIF files.”

Recovery: Refresh retries the current listing (clearing the previous error); Test Connection in the settings verifies reachability before browsing.

3.10.6 Session Management

Temporary files: downloads land in a session-scoped temp location and are removed when Orbitron exits normally.
State persistence: the remote target is saved to ~/.config/Orbitron/config.toml; the browser path is not saved (it always opens at the remote root). Saved sessions record remote overlay descriptors (the referenced files must still be reachable on reload).
Concurrent operations: one listing or download runs at a time (in_flight: Option<RemoteInFlight>); a single shared RemoteContext backs the browser.

3.10.7 Transport

Listing and fetching run over the SSH/SFTP subsystem using the user’s system ssh (via the openssh / openssh-sftp-client crates). There is no HTTP API, no auth token, and nothing to deploy on the remote host beyond the standard sftp-server. Authentication, ports, identity files, and jump hosts are all handled by ~/.ssh/config and ssh-agent.

3.10.8 Implementation References

Browser UI: ui/shell/src/remote/browser.rs (show_browser)
Context state: ui/shell/src/remote/context/ (RemoteContext)
Background jobs: ui/shell/src/remote/context/jobs.rs (start_download_job)
SFTP backend: core/services/src/data_source/sftp/mod.rs (SftpDataSource)

Example workflow: 1. Configure the target: File → Configure Remote…, enter mycluster:/scratch/$USER/runs, save. 2. Open the browser: File → Open Remote…. 3. Navigate: double-click the gaussian_runs/ directory. 4. Select optimization.log. 5. Click Load; the file is fetched over SFTP and opens in the viewer.

3.11 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.11.1 Built-in Presets (Viewer)

Switch between standard orthogonal views using keyboard shortcuts or the Camera menu:

Preset	Shortcut	Menu Path	Camera Orientation
Front	`1`	`Camera → Presets → Front (1)`	Yaw: 0°, Pitch: 0°
Side	`2`	`Camera → Presets → Side (2)`	Yaw: 90°, Pitch: 0°
Top	`3`	`Camera → Presets → 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)

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

Session Persistence: The current camera state (yaw, pitch, distance, target) is saved when you use Ctrl+S to save a session (.orbitron file). When you reopen the session, the camera returns to the saved position regardless of which preset was active.

3.11.2 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.11.3 Implementation References

Preset enum: ui/shell/src/camera.rs:17 (CameraPreset { Front, Side, Top })
Preset application: ui/shell/src/camera.rs:182 (apply_preset method)
Keyboard bindings: ui/shell/src/keyboard.rs:58-60 (Digit1/2/3 → Front/Side/Top)
Camera menu: ui/shell/src/menu/camera_menu.rs:49-60 (Presets submenu)
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.12 Session Files

Orbitron saves complete viewer state to .orbitron.json files, allowing you to preserve camera positions, selections, measurements, annotations, overlays, export settings, and appearance customizations. Sessions are portable JSON documents that can be shared, versioned, and edited.

3.12.1 Saving and Loading Sessions

Saving: - Keyboard shortcut: Ctrl+S - Menu: File → Save Session - Default filename: session.orbitron.json - Saves current viewer state to JSON file

Loading: - Keyboard shortcut: Ctrl+Shift+O - Menu: File → Open Session… - Restores all saved state from JSON file - Automatically loads source molecular structure if path is valid

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

3.12.2 Session File Structure

Sessions are JSON files with the following top-level fields:

Core Scene State: - source_path (string, optional): Path to original molecular structure file - render_mode (string): Rendering style (“BallStick”, “Spacefill”, “Stick”, “Wireframe”, “Cartoon”) - show_atom_labels (boolean): Atom labels visibility - show_atom_indices (boolean): Atom index visibility - atom_index_base (number, 0-1): Index base (0 or 1) - show_bonds (boolean): Bond visibility - show_unit_cell (boolean): Unit cell box visibility

Camera State: - camera (object): Complete camera configuration - yaw (number): Horizontal rotation angle (radians) - pitch (number): Vertical rotation angle (radians) - distance (number): Camera distance from target (Ångströms) - target (array): Look-at point [x, y, z] (Ångströms) - camera_fov_degrees (number, default: 45.0): Field of view (degrees) - camera_projection (string): Projection type (“Perspective” or “Orthographic”) - camera_ortho_half_extent (number, default: 10.0): Orthographic zoom extent - camera_pan_sensitivity (number): Pan speed multiplier - pan_sensitivity_custom (boolean): Whether sensitivity is user-customized

Selection & Measurement: - highlighted_atoms (array): Selected atom IDs [u64, ...] - measurement_mode (string): Active mode (“None”, “Distance”, “Angle”, “Dihedral”) - measurement_buffer (array): Buffered atom IDs for measurement [u64, ...]

Appearance & Theme: - dark_theme (boolean): Dark mode enabled - colorblind_safe (boolean): Colorblind palette enabled - theme (object): Complete theme settings (ThemeSettings struct) - Atom/bond colors, sizes, styles - Lighting parameters - Background color - Bond rendering controls (thickness, taper, dash, halo, etc.) - See §3.5 for appearance controls - appearance_active_preset (string, optional): Active appearance preset name - lighting_active_preset (string, optional): Active lighting preset name - show_cartoon (boolean, default: false): Cartoon representation visibility - presentation_mode (boolean, default: false): Presentation mode active

Overlays: - overlays (array): List of overlay entries - Each entry contains: - name (string): Display name for overlay - source_label (string): Human-readable source identifier - source_path (string, optional): Path to overlay file (relative when possible) - kind (string): Overlay type (“SceneGeometry” or “VolumetricField”) - visible (boolean): Visibility toggle - translation (array): Position offset [x, y, z] (Ångströms) - rotation_deg (array): Rotation angles [rx, ry, rz] (degrees) - blend_mode (string, default: “Alpha”): Blend mode (“Alpha” or “Additive”) - show_base_scene (boolean, default: true): Base scene visibility

Annotations: - annotations (array): List of annotation items (AnnotationItem struct) - Each item contains: - id (number): Stable identifier (u64) - kind (string): Annotation type (“Text” or “Arrow”) - text (string): Label text (for Text annotations) - start (array): Start position [x, y] (normalized viewport coordinates 0.0–1.0) - end (array): End position [x, y] (for Arrow annotations) - visible (boolean, default: true): Visibility toggle - color (array): RGBA color [r, g, b, a] (0.0–1.0) - size (number, default: 16.0): Font size (points) or arrow thickness - font (string, default: “Sans”): Font family (“Sans” or “Mono”) - boldness (number, default: 1.0): Boldness multiplier (0.6–2.0) - annotation_mode (boolean, default: false): Annotation edit mode active

Export Settings: - image_export_profile (string, optional): Active export preset name - image_export_settings (object): Complete export configuration (ImageExportSettings struct) - Resolution (width, height) - DPI, color profile, safe margins - Watermark settings - Post-processing options - See §3.5 for export dialog documentation - custom_export_presets (array): User-defined export presets (CustomExportPreset struct) - batch_export_profiles (array): Selected built-in presets for batch export - batch_export_custom_presets (array): Selected custom presets for batch export

Miscellaneous: - status_text (string): Last status message - atom_label_overrides (array): Custom atom labels [[atom_id, "label"], ...] - auto_view_on_load (boolean, default: false): Auto-frame scene on load

3.12.3 Example Session File

{
  "source_path": "/path/to/molecule.xyz",
  "camera": {
    "yaw": 0.0,
    "pitch": 0.0,
    "distance": 15.0,
    "target": [0.0, 0.0, 0.0]
  },
  "render_mode": "BallStick",
  "show_atom_labels": true,
  "show_atom_indices": false,
  "atom_index_base": 0,
  "show_bonds": true,
  "show_unit_cell": true,
  "dark_theme": false,
  "colorblind_safe": false,
  "highlighted_atoms": [1, 5, 9],
  "measurement_mode": "Distance",
  "measurement_buffer": [1, 5],
  "status_text": "Distance: 1.543 Å",
  "atom_label_overrides": [[1, "C1"], [5, "O1"]],
  "camera_fov_degrees": 45.0,
  "camera_projection": "Perspective",
  "camera_pan_sensitivity": 1.0,
  "pan_sensitivity_custom": false,
  "show_base_scene": true,
  "show_cartoon": false,
  "auto_view_on_load": false,
  "presentation_mode": false,
  "overlays": [
    {
      "name": "Comparison Structure",
      "source_label": "molecule2.xyz",
      "source_path": "./molecule2.xyz",
      "kind": "SceneGeometry",
      "visible": true,
      "translation": [0.0, 0.0, 0.0],
      "rotation_deg": [0.0, 0.0, 0.0],
      "blend_mode": "Alpha"
    }
  ],
  "annotations": [
    {
      "id": 1,
      "kind": "Text",
      "text": "Active Site",
      "start": [0.3, 0.5],
      "end": [0.3, 0.5],
      "visible": true,
      "color": [0.91, 0.55, 0.28, 1.0],
      "size": 18.0,
      "font": "Sans",
      "boldness": 1.2
    },
    {
      "id": 2,
      "kind": "Arrow",
      "text": "",
      "start": [0.2, 0.6],
      "end": [0.4, 0.4],
      "visible": true,
      "color": [1.0, 0.0, 0.0, 1.0],
      "size": 14.0,
      "font": "Sans",
      "boldness": 1.0
    }
  ],
  "annotation_mode": false,
  "theme": {
    "atom_base_radius": 0.35,
    "bond_thickness": 0.12,
    "background_color": [0.95, 0.95, 0.95],
    "...": "additional theme fields omitted for brevity"
  },
  "image_export_profile": "Publication",
  "image_export_settings": {
    "width": 3000,
    "height": 2000,
    "dpi": 300,
    "...": "additional export fields omitted for brevity"
  },
  "custom_export_presets": [],
  "batch_export_profiles": ["Publication", "Presentation"],
  "batch_export_custom_presets": []
}

3.12.4 File Paths in Sessions

Relative vs Absolute Paths: - source_path and overlay source_path fields store file paths - Orbitron attempts to save relative paths when possible (relative to session file location) - Absolute paths used when files are outside session directory tree - On load, Orbitron tries both relative and absolute interpretations

Portability: - Store session file alongside molecular structure files for maximum portability - Use relative paths (e.g., ./data/molecule.xyz) when sharing sessions - Absolute paths (e.g., /home/user/molecules/benzene.xyz) may break when moving sessions

Missing Files: - If source_path is invalid on load, Orbitron shows error toast but loads session state - Missing overlay files skip loading with warning toast - Camera, selections, and settings still restore correctly

3.12.5 Session Versioning and Compatibility

Format Stability: - Session format uses Rust’s serde serialization with #[serde(default)] for backward compatibility - New fields added with default values to maintain compatibility with old sessions - Old sessions loading in new Orbitron versions: ✅ Supported (missing fields use defaults) - New sessions loading in old Orbitron versions: ⚠️ May work (unknown fields ignored, but new features won’t load)

Version Markers: - No explicit version field in current format - Compatibility inferred from present/absent fields - Format considered stable as of first release

Schema Evolution Examples: - atom_index_base added with #[serde(default = "default_atom_index_base")] → Old sessions default to 0 - show_unit_cell added with #[serde(default = "default_show_unit_cell")] → Old sessions default to true - camera_fov_degrees added with default function → Old sessions use 45.0°

3.12.6 What’s Saved vs Not Saved

✅ Saved in Sessions: - Camera state (position, orientation, projection, FOV) - Selection state (highlighted atoms, measurement mode, measurement buffer) - Appearance settings (theme, colors, bond styles, lighting) - Overlays (geometry and volumetric, with transforms and visibility) - Annotations (text labels, arrows, with positions and styles) - Export settings (active preset, custom presets, batch export selections) - UI state (dark mode, colorblind mode, presentation mode, label visibility) - Custom atom labels

❌ Not Saved in Sessions: - Molecular structure data (only path stored; file must exist on load) - Task metadata (Gaussian/NWChem/Molpro/Molcas run summaries; reloaded from source file) - Orbital meshes (regenerated from CUBE files on load) - NBO data (reloaded from source .47 files) - Frequency animation state (cleared on load) - Window size/position - Panel layout (always uses default layout) - Undo/redo history (edit mode state not preserved)

3.12.7 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.orbitron.json 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 session file with collaborators (include all structure files)

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.orbitron.json) 6. Distribute sessions to students with structure files

3.12.8 Manual Editing

Sessions are human-readable JSON and can be manually edited:

Safe Edits: - Change source_path to point to different file - Adjust camera position (yaw, pitch, distance, target) - Modify colors (RGBA arrays) - Change annotation text content - Toggle visibility flags (visible, show_atom_labels, etc.) - Update status_text message

Advanced Edits: - Batch-modify annotation positions - Copy/paste overlays between sessions - Merge custom export presets from multiple sessions - Script-based session generation for batch visualization

Caution: - Invalid JSON syntax will prevent loading - Invalid field values may cause errors or be silently ignored - Atom IDs (highlighted_atoms, measurement_buffer) must match actual atoms in structure - Maintain array structure for arrays (don’t mix types)

3.12.9 Implementation References

Session state struct: ui/shell/src/session/types.rs:20 (SessionState)
Camera state struct: ui/shell/src/session/types.rs:80 (CameraState)
Overlay entry: ui/shell/src/session/types.rs:210 (SessionOverlayEntry)
Save logic: ui/shell/src/session/save.rs:10 (build_session_state)
Load logic: ui/shell/src/session/load.rs:236 (load_session_from_path)
Restore logic: ui/shell/src/session/restore.rs (session state → viewer state)
File dialogs: ui/shell/src/session/dialogs.rs:106 (save_session_via_dialog)
Annotation type: viewer/core/src/ui_state/annotation_state.rs:24 (AnnotationItem)
Overlay type: viewer/core/src/ui_state/overlay_state.rs:23 (OverlayKind)