Install

Download prebuilt packages

1. Visit the Orbitron releases page and download the assets for your platform:
   • macOS: Orbitron Viewer.dmg (or Orbitron Viewer.tar.gz) holds only Orbitron Viewer.app — the desktop viewer. The command-line tools ship separately as orbitron-macos.zip and orbitron-tui-macos.zip.
   • Windows: orbitron-windows.zip contains orbitron-viewer.exe, orbitron.exe, and orbitron-tui.exe alongside their runtime DLLs.
   • Linux: three bare binaries, attached individually rather than as an archive — orbitron-viewer-linux, orbitron-linux, and orbitron-tui-linux (chmod +x them after downloading).
2. Drag Orbitron Viewer.app to /Applications on macOS. Place the command-line binaries somewhere on your PATH (e.g., /usr/local/bin, ~/bin, or %USERPROFILE%\AppData\Local\Programs\Orbitron). Double-click Orbitron Viewer.app 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 Viewer.app (wraps orbitron-viewer for macOS desktop integration) - Terminal UI: orbitron-tui (separate terminal-based interface)

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 cp310-abi3 wheel per platform (one build runs on CPython 3.10+). Install directly from the release URL — no Rust/HDF5 needed:

# Linux
pip install https://github.com/charliecpeterson/orbitron/releases/download/v0.5.0/orbitron-0.5.0-cp310-abi3-manylinux_2_28_x86_64.whl
# macOS (Apple Silicon)
pip install https://github.com/charliecpeterson/orbitron/releases/download/v0.5.0/orbitron-0.5.0-cp310-abi3-macosx_11_0_arm64.whl
# Windows
pip install https://github.com/charliecpeterson/orbitron/releases/download/v0.5.0/orbitron-0.5.0-cp310-abi3-win_amd64.whl

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

Orbitron is not currently published on PyPI. Install a release wheel from the URL above; pip install orbitron will not install this project until a PyPI release is announced.

Verify installation:

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

From Source

If wheels are not available for your platform, use the repository’s conda setup so Rust, HDF5, Python, and the viewer build tools stay aligned:

./scripts/setup-conda-env.sh
conda run --no-capture-output -n orbitron-dev \
  python -m pip install -e extensions/python-bridge

The editable install runs the PEP 517 backend and stages both the WASM viewer and widget assets. For Python-only iteration after that first build, see the Python binding development notes.

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:

Hosted viewer

Install the Python wheel, then copy its orbitron.viewer_assets directory to your static host. Place .orbpack scenes beside it and point one iframe per scene at index.html?scene=.... Source builds stage the same four runtime files with extensions/python-bridge/scripts/stage_viewer_assets.sh.

See §10 Web Viewer Embedding for complete integration guide.

Self-contained HTML

Use File → Export Web View in the desktop app or orbitron.export_html(scene_or_bundle, "viewer.html") in Python. The output contains the runtime and scene in one file. Reveal.js and Marp can load it in an iframe. For PowerPoint, link to the HTML or use a PNG fallback; the embedding guide explains the host-application limits.