Let's be honest, getting open-source projects to play nicely together can be an absolute nightmare. You follow one guide, it's outdated. You try to compile something, and you're suddenly in a dependency hell that makes you question all your life choices. After wrestling with countless cryptic error messages and conflicting documentation, I finally got this workflow running smoothly. This guide is the product of that struggle—a complete, step-by-step walkthrough to save you the headache I went through. If you're trying to get this 3D tracking setup working, I hope this helps you bypass the frustration and get straight to creating.
This document provides a detailed guide to setting up and using the Polyfjord COLMAP/GLOMAP workflow on a Linux-based system. This workflow is designed to automate the process of 3D camera tracking and scene reconstruction from video footage using open-source tools. The end result is a 3D scene that can be imported into software like Blender, allowing you to seamlessly blend virtual objects with your original footage.
These instructions were tested on the following setup. You should have similar or better specs for a smooth experience.
- VM: LXC
- OS: Debian 13
- CPUs: Minimum 4 (More is better; this was tested with 10)
- RAM: 8GB recommended. (Building from source with the commands below used over 4GB of RAM)
- HHD: 5GB+ (A minimum of 5GB is needed for the OS and all the required library packages)
These instructions are tailored for Debian-based Linux distributions.
This is a versatile tool for handling multimedia files. In this workflow, it's used to extract individual frames from your video footage, turning them into an image sequence that COLMAP can process.
sudo apt-get install ffmpeg -yNext, you'll need to install a number of libraries and build tools required to compile COLMAP and GLOMAP from source.
# Install CMake, Ninja, C++ compiler, and git
sudo apt-get install \
git \
cmake \
ninja-build \
build-essential \
libboost-program-options-dev \
libboost-graph-dev \
libboost-system-dev \
libeigen3-dev \
libfreeimage-dev \
libmetis-dev \
libgoogle-glog-dev \
libgtest-dev \
libgmock-dev \
libsqlite3-dev \
libglew-dev \
qtbase5-dev \
libqt5opengl5-dev \
libcgal-dev \
libceres-dev \
libcurl4-openssl-dev \
libsuitesparse-devFor better performance, we'll use Intel's MKL.
# Edit your sources list to include non-free packages
sudo nano /etc/apt/sources.list.d/debian.sources
# In the editor, add non-free and non-free-firmware to the deb lines.
# For example: `Components: main contrib non-free non-free-firmware`
# Update your package list and install the library
sudo apt update
sudo apt install libmkl-full-dev -yThe version of COLMAP in the default Debian repositories is too old to work with the desired version of GLOMAP. Therefore, we must build a newer version from source.
# Navigate to your home directory and clone a specific, stable version of COLMAP
cd ~
git clone --branch 3.13.0 https://github.com/colmap/colmap.git
# Create a build directory and configure the project
cd colmap
mkdir build && cd build
cmake .. -GNinja -DBLA_VENDOR=Intel10_64lp
# Compile and install
ninja -j4
sudo ninja installNote: Don't clone from master, always select a stable branch. Master branch is used for development, so it's usually not stable.
Note: The ninja -j4 command builds the software using 4 parallel jobs. Each job can use 1-2GB of RAM, so with -j4, you might need 4-8GB available. Adjust this number based on your available RAM and CPU cores.
Now we'll do the same for GLOMAP, a faster alternative for 3D reconstruction.
# Navigate to your home directory and clone a specific version of GLOMAP
cd ~
git clone --branch 1.2.0 https://github.com/colmap/glomap.git
# Create a build directory and configure the project
cd glomap
mkdir build && cd build
cmake .. -GNinja -DFETCH_COLMAP=OFF -DCOLMAP_DIR=/usr/local/share/colmap
# Compile and install
ninja -j4
sudo ninja installNote: The -DFETCH_COLMAP=OFF flag tells the build process not to download another copy of COLMAP, since we already built and installed it ourselves.
With the tools installed, you can now set up a dedicated workspace for your projects.
# Navigate to your home directory
cd ~
# Create the workspace and subdirectories
mkdir workspace && cd workspace
mkdir VIDEOS
mkdir SCENES
# Download the automation script and make it executable
wget https://gist.githubusercontent.com/Chaos-man/cbe063cbfb0624026f022a0ae8de021f/raw/AutoTracker_v1.4_Linux.sh
chmod +x AutoTracker_v1.4_Linux.shVIDEOS: This is where you will place the video files you want to process.SCENES: The script will save the reconstructed 3D scenes here.
- Place your video files inside the
~/workspace/VIDEOSdirectory. - Navigate to the
~/workspacedirectory in your terminal. - Run the script.
For a headless environment (e.g., a server without a graphical user interface), you must set an environment variable before running the script to prevent it from trying to open a graphical window.
export QT_QPA_PLATFORM=offscreenNow, execute the script:
# For CPU-based reconstruction
./AutoTracker_v1.4_Linux.sh
# For GPU-based reconstruction (if you have a compatible NVIDIA GPU)
USE_GPU=1 ./AutoTracker_v1.4_Linux.shNote: This guide does not cover the setup process for NVIDIA drivers or the CUDA toolkit.
The AutoTracker script has been updated to reflect recent changes in COLMAP's command-line arguments. Specifically, the flags for GPU usage have changed:
--SiftExtraction.use_gpuis now--FeatureExtraction.use_gpu--SiftMatching.use_gpuis now--FeatureMatching.use_gpu
The linked version of the script already includes these changes.