GTSFM is an end-to-end SFM pipeline based on GTSAM. GTSFM was designed from the ground-up to natively support parallel computation using Dask.

The majority of our code is governed by a MIT license and is suitable for commercial use. However, certain implementations featured in our repo (SuperPoint, SuperGlue) are governed by a non-commercial license and may not be used commercially.

GTSFM requires no compilation, as Python wheels are provided for GTSAM.

To install GTSFM, first, we need to create a conda environment.

Linux On Linux, with CUDA support:

conda env create -f environment_linux.yml
conda activate gtsfm-v1 # you may need "source activate gtsfm-v1" depending upon your bash and conda set-up

The Python3.8 gtsam wheel for Linux is available here.

Mac On Mac OSX, there is no CUDA support, so run:

conda env create -f environment_mac.yml
conda activate gtsfm-v1

Download the Python 3.8 gtsam wheel for Mac here, and install it as

pip install ~/Downloads/gtsam-4.1.1-py3-none-any.whl

Now, install gtsfm as a module:

pip install -e .

Make sure that you can run python -c "import gtsfm; import gtsam; print('hello world')" in python, and you are good to go!

On Mac OSX, there is no pydegensac wheel in pypi, instead build pydegensac:

git clone https://github.com/ducha-aiki/pydegensac.git
cd pydegensac
python setup.py bdist_wheel
pip install dist/pydegensac-0.1.2-cp38-cp38-macosx_10_15_x86_64.whl

Before running reconstruction, if you intend to use modules with pre-trained weights, such as SuperPoint, SuperGlue, or PatchmatchNet, please first run:

./download_model_weights.sh

To run SfM with a dataset with only a image directory and EXIF, with image file names ending with "jpg", run:

python gtsfm/runner/run_scene_optimizer.py --config_name {CONFIG_NAME} --dataset_root {DATASET_ROOT} --image_extension jpg --num_workers {NUM_WORKERS}

If you would like to compare GTSFM output with COLMAP output, please run:

python gtsfm/runner/run_scene_optimizer_colmap_loader.py --config_name {CONFIG_NAME} --images_dir {IMAGES_DIR} --colmap_files_dirpath {COLMAP_FILES_DIRPATH} --image_extension jpg --num_workers {NUM_WORKERS} --max_frame_lookahead {MAX_FRAME_LOOKAHEAD}

where COLMAP_FILES_DIRPATH is a directory where .txt files such as cameras.txt, images.txt, etc have been saved.

GTSFM is designed in an extremely modular way. Each module can be swapped out with a new one, as long as it implements the API of the module's abstract base class. The code is organized as follows:

• gtsfm: source code, organized as:
  • averaging
    • rotation: rotation averaging implementations (Shonan, Chordal, etc)
    • translation: translation averaging implementations (1d-SFM, etc)
  • bundle: bundle adjustment implementations
  • common: basic classes used through GTSFM, such as Keypoints, Image, SfmTrack2d, etc
  • data_association: 3d point triangulation (DLT) w/ or w/o RANSAC, from 2d point-tracks
  • densify
  • frontend: SfM front-end code, including:
    • detector: keypoint detector implementations (DoG, etc)
    • descriptor: feature descriptor implementations (SIFT, etc)
    • matcher: descriptor matching implementations (Superglue, etc)
    • verifier: 2d-correspondence verifier implementations (Degensac, OA-Net, etc)
  • loader: image data loaders
  • utils: utility functions such as serialization routines and pose comparisons, etc
• tests: unit tests on every function and module

Contributions are always welcome! Please be aware of our contribution guidelines for this project.

Open-source Python implementation:

@misc{
    author = {Ayush Baid, Fan Jiang, Akshay Krishnan, John Lambert, Aditya Singh
       Aishwarya Venkataramanan, Sushmita Warrier, Jing Wu, Xiaolong Wu, Frank Dellaert},
    title = {GTSFM: Georgia Tech Structure from Motion},
    howpublished={\url{https://github.com/borglab/gtsfm}},
    year = {2021},
}

Note: authors are listed in alphabetical order.