Installation: OpenDroneKit docs

OpenDroneKit runs offline by default. Nothing here calls home, and every optional dependency below is optional because the toolkit refuses the corresponding capability rather than degrading it silently.

Requirements

Component	Version	Why
Python	3.11+	The codebase uses `X \| Y` type syntax and `tomllib`.
pip	any recent	—
Git	any	Only for cloning.

Everything else is a Python package.

Install

git clone <repository-url> OpenDroneKit
cd OpenDroneKit
pip install -r requirements.txt

Verify with the test suite. It is the only installation check worth trusting, because it exercises the code rather than the import graph:

python -m pytest

A clean run reports several hundred passes and a handful of skips. Skips are expected and are not failures: they mark capabilities whose optional dependency is absent on this machine (see below).

Run it

Desktop shell:

python main.py

Headless processing of an image set:

python run_pipeline.py --images <dataset_dir> --engine colmap --output final_toolkit_outputs

Web API (see docs/DEPLOYMENT.md for anything beyond a laptop):

uvicorn services.api.main:app --reload

Optional dependencies, and what you lose without each

This is the part worth reading. The toolkit is built so that a missing dependency produces a refusal with a reason, never a quietly worse answer.

Missing	What stops working	What you get instead
`open3d`	Poisson meshing (`pr.mesh`)	A warning in the run's output and no mesh file. The point cloud, DSM and orthomosaic are unaffected.
CUDA-enabled COLMAP	Dense point clouds	Sparse cloud only, reported up front by `Api.reconstruction_capabilities()`. The sparse cloud is never inflated to look dense.
`rasterio`	GeoTIFF reading, terrain following from DEMs	Those tests skip; planning falls back to flat earth with a warning on every plan.
`onnxruntime` / `opencv-python`	Model inference	Detection capabilities refuse rather than returning empty results.
`pymavlink`	Flight control, telemetry	Planning and processing are unaffected.
`torch`, `ultralytics`	Training only	Nothing at runtime; the shipped models are ONNX.
PostgreSQL + PostGIS	Multi-user deployment	SQLite, with geometry stored as GeoJSON text. See the note in `docs/DEPLOYMENT.md` — this is also true with PostGIS today.

GPU

No GPU is required to run OpenDroneKit. A GPU matters for two things:

Training your own models (docs/../training/), which is optional.
Dense reconstruction, which needs CUDA COLMAP specifically. Check what this machine can do before starting a long job:

from app.api import Api
Api(session).reconstruction_capabilities()

Windows notes

The project is developed and tested on Windows as well as Linux. Two things bite:

Page file size. Training locally can fail with WinError 1455 or DataLoader worker exited unexpectedly. Both are the same underlying limit: each worker process loads its own copy of torch's CUDA libraries. Set num_workers: 0 in the training config, or raise the page file.
Console encoding. Set PYTHONIOENCODING=utf-8 before reading logs that contain non-ASCII characters, or cp1252 will raise on output that is perfectly valid.

Model weights

Weights are not in the repository — they are large binaries and .onnx is gitignored. models/model_registry.json is tracked and records, for every model, the path, labels, input size, published metrics and a sha256 digest.

The digest is verified at load. A model whose file does not match its recorded digest is refused rather than used, because published metrics describe a specific file and not a filename.

To see what is installed on this machine:

python -m training.register --list

This page is the repository’s own docs/INSTALLATION.md, rendered at build time from commit 1ef6351. Links to code open on GitHub at the same commit.