Install

Download prebuilt packages

1. Visit the Orbitron releases page and download the archive for your platform:
   • macOS: Orbitron.dmg contains Orbitron.app (desktop viewer) and a bin/ folder with the command-line tools.
   • Windows / Linux: grab the .zip or .tar.gz bundle; it includes orbitron (GUI/CLI launcher) and orbitron-tui.
2. Extract the archive and place the binaries somewhere on your PATH (e.g., /usr/local/bin, ~/bin, or %USERPROFILE%\AppData\Local\Programs\Orbitron\bin).
   Double-click Orbitron.app on macOS or run orbitron --help in a terminal to confirm the installation.

Binary naming clarification: - GUI standalone: orbitron-viewer (built from ui/shell crate, launched by double-clicking app icon) - CLI tool: orbitron (command-line interface with orbitron view to launch GUI) - macOS app bundle: Orbitron.app (wraps orbitron-viewer for macOS desktop integration) - Terminal UI: orbitron-tui (separate terminal-based interface) - Remote file access: built in — the desktop, CLI, and Python read files on a remote host over your system ssh/sftp; no separate server binary is required.

System requirements

• GPU: Metal (macOS), Vulkan (Linux), or DirectX 12 (Windows) for the desktop viewer. CLI/TUI binaries run headless; the viewer can fall back to OpenGL with WGPU_BACKEND=gl.
• Optional: install maturin if you plan to rebuild the Python bridge locally.

For source builds, cargo run workflows, and contributor tooling, see the Developer Guide.

Python Package Installation

From Wheels (Recommended)

Each release attaches a cp38-abi3 wheel per platform (one build runs on CPython 3.8+). Install directly from the release URL — no Rust/HDF5 needed:

# Linux
pip install https://github.com/charliecpeterson/orbitron/releases/download/v0.2.0/orbitron-0.2.0-cp38-abi3-manylinux_2_34_x86_64.whl
# macOS (Apple Silicon)
pip install https://github.com/charliecpeterson/orbitron/releases/download/v0.2.0/orbitron-0.2.0-cp38-abi3-macosx_11_0_arm64.whl
# Windows
pip install https://github.com/charliecpeterson/orbitron/releases/download/v0.2.0/orbitron-0.2.0-cp38-abi3-win_amd64.whl

Platform wheels (all cp38-abi3): - Linux: *-manylinux_2_34_x86_64.whl - macOS Apple Silicon: *-macosx_11_0_arm64.whl - Windows: *-win_amd64.whl - macOS Intel: not published — build from source.

Not yet on PyPI (planned for a future release).

Verify installation:

from orbitron import Orbitron
orb = Orbitron()
print("Orbitron installed successfully!")

From Source

If wheels aren’t available for your platform:

cd extensions/python-bridge
conda activate orbitron-dev  # Or your conda environment with HDF5
pip install maturin
maturin develop --release --features python

Jupyter Notebook Setup

For Jupyter integration:

pip install jupyter ipywidgets
jupyter notebook extensions/python-bridge/examples/orbitron_tutorial.ipynb

See §7 Python Bridge for complete API reference and examples.

Web Viewer Installation

For embedding the molecular viewer in websites or presentations:

ZIP Bundle (For Websites)

1. Download orbitron-viewer-web-v0.2.0.zip from releases page
2. Extract the archive
3. Place your molecule.bin file in the extracted folder
4. Open index.html?scene=molecule.bin in a browser
5. Or upload all files to your website

See §10 Web Viewer Embedding for complete integration guide.

Standalone HTML (For Presentations)

1. Download orbitron-viewer-standalone-v0.2.0.html from releases page
2. Place your molecule.bin file in the same folder
3. For PowerPoint: Insert → Object → Web Page → Select the HTML file
4. For Reveal.js/Marp: Use <iframe src="orbitron-viewer-standalone.html">

Creating .bin files:

# Using CLI
orbitron convert molecule.xyz -o molecule.bin

# Using Python
from orbitron import Orbitron
orb = Orbitron()
scene = orb.load("molecule.xyz")
with open("molecule.bin", "wb") as f:
    f.write(scene.to_bytes())