Skip to content

Python Packages

Work in Progress

APIs may change and features may be incomplete.

Python packages for post-processing, visualization, and C++ access.

Two Ways to Install

1. As Python packages — pip install into a virtual environment for programmatic access or package development.

2. As a CLI tool (thor-tools) — uv tool install for the thor-tools command on PATH, with isolation managed by uv.

Packages

Package Purpose
thor-rt Python tools: shared utilities, MCRT analysis, raytracer visualization, workflow helpers, and thor-tools CLI
thor-bindings C++ Python bindings via nanobind
thor-testkit Regression test tools (internal)

Environment Setup

First, set the path to your THOR repository:

export THOR_PATH=/path/to/thor

Before installing THOR's Python packages, create an isolated environment using your preferred tool:

python -m venv thor-env
source thor-env/bin/activate  # Linux/macOS
On Windows: thor-env\Scripts\activate

uv venv thor-env
source thor-env/bin/activate

conda create -n thor python=3.11
conda activate thor

Once activated, proceed with the installation steps below.

Installation

Packages live under python/ and use standard pyproject.toml builds.

Python package (into your environment)

With your virtual environment activated:

pip install -e "$THOR_PATH/python/thor-rt[all]"

You can also install subsets:

pip install -e "$THOR_PATH/python/thor-rt[mcrt]"       # MCRT commands only
pip install -e "$THOR_PATH/python/thor-rt[raytracer]"  # Raytracer commands only
pip install -e "$THOR_PATH/python/thor-rt"             # Base CLI only (no commands)

C++ Bindings (optional)

thor-bindings requires the same build environment as THOR itself (see Installation):

pip install -e "$THOR_PATH/python/thor-bindings"

CLI tool (no virtual environment needed)

Install thor-tools globally with uv's tool manager (uv manages an isolated environment for you):

# With all plugins (MCRT + raytracer)
uv tool install "$THOR_PATH/python/thor-rt[all]"

# MCRT commands only
uv tool install "$THOR_PATH/python/thor-rt[mcrt]"

# Raytracer commands only
uv tool install "$THOR_PATH/python/thor-rt[raytracer]"

After installation, thor-tools is on your PATH. Verify with uv tool list.

To update after pulling new changes:

uv tool install "$THOR_PATH/python/thor-rt[all]" --reinstall

CLI

The thor-rt package provides the thor-tools entry point. MCRT and raytracer sub-commands register as plugins:

thor-tools
├── mcrt
│   ├── projection create
│   ├── spectrum plot
│   └── traces {analyze, info, summary, compare}
└── raytracer
    ├── plot-frame
    ├── render-movie
    ├── batch-parallel-render
    ├── merge-parallel-render
    └── interpolate-movie

See CLI Reference for full usage.