Getting Started

This document will take you through installing geodex, building the tests and examples, and running your first computations.

Installation

geodex is a header-only C++20 library — there is nothing to compile for the core library itself. This page covers getting the source, verifying the build system, and running the bundled tests and examples.

Requirements

  • C++20 compiler — GCC 10+, Clang 13+, or MSVC 19.29+

  • CMake 3.20 or later

  • Eigen3 — fetched automatically via CMake FetchContent (no manual install needed)

  • GoogleTest — fetched automatically when -DBUILD_TESTING=ON

Getting the source

git clone https://github.com/utiasSTARS/geodex.git
cd geodex

Configure and build

The core library has no compiled output. CMake is needed only to build tests and examples:

cmake -B build -DCMAKE_BUILD_TYPE=Release \
      -DBUILD_TESTING=ON \
      -DBUILD_EXAMPLES=ON
cmake --build build

Note

On first configure, CMake will download Eigen3 and GoogleTest via FetchContent. This requires an internet connection and takes a minute. Subsequent builds are instant.

Run the tests

ctest --test-dir build --output-on-failure

All tests should pass. If any fail, check that your compiler supports C++20 concepts. You may need to pass -DCMAKE_CXX_STANDARD=20 explicitly with some toolchains.

Run the examples

After building with -DBUILD_EXAMPLES=ON:

./build/examples/sphere_basics
./build/examples/sphere_distance

Python equivalents of all examples are provided in the examples/ directory:

python examples/sphere_basics.py
python examples/sphere_distance.py

Using geodex in your project

The recommended approach is CMake FetchContent:

include(FetchContent)
FetchContent_Declare(
  geodex
  GIT_REPOSITORY https://github.com/utiasSTARS/geodex.git
  GIT_TAG main
  GIT_SHALLOW TRUE
)
FetchContent_MakeAvailable(geodex)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE geodex)

This pulls in Eigen automatically. Then just include the main geodex header:

#include <geodex/geodex.hpp>

Python Installation

geodex also provides Python bindings built with nanobind. The bindings expose the same manifold types and algorithms as the C++ library, and use numpy arrays for all operations.

Requirements

  • Python 3.9 or later

  • NumPy 1.21 or later

  • A C++20 compiler (GCC 12+, Clang 14+)

Install from source

Clone the repository and install the Python bindings:

git clone https://github.com/utiasSTARS/geodex.git
cd geodex
python3 -m venv .venv
source .venv/bin/activate
pip install .

Development install

For an editable install with test dependencies, create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Then install in editable mode with test dependencies using one of the following:

Option A — Without build isolation (faster for repeated installs during development):

pip install scikit-build-core>=0.10 nanobind>=2.4
pip install --no-build-isolation -ve ".[test]"

Option B — With build isolation (simpler, pip handles build dependencies automatically):

pip install -ve ".[test]"

Verify the installation

import geodex
import numpy as np

sphere = geodex.Sphere()
print(sphere.dim())  # 2
p = np.array([0., 0., 1.])
q = np.array([1., 0., 0.])
print(sphere.distance(p, q))  # 1.5708 ≈ π/2

Next steps

  • Core Concepts — geometric background and how geodex models it in C++20

  • geodex Basics — learn the core operations on built-in manifolds (C++ and Python)