SfM Tool

A tool for creating and exploring Structure from Motion (SfM) reconstructions, built on COLMAP and OpenCV.

Under construction - project is being restructured to better fit what it evolved into.

Components

• sfm CLI - Create workspaces, run SfM solves, and inspect reconstructions
• SfM Explorer GUI - View reconstructions in 3D, explore tracks and camera rays
• Python bindings - Access SfM functionality from Python via sfmtool-py

Quick Start

# Create a workspace with your images
mkdir -p workspace/images
cp /path/to/images/*.jpg workspace/images/
cd workspace

# Initialize and solve
sfm ws init .
sfm solve -g images/

# Inspect the result
sfm inspect sfmr/[filename].sfmr

Convert videos to image sequences

To try many different things with a particular 3D reconstruction, having the data as a video complicates individual frame access. Therefore the sfm command expects you to always convert to images first.

Here's an example of using ffmpeg to convert a single video in the current directory into a sequence of images in a frames subdirectory:

# Assumes there's one video in the current directory
VIDEO_FILE=$(echo *.mp4)

IMAGE_BASE=$(basename "$VIDEO_FILE")
IMAGE_BASE=${IMAGE_BASE%.*}

mkdir -p frames
ffmpeg -i "$VIDEO_FILE" \
    -qscale:v 2 \
    frames/"${IMAGE_BASE}_%04d.jpg"

Building

This project uses Pixi for environment management with Rust and Python.

# Run the Sfm Explorer GUI
pixi run gui

# Run tests
pixi run test

# Serve docs locally
pixi run docs-serve

Project Structure

crates/
  sfmtool-archive-io/       Shared ZIP + zstd container primitives
  sfmtool-sfmr-format/      .sfmr reconstruction file I/O
  sfmtool-sift-format/      SIFT feature file I/O
  sfmtool-matches-format/   Feature matches file I/O
  sfmtool-camrig-format/    .camrig camera-rig file I/O
  sfmtool-kdf-format/       .kdf kd-forest file I/O
  sfmtool-colmap/           COLMAP integration
  sfmtool-core/             Core project functionality
  sfm-explorer/             SfM Explorer GUI
  sfmtool-py/               Python bindings

License

Apache-2.0