# unsigned-long/ikalibr architecture

> Architecture diagram of the GitHub repository unsigned-long/ikalibr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/unsigned-long/ikalibr
- Repository: https://github.com/unsigned-long/ikalibr

## Overview

##### Project Type and Purpose
- iKalibr is a C++-based, ROS-integrated, targetless spatiotemporal calibration framework for multi-sensor rigs (IMUs, cameras, LiDARs, radars, RGB-D, event cameras).
- It provides a modular calibration pipeline: data ingestion → preprocessing/feature extraction → factor graph construction → optimization (via Ceres) → results/visualization.
- It ships as a ROS package (msgs, launches), a library (include/src/thirdparty), and a suite of CLI tools (exe/, script/).

##### File-Structure Analysis
- Top-level:
- /: exposed headers, organized by module (calib, core, factor, sensor, solver, util, viewer)
- src/: corresponding implementation files
- exe/: entry-point applications (solver, tool, nofree demos)
- launch/: ROS launch files for each tool/solver
- msg/: ROS message definitions for sensor data
- config/, data/: YAML instrument configurations and raw data sets
- thirdparty/: bundled external libs (ctraj, opengv, ufomap, veta)
- script/: Python helpers for plotting, data conversion
- CMakeLists.txt + package.xml: build and ROS packaging
- Architectural patterns:
- Modular C++ namespaces: sensor ↔ core ↔ factor ↔ solver ↔ util ↔ viewer
- Plugin-style support: new sensor types and factor types via headers in include/sensor and include/factor
- CLI + ROS interface: exe/ for command-line; launch/ + msg/ for rosbag and runtime
- Config-driven pipelines: YAML files in config/ steer loader, solver, prior settings

##### Key Insights from README
- Core pipeline is illustrated in docs/img/overview.drawio.jpg
- Supports targetless spatial + temporal calibration; no external targets needed
- Encourages extension to new sensor modalities
- Uses continuous-time velocity estimation for RGB-D specialization

1. Data Sources
- Raw recordings (rosbag, CSV, images, point clouds)
- Live sensors (ros topics)
2. Configuration Manager
- YAML loader (configor)
- Parameter manager (spat_temp_priori, calib_param_manager)
3. Sensor Interface & Data Loader
- sensor_data_loader modules (camera, imu, lidar, radar, event, depth)
4. Preprocessing & Feature Extraction
- core/event_preprocessing, feature_tracking, optical_flow_trace, scan_undistortion
5. Factor Graph Builder
- factor/* modules generate residuals: imu factors, visual factors, lidar factors, radar factors
6. Optimization Engine
- solver/calib_solver + Ceres callbacks
- Thirdparty optimization libs (ceres via include/calib/ceres_callback)
7. Output & Visualization
- viewer modules (visual_ang_vel_drawer, visual_colorized_cloud_map, etc.)
- CLI / ROS topics / result YAML files
8. Auxiliary Tools
- exe/tool (bag_merge, imgs_to_bag, data_format_transformer, imu_intri_calib)
- script/ Python helpers

- Data Sources → Sensor Interface
- Sensor Interface → Preprocessing & Feature Extraction
- Preprocessed Features → Factor Graph Builder
- Factors + Config Manager → Optimization Engine
- Optimizer → Output Manager → Viewer / YAML / ROS topics
- CLI tools call specific subsets of Sensor Interface / Config Manager / Output

c. Architectural Patterns & Principles
- Separation of Concerns: each module (sensor, core, factor, solver, viewer) in its own namespace/folder
- Extensibility: new sensor/factor types drop into include/sensor or include/factor; CMake auto-discovers
- Config-Driven Behavior: central configor JSON/YAML loader used across modules
- ROS Decoupling: message definitions + launch files isolate runtime orchestration

d. Key Technologies & Libraries
- C++17, CMake, ROS (msgs, launch, package.xml)
- Ceres Solver
- YAML configs via configor
- Thirdparty: opengv, ctraj, ufomap, veta
- Python scripts for visualization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        DS_Config["Configuration Files"]:::db
        DS_Data["Sample Datasets"]:::db
        DS_Live["Live Sensors (ros topics)"]:::input
        DS_Raw["Raw Recordings (rosbag, CSV, images, point clouds)"]:::input
    end

    %% Configuration Manager
    subgraph "Configuration Manager"
        CM_Loader["YAML Loader (configor)"]:::config
        CM_Param["Parameter Manager"]:::config
        CM_Priori["Spatial-Temporal Priori"]:::config
    end

    %% Sensor Interface & Data Loader
    subgraph "Sensor Interface & Data Loader" 
        SI_SensorModels["Sensor Models & Interfaces"]:::sensor
        SI_Camera["Camera Data Loader"]:::sensor
        SI_IMU["IMU Data Loader"]:::sensor
        SI_LiDAR["LiDAR Data Loader"]:::sensor
        SI_Radar["Radar Data Loader"]:::sensor
        SI_Event["Event Data Loader"]:::sensor
        SI_RGBD["Depth/RGB-D Data Loader"]:::sensor
    end

    %% Preprocessing & Feature Extraction
    subgraph "Preprocessing & Feature Extraction"
        PP_Event["Event Preprocessing"]:::core
        PP_Circle["Event Circle Tracking"]:::core
        PP_SAC["Event Trace SAC"]:::core
        PP_Feature["Feature Tracking"]:::core
        PP_Optical["Optical Flow Trace"]:::core
        PP_Scan["Scan Undistortion"]:::core
    end

    %% Factor Graph Builder
    subgraph "Factor Graph Builder"
        FG_Factors["Factor Definitions"]:::factor
        FG_Instantiate["Factor Instantiation"]:::factor
    end

    %% Optimization Engine
    subgraph "Optimization Engine"
        OE_Ceres["Ceres Callback Integration"]:::solver
        OE_SolverCore["Solver Core & Interfaces"]:::solver
        OE_Impl["Solver Implementations"]:::solver
    end

    %% Output & Visualization
    subgraph "Output & Visualization"
        OV_Viewer["Viewer Modules"]:::viewer
        OV_ROS["ROS Messages & Launch"]:::viewer
        OV_Serialize["Result Serialization"]:::viewer
    end

    %% Auxiliary Tools
    subgraph "Auxiliary Tools"
        AT_CLI["Command-Line Tools"]:::tools
        AT_Demo["Demo / No-Free Tools"]:::tools
        AT_Scripts["Python Helpers"]:::tools
    end

    %% Third-Party & Build
    subgraph "External Dependencies"
        TP_Libs["Third-Party Libraries"]:::external
        BB_Build["Build & Packaging"]:::external
    end

    %% Data Flows
    DS_Config -->|loads| CM_Loader
    DS_Data -->|feeds| SI_SensorModels
    DS_Raw --> SI_SensorModels
    DS_Live --> SI_SensorModels

    CM_Loader --> CM_Param
    CM_Param --> CM_Priori

    SI_SensorModels --> SI_Camera
    SI_SensorModels --> SI_IMU
    SI_SensorModels --> SI_LiDAR
    SI_SensorModels --> SI_Radar
    SI_SensorModels --> SI_Event
    SI_SensorModels --> SI_RGBD

    SI_Camera --> PP_Event
    SI_IMU --> PP_Event
    SI_LiDAR --> PP_Scan
    SI_Radar --> PP_Scan
    SI_Event --> PP_Circle
    SI_Event --> PP_SAC
    SI_RGBD --> PP_Feature

    PP_Event --> FG_Factors
    PP_Circle --> FG_Factors
    PP_SAC --> FG_Factors
    PP_Feature --> FG_Factors
    PP_Optical --> FG_Factors
    PP_Scan --> FG_Factors

    CM_Param --> OE_SolverCore
    FG_Factors --> OE_Ceres
    FG_Instantiate --> OE_Ceres

    OE_Ceres --> OE_SolverCore
    OE_SolverCore --> OE_Impl
    OE_Impl --> OV_Serialize

    OV_Serialize --> OV_Viewer
    OV_Serialize --> OV_ROS

    AT_CLI --> SI_SensorModels
    AT_CLI --> CM_Param
    AT_Demo --> SI_SensorModels
    AT_Scripts --> OV_Viewer

    TP_Libs --> OE_Ceres
    BB_Build --> TP_Libs
    BB_Build --> CM_Loader

    %% Click Events
    click DS_Config "https://github.com/unsigned-long/ikalibr/tree/master/config/"
    click DS_Data "https://github.com/unsigned-long/ikalibr/tree/master/data/"
    click CM_Loader "https://github.com/unsigned-long/ikalibr/blob/master/include/config/configor.h"
    click CM_Loader "https://github.com/unsigned-long/ikalibr/blob/master/src/config/configor.cpp"
    click CM_Param "https://github.com/unsigned-long/ikalibr/blob/master/include/calib/calib_param_manager.h"
    click CM_Param "https://github.com/unsigned-long/ikalibr/blob/master/src/calib/calib_param_manager.cpp"
    click CM_Priori "https://github.com/unsigned-long/ikalibr/blob/master/include/calib/spat_temp_priori.h"
    click CM_Priori "https://github.com/unsigned-long/ikalibr/blob/master/src/calib/spat_temp_priori.cpp"
    click SI_SensorModels "https://github.com/unsigned-long/ikalibr/tree/master/include/sensor/"
    click SI_Camera "https://github.com/unsigned-long/ikalibr/blob/master/include/sensor/camera_data_loader.h"
    click SI_Camera "https://github.com/unsigned-long/ikalibr/blob/master/src/sensor/camera_data_loader.cpp"
    click SI_IMU "https://github.com/unsigned-long/ikalibr/blob/master/include/sensor/imu_data_loader.h"
    click SI_IMU "https://github.com/unsigned-long/ikalibr/blob/master/src/sensor/imu_data_loader.cpp"
    click SI_LiDAR "https://github.com/unsigned-long/ikalibr/blob/master/include/sensor/lidar_data_loader.h"
    click SI_LiDAR "https://github.com/unsigned-long/ikalibr/blob/master/src/sensor/lidar_data_loader.cpp"
    click SI_Radar "https://github.com/unsigned-long/ikalibr/blob/master/include/sensor/radar_data_loader.h"
    click SI_Radar "https://github.com/unsigned-long/ikalibr/blob/master/src/sensor/radar_data_loader.cpp"
    click SI_Event "https://github.com/unsigned-long/ikalibr/blob/master/include/sensor/event_data_loader.h"
    click SI_Event "https://github.com/unsigned-long/ikalibr/blob/master/src/sensor/event_data_loader.cpp"
    click SI_RGBD "https://github.com/unsigned-long/ikalibr/blob/master/include/sensor/depth_data_loader.h"
    click SI_RGBD "https://github.com/unsigned-long/ikalibr/blob/master/src/sensor/depth_data_loader.cpp"
    click PP_Event "https://github.com/unsigned-long/ikalibr/blob/master/include/core/event_preprocessing.h"
    click PP_Event "https://github.com/unsigned-long/ikalibr/blob/master/src/core/event_preprocessing.cpp"
    click PP_Circle "https://github.com/unsigned-long/ikalibr/blob/master/include/core/ev_circle_tracking.h"
    click PP_Circle "https://github.com/unsigned-long/ikalibr/blob/master/src/core/ev_circle_tracking.cpp"
    click PP_SAC "https://github.com/unsigned-long/ikalibr/blob/master/include/core/event_trace_sac.h"
    click PP_SAC "https://github.com/unsigned-long/ikalibr/blob/master/src/core/event_trace_sac.cpp"
    click PP_Feature "https://github.com/unsigned-long/ikalibr/blob/master/include/core/feature_tracking.h"
    click PP_Feature "https://github.com/unsigned-long/ikalibr/blob/master/src/core/feature_tracking.cpp"
    click PP_Optical "https://github.com/unsigned-long/ikalibr/blob/master/include/core/optical_flow_trace.h"
    click PP_Optical "https://github.com/unsigned-long/ikalibr/blob/master/src/core/optical_flow_trace.cpp"
    click PP_Scan "https://github.com/unsigned-long/ikalibr/blob/master/include/core/scan_undistortion.h"
    click PP_Scan "https://github.com/unsigned-long/ikalibr/blob/master/src/core/scan_undistortion.cpp"
    click FG_Factors "https://github.com/unsigned-long/ikalibr/tree/master/include/factor/"
    click FG_Instantiate "https://github.com/unsigned-long/ikalibr/blob/master/include/factor/data_correspondence.h"
    click FG_Instantiate "https://github.com/unsigned-long/ikalibr/blob/master/src/factor/data_correspondence.cpp"
    click OE_Ceres "https://github.com/unsigned-long/ikalibr/blob/master/include/calib/ceres_callback.h"
    click OE_Ceres "https://github.com/unsigned-long/ikalibr/blob/master/src/calib/ceres_callback.cpp"
    click OE_SolverCore "https://github.com/unsigned-long/ikalibr/blob/master/include/solver/calib_solver.h"
    click OE_SolverCore "https://github.com/unsigned-long/ikalibr/blob/master/include/solver/calib_solver_tpl.hpp"
    click OE_SolverCore "https://github.com/unsigned-long/ikalibr/blob/master/include/solver/batch_opt_option.hpp"
    click OE_Impl "https://github.com/unsigned-long/ikalibr/tree/master/src/solver/"
    click OV_Viewer "https://github.com/unsigned-long/ikalibr/tree/master/include/viewer/"
    click OV_ROS "https://github.com/unsigned-long/ikalibr/tree/master/msg/"
    click OV_ROS "https://github.com/unsigned-long/ikalibr/tree/master/launch/"
    click OV_Serialize "https://github.com/unsigned-long/ikalibr/blob/master/include/util/cereal_archive_helper.hpp"
    click OV_Serialize "https://github.com/unsigned-long/ikalibr/blob/master/include/util/cereal_yaml.hpp"
    click AT_CLI "https://github.com/unsigned-long/ikalibr/tree/master/exe/tool/"
    click AT_Demo "https://github.com/unsigned-long/ikalibr/tree/master/exe/nofree/"
    click AT_Scripts "https://github.com/unsigned-long/ikalibr/tree/master/script/"
    click TP_Libs "https://github.com/unsigned-long/ikalibr/tree/master/thirdparty/"
    click BB_Build "https://github.com/unsigned-long/ikalibr/blob/master/CMakeLists.txt"

    %% Styles
    classDef db fill:#cde,stroke:#333,stroke-width:1px
    classDef input fill:#eef,stroke:#333,stroke-width:1px
    classDef config fill:#ddf,stroke:#333,stroke-width:1px
    classDef sensor fill:#b3d9ff,stroke:#333,stroke-width:1px
    classDef core fill:#d4f4dd,stroke:#333,stroke-width:1px
    classDef factor fill:#b2f2bb,stroke:#333,stroke-width:1px
    classDef solver fill:#ffd699,stroke:#333,stroke-width:1px
    classDef viewer fill:#e0b3ff,stroke:#333,stroke-width:1px
    classDef tools fill:#f4d6e0,stroke:#333,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px
```
