Colmap
Scale Is Unknown
Structure from motion produces geometry in arbitrary units. Anchor the scale with a known dimension or ground control points before you trust any measurement.
Feature Based
The pipeline matches visible texture. Reflective, transparent, or featureless surfaces produce holes, drift, and false geometry.
CLI First
Every step is a recorded command with logged output. That is what makes a run reproducible and auditable in an investigation.
Introduction
COLMAP is an open-source Structure-from-Motion (SfM) and Multi-View Stereo (MVS) pipeline. From a set of photos of a static scene it computes the camera positions, a sparse and a dense 3D point cloud, and optionally a textured mesh. It runs as a GUI and as a command-line tool.
Pick COLMAP when the reconstruction has to be reproducible: every step is a command with explicit inputs and outputs, so a third party can rerun the pipeline and compare the result. Use the Meshroom page for a GUI-first open-source workflow, and Metashape for a commercial pipeline with a guided interface. The method itself is documented in the photogrammetry technique.
Installation
- Download the build for your platform from the official site. Prebuilt packages exist for Windows, macOS, and Linux. The package includes the GUI and the
colmapcommand-line tool. - Build from source only when you need the latest state: the GitHub repository documents the build for each platform.
- Verify the install by running
colmap help -ain a terminal. The full command list confirms the CLI works, which is the interface you will document.
Usage
The standard reconstruction runs five steps. Each step reads and writes named files, so the run is a chain you can store and rerun.
Prepare the image set· photos or extracted frames
Collect the images into one folder. For video footage, extract frames at a fixed interval so consecutive views overlap most of the frame. Keep the scene static, avoid motion blur, and keep exposure stable. What goes in: original photos or extracted frames. What comes out: a single image directory that becomes the input for every later step.
Extract features· SIFT descriptors
Run the feature extractor. It writes a database file holding the SIFT features of every image. The database is the working file of the whole reconstruction.
Match features· exhaustive or sequential
Match features between image pairs. For a photo set taken from many viewpoints, run the exhaustive matcher. For frames extracted from a single camera path, run the sequential matcher, which matches neighboring frames. Both write the matches into the same database.
Run the SfM mapper· cameras and sparse cloud
The mapper registers the images, estimates every camera position, and triangulates the sparse 3D point cloud. The output is a sparse model folder of text files: cameras, images, and points. Check the registration ratio and the mean reprojection error. A low registration count points to coverage gaps or duplicate frames.
Densify and mesh· MVS
Run dense reconstruction to grow the sparse cloud into a dense point cloud, then mesh it. What comes out: a dense PLY point cloud and a mesh file. Both are the import targets for Blender.
Quick reference
| Step | Command | Output |
|---|---|---|
| Extract features | colmap feature_extractor --database_path COLMAP.db --image_path IMAGES | Feature database (COLMAP.db) |
| Match features (photo set) | colmap exhaustive_matcher --database_path COLMAP.db | Matches in the database |
| Match features (video frames) | colmap sequential_matcher --database_path COLMAP.db | Matches in the database |
| Reconstruct structure | colmap mapper --database_path COLMAP.db --image_path IMAGES --output_path SPARSE | Sparse model folder: cameras.txt, images.txt, points3D.txt |
| Dense reconstruction | colmap patch_match --workspace_path SPARSE | Dense point cloud (dense.ply) |
| Mesh | colmap poisson_mesher --workspace_path SPARSE | Mesh file |
Store the sparse model folder in your case file. It is text, so a reviewer can read which images registered and with what error, without rerunning anything.
In an Investigation
Use the block below to document how you ran COLMAP on the evidence.
Documentation: how to document COLMAP
In Your Method Section
Guidance: Describe the purpose, the tool version, and the input data.
- Investigative Objective: To reconstruct the 3D geometry and camera positions of the scene from a set of 2D images for spatial analysis.
- Software Version: COLMAP [Version] (e.g., 4.2.0).
- Input Data: [Image set name/ID], [N] images derived from [source footage/document], Source Hash: [First 6 digits].
In Your Decision Log
Guidance: Record the specific procedural parameters and integrity checks.
- Specific Settings: Feature extractor (SIFT), matcher (exhaustive or sequential, with reason), any camera model override, GCPs used or not.
- Assumptions: The scene was static during capture and the camera intrinsics stayed constant (or: the camera model was set to [model]).
- Integrity Check: Analysis ran on a working copy, never the original evidence file.
- Date Performed: [YYYY-MM-DD].
Verification & Mitigation
Guidance: How did you verify accuracy and mitigate bias?
- Verification: Read the registration ratio and mean reprojection error from the mapper output. Compared the reconstructed scale against a known reference dimension.
- Bias Mitigation: Used ground control points where possible to constrain the reconstruction and avoid drift. Kept the image set static.
Example Methodology Statement
"Scene geometry was reconstructed with COLMAP (v4.2.0) from [N] images of [source] (Hash: A1B2C3). SIFT features were extracted and matched exhaustively. The incremental reconstruction registered [N] of [N] images with a mean reprojection error of [X.X] pixels. Scale was anchored to a reference measurement of [X.X m], and the result was verified by overlaying the reconstruction against [reference]."
Into Blender
COLMAP outputs two formats that Blender reads directly.
- Point clouds (sparse or dense PLY): import with File > Import > Stanford PLY (.ply), or use the Photogrammetry Importer add-on, which also handles georeferenced placement.
- Mesh (PLY or OBJ): import with the matching PLY or Wavefront OBJ importer.
Three caveats before you model against the result:
- Scale is arbitrary. COLMAP has no units. Anchor it to a known dimension before the import, or rescale the object in Blender against a measurable feature after the import.
- Check the orientation. COLMAP works in a camera coordinate system (Z points down in the camera frame). The reconstructed cloud needs a rotation to sit flat on the Blender ground plane.
- For georeferenced scenes: place the reconstruction relative to the site with ground control points or the QGIS baseline (custom CRS and origin point), so the model aligns with maps and measurements.
Limitations
- Reflective, transparent, and featureless surfaces (water, glass, blank walls, snow, sky) produce holes, drift, and false geometry.
- The scene must be static. Moving people or vehicles register as ghosts or drop images from the reconstruction.
- The output has no real-world scale without a reference dimension or ground control points.
- Exhaustive matching grows quadratically with the image count. Drone surveys of thousands of frames need a workstation with serious RAM.
Related
Resources
- Photogrammetry, the technique this tool implements, with pitfalls
- Photogrammetry Importer, the Blender add-on that imports PLY with georeferencing
- Meshroom, a GUI-first open-source alternative
- QGIS, for the geospatial baseline that anchors the reconstruction
Sources
- COLMAP official site, documentation and downloads
- COLMAP command-line reference, the commands used in the Usage steps
- COLMAP releases on GitHub, current version 4.2.0 (2026-09-01)
- COLMAP changelog, per-version changes