calibration

Calibration Library

A C++ library for camera calibration and vision-related geometric transformations.

Features

• Intrinsic and extrinsic calibration from planar targets
• Hand-eye calibration with bundle adjustment
• Homography and planar pose refinement utilities
• Support for multiple camera models, including Scheimpflug projection
• Unified optimisation interface with covariance estimation
• JSON configuration import/export
• Automatic JSON serialization for aggregate types

Dependencies

• Eigen3: Linear algebra library
• Ceres: Non-linear optimization
• nlohmann-json: JSON parsing and serialization
• CLI11: Command-line argument parsing
• GoogleTest & GoogleMock: Unit testing frameworks
• Boost.PFR: Header-only reflection for aggregates

Build

Linux and macOS

Install the build dependencies using your system package manager.

Ubuntu

sudo apt update
sudo apt install -y cmake ninja-build libeigen3-dev libceres-dev nlohmann-json3-dev libgtest-dev libgmock-dev libboost-dev cli11

macOS

brew update
brew install cmake ninja eigen ceres-solver nlohmann-json googletest boost cli11

Configure and build:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build -j2

Run a smoke test:

./build/examples/homography <<EOF
4
0   0    10 20
100 0    110 18
100 50   120 70
0   50   8  72
EOF

Windows

Install dependencies with vcpkg:

git clone https://github.com/microsoft/vcpkg $env:USERPROFILE\vcpkg
& $env:USERPROFILE\vcpkg\bootstrap-vcpkg.bat
& $env:USERPROFILE\vcpkg\vcpkg.exe install ceres eigen3 nlohmann-json gtest boost-pfr cli11 --triplet x64-windows

Configure and build:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release `
  -DCMAKE_TOOLCHAIN_FILE="$env:USERPROFILE\vcpkg\scripts\buildsystems\vcpkg.cmake"
cmake --build build --config Release -j2

Usage

The library exposes lightweight C++ APIs with a common optimisation interface. Typical entry points include:

• optimize_intrinsics – refine camera intrinsics and poses from planar views
• optimize_extrinsics – calibrate camera poses relative to a target
• optimize_handeye – refine gripper→camera transform from motion pairs
• optimize_planar_pose – estimate single planar pose with distortion

Example for hand‑eye calibration:

#include <calib/handeye.h>
using namespace calib;

std::vector<Eigen::Affine3d> base_T_gripper = ...;
std::vector<Eigen::Affine3d> camera_T_target = ...;
Eigen::Affine3d guess = ...; // initial gripper->camera transform

HandeyeOptions opts;
auto result = optimize_handeye(base_T_gripper, camera_T_target, guess, opts);
if (result.success) {
    std::cout << result.report << std::endl;
    std::cout << "Estimated transform:\n" << result.g_T_c.matrix() << std::endl;
}

Command-line tool

A small calib_app utility is available for running calibrations from JSON files. It accepts the path to a config file and optional overrides:

calib_app --config input.json [--task intrinsics] [--output result.json]

The config file specifies the calibration input and task type, while the command-line options provided by CLI11 allow overriding the task mode or the output file.

Code Quality

This project maintains high code quality through:

• Static Analysis: clang-tidy and cppcheck integration in CI
• Test Coverage: Comprehensive unit tests with coverage reporting
• Code Formatting: Consistent style with clang-format
• Pre-commit Hooks: Automated quality checks before commits

Running Static Analysis Locally

# Install tools
sudo apt install clang-tidy cppcheck clang-format

# Run static analysis
make lint

# Format code
make format

# Generate coverage report
make coverage

Documentation

For detailed documentation, see the doc directory.

License

This project is licensed under the MIT License - see the LICENCE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

This site is open source. Improve this page.