This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
This file is adapted from the hand-crafted .github/copilot-instructions.md, which has proven to work well for coding agents on this repo. Keep the two in sync when changing project-wide guidance.
OpenSfM is a Structure-from-Motion library with a hybrid architecture:
- Core Logic (C++): Heavy computational tasks (geometry, bundle adjustment, features, dense, map) live in C++ under
opensfm/src/lib/. Each library (e.g.,geometry,bundle,sfm,map) is laid out assrc/(implementation),test/(gtest*_test.cc), andpython/(PyBind11 bindings). They are exposed to Python as compiled modules (e.g.,pygeometry,pybundle,pymap) and imported from the root package (e.g.,from opensfm import pygeometry). - Pipeline Layout (Python): Application logic, pipeline orchestration, and the CLI are in the Python
opensfm/package. - Two-layer commands:
opensfm/commands/<name>.pyare thin CLI wrappers (subclassCommandBase, definename/help, parse args) that delegate toopensfm/actions/<name>.py, where the realrun_dataset(data, ...)logic lives. Add new pipeline steps in both places. - Data Abstraction: The
DataSetclass (opensfm/dataset.py) is the central definition for filesystem interactions. All pipeline stages read/write to a hardcoded directory structure (images/,config.yaml,reconstruction.json) managed by this class. - State Management: The
Reconstructionclass (opensfm/types.py) wraps the C++pymap.Mapobject. This pattern (Python class holding a C++ handle) is pervasive.
Always activate the conda environment at least once before building, running, or testing:
conda activate opensfm.
The project uses scikit-build-core to compile C++ extensions (config in pyproject.toml).
- Full Build:
pip install -e .[test]— builds C++ extensions plus tests and installs the package in editable mode. The build directory isbuild/(compiled.sofiles live there via editable redirect mode). - Rebuild C++: Re-run
pip install -e .after changing.ccfiles. - Dependencies: Python deps are in
pyproject.toml. The outer environment (C++ toolchain, libraries) is set up throughcondaandconda.yml. Any change toconda.ymlrequires recreating the env:conda env create --file conda.yml --yesthenconda activate opensfm.
- Frameworks:
- Python:
pytest, tests inopensfm/test/test_*.py. - C++:
gtest, tests inopensfm/src/lib/<XXX>/test/*_test.cc.
- Python:
- Run Python tests:
pytest opensfm/test/. First runexport LD_PRELOAD=$CONDA_PREFIX/lib/libtcmalloc.so(tcmalloc is mandatory). Run a single test withpytest opensfm/test/test_foo.py::test_bar.not slowexcludes long integration tests. - Run C++ tests: built with
OPENSFM_BUILD_TESTS=ON; run viactest --output-on-failurefrom the CMake build directory. - Coverage:
./run_coverage.bash(handles conda activation; defaults tonot slow). - Style: favor many small tests with few asserts, ideally one function per test; only 1-2 larger integration tests per file. Prefer toy/synthetic examples that verify correctness, not just return semantics.
- Synthetic Data: Python tests rely heavily on synthetic scenes generated in
opensfm/test/conftest.py(e.g., fixturesscene_synthetic,scene_synthetic_cube).
- Entry Point:
bin/opensfm(bash, setsLD_PRELOADfor tcmalloc) →bin/opensfm_main.py→commands.command_runner. - Example:
bin/opensfm reconstruct path/to/datasetinvokesCommand.run_implinopensfm/commands/reconstruct.py, which callsactions/reconstruct.py::run_dataset.
- Wrappers: Prefer Python wrappers over raw C++ objects (e.g., use
opensfm.types.Reconstructioninstead ofopensfm.pymap.Mapwhere possible).
- Readability: Prioritize clear, simple, maintainable code. You're a seasoned engineer who knows real-world trade-offs — apply frameworks/design patterns only when strictly justified now, not for hypothetical futures. Use descriptive names; break complex functions into smaller, focused ones.
- Documentation: Docstrings for all public functions/classes. For complex algorithms, comment the rationale and key steps.
- C++ Style: Follow existing style; format with
clang-format(.clang-formatat repo root). Key points:- Stick to STL and Eigen for data structures. Avoid OpenCV datastructures in C++, except for image resizing.
- Use SoA (Structure of Arrays) for performance-critical data like point clouds.
- Minimize heap allocation/fragmentation: prefer stack-allocated buffers; reuse heap buffers; avoid tiny allocations inside long loops.
- Design: Reuse the core lib's data structures. Manipulating large reconstructions efficiently is paramount — minimize copies, apply Data-Oriented Design, and leverage GPU acceleration where possible.
- Codebase uses
pyre-strict. New code needs complete type annotations; files often carry a# pyre-strictheader.
- Definition: Default parameters are in
opensfm/config.py(dataclassOpenSfMConfig) — also the reference doc for tunable parameters. - Overrides: Overridden by
config.yamlin the dataset directory. - Access:
data.config['param_name']wheredatais aDataSet.
opensfm/dataset.py: READ THIS FIRST for file I/O — defines where every file lives.opensfm/types.py: Key data structures (Reconstruction,Shot,Camera).opensfm/config.py: All tunable parameters.opensfm/src/lib/map/map.cc: C++ backing implementation forReconstruction.opensfm/commands/+opensfm/actions/: CLI wrappers and their implementations.
- Direct File Access: Avoid manual
open(). Usedataset.load_*/dataset.save_*to stay consistent with the expected directory structure. - Geometry Types: Be careful with rotation representations (angle-axis vs matrices). Check
pygeometryhelpers /opensfm/src/lib/geometry/when behavior is unclear. - Skipping Conda: Activate the conda environment at least once before building/running.
- tcmalloc: Required at runtime — set
LD_PRELOAD=$CONDA_PREFIX/lib/libtcmalloc.so(thebin/opensfmwrapper does this for you).
- Multi-Platform: Runs on Windows, Linux, macOS. Avoid platform-specific code; use cross-platform libraries (Qt for GUI, STL/Eigen for C++).
- Code edits: Favor
sed/awkfor complex code replacements over ad-hoc Python scripts that open/write files directly, so changes stay clear and auditable.
- No Git operations: This is a shared repository. Do not perform Git operations (commit, push, pull, merge, rebase, etc.) — leave them to human developers so proper code review and collaboration are preserved. Only do so if the user explicitly asks in the current session.