Quick Start

This page gets Orbitron installed, opened, and useful from the desktop, CLI, terminal UI, and Python. For platform-specific installation details, see Install.

1. Install Orbitron

Download the latest release for your platform:

  • macOS: Orbitron Viewer.dmg
  • Linux: the bare binaries orbitron-viewer-linux, orbitron-linux, and orbitron-tui-linux
  • Windows: orbitron-windows.zip
  • Python: the cp310-abi3 wheel for your platform

Releases are attached to the latest GitHub release.

Put the orbitron and orbitron-tui binaries somewhere on your PATH if you want the CLI or TUI commands available from any terminal.

2. Open a File in the Desktop Viewer

Launch the viewer directly:

orbitron-viewer molecule.xyz

Or launch it through the CLI:

orbitron view molecule.xyz

The viewer can load common molecular and computational-chemistry formats, including XYZ, PDB, CIF, SDF, VASP, Gaussian, NWChem, Molpro, Molcas, DIRAC, Quantum ESPRESSO, Molden, CUBE, and NBO outputs.

3. Inspect a File From the CLI

Print a human-readable summary:

orbitron info calculation.out

Use JSON for scripts:

orbitron info calculation.out --json

For quantum-chemistry logs with multiple stages or tasks, use inspect:

orbitron inspect calculation.out

To start from a SMILES string instead of a file:

orbitron from-smiles 'CCO' -o ethanol.sdf
orbitron view --blank

The desktop’s blank session provides atom, ring, fragment, SMILES, conformer, metal-complex, and residue-mutation workflows under Edit. See Viewer §3.7 for the supported chemistry and refusal conditions.

4. Use the Terminal UI

For SSH sessions or machines without a graphical desktop:

orbitron-tui calculation.out

You can also launch the TUI through the CLI:

orbitron view calculation.out --tui

5. Use Python

Install the wheel from the release page, then load a file:

import orbitron as orb

scene = orb.load("calculation.out")
scene

In Jupyter, returning a Scene displays the inline viewer when the bundled viewer assets are available.

Export a self-contained HTML viewer:

orb.export_html(scene, "calculation.html")

That HTML file can be opened in a browser, embedded in slides, or archived with the calculation.

Next Steps

  • Graphical Viewer - controls, measurements, overlays, orbitals, vibrations, and sessions.
  • Automation CLI - scripting, JSON output, conversion, rendering, identifiers, and batch workflows.
  • Terminal UI - keyboard-first inspection over SSH.
  • Python Bridge - Jupyter, scripting, rendering, widgets, and HTML export.
  • Web Viewer Embedding - standalone HTML and web-component embedding.