Terminal UI

Run from automation/tui:

orbitron-tui fixtures/benzene.xyz

Note: The binary requires an interactive terminal. If you see Terminal initialization failed: Device not configured, run the command directly in iTerm/Terminal rather than inside an IDE pane.

Before parsing a source or switching into raw terminal mode, the TUI estimates the load’s peak host memory from its file type, size, and any counts available in the first 64 KiB. A tight projection is shown in the ordinary terminal and defaults to cancellation unless you enter y. A configured max_memory cap refuses the load. To set a cap for one launch, use the CLI entry point:

orbitron --max-memory 8589934592 view calculation.out --tui

Use --allow-large with either orbitron-tui or orbitron view --tui to skip an advisory confirmation after checking the risk. The flag cannot bypass a configured cap or a projection beyond physical memory and swap.

The TUI shares loader/analysis code with the CLI but renders via ratatui. It is keyboard-first and pane-focused: at any moment one pane is focused and owns the contextual keys, and Tab / Shift+Tab cycle focus between the panes that exist for the loaded file. A branded header bar shows the file, detected format, and atom/bond counts; a brief splash appears on launch. The panes:

• View — ASCII shaded molecule viewport: arrow-key rotation, zoom, roll, glyph modes (element symbols → depth → density), and a toggleable bond overlay.
• Atoms — navigable atom list with keyboard selection, filter-by-element, and geometry measurements (pick 2 atoms for a distance, 3 for an angle, 4 for a dihedral; the value shows in Properties).
• Analysis: permanent dipole, charge / orbital / NBO highlights, computed bond orders, cross-program task provenance and SCF histories, and periodic band / first-Brillouin-zone summaries. Gaussian-stage and NWChem-task stepping use the same records as the CLI and desktop. A computed bond-order method displays at most 100 pair rows and 100 three-center rows, followed by the exact omitted count. Use orbitron analyze bond-orders FILE --json when you need the complete matrix. Calculation-task sections likewise display at most 100 tasks, 100 state energies per task, 100 SCF cycles per task, and 100 SCF task sections. Each truncated section gives its exact omitted count; use orbitron info FILE --json for the complete task records.
• Properties (below the atom list) also reports a declared molecular charge and multiplicity, implied electron count, impossible spin parity, and a mismatch with the sum of atomic formal charges. The TUI displays this state; editing it is a desktop or Python workflow.
• Sequence — trajectory frame playback and multi-stage/task stepping (appears when the file has frames, stages, or tasks).
• Vibrations — normal-mode selection and animation (appears for freq jobs).
• Slice — a 2D orbital/density cross-section as a colored ASCII heatmap on the plane through the 3 atoms picked in the Atoms pane (appears when the scene has a basis set).

Inline image preview is available on Kitty/WezTerm-capable terminals (g).

A one-line key hint for the focused pane sits along the bottom of the screen, and ? opens the full key reference as an overlay. An abbreviated version is available from the shell with orbitron-tui --help:

Pane	Keys	Action
Global	Tab / Shift+Tab	Next / previous pane
	?	Toggle key reference
	g	Inline preview (Kitty / WezTerm)
	q / Esc / Ctrl+C	Quit
View	arrows / h j k l	Rotate
	[ ]	Roll (z-axis)
	+ / -	Zoom in / out
	m	Cycle glyph mode (symbols → depth → density)
	b	Toggle bonds
	r	Reset view
Atoms	arrows / j k	Move selection
	PgUp / PgDn	Jump ±10
	Home / End	First / last atom
	/	Filter by element
	space	Add / remove atom for a measurement
	c	Clear measurement
	mouse click	Select atom
Analysis	arrows / j k	Move highlight cursor
	Enter	Apply highlight
	t	Highlight largest |charge| atoms
	o / b	Cycle orbital / NBO contributors
	c	Clear highlights
	i	Compute chemical identifiers (formula / InChI / SMILES)
	{ }	Previous / next Gaussian stage
	< >	Previous / next NWChem task
Sequence	space	Play / pause
	n / p (or arrows)	Next / previous frame
	{ }	Previous / next Gaussian stage
	< >	Previous / next NWChem task
Vibrations	arrows / j k	Select normal mode
	space	Play / pause animation
	+ / -	Amplitude up / down
Slice	m	Toggle orbital / density
	↑ / k	Next MO
	↓ / j	Previous MO

5.1 First-run Mac Tips

• If you launch the unsigned .app from GitHub releases, macOS blocks it the first time. Right-click the app in Finder, choose Open, then confirm. After you approve once, you can double-click as usual.

• Alternatively, remove the quarantine attribute manually:

  xattr -dr com.apple.quarantine "/Applications/Orbitron Viewer.app"

• The CLI/TUI binaries don’t require this step; they run fine from the command line after cargo build --release.

Status: the TUI is a keyboard-first interactive viewer that sits between the CLI and the desktop GUI. It renders in the terminal as ASCII, but supports keyboard atom selection, filter-by-element, geometry measurements, vibration animation, and 2D orbital/density slices.

See Analysis Results for the data each analysis section represents and the matching CLI, desktop, and Python entry points.