⚠️Please note that this repository is still under active development. We will keep updating it regularly. Feel free to open an issue if you encounter any problem.

• 2025/12/02: Added a Dockerfile and quick test command to run the bundled examples/kitchen dataset.
• 2025/11/27: We changed the data structure into a more SIMD-friendly format, which further speeds up the whole pipeline by around 10%.

Note: The project requires an NVIDIA GPU with CUDA support. The code is tested on Ubuntu 20.04 with CUDA 12.1 and PyTorch 2.3.1. Windows system is strongly unrecommended as the bae package lacks support for Windows.
Start with cloning the repository:

git clone https://github.com/cre185/instantsfm.git --recursive

Create a conda environment:

conda create -n instantsfm python=3.12
conda activate instantsfm

Install PyTorch and dependencies. We have tested with PyTorch (2.3.1 with CUDA 12.1). Choose your own version according to your CUDA version here:

pip3 install torch torchvision

If scikit-sparse installation fails due to suitesparse, this dependency shall be installed manually. For example,

conda install -c conda-forge suitesparse
# Linux
export SUITESPARSE_INCLUDE_DIR=$CONDA_PREFIX/include/suitesparse
export SUITESPARSE_LIBRARY_DIR=$CONDA_PREFIX/lib
# Windows
export SUITESPARSE_INCLUDE_DIR=$CONDA_PREFIX\Library\include\suitesparse
export SUITESPARSE_LIBRARY_DIR=$CONDA_PREFIX\Library\lib

Then you can install instantsfm locally by running:

pip install -e .

Install bae by running:

pip install git+ssh://git@github.com/zitongzhan/bae.git

If you find error like

fatal error: cudss.h: No such file or directory
   10 | #include <cudss.h>
      |          ^~~~~~~~~
compilation terminated

then you need to download and install cuDSS package from here.
The cuDSS should match the version of CUDA toolchain. For example, cuDSS 0.7 should be used with CUDA 13.

If opencv-python fail to load xcb, you can install opencv-python-headless

pip install opencv-python-headless

By default feature extraction is done via COLMAP, which requires you to install COLMAP first. You can follow the instructions here or install through conda:

conda install conda-forge::colmap

Make sure the colmap command is available in your terminal.

To run the demo, simply try the command python demo.py. In the demo, you can choose to reconstruct either from user-provided images or from a image directory. A valid input image directory should follow the structure shown below:

- demo_input_folder/
    - images/
    - database.db (optional, will be used if provided, and will be generated if not provided)

In both cases, the output will be saved in the corresponding folder(demo_output/ or your specified folder), and the results will be displayed directly in the web viewer.

If you built the provided Dockerfile into an image tagged instantsfm, you can sanity‑check the pipeline on the bundled examples/kitchen data with a single container run. This Dockerfile supports both arm64 and x86_64 architectures. Build the Docker image with:

docker build -t instantsfm .

The command below mounts the repo so results persist to your host and uses --rm for a clean exit:

docker run --rm --gpus all --ipc=host --ulimit memlock=-1 --ulimit stack=67108864 \
  -v "$PWD":/workspace/InstantSfM -w /workspace/InstantSfM instantsfm \
  bash -lc "ins-feat --data_path examples/kitchen --feature_handler colmap --manual_config_name colmap && \
            ins-sfm --data_path examples/kitchen --manual_config_name colmap --export_txt"

Outputs will appear under examples/kitchen/sparse on the host.

The whole pipeline consists of three main steps: feature extraction and matching, global structure from motion (SfM), and 3DGS training.
Before performing these steps, prepair your dataset (a collection of images) in a folder structure like mentioned in the demo section, that is, a folder containing a subfolder images/ with all the images inside.
To extract features and perform matching, use the following command:

ins-feat --data_path /path/to/folder

To run the global SfM and bundle adjustment, use:

ins-sfm --data_path /path/to/folder

We also provided 3DGS training support, and you can run it with the following command:

ins-gs --data_path /path/to/folder

Visualization of the reconstruction process is also supported, to visualize the reconstruction process, use:

ins-sfm --data_path /path/to/folder --enable_gui

You can also add --record_recon to the command above to take record of the reconstruction process. The recorded data will be saved in /path/to/folder/record/. If record is available, use the command below to visualize the recorded reconstruction process afterwards:

ins-vis --data_path /path/to/folder

For a more detailed usage, you can run the command with --help to see all available options.

While the default configuration should work for most cases, you can also try to modify the configuration in the config/ folder to improve the performance on your own dataset.
Want to apply several modifications to config files while keeping the original ones? Add the --manual_config_name argument and specify the name of your own config file. For example, if you created a new config file config/my_config.py, add --manual_config_name my_config to the command line. Please make sure the config file is a valid one, the recommended way is to copy an original config file and modify it.

Acknowledgments: We thank the following great works: BAE, Pypose, COLMAP, GLOMAP, VGGT, VGGSfM. We would like to thank Linfei Pan for the help.

If you find our code or paper useful, please consider citing:

@article{zhong2025instantsfm,
  title = {InstantSfM: Fully Sparse and Parallel Structure-from-Motion},
  author={Jiankun Zhong and Zitong Zhan and Quankai Gao and Ziyu Chen and Haozhe Lou and Jiageng Mao and Ulrich Neumann and Yue Wang},
  journal = {arXiv preprint arXiv:2510.13310},
  year = {2025},
  url = {https://arxiv.org/abs/2510.13310}
}

and

@article{zhan2025bundle,
  title = {Bundle Adjustment in the Eager Mode},
  author = {Zhan, Zitong and Xu, Huan and Fang, Zihang and Wei, Xinpeng and Hu, Yaoyu and Wang, Chen},
  journal = {arXiv preprint arXiv:2409.12190},
  year = {2025},
  url = {https://arxiv.org/abs/2409.12190}
}