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 implementationscommon
: basic classes used through GTSFM, such asKeypoints
,Image
,SfmTrack2d
, etcdata_association
: 3d point triangulation (DLT) w/ or w/o RANSAC, from 2d point-tracksdensify
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 loadersutils
: 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.