pycolmap

Most PyCOLMAP functions accept configuration parameters via Python dictionaries or specific option objects (e.g., SiftExtractionOptions). Dictionaries are recursively merged into the default settings.

# Using a dictionary
pycolmap.extract_features(database_path, image_dir, sift_options={"max_num_features": 512})

# Using an option object
ops = pycolmap.SiftExtractionOptions()
ops.max_num_features = 512
pycolmap.extract_features(database_path, image_dir, sift_options=ops)

# To inspect defaults:
help(pycolmap.SiftExtractionOptions)

You can install pre-built wheels for Python 8/9/10 on Linux, macOS (Intel and Apple Silicon), and Windows using pip. Note that PyPI wheels are not built with CUDA support; if you require CUDA acceleration, you must build from source.

pip install pycolmap

To enable CUDA support or CGAL (for Delauney Triangulation), build from source. You must first install COLMAP (version 3.8 or 3.9.1 for PyCOLMAP 0.4.0 - 0.6.0) following the official COLMAP guide.

Linux and macOS:

python -m pip install .

Windows (using VCPKG): Run the following in PowerShell after installing COLMAP via VCPKG:

py -m pip install . `
    --cmake.define.CMAKE_TOOLCHAIN_FILE="$VCPKG_INSTALLATION_ROOT/scripts/buildsystems/vcpkg.cmake" `
    --cmake.define.VCPKG_TARGET_TRIPLET="x64-windows"

git clone -b 0.6.0 https://github.com/colmap/pycolmap.git
cd pycolmap

PyCOLMAP provides robust RANSAC-based estimators for relative geometry between two images.

Essential Matrix Estimation:

• points1: Nx2 array (pixel coordinates in image 1).
• points2: Nx2 array (pixel coordinates in image 2).
• camera1: pycolmap.Camera of image 1.
• camera2: pycolmap.Camera of image 2.
• options (optional): dict or pycolmap.RANSACOptions (default inlier threshold is 4px).

Fundamental Matrix Estimation:

• points1: Nx2 array.
• points2: Nx2 array.
• options (optional): dict or pycolmap.RANSACOptions.

# Essential Matrix
answer = pycolmap.essential_matrix_estimation(points1, points2, camera1, camera2)

# Fundamental Matrix
answer = pycolmap.fundamental_matrix_estimation(points1, points2, options)

The Reconstruction object allows you to load, inspect, transform, and export 3D models. The API mirrors the COLMAP C++ library.

Key capabilities:

• Access images, points3D, and cameras via .images, .points3D, and .cameras dictionaries.
• Project 3D points to image coordinates using camera.img_from_cam().
• Align reconstructions using pycolmap.align_reconstructions_via_reprojections().
• Export to text or PLY formats.

import pycolmap

# Load
reconstruction = pycolmap.Reconstruction("path/to/reconstruction/dir")
print(reconstruction.summary())

# Access data
for image_id, image in reconstruction.images.items():
    print(image_id, image)

# Project a point
# uv = camera.img_from_cam(image.cam_from_world * point3D.xyz)

# Export
reconstruction.write_text("path/to/new/reconstruction/dir/")
reconstruction.export_PLY("rec.ply")

Estimators require a pycolmap.Camera object. You can instantiate it using a model name and parameters, or by passing a dictionary.

Using Constructor:

• model: String (e.g., 'SIMPLE_PINHOLE') or ID.
• width: Image width.
• height: Image height.
• params: List of camera parameters (e.g., [focal_length, cx, cy] for a pinhole model).

Using Dictionary:

• model: Camera model name or ID.
• width: Image width.
• height: Image height.
• params: List of extra camera parameters.

# Via constructor
camera = pycolmap.Camera(
    model='SIMPLE_PINHOLE',
    width=width,
    height=height,
    params=[focal_length, cx, cy],
)

# Via dictionary
camera_dict = {
    'model': 'SIMPLE_PINHOLE',
    'width': 1920,
    'height': 1080,
    'params': [f, cx, cy]
}

Use pycolmap.absolute_pose_estimation to estimate the pose of a query camera given 2D-3D correspondences.

Parameters:

• points2D: Nx2 array (Numpy array or list) of pixel coordinates.
• points3D: Nx3 array (Numpy array or list) of world coordinates.
• camera: pycolmap.Camera object.
• estimation_options (optional): dict or pycolmap.AbsolutePoseEstimationOptions.
• refinement_options (optional): dict or pycolmap.AbsolutePoseRefinementOptions.

Returns: A dictionary of estimation outputs or None if the estimation fails.

answer = pycolmap.absolute_pose_estimation(
    points2D, 
    points3D, 
    camera,
    estimation_options=dict(ransac=dict(max_error=12.0)),
    refinement_options=dict(refine_focal_length=True),
)

Use the pycolmap.Sift class to extract keypoints and descriptors from a grayscale image. The input image should be a float array with values in the range [0, 1].

Parameters:

• image: HxW float array.
• options (optional): dict or pycolmap.SiftExtractionOptions.
• device (optional): pycolmap.Device (defaults to .auto, which uses GPU if available).

Returns:

• keypoints: Nx4 array; format: [x, y, scale, orientation].
• descriptors: Nx128 array; L2-normalized descriptors.

import numpy as np
import pycolmap
from PIL import Image, ImageOps

# Prepare grayscale image [0, 1]
img = Image.open('image.jpg').convert('RGB')
img = ImageOps.grayscale(img)
img_array = np.array(img).astype(np.float32) / 255.

sift = pycolmap.Sift()
keypoints, descriptors = sift.extract(img_array)

RANSAC parameters for geometric estimators are managed via pycolmap.RANSACOptions. These objects behave similarly to Python dataclasses.

ransac_options = pycolmap.RANSACOptions(
    max_error=4.0,  # e.g., reprojection error in pixels
    min_inlier_ratio=0.01,
    confidence=0.9999,
    min_num_trials=1000,
    max_num_trials=100000,
)

The pycolmap module exports several attributes to check the environment and versioning:

• __version__: The version of the pycolmap bindings.
• COLMAP_version: The version of the underlying COLMAP library.
• COLMAP_build: Build information for the COLMAP library.
• has_cuda: A boolean indicating if CUDA support is available (based on Device.AUTO).

import pycolmap

print(f"Pycolmap version: {pycolmap.__version__}}")
print(f"COLMAP version: {pycolmap.COLMAP_version}")
print(f"CUDA available: {pycolmap.has_cuda}")

The pycolmap.Device enum allows you to specify whether operations should run on the CPU or GPU (CUDA). Using auto allows the library to decide based on availability.

Available values:

• auto: Automatic selection.
• cpu: Force CPU execution.
• cuda: Force CUDA execution.

import pycolmap

# Example usage in a hypothetical function that accepts a device
# device = pycolmap.Device.cuda