Skip to content

Installation

This page covers building the Triton Video Sampling toolkit from source.

System Requirements

  • Operating System: Linux, macOS, or Windows (WSL2)
  • Disk Space: ~500 MB for build dependencies + source
  • RAM: 2 GB minimum, 8 GB recommended for parallel builds
  • CPU: Any modern x86_64 or ARM64 processor

Build Dependencies

Required

  1. C++17 Compiler

    • GCC 7+ (Linux)
    • Clang 5+ (macOS/Linux)
    • MSVC 2017+ (Windows, not tested)

  2. CMake 3.16+

    • Used for build configuration

  3. OpenCV 4.x with video I/O support

    • Requires FFMPEG or GStreamer backend
    • Must be compiled with -DWITH_FFMPEG=ON or -DWITH_GSTREAMER=ON

Optional

  1. OpenMP (for parallel processing via --jobs)
    • Included with GCC and Clang on most systems
    • Provides ~4–8× speedup on multi-core CPUs

Auto-Fetched by CMake

These dependencies are downloaded and built automatically:

No manual installation required.

Installation by Platform

Ubuntu / Debian

# Install build tools and OpenCV
sudo apt update
sudo apt install -y \
  build-essential \
  cmake \
  libopencv-dev \
  libomp-dev

# Verify OpenCV version (should be 4.x)
pkg-config --modversion opencv4

# Clone repository
git clone https://github.com/mbari-org/triton-video-sampling.git
cd triton-video-sampling

# Build
mkdir build && cd build
cmake ..
make -j$(nproc)

# Binaries: ./sample and ./calibrate
./sample --help

Tested on: Ubuntu 20.04, 22.04, 24.04

Fedora / RHEL

# Install build tools and OpenCV
sudo dnf install -y \
  gcc-c++ \
  cmake \
  opencv-devel

# Clone and build
git clone https://github.com/mbari-org/triton-video-sampling.git
cd triton-video-sampling
mkdir build && cd build
cmake ..
make -j$(nproc)

Tested on: Fedora 38, 39

macOS

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install cmake opencv

# Clone and build
git clone https://github.com/mbari-org/triton-video-sampling.git
cd triton-video-sampling
mkdir build && cd build
cmake ..
make -j$(sysctl -n hw.ncpu)

Tested on: macOS 13 (Ventura), 14 (Sonoma)

Note: Apple Silicon (M1/M2) is supported via Rosetta 2 or native ARM64 builds.

Windows (WSL2)

Use Windows Subsystem for Linux 2 with Ubuntu:

# Inside WSL2 Ubuntu terminal
sudo apt update
sudo apt install -y build-essential cmake libopencv-dev

# Clone and build (follow Ubuntu instructions above)

Native Windows build (not officially supported):

  • Install Visual Studio 2019+ with C++ tools
  • Install vcpkg: vcpkg install opencv4[ffmpeg]
  • Use CMake GUI to configure and generate Visual Studio solution

Verifying Installation

Check OpenCV Video Support

# Check if FFMPEG is enabled
pkg-config --libs opencv4 | grep -i ffmpeg

# Test video reading
python3 -c "import cv2; cap = cv2.VideoCapture('test.mp4'); print(cap.isOpened())"

If FFMPEG is missing, reinstall OpenCV:

# Ubuntu: remove pip version, use system package
pip3 uninstall opencv-python
sudo apt install libopencv-dev

Check OpenMP Support

# GCC: check for -fopenmp flag
gcc -fopenmp --version

# Test parallel execution
./sample --jobs 4 --help  # Should not error

If OpenMP is missing:

# Ubuntu
sudo apt install libomp-dev

# macOS (may require libomp from Homebrew)
brew install libomp

Build Options

Release Build (Default)

Optimized for performance (-O3, vectorization enabled):

cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

Debug Build

Includes debug symbols, no optimization (for development):

cmake -DCMAKE_BUILD_TYPE=Debug ..
make -j$(nproc)

Specify OpenCV Path

If CMake can't find OpenCV automatically:

cmake -DOpenCV_DIR=/usr/local/lib/cmake/opencv4 ..

or

cmake -DOpenCV_DIR=/opt/homebrew/Cellar/opencv/4.8.0/lib/cmake/opencv4 ..

Disable OpenMP

If you encounter OpenMP issues:

cmake -DUSE_OPENMP=OFF ..
make

Note: This disables the --jobs parameter.

Post-Installation

Add to PATH (Optional)

# Add to ~/.bashrc or ~/.zshrc
export PATH="/path/to/triton-video-sampling/build:$PATH"

# Reload shell
source ~/.bashrc

Now you can run sample and calibrate from anywhere.

Test Installation

# Create a test directory
mkdir -p ~/triton-test && cd ~/triton-test

# Download a sample video (or use your own)
# ...

# Run calibrate
/path/to/build/calibrate sample_video.mp4

# Run sample
/path/to/build/sample \
  --root-dir . \
  --camera 1 \
  --max-frames 10 \
  --output-dir ./frames

If both commands succeed and frames are extracted, installation is complete!

Troubleshooting

CMake can't find OpenCV

Error: 

CMake Error: Could not find OpenCV

Solution: 1. Verify OpenCV is installed: pkg-config --modversion opencv4 2. If missing, install: sudo apt install libopencv-dev 3. If installed, specify path: cmake -DOpenCV_DIR=/path/to/opencv/cmake ..

Compiler doesn't support C++17

Error: 

error: 'filesystem' is not a namespace-name

Solution: 1. Check compiler version: g++ --version (need GCC 7+) 2. Update compiler: sudo apt install g++-9 3. Specify compiler: cmake -DCMAKE_CXX_COMPILER=g++-9 ..

OpenCV can't open videos

Error (at runtime): 

[error] cannot reopen video.mp4

Solution: 1. Check FFMPEG support: pkg-config --libs opencv4 | grep -i ffmpeg 2. If missing, reinstall OpenCV from system packages (not pip): 

pip3 uninstall opencv-python opencv-python-headless
sudo apt install libopencv-dev
3. Rebuild project: cd build && make clean && cmake .. && make

Build fails with missing headers

Error: 

fatal error: CLI/CLI.hpp: No such file or directory

Solution: This should not happen (CLI11 is auto-fetched). Try: 1. Delete build directory: rm -rf build 2. Rebuild from scratch: mkdir build && cd build && cmake .. && make

Next Steps

  • Usage: Command-line reference for sample and calibrate
  • Tuning Guide: How to optimize parameters for your dataset
  • Troubleshooting: Common runtime issues and solutions