# InstantSfM **Repository Path**: gotoeasy/InstantSfM ## Basic Information - **Project Name**: InstantSfM - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-12 - **Last Updated**: 2026-06-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README
# InstantSfM #### Towards GPU-Native SfM for the Deep Learning Era

Jiankun Zhong1,3*, Zitong Zhan2*, Quankai Gao1*, Ziyu Chen1, Haozhe Lou1, Jiageng Mao1, Ulrich Neumann1, Chen Wang2, Yue Wang1
1University of Southern California 2University at Buffalo 3Tsinghua University

KPI dashboard | Paper | Video

**⚠️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.**

Garden bundle adjustment example

Counter bundle adjustment example

Kitchen bundle adjustment example

Garden Counter Kitchen
## News📰 - **2026/03/31**: Fix the accuracy of retriangulation between bundle adjustment loops. More runtime improvements on the way. - **2026/02/06**: Bumped to version 0.2.0 with tools for depth generation. Detailed information can be found below. - **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%. ## 1. Installation **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: ```bash git clone https://github.com/cre185/instantsfm.git --recursive ``` Create a conda environment: ```bash 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](https://pytorch.org/get-started/previous-versions/): ```bash pip3 install torch torchvision ``` If scikit-sparse installation fails due to suitesparse, this dependency shall be installed manually. For example, ```bash 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: ```bash pip install -e . ``` Install bae by running: ```bash pip install git+https://github.com/sair-lab/bae.git ``` If you find error like ```bash fatal error: cudss.h: No such file or directory 10 | #include | ^~~~~~~~~ compilation terminated ``` then you need to download and install cuDSS package using [instructions](https://github.com/sair-lab/bae#setup-instructions) and package [source](https://developer.nvidia.com/cudss-downloads?target_os=Linux&target_arch=x86_64&Distribution=Ubuntu&target_version=20.04&target_type=deb_local). 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 ```bash 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](https://colmap.github.io/install.html) or install through [conda](https://anaconda.org/conda-forge/colmap): ```bash conda install conda-forge::colmap ``` Make sure the `colmap` command is available in your terminal. ## 2. Demo 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. ## Docker quick test (kitchen example) 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: ```bash docker build -t instantsfm . ``` The command below mounts the repo so results persist to your host and uses `--rm` for a clean exit: ```bash 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. ## 3. Command Line Usage 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: ```bash ins-feat --data_path /path/to/folder ``` To run the global SfM and bundle adjustment, use: ```bash ins-sfm --data_path /path/to/folder ``` We also provided 3DGS training support, and you can run it with the following command: ```bash ins-gs --data_path /path/to/folder ``` Visualization of the reconstruction process is also supported, to visualize the reconstruction process, use: ```bash 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: ```bash ins-vis --data_path /path/to/folder ``` For a more detailed usage, you can run the command with `--help` to see all available options. ## 4. Tools for extra data processing We provide extra tools for data processing based on prevalent models in the `tools/` folder. Please refer to [tools/usage.md](tools/usage.md) for more details. Currently we support Video Depth Anything for metric scale depth estimation from videos. More tools will be added in the future. ## 5. Manual configuration 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](https://github.com/zitongzhan/bae), [Pypose](https://github.com/pypose/pypose), [COLMAP](https://github.com/colmap/colmap), [GLOMAP](https://github.com/colmap/glomap), [VGGT](https://github.com/facebookresearch/vggt), [VGGSfM](https://github.com/facebookresearch/vggsfm). We would like to thank Linfei Pan for the help. ## Citation If you find our code or paper useful, please consider citing: ``` @article{zhong2026instantsfm, title = {InstantSfM: Towards GPU-Native SfM for the Deep Learning Era}, author = {Zhong, Jiankun and Zhan, Zitong and Gao, Quankai and Chen, Ziyu and Lou, Haozhe and Mao, Jiageng and Neumann, Ulrich and Wang, Chen and Wang, Yue}, journal = {arXiv preprint arXiv:2510.13310}, year = {2025}, url = {https://arxiv.org/abs/2510.13310}, code = {https://github.com/cre185/InstantSfM} } ``` and ``` @article{zhan2026bundle, 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 = {IEEE Transactions on Robotics}, year = {2026}, url = {https://arxiv.org/abs/2409.12190} } ```