Number of images < 100? ├── Yes → Exhaustive matching (highest quality, acceptable time) └── No → Are images sequentially related (video frames)?
├── Yes → Sequential matching (overlap=10-20)
└── No → Number of images > 500?
├── Yes → Vocab tree matching
└── No → Exhaustive matching (still acceptable for 100-500 images)

# Ubuntu 22.04+ (recommended) sudo apt install colmap
# Or build from source (to get the latest 4.0 features) git clone https://github.com/colmap/colmap.git cd colmap mkdir build && cd build cmake .. -DCMAKE_CUDA_ARCHITECTURES=native make -j$(nproc) sudo make install
# Verify install colmap --version # COLMAP 4.0.x

project/ ├── images/
# All input images (JPEG/PNG) ├── database.db
# COLMAP database (auto-generated) ├── sparse/
# Sparse reconstruction output │
└── 0/
# First reconstruction model │
├── cameras.bin │
├── images.bin │
└── points3D.bin └── dense/
# Dense reconstruction (not needed for 3DGS, can skip)

colmap feature_extractor \
--database_path ./database.db \
--image_path ./images/ \
--ImageReader.camera_model SIMPLE_RADIAL \
--ImageReader.single_camera 1 \
--SiftExtraction.use_gpu 1 \
--SiftExtraction.max_image_size 3200 \
--SiftExtraction.max_num_features 8192

# Option A: Exhaustive matching (< 100 images) colmap exhaustive_matcher \
--database_path ./database.db \
--SiftMatching.use_gpu 1 \
--SiftMatching.max_ratio 0.8 \
--SiftMatching.max_distance 0.7
# Option B: Sequential matching (video frames) colmap sequential_matcher \
--database_path ./database.db \
--SiftMatching.use_gpu 1 \
--SequentialMatching.overlap 15 \
--SequentialMatching.loop_detection 1 \
--SequentialMatching.vocab_tree_path ./vocab_tree_flickr100K_words256K.bin
# Option C: Vocab tree matching (> 500 images) colmap vocab_tree_matcher \
--database_path ./database.db \
--SiftMatching.use_gpu 1 \
--VocabTreeMatching.vocab_tree_path ./vocab_tree_flickr100K_words256K.bin \
--VocabTreeMatching.num_images 100

# Pretrained vocab tree provided by COLMAP wget https://demuc.de/colmap/vocab_tree_flickr100K_words256K.bin

# Incremental reconstruction (default, recommended) colmap mapper \
--database_path ./database.db \
--image_path ./images/ \
--output_path ./sparse/ \
--Mapper.ba_refine_focal_length 1 \
--Mapper.ba_refine_extra_params 1 \
--Mapper.min_num_matches 15
# Or use GLOMAP (global, faster) glomap mapper \
--database_path ./database.db \
--image_path ./images/ \
--output_path ./sparse/

# View reconstruction stats colmap model_analyzer \
--path ./sparse/0/
# Example output: # Cameras: 1 # Images: 247 (registered: 243) # Points: 45,892 # Mean reprojection error: 0.72px # Mean track length: 4.3

colmap image_undistorter \
--image_path ./images/ \
--input_path ./sparse/0/ \
--output_path ./undistorted/ \
--output_type COLMAP \
--max_image_size 2000

undistorted/ ├── images/
# Undistorted images ├── sparse/
# Updated sparse model (intrinsics become PINHOLE) │
├── cameras.bin │
├── images.bin │
└── points3D.bin └── stereo/
# Stereo matching data (can be ignored)

# From an image folder ns-process-data images \
--data ./images/ \
--output-dir ./processed/ \
--num-downscales 2 \
--colmap-feature-type sift-gpu
# From a video file ns-process-data video \
--data ./input.mp4 \
--output-dir ./processed/ \
--num-frames-target 300 \
--colmap-feature-type sift-gpu

processed/ ├── images/
# Original-resolution undistorted images ├── images_2/
# 1/2 resolution ├── images_4/
# 1/4 resolution ├── images_8/
# 1/8 resolution ├── colmap/
# Raw COLMAP output │
└── sparse/0/ ├── transforms.json
# Nerfstudio-format camera parameters └── dataparser_transforms.json

# RealityScan 2.1.1 CLI example RealityScan -addFolder ./images/ \
-align \
-exportColmap ./output/sparse/ \
-quit

#!/usr/bin/env python3 """ 07_sfm_pipeline.py Inktoys · SfM pose estimation automation script Uses pycolmap to run the full pipeline from feature extraction to sparse reconstruction """
import pycolmap from pathlib import Path import shutil import time
class SfMPipeline:
def __init__(self, image_dir: str, output_dir: str,
camera_model: str = "SIMPLE_RADIAL",
single_camera: bool = True,
matching_strategy: str = "auto"):
"""
Args:
image_dir: Input image directory
output_dir: Output directory
camera_model: Camera model
single_camera: Whether all images come from the same camera
matching_strategy: "exhaustive", "sequential", "vocab_tree", "auto"
"""
self.image_dir = Path(image_dir)
self.output_dir = Path(output_dir)
self.db_path = self.output_dir / "database.db"
self.sparse_dir = self.output_dir / "sparse"
self.camera_model = camera_model
self.single_camera = single_camera
self.matching_strategy = matching_strategy
self.output_dir.mkdir(parents=True, exist_ok=True)
self.sparse_dir.mkdir(parents=True, exist_ok=True)
def count_images(self) -> int:
"""Count input images"""
extensions = {".jpg", ".jpeg", ".png", ".tiff", ".tif"}
count = sum(1 for f in self.image_dir.iterdir()
if f.suffix.lower() in extensions)
return count
def auto_select_matching(self) -> str:
"""Auto-select matching strategy based on image count"""
n = self.count_images()
if n <= 100:
return "exhaustive"
elif n <= 500:
return "sequential"
# Assume video frames
else:
return "vocab_tree"
def extract_features(self):
"""Step 1: feature extraction"""
print(f"[1/4] Feature extraction ({self.count_images()} images)...")
t0 = time.time()
pycolmap.extract_features(
database_path=str(self.db_path),
image_path=str(self.image_dir),
camera_model=self.camera_model,
camera_params="",
# Read automatically from EXIF
single_camera=self.single_camera,
sift_options=pycolmap.SiftExtractionOptions(
use_gpu=True,
max_image_size=3200,
max_num_features=8192,
)
)
print(f"
Done in {time.time()-t0:.1f}s")
def match_features(self):
"""Step 2: feature matching"""
strategy = self.matching_strategy
if strategy == "auto":
strategy = self.auto_select_matching()
print(f"[2/4] Feature matching (strategy: {strategy})...")
t0 = time.time()
matching_options = pycolmap.SiftMatchingOptions(
use_gpu=True,
max_ratio=0.8,
max_distance=0.7,
)
if strategy == "exhaustive":
pycolmap.match_exhaustive(
database_path=str(self.db_path),
sift_options=matching_options,
)
elif strategy == "sequential":
pycolmap.match_sequential(
database_path=str(self.db_path),
sift_options=matching_options,
sequential_options=pycolmap.SequentialMatchingOptions(
overlap=15,
loop_detection=True,
)
)
elif strategy == "vocab_tree":
pycolmap.match_vocab_tree(
database_path=str(self.db_path),
sift_options=matching_options,
vocab_tree_options=pycolmap.VocabTreeMatchingOptions(
vocab_tree_path="./vocab_tree_flickr100K_words256K.bin",
num_images=100,
)
)
print(f"
Done in {time.time()-t0:.1f}s")
def reconstruct(self):
"""Step 3: incremental reconstruction"""
print("[3/4] Incremental reconstruction...")
t0 = time.time()
mapper_options = pycolmap.IncrementalMapperOptions()
mapper_options.ba_refine_focal_length = True
mapper_options.ba_refine_extra_params = True
mapper_options.min_num_matches = 15
maps = pycolmap.incremental_mapping(
database_path=str(self.db_path),
image_path=str(self.image_dir),
output_path=str(self.sparse_dir),
options=mapper_options,
)
print(f"
Done in {time.time()-t0:.1f}s")
print(f"
Produced {len(maps)} model(s)")
return maps
def analyze_result(self) -> dict:
"""Step 4: analyze the reconstruction"""
print("[4/4] Analyzing reconstruction...")
model_path = self.sparse_dir / "0"
if not model_path.exists():
print("
No reconstruction model was produced!")
return {"success": False}
reconstruction = pycolmap.Reconstruction()
reconstruction.read(str(model_path))
num_images = len(reconstruction.images)
num_registered = sum(1 for img in reconstruction.images.values()
if img.registered)
num_points = len(reconstruction.points3D)
# Compute mean reprojection error
total_error = 0
total_obs = 0
for point in reconstruction.points3D.values():
total_error += point.error * len(point.track.elements)
total_obs += len(point.track.elements)
mean_error = total_error / max(total_obs, 1)
# Compute mean track length
track_lengths = [len(p.track.elements) for p in reconstruction.points3D.values()]
mean_track = sum(track_lengths) / max(len(track_lengths), 1)
total_input = self.count_images()
registration_rate = num_registered / total_input * 100
result = {
"success": True,
"total_images": total_input,
"registered_images": num_registered,
"registration_rate": registration_rate,
"num_points": num_points,
"mean_reprojection_error": mean_error,
"mean_track_length": mean_track,
}
print(f"
Total images: {total_input}")
print(f"
Registered: {num_registered} ({registration_rate:.1f}%)")
print(f"
3D points: {num_points}")
print(f"
Mean reprojection error: {mean_error:.2f}px")
print(f"
Mean track length: {mean_track:.1f}")
# Quality verdict
if registration_rate >= 95 and mean_error < 1.0:
print("
Excellent — proceed to training")
elif registration_rate >= 85 and mean_error < 1.5:
print("
Acceptable, but inspect the unregistered images")
else:
print("
Insufficient quality — investigate")
return result
def undistort(self):
"""Undistort images (required before 3DGS training)"""
print("[Extra] Undistorting images...")
undistorted_dir = self.output_dir / "undistorted"
undistorted_dir.mkdir(exist_ok=True)
pycolmap.undistort_images(
output_path=str(undistorted_dir),
input_path=str(self.sparse_dir / "0"),
image_path=str(self.image_dir),
output_type="COLMAP",
max_image_size=2000,
)
print(f"
Output: {undistorted_dir}")
print("
Undistortion complete; ready for 3DGS training")
def run(self):
"""Run the full SfM pipeline"""
print("=" * 60)
print("Inktoys · SfM pose estimation")
print("=" * 60)
total_start = time.time()
self.extract_features()
self.match_features()
self.reconstruct()
result = self.analyze_result()
if result.get("success") and result.get("registration_rate", 0) > 85:
self.undistort()
total_time = time.time() - total_start
print(f" Total time: {total_time/60:.1f} minutes")
print("=" * 60)
return result
if __name__ == "__main__":
import argparse
parser = argparse.ArgumentParser(description="3DGS SfM pose estimation")
parser.add_argument("images", help="Input image directory")
parser.add_argument("output", help="Output directory")
parser.add_argument("--camera-model", default="SIMPLE_RADIAL",
choices=["SIMPLE_PINHOLE","PINHOLE","SIMPLE_RADIAL",
"RADIAL","OPENCV","OPENCV_FISHEYE"])
parser.add_argument("--matching", default="auto",
choices=["exhaustive","sequential","vocab_tree","auto"])
parser.add_argument("--multi-camera", action="store_true",
help="Images come from multiple different cameras")
args = parser.parse_args()
pipeline = SfMPipeline(
args.images, args.output,
camera_model=args.camera_model,
single_camera=not args.multi_camera,
matching_strategy=args.matching,
)
pipeline.run()

# Basic usage (auto-select matching strategy) python 07_sfm_pipeline.py ./images/ ./sfm_output/
# Force sequential matching (video frames) python 07_sfm_pipeline.py ./frames/ ./sfm_output/ --matching sequential
# GoPro wide-angle lens python 07_sfm_pipeline.py ./gopro_frames/ ./sfm_output/ --camera-model OPENCV
# Mixed multi-camera capture python 07_sfm_pipeline.py ./mixed_images/ ./sfm_output/ --multi-camera

# Launch GUI colmap gui
# Or open an existing project directly colmap gui --database_path ./database.db --image_path ./images/

# See which images failed to register colmap model_analyzer --path ./sparse/0/ \

# 1. Try merging models colmap model_merger \
--input_path1 ./sparse/0/ \
--input_path2 ./sparse/1/ \
--output_path ./sparse/merged/
# 2. If they can't be merged, check for matching gaps # Usually a stretch of the capture path has no overlap
# 3. Increase the matching window or use exhaustive matching colmap exhaustive_matcher --database_path ./database.db
# 4. Re-run the mapper colmap mapper \
--database_path ./database.db \
--image_path ./images/ \
--output_path ./sparse_retry/

# Check whether camera distribution makes sense import pycolmap import numpy as np
reconstruction = pycolmap.Reconstruction() reconstruction.read("./sparse/0/")
# Extract all camera positions positions = [] for img in reconstruction.images.values():
if img.registered:
# Camera position = -R^T * t
R = img.rotmat()
t = img.tvec
pos = -R.T @ t
positions.append(pos)
positions = np.array(positions)
# Inspect camera distribution print(f"Cameras: {len(positions)}") print(f"X range: [{positions[:,0].min():.2f}, {positions[:,0].max():.2f}]") print(f"Y range: [{positions[:,1].min():.2f}, {positions[:,1].max():.2f}]") print(f"Z range: [{positions[:,2].min():.2f}, {positions[:,2].max():.2f}]")
# If the range on any axis is unusually large or small, the reconstruction has problems # In a normal orbit capture, cameras should roughly lie on a circle/ellipse

# 1. Reduce image resolution --SiftExtraction.max_image_size 2000
# Down from 3200
# 2. Reduce feature count --SiftExtraction.max_num_features 4096
# Down from 8192
# 3. Switch to a more efficient matching strategy # Exhaustive → sequential or vocab tree
# 4. Restrict GPU memory usage --SiftMatching.gpu_index 0
# Pin a specific GPU
# 5. Process in batches (very large datasets) # Split images into subsets, reconstruct each, then merge

# Inspect EXIF exiftool -FocalLength -FocalLengthIn35mmFormat ./images/*.jpg \

# DISK + LightGlue (requires hloc) pip install hloc
# hloc workflow python -m hloc.extract_features \
--image_dir ./images/ \
--output_dir ./features/ \
--model disk
python -m hloc.match_features \
--features ./features/ \
--output_dir ./matches/ \
--model lightglue
# Import matches into the COLMAP database python -m hloc.import_into_colmap \
--database_path ./database.db \
--features ./features/ \
--matches ./matches/
# Then run the COLMAP mapper as usual colmap mapper \
--database_path ./database.db \
--image_path ./images/ \
--output_path ./sparse/

colmap mapper \
--database_path ./database.db \
--image_path ./images/ \
--output_path ./sparse/ \
--Mapper.ba_refine_focal_length 0 \
--Mapper.ba_refine_extra_params 0

# Manually specify match pairs (advanced) # Create match_list.txt with one image-pair per line echo "frame_001.jpg frame_002.jpg" > match_list.txt echo "frame_002.jpg frame_003.jpg" >> match_list.txt # ...
colmap matches_importer \
--database_path ./database.db \
--match_list_path ./match_list.txt \
--match_type pairs

"""Convert COLMAP output to various 3DGS-framework input formats"""
import pycolmap import numpy as np import json from pathlib import Path
def colmap_to_transforms_json(colmap_path: str, output_path: str):
"""Convert to Nerfstudio / instant-ngp transforms.json format"""
reconstruction = pycolmap.Reconstruction()
reconstruction.read(colmap_path)
# Read camera intrinsics
camera = list(reconstruction.cameras.values())[0]
frames = []
for img_id, img in reconstruction.images.items():
if not img.registered:
continue
# COLMAP uses a world-to-camera transform
# transforms.json expects camera-to-world (c2w)
R = img.rotmat()
t = img.tvec
# c2w = [R\