Skip to content

Python API overview

pyTheia is a normal Python package with a compiled extension. After building, import the public namespace as usual:

import pytheia as pt

The top-level package re-exports everything from the native submodule pytheia.pytheia. You normally do not import pytheia.pytheia in application code; use import pytheia (or import pytheia as pt) instead.

Submodules correspond to the same areas as in the C++ library (see the API Reference). They are exposed as attributes of pt:

Submodule Role (short)
pt.io Reading and writing reconstructions and related data.
pt.math Math helpers and Sophus Lie-group bindings.
pt.matching Feature matching and correspondence utilities.
pt.mvs Multi-view stereo oriented helpers.
pt.sfm Reconstruction, BA, cameras, tracks, pipelines, alignment and cross-reconstruction Sim(3) pose graph (see Transformations).
pt.solvers Geometric estimation and solvers.

Type information (PEP 561)

The wheel ships py.typed and .pyi stubs next to the extension so editors and mypy/pyright can resolve symbols without loading the binary.

  • Stubs are generated with pybind11-stubgen during development (see pip install ".[dev]" in the root pyproject.toml).

  • Regenerate after changing bindings:

    pip install ".[dev]"
export PYTHONPATH=$(pwd)/src
python -m pybind11_stubgen pytheia.pytheia -o src

    The project build (python setup.py bdist_wheel) runs the same step when pybind11-stubgen is installed and GENERATE_STUBS is not 0.

Examples in the repo

  • pyexamples/ — small, self-contained scripts (OpenCV features, classic matchers, NeRFStudio export helpers). Fewer optional dependencies.
  • examples/ — showcase workflows: vismatch matchers, Rerun visualization, and Gaussian splatting export notes. Install optional deps with pip install ".[examples]" (see repository examples/requirements.txt).
  • pytests/ — unit and integration tests.

See Examples showcase for a map of both trees.

Python versus C++ (tabbed snippets)

The HTML manual can show the same workflow in both languages. Use the pattern from chapter-contributing (dual-language examples). For instance:

import pytheia as pt

rec = pt.sfm.Reconstruction()

#include <theia/sfm/reconstruction.h>

theia::sfm::Reconstruction reconstruction;

Relationship to the C++ reference

Chapters under api are written in the C++ domain and describe the underlying Theia types. Python names and signatures follow the bindings in src/pytheia/ (pybind11). Where names match, the C++ chapter is the conceptual reference; use the stubs or help() on the Python objects for the exact wrapper surface.