COLMAP Rerun Visualizer

Visualize COLMAP sparse / dense reconstruction output using Rerun's 3D visualization capabilities.

https://github.com/user-attachments/assets/590b9902-6213-4545-985a-af478ab6d576

Features

• Interactive 3D visualization of COLMAP reconstructions
• Support for both filtered and unfiltered point clouds
• Dataset-specific visualization presets
• Resolution scaling for performance optimization
• Python API and CLI interface

Installation

From PyPI

pip install colmap-rerun

From Source

git clone https://github.com/vincentqyw/colmap_rerun.git
cd colmap_rerun
pip install -e .

For development:

pip install -e ".[dev]"

Quick Start

Example Dataset

We provide sample reconstruction data to help you get started:

1. Download the sample data from Google Drive
2. Unzip the downloaded file to get the following directory structure:

sample_data/dense/
├── images/               # Input images (JPG/PNG format)
├── sparse/               # COLMAP sparse reconstruction
│   ├── cameras.bin       # Camera intrinsic parameters
│   ├── images.bin        # Camera extrinsic parameters (poses)
│   └── points3D.bin      # Reconstructed 3D point cloud
└── stereo/
    └── depth_maps/       # Depth maps (optional)

3. Visualize the reconstruction:

Using CLI

The CLI provides several options for visualizing COLMAP reconstructions:

Basic Usage

Visualize dense reconstruction (automatically finds sparse model and images):

viz-colmap --dense_model sample_data/dense

Advanced Options

Visualize sparse reconstruction with custom paths:

viz-colmap --sparse_model sample_data/sparse --images_path sample_data/images

Resize images for better performance:

viz-colmap --dense_model sample_data/dense --resize 640 480

Show unfiltered point cloud (includes noisy data):

viz-colmap --dense_model sample_data/dense --unfiltered

CLI Arguments

Argument	Description	Required
--dense_model	Path to dense reconstruction folder (contains sparse/ and images/)	No
--sparse_model	Path to sparse reconstruction folder (contains cameras.bin, images.bin, points3D.bin)	Required if no dense_model
--images_path	Path to folder containing input images	Required if no dense_model
--resize W H	Resize images to width W and height H for better performance	No
--unfiltered	Show unfiltered point cloud (includes noisy data)	No

Or using Python API:

from pathlib import Path
from colmap_rerun import visualize_reconstruction
from colmap_rerun.core.read_write_model import read_model

# Setting data root
data_root = Path("sample_data/dense")

# Load reconstruction
cameras, images, points3D = read_model(data_root / "sparse")

# Visualize
visualize_reconstruction(
    cameras=cameras,
    images=images,
    points3D=points3D,
    images_root=Path(data_root / "images"),
    depths_root=Path(data_root / "stereo/depth_maps"),  # optional
)

Documentation

Full documentation is available at docs/.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

1. Install development dependencies:

pip install -e ".[dev]"

2. Run tests:

pytest

3. Format code:

black .

Code of Conduct

This project adheres to the Contributor Covenant code of conduct.

Acknowledgements

• This project uses Rerun for visualization
• Inspired by COLMAP's 3D reconstruction capabilities

License

MIT - See LICENSE for details.