Detailed Installation

This page expands the recommended installation workflow from Installation. It lists the shell commands, environment values, package names, and CMake options used by the repository tasks so the build configuration is visible. The values are expanded from the top-level and module-local mise.toml files, but the steps below use direct commands.

Dependencies

The code was implemented and tested with Ubuntu 24.04, CUDA 12.8, CUDA_ARCH=86, and TORCH_CUDA_ARCH_LIST=8.6. Adjust the CUDA paths and architecture values for your GPU before building on a different machine.

The standard tool versions used by the repository are:

• CMake 3.26

• Python 3.12.12

• uv

• clang-format 21.1.8, for development formatting checks

Set the CUDA and runtime environment from the repository root:

export CUDA_HOME=/usr/local/cuda-12.8
export CUDA_VERSION=12.8
export CUDA_ARCH=86
export TORCH_CUDA_ARCH_LIST=8.6
export RERUN_VERSION=0.25.1
export ONNX_VERSION=1.22.0
export ASAN_OPTIONS=protect_shadow_gap=0
export PATH="${CUDA_HOME}/bin:${PATH}"
export LD_LIBRARY_PATH="${CUDA_HOME}/lib64:${LD_LIBRARY_PATH:-}"
export CPLUS_INCLUDE_PATH="${CUDA_HOME}/targets/x86_64-linux/include:${CPLUS_INCLUDE_PATH:-}"
export LIBRARY_PATH="${CUDA_HOME}/targets/x86_64-linux/lib:${LIBRARY_PATH:-}"

Install the CUDA repository keyring and standard system dependencies:

wget -qO /tmp/cuda-keyring.deb \
  https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i /tmp/cuda-keyring.deb
rm -f /tmp/cuda-keyring.deb

sudo apt-get update
sudo apt-get install -y --no-install-recommends \
  ninja-build \
  g++-14 gcc-14 \
  gcc-9 g++-9 \
  git libssl-dev \
  libboost-all-dev \
  libgoogle-glog-dev \
  cuda-toolkit-12-8 \
  libgflags-dev \
  libatlas-base-dev \
  libopenblas-dev \
  liblapack-dev \
  libyaml-cpp-dev \
  libeigen3-dev \
  libtbb-dev \
  libpng-dev \
  libjpeg-turbo8-dev \
  wget unzip

if apt-cache show libcudnn9-cuda-12 >/dev/null 2>&1; then
  sudo apt-get install -y libcudnn9-cuda-12
elif apt-cache show cudnn9-cuda-12 >/dev/null 2>&1; then
  sudo apt-get install -y cudnn9-cuda-12
fi

Install OpenCV when building the visual place localization module with its OpenCV-dependent components:

sudo apt-get install -y libopencv-dev

Clone the Repository

Clone the repository and download the third-party libraries:

git clone <slam-mer-repository-url>
cd slam-mer
./scripts/sync_optional_modules.sh
git submodule update --init --recursive

Python Tool Environment

Create the Python environment from the repository root:

uv sync

Use optional Python extras when needed:

uv sync --extra dev
uv sync --extra docs

The dev extra installs pre-commit. The docs extra installs Sphinx, the Read the Docs theme, Breathe, and Exhale.

Compile Third-Party Libraries

Build GTSAM from source:

if [ ! -d "thirdparty/gtsam/build/install" ]; then
  if git -C thirdparty/gtsam apply --unidiff-zero --reverse --check \
      ../gtsam_similarity3.patch >/dev/null 2>&1; then
    echo "thirdparty/gtsam_similarity3.patch already applied."
  elif git -C thirdparty/gtsam apply --unidiff-zero --check \
      ../gtsam_similarity3.patch; then
    git -C thirdparty/gtsam apply --unidiff-zero ../gtsam_similarity3.patch
    echo "Applied thirdparty/gtsam_similarity3.patch."
  else
    echo "Failed to apply thirdparty/gtsam_similarity3.patch cleanly." >&2
    exit 1
  fi
else
  echo "GTSAM install exists, skipping patch application."
fi

cmake -B thirdparty/gtsam/build -S thirdparty/gtsam \
      -DCMAKE_BUILD_TYPE=Release \
      -DGTSAM_SUPPORT_NESTED_DISSECTION=OFF \
      -DGTSAM_USE_SYSTEM_EIGEN=ON \
      -DGTSAM_WITH_TBB=ON \
      -DGTSAM_BUILD_TESTS=OFF \
      -DGTSAM_BUILD_EXAMPLES_ALWAYS=OFF \
      -DGTSAM_BUILD_TIMING_ALWAYS=OFF \
      -DGTSAM_BUILD_UNSTABLE=OFF \
      -DGTSAM_LIBRARY_TYPE=SHARED \
      -DCMAKE_BUILD_WITH_INSTALL_RPATH=ON \
      -DCMAKE_INSTALL_PREFIX=./thirdparty/gtsam/build/install \
      -DCMAKE_INSTALL_MESSAGE=NEVER \
      -GNinja
ninja -C thirdparty/gtsam/build
ninja -C thirdparty/gtsam/build install

Build Rerun SDK 0.25.1:

if [ ! -d "thirdparty/rerun_cpp_sdk" ]; then
  wget -O thirdparty/rerun_cpp_sdk.zip \
    "https://github.com/rerun-io/rerun/releases/download/${RERUN_VERSION}/rerun_cpp_sdk.zip"
fi

if [ -f "thirdparty/rerun_cpp_sdk.zip" ]; then
  unzip -o thirdparty/rerun_cpp_sdk.zip -d thirdparty
  rm -f thirdparty/rerun_cpp_sdk.zip
fi

cmake -B thirdparty/rerun_cpp_sdk/build -S thirdparty/rerun_cpp_sdk \
      -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=thirdparty/rerun_cpp_sdk/build/install \
      -DCUDA_NVRTC_SHORTHASH=IGNORE \
      -DBUILD_SHARED_LIBS=ON \
      -DCMAKE_INSTALL_MESSAGE=NEVER \
      -GNinja
ninja -C thirdparty/rerun_cpp_sdk/build rerun_sdk
ninja -C thirdparty/rerun_cpp_sdk/build install

Build PoseLib:

cmake -B thirdparty/PoseLib/build -S thirdparty/PoseLib \
      -DBUILD_SHARED_LIBS=ON \
      -DWITH_BENCHMARK=OFF \
      -DBUILD_TESTS=OFF \
      -DPYTHON_PACKAGE=OFF \
      -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=thirdparty/PoseLib/build/install \
      -DCMAKE_INSTALL_MESSAGE=NEVER \
      -GNinja
ninja -C thirdparty/PoseLib/build
ninja -C thirdparty/PoseLib/build install

Build FAISS with GPU support:

cmake -B thirdparty/faiss/build -S thirdparty/faiss \
      -DBUILD_SHARED_LIBS=ON \
      -DFAISS_ENABLE_GPU=ON \
      -DFAISS_ENABLE_MKL=OFF \
      -DBLA_VENDOR=OpenBLAS \
      -DFAISS_OPT_LEVEL=avx2 \
      -DCUDAToolkit_ROOT=/usr/local/cuda-${CUDA_VERSION} \
      -DCMAKE_CUDA_ARCHITECTURES=${CUDA_ARCH} \
      -DBUILD_TESTING=OFF \
      -DFAISS_ENABLE_PYTHON=OFF \
      -DFAISS_ENABLE_C_API=OFF \
      -DFAISS_ENABLE_EXTRAS=OFF \
      -DFAISS_USE_LTO=OFF \
      -DCMAKE_CUDA_COMPILER=/usr/local/cuda-${CUDA_VERSION}/bin/nvcc \
      -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=thirdparty/faiss/build/install \
      -DCMAKE_INSTALL_MESSAGE=NEVER \
      -GNinja
ninja -C thirdparty/faiss/build
ninja -C thirdparty/faiss/build install

Optional SLAM Modules

The optional modules live in thirdparty/depth_inference and thirdparty/visual_place_localization. Both modules use CUDA 12.8 and ONNX Runtime 1.22.0. The module-local configuration files currently list CUDA_ARCH=89; keep the top-level CUDA_ARCH=86 value above unless you are intentionally changing the target GPU architecture.

Prepare and build the depth inference module:

cd thirdparty/depth_inference
uv sync

if [ -d "thirdparty/onnxruntime-linux-x64-gpu-${ONNX_VERSION}" ]; then
  echo "ONNX Runtime already installed."
else
  wget -O "thirdparty/onnxruntime-linux-x64-gpu-${ONNX_VERSION}.tgz" \
    "https://github.com/microsoft/onnxruntime/releases/download/v${ONNX_VERSION}/onnxruntime-linux-x64-gpu-${ONNX_VERSION}.tgz"
  tar -xvf "thirdparty/onnxruntime-linux-x64-gpu-${ONNX_VERSION}.tgz" -C thirdparty/
  rm "thirdparty/onnxruntime-linux-x64-gpu-${ONNX_VERSION}.tgz"
fi

if [ -d assets/mast3r_onnx_model ]; then
  echo "MAST3R assets already installed."
else
  gh release download v0.1.0 -p "mast3r_onnx_model.tar.gz.part-*" -D assets/
  cat assets/mast3r_onnx_model.tar.gz.part-* > assets/mast3r_onnx_model.tar.gz
  tar -xvf assets/mast3r_onnx_model.tar.gz -C assets/
  rm -f assets/mast3r_onnx_model.tar.gz*
fi

if [ -d assets/dust3r_onnx_model ]; then
  echo "DUSt3R assets already installed."
else
  gh release download v0.1.0 -p "dust3r_onnx_model.tar.gz.part-*" -D assets/
  cat assets/dust3r_onnx_model.tar.gz.part-* > assets/dust3r_onnx_model.tar.gz
  tar -xvf assets/dust3r_onnx_model.tar.gz -C assets/
  rm -f assets/dust3r_onnx_model.tar.gz
fi

if [ -d assets/depth_anything_v2_onnx_model ]; then
  echo "Depth Anything V2 assets already installed."
else
  gh release download v0.1.0 -p "depth_anything_v2_onnx_model.tar.gz" -D assets/
  tar -xvf assets/depth_anything_v2_onnx_model.tar.gz -C assets/
  rm -f assets/depth_anything_v2_onnx_model.tar.gz
fi

cmake -B build -S . \
      -DCMAKE_BUILD_TYPE=Debug \
      -DBUILD_SHARED=ON \
      -DBUILD_TESTS=OFF \
      -DCMAKE_INSTALL_PREFIX="${PWD}/build/install" \
      -DCMAKE_BUILD_WITH_INSTALL_RPATH=ON \
      -GNinja
ninja -C build
ninja -C build install
cd ../..

Prepare and build the visual place localization module. This module reuses the top-level FAISS installation through Faiss_DIR:

cd thirdparty/visual_place_localization
uv sync

archive="thirdparty/onnxruntime-linux-x64-gpu-${ONNX_VERSION}.tgz"
install_dir="thirdparty/onnxruntime-linux-x64-gpu-${ONNX_VERSION}"

cleanup_archive() {
  rm -f "${archive}"
}
trap cleanup_archive EXIT

if [ -f "${install_dir}/include/onnxruntime_cxx_api.h" ] && \
   [ -f "${install_dir}/lib/libonnxruntime.so" ]; then
  echo "ONNX Runtime already installed."
else
  if [ -d "${install_dir}" ]; then
    echo "Removing incomplete ONNX Runtime install at ${install_dir}."
    rm -rf "${install_dir}"
  fi

  mkdir -p thirdparty
  rm -f "${archive}"
  df -h thirdparty

  wget -O "${archive}" \
    "https://github.com/microsoft/onnxruntime/releases/download/v${ONNX_VERSION}/onnxruntime-linux-x64-gpu-${ONNX_VERSION}.tgz"
  df -h thirdparty

  tar -xzf "${archive}" -C thirdparty/
  df -h thirdparty
fi

if [ -d assets/visual_place_recognition/megaloc_onnx_model ]; then
  echo "MegaLoc assets already installed."
else
  gh release download v0.1.0 -p "megaloc_onnx_model.tar.gz" \
    --dir assets/visual_place_recognition/
  tar -xvf assets/visual_place_recognition/megaloc_onnx_model.tar.gz \
    -C assets/visual_place_recognition/
  rm -f assets/visual_place_recognition/megaloc_onnx_model.tar.gz
fi

cmake -B build -S . \
      -DCMAKE_BUILD_TYPE=Release \
      -DUSE_GPU_DATABASE=ON \
      -DBUILD_TESTS=OFF \
      -DBUILD_SHARED=ON \
      -DFaiss_DIR="${PWD}/../faiss/build/install/share/faiss" \
      -DCMAKE_INSTALL_PREFIX="${PWD}/build/install" \
      -GNinja
ninja -C build
ninja -C build install
cd ../..

LibTorch and ALIKED

ALIKED is compiled from utils/aliked during the main SLAM-MER build when WITH_ALIKED=ON. Download LibTorch 2.9.0+cu128 before enabling ALIKED:

if [ -d "thirdparty/libtorch" ]; then
  echo "libtorch already present: thirdparty/libtorch"
else
  archive="libtorch-shared-with-deps-2.9.0+cu128.zip"
  url="https://download.pytorch.org/libtorch/cu128/libtorch-shared-with-deps-2.9.0%2Bcu128.zip"

  cd thirdparty
  wget -O "${archive}" "${url}"
  unzip "${archive}"
  rm -f "${archive}"
  cd ..
fi

Compile the Visual-SLAM Pipeline

After compiling the third-party libraries and optional modules, configure and install the full SLAM-MER Release build:

cmake -B build -S . \
      -DCMAKE_BUILD_TYPE=Release \
      -DDEPTH_INFERENCE:BOOL=ON \
      -DVISUAL_PLACE_LOCALIZATION:BOOL=ON \
      -DCMAKE_INSTALL_PREFIX=./build/install \
      -GNinja
ninja -C build install

For a Debug build with verbose logging enabled:

cmake -B build -S . \
      -DCMAKE_BUILD_TYPE=Debug \
      -DLOG_TERMINAL:BOOL=OFF \
      -DLOG_INTERFACE:BOOL=ON \
      -DLOG_CUDA:BOOL=ON \
      -DLOG_TIME:BOOL=ON \
      -DLOG_LOCALIZATION:BOOL=ON \
      -DLOG_POSE_ESTIMATION:BOOL=ON \
      -DLOG_SETTINGS:BOOL=ON \
      -DLOG_SLAM:BOOL=ON \
      -DLOG_ADJUSTMENT:BOOL=ON \
      -DLOG_REPRESENTATION:BOOL=ON \
      -DDEPTH_INFERENCE:BOOL=ON \
      -DVISUAL_PLACE_LOCALIZATION:BOOL=ON \
      -DCMAKE_INSTALL_PREFIX=./build/install \
      -GNinja
ninja -C build install

To build only the core libraries without depth inference or visual place localization:

cmake -B build -S . \
      -DCMAKE_BUILD_TYPE="${SLAM_MER_BUILD_TYPE:-Release}" \
      -DDEPTH_INFERENCE:BOOL=OFF \
      -DVISUAL_PLACE_LOCALIZATION:BOOL=OFF \
      -DWITH_ALIKED:BOOL="${SLAM_MER_WITH_ALIKED:-ON}" \
      -DCMAKE_INSTALL_PREFIX=./build/install \
      -GNinja
ninja -C build install

Set SLAM_MER_WITH_ALIKED=OFF for the reduced build when thirdparty/libtorch is unavailable. For the complete CMake option list, see the top-level COMPILATION_OPTIONS.md.

To control which transformation templates are compiled, use -DSLAM_TRANSFORMATION_INSTANTIATIONS=ALL|POSE3|SIMILARITY3 (default: ALL).

If the Rerun viewer has GUI backend issues, for example in WSL2, start the web viewer in advance:

rerun --web-viewer

Or run the matching Rerun Python package directly:

uvx --from rerun-sdk==X.XX.X rerun --web-viewer

Runnable examples, dataset download instructions, and experiment-specific executables are maintained outside this library repository:

https://github.com/slam-mer/slam-mer_examples

This repository currently provides the SLAM-MER libraries and documentation. It does not contain the old dataset download scripts that were previously documented here.

Evaluation

When an example writes a TUM-format trajectory, it can be evaluated with evo. Install evo with:

pip install evo

For absolute pose errors, use the command by replacing the filenames:

evo_ape tum <groundtruth_file> <output_file> -as

Documentation

Install documentation system packages:

sudo apt update
sudo apt install -y \
  python3-sphinx \
  python3-sphinx-rtd-theme \
  doxygen \
  python3-exhale \
  python3-breathe

Build the full Sphinx and Doxygen documentation:

uv sync --extra docs
rm -rf doc/_build doc/api doc/doxygen/_docs
cd doc/doxygen
doxygen Doxyfile.cfg
cd ..
make html
cd ..

For quick prose-only rebuilds that skip Doxygen regeneration, use:

cd doc
SLAM_MER_DOCS_FAST=1 make html
cd ..

The generated HTML is written to doc/_build/html/index.html.

Register pre-commit and pre-push hooks from the repository root:

uv sync --extra dev
uv run pre-commit install --install-hooks --hook-type pre-commit --hook-type pre-push

After this step, pre-commit runs on every git commit and pre-push checks run on every git push.

Debugging the Code

To enable Address Sanitizer (ASan), build the project with -DUSE_ASAN=ON. Libraries that use prebuilt LibTorch binaries, such as ALIKED, must not be built with ASan due to GCC incompatibilities.

Build the project with ASan enabled using the following commands:

cmake -B build -S . \
      -DCMAKE_BUILD_TYPE=Debug \
      -DWITH_ALIKED=OFF \
      -DUSE_ASAN=ON \
      -DDEPTH_INFERENCE=OFF \
      -DVISUAL_PLACE_LOCALIZATION=OFF \
      -DCMAKE_INSTALL_PREFIX=./build/install \
      -GNinja
ninja -C build install

To use Compute Sanitizer for CUDA memory error detection, build with -DUSE_ASAN=OFF, because ASan and Compute Sanitizer cannot be used together.

Build with Compute Sanitizer support:

cmake -B build -S . \
      -DCMAKE_BUILD_TYPE=Debug \
      -DWITH_ALIKED=ON \
      -DUSE_ASAN=OFF \
      -DCMAKE_INSTALL_PREFIX=./build/install \
      -GNinja
ninja -C build install

Then run the executable from the examples repository with Compute Sanitizer:

compute-sanitizer <example-executable>

In Release builds, most LOG_* CMake options are forced off by cmake/Options.cmake. Use a Debug build when verbose runtime logging is needed.