PyCuSFM: Cuda Accelerated Structure from Motion

Overview

This repository provides the official python implementation of cuSFM, a novel CUDA-accelerated Structure-from-Motion framework for reconstructing 3D environmental models from images. Key features include:

• CUDA-accelerated feature extraction, matching, and graph optimization for superior speed and scalability
• Precise and robust camera pose estimation
• Accurate and consistent 3D environment reconstruction with COLMAP-compatible outputs
• Support for any number and type of camera inputs
• Reliable extrinsic calibration for multi-camera setups
• Localization mode for integrating new data into pre-built maps

Refer to paper for technical details and benchmark results about cuSFM.

Updates

Version 0.1.3 - Latest Release

• Added keyframe metadata generator to simplify frames_meta.json creation (Tool docs)
• Populated RGB values in the output sparse point cloud with --output_rgb (Mapping docs)
• Added OPENCV_FISHEYE camera model support and camera models doc
• Added rolling shutter guidance

Version 0.1.2

• Added support for COLMAP binary format (.bin) output with --export_binary_colmap_files flag
• Added distortion parameter output support for COLMAP FULL_OPENCV camera model

For more details, see tutorial - Step-Specific Options → Step 6: COLMAP Conversion.

Version 0.1.1

• Added build for CUDA 13 that support Blackwell GPUs
• Added CUDA 13 docker file

Version 0.1.0 - Initial Release

• Initial release of everything

COLMAP vs cuSFM

Trajectory Initialization Requirements

The need for initial trajectory guess depends on your input data type:

How to provide initial poses: Populate the camera_to_world field in the frames_meta.json file with 6DOF camera poses. See the tutorial for detailed instructions on pose formats and types.

Note: Support for un-posed sequential monocular images will be added in future release.

Installation

Prerequisites

Before installation, ensure your system meets the following requirements based on your CUDA version:

Common Requirements

• Operating System: Ubuntu 24.04 LTS (recommended)
• Python: Version 3.8 or higher
• Git LFS: For downloading large model files

CUDA-Specific Requirements

For CUDA 12:

• NVIDIA Driver: Version 525 or higher
• CUDA Toolkit: 12.0 or compatible version

For CUDA 13:

• NVIDIA Driver: Version 580 or higher
• CUDA Toolkit: 13.0 or compatible version

Note: Check your current driver version with nvidia-smi and CUDA version with nvcc --version before proceeding.

Download Repository

Install Git LFS (if not already installed):

# Install Git LFS
sudo apt-get install git-lfs

# Initialize Git LFS
git lfs install

Clone the repository and navigate to the project directory:

git clone https://github.com/nvidia-isaac/PyCuSFM
cd pycusfm

Repository Setup

Important: Before proceeding with installation, you must configure the repo based on your CUDA version on system:

# For CUDA 12 systems
./setup.bash cuda12

# For CUDA 13 systems
./setup.bash cuda13

This script creates symbolic links to the appropriate CUDA-specific binaries and libraries in the pycusfm/ directory. The setup is required before any installation or usage.

Important Notes:

• Run this setup script immediately after cloning the repository
• Verify your CUDA version with nvcc --version before running the setup script
• The script will automatically clean up previous symlinks and create new ones for the selected CUDA version

Choose one of the following installation methods based on your preference:

# Check NVIDIA driver version
nvidia-smi

# Check CUDA version
nvcc --version

# Check Python version
python3 --version

# Run the automated installation script
./install_in_host.sh

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Build Docker image and run container with PyCuSFM installation (CUDA 13 - default)
./run_in_docker.sh --build_docker --install

# Build Docker image and run container with PyCuSFM installation (CUDA 12)
./run_in_docker.sh --cuda cuda12 --build_docker --install

Usage

Quick Start

# Basic usage
cusfm_cli --input_dir <input_dir> --cusfm_base_dir <output_dir>

# Example with sample data
cusfm_cli --input_dir data/r2b_galileo --cusfm_base_dir results/cusfm_output

For detailed instructions, examples, and advanced configurations, see our Complete Tutorial covering:

• Data Requirements: Input format and structure
• Command Line Options: All available parameters and flags
• Quick Start Guide: Step-by-step example with sample data
• KITTI Dataset: Running on standard benchmark datasets
• Advanced Features: Multi-camera setups, AV data, rolling shutter correction, bundle adjustment runner for COLMAP format

Acknowledgments

We would like to express our gratitude to the authors of the following projects, whose work has significantly contributed to the development of cuSFM:

• PyCuVSLAM
• cuDSS
• CV-CUDA
• ALIKED-TensorRT
• LightGlue
• LightGlue-ONNX
• COLMAP
• SuperPoint

Third-Party Dependency

Citation

If you find our work useful in your research, please consider giving a star :star: and citing the following paper :pencil:.

@article{2025CuSfM,
  title={CuSfM: CUDA-Accelerated Structure-from-Motion},
  author={Yu, Jingrui and Liu, Jun and Ren, Kefei and Biswas, Joydeep and Ye, Rurui and Wu, Keqiang and Majithia, Chirag and Zeng, Di},
  journal={arXiv preprint arXiv:2510.15271},
  year={2025},
  eprint={2510.15271},
  archivePrefix={arXiv},
  primaryClass={cs.CV}
}