Skip to content

Instantly share code, notes, and snippets.

@Chaos-man
Forked from polyfjord/AutoTracker_v1.4.bat
Last active November 11, 2025 20:57
Show Gist options
  • Select an option

  • Save Chaos-man/cbe063cbfb0624026f022a0ae8de021f to your computer and use it in GitHub Desktop.

Select an option

Save Chaos-man/cbe063cbfb0624026f022a0ae8de021f to your computer and use it in GitHub Desktop.
AutoTracker workflow using GLOMAP (Linux headless CPU version)

A (Hopefully) Pain-Free Guide to the Polyfjord COLMAP/GLOMAP Workflow

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.

System Specifications

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)

Installation

These instructions are tailored for Debian-based Linux distributions.

Step 1: Install FFmpeg

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 -y

Step 2: Install COLMAP & GLOMAP Dependencies

Next, 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-dev

Step 3: Install Intel's Math Kernel Library (MKL)

For 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 -y

Step 4: Build and Install COLMAP from Source

The 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 install

Note: 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.

Step 5: Build and Install GLOMAP from Source

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 install

Note: The -DFETCH_COLMAP=OFF flag tells the build process not to download another copy of COLMAP, since we already built and installed it ourselves.

Workspace Setup

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.sh
  • VIDEOS: This is where you will place the video files you want to process.
  • SCENES: The script will save the reconstructed 3D scenes here.

Usage

  1. Place your video files inside the ~/workspace/VIDEOS directory.
  2. Navigate to the ~/workspace directory in your terminal.
  3. 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=offscreen

Now, 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.sh

Note: This guide does not cover the setup process for NVIDIA drivers or the CUDA toolkit.

An Important Note on Script Updates

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_gpu is now --FeatureExtraction.use_gpu
  • --SiftMatching.use_gpu is now --FeatureMatching.use_gpu

The linked version of the script already includes these changes.

#!/bin/bash
# ================================================================
# This script was originally created by:
# Wolkensteine (https://mastodon.wolkenheim.eu/@Wolkensteine)
# This script was updated by:
# Chaos-man (https://github.com/Chaos-man)
# It is provided free of charge and comes with no warrenty.
# Use this at your own risk.
# ================================================================
#
# Use case:
# As described in Polyfjords video (https://youtu.be/xx85eyN1Xc0) this is about making a very simple 3D-Tracking workflow with only open source software.
#
# The original script can be found on codeberg.org:
# https://codeberg.org/wolkensteine/Polyfjord-COLMAP-Workflow
set -euo pipefail
THREADS_TO_USE="$(getconf _NPROCESSORS_ONLN)"
# Use environment variable if set, otherwise default to 0
use_gpu=${USE_GPU:-0}
if ! command -v ffmpeg >/dev/null 2>&1
then
echo "ffmpeg could not be found. Please check that it is installed and within your PATH."
exit 1
fi
if ! command -v colmap >/dev/null 2>&1
then
echo "colmap could not be found. Please check that it is installed and within your PATH."
exit 1
fi
VIDEOS_DIR=VIDEOS
SCENES_DIR=SCENES
if [ ! -d "$VIDEOS_DIR" ]; then
echo "The directory $VIDEOS_DIR does not exist."
exit 1
fi
if [ ! -d "$SCENES_DIR" ]; then
echo "The directory $SCENES_DIR does not exist."
exit 1
fi
process_video_file () {
echo "Processing: $1"
if [ -d "$SCENES_DIR/$2" ]; then
echo "↻ Skipping $1 – it looks to be already reconstructed."
return
fi
IMG_DIR="$SCENES_DIR/$2/images"
SPARSE_DIR="$SCENES_DIR/$2/sparse"
mkdir -p "$IMG_DIR"
mkdir -p "$SPARSE_DIR"
echo "[1/4] Extracting frames."
ffmpeg -stats -i "$1" -qscale:v 2 "$IMG_DIR/frame_%06d.jpg"
echo "[2/4] Extracting features ..."
colmap feature_extractor \
--database_path "$SCENES_DIR/$2/database.db" \
--image_path "$IMG_DIR" \
--ImageReader.single_camera 1 \
--FeatureExtraction.use_gpu $use_gpu \
--SiftExtraction.max_image_size 4096 || { echo " ✖ feature_extractor failed"; return; }
echo "[3/4] Matching features ..."
colmap sequential_matcher \
--database_path "$SCENES_DIR/$2/database.db" \
--SequentialMatching.overlap 15 \
--FeatureMatching.use_gpu $use_gpu || { echo " ✖ sequential_matcher failed"; return; }
echo "[4/4] Mapping ..."
glomap mapper \
--database_path "$SCENES_DIR/$2/database.db" \
--image_path "$IMG_DIR" \
--output_path "$SPARSE_DIR" || { echo " ✖ GLOMAP mapper failed"; return; }
# Original version with colmap
#colmap mapper \
# --database_path "$SCENES_DIR/$2/database.db" \
# --image_path "$IMG_DIR" \
# --output_path "$SPARSE_DIR" \
# --Mapper.num_threads "$THREADS_TO_USE"
echo "Done. Exporting best model."
colmap model_converter \
--input_path "$SPARSE_DIR/0" \
--output_path "$SPARSE_DIR" \
--output_type TXT || { echo " ✖ model_converter failed"; return; }
}
NUMBER_OF_VIDEO_FILES="$(ls "$VIDEOS_DIR" | wc -l)"
if [ ! "$NUMBER_OF_VIDEO_FILES" -gt "0" ]; then
echo "No video files found."
exit 1
fi
echo "Starting COLMAP on $NUMBER_OF_VIDEO_FILES video file(s)."
FILES="$VIDEOS_DIR/*"
for FILE in $FILES
do
process_video_file $FILE ${FILE/$VIDEOS_DIR\//}
done
echo "Finished."
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment