# hku-mars/livox_camera_calib architecture

> Architecture diagram of the GitHub repository hku-mars/livox_camera_calib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hku-mars/livox_camera_calib
- Repository: https://github.com/hku-mars/livox_camera_calib

## Overview

##### Project Type and Purpose
- This is a ROS-based C++ toolkit (“lidar_camera_calib”) for extrinsic calibration between a high-resolution LiDAR sensor and a camera, in both indoor and outdoor, targetless environments. It provides single-scene and multi-scene calibration modes, producing pixel-level alignment accuracy by leveraging PCL, Eigen, and Ceres Solver.

##### Key Architectural Components
a. ROS Infrastructure
- ROS Master & Parameter Server
- Topics:
– /camera/image_raw  (sensor_msgs/Image via cv_bridge)
– /velodyne_points or /pcd_cloud (sensor_msgs/PointCloud2)
b. Nodes
- bag_to_pcd node (src/bag_to_pcd.cpp)
– Reads ROS bags or live LiDAR streams
– Converts to PCL PointCloud2 and writes .pcd files
- Single-scene calibration node (src/lidar_camera_calib.cpp)
– Loads YAML config (config/calib.yaml) via rosparam
– Subscribes to image + point cloud topics
– Extracts edges, formulates optimization problem
– Uses Eigen for transforms + Ceres for non-linear optimization
– Publishes calibrated extrinsic to text (result/extrinsic.txt)
– Publishes debug/visualization topics for RViz
- Multi-scene calibration node (src/lidar_camera_multi_calib.cpp)
– Similar pipeline, loops over N scene pairs from config/multi_calib.yaml
– Rough calibration followed by fine optimization
c. Configuration & Assets
- YAML files in config/ (single and multi-scene parameters, file paths, camera intrinsics)
- RViz configurations in rviz_cfg/ for visualizing point cloud overlaid on image
- Example data & results in pics/ and result/
d. External Libraries & Build
- PCL (Point Cloud Library)
- Eigen (linear algebra)
- Ceres Solver (optimization)
- ROS packages: cv_bridge, pcl_conversions
- Built with catkin/CMake (CMakeLists.txt, package.xml)

##### Relationships and Data Flow
1. Launch File (launch/calib.launch or multi_calib.launch)
→ Loads launch arguments & rosparams from config/*.yaml
→ Starts bag_to_pcd (if using recorded data)
→ Starts calibration node(s)
2. bag_to_pcd node reads LiDAR stream → writes .pcd & publishes PointCloud2
3. Calibration node:
– Subscribes PointCloud2 + Image
– Edge extraction → Match 2D image edges with 3D cloud edges
– Ceres optimization → Compute extrinsic transform T_lidar_to_cam
– Publishes transform and viz topics → rviz for overlay
– Writes final extrinsic.txt
4. Multi-scene node loops above steps over multiple input pairs, aggregates results.

##### Architectural Patterns & Principles
- Modularity via ROS nodes
- Separation of concerns: data acquisition (bag_to_pcd), processing/optimization, visualization
- Configuration-driven via YAML + ROS parameter server
- Pipeline pattern: sensor data → feature extraction → optimization → result publication
- Use of standard robotics middleware (ROS topics/services)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% ROS Infrastructure
    subgraph "ROS Infrastructure"
        direction TB
        Master["ROS Master & Parameter Server"]:::middleware
    end

    subgraph "Launch Files"
        direction TB
        CalibLaunch["calib.launch"]:::config
        MultiCalibLaunch["multi_calib.launch"]:::config
        BagToPcdLaunch["bag_to_pcd.launch"]:::config
    end

    %% Processing Nodes
    subgraph "Calibration Pipeline"
        direction TB
        BagToPcd["bag_to_pcd Node\n(Reads LiDAR → .pcd)"]:::processing
        SingleCalib["Single-scene Calibration Node\n(Edges → Ceres → extrinsic)"]:::processing
        MultiCalib["Multi-scene Calibration Node\n(Loop over N scenes)"]:::processing
    end

    %% Configuration Store
    ConfigStore["YAML Config Store\n(config/*.yaml)"]:::config

    %% External Libraries & Build
    ExternalLibs["External Libraries & Build\n(PCL, Eigen, Ceres, CMake)"]:::external

    %% RViz Visualizer
    RViz["RViz Visualizer\n(rviz_cfg/*.rviz)"]:::external

    %% Data Storage
    DataStore["Data Storage\n(.pcd files, extrinsic.txt)"]:::storage

    %% Connections
    Master --> CalibLaunch
    Master --> MultiCalibLaunch
    Master --> BagToPcdLaunch

    CalibLaunch --> BagToPcd
    CalibLaunch --> SingleCalib
    MultiCalibLaunch --> BagToPcd
    MultiCalibLaunch --> MultiCalib

    BagToPcd -->|"/velodyne_points\nor /pcd_cloud"| SingleCalib
    BagToPcd -->|"/velodyne_points\nor /pcd_cloud"| MultiCalib

    SingleCalib -->|writes| DataStore
    MultiCalib -->|writes| DataStore

    SingleCalib -->|publishes viz topics| RViz
    MultiCalib -->|publishes viz topics| RViz

    ConfigStore --> CalibLaunch
    ConfigStore --> MultiCalibLaunch
    ConfigStore --> SingleCalib
    ConfigStore --> MultiCalib

    ExternalLibs --> BagToPcd
    ExternalLibs --> SingleCalib
    ExternalLibs --> MultiCalib

    %% Loop annotation
    MultiCalib -. loop over scenes .-> MultiCalib

    %% Click Events
    click CalibLaunch "https://github.com/hku-mars/livox_camera_calib/blob/master/launch/calib.launch"
    click MultiCalibLaunch "https://github.com/hku-mars/livox_camera_calib/blob/master/launch/multi_calib.launch"
    click BagToPcdLaunch "https://github.com/hku-mars/livox_camera_calib/blob/master/launch/bag_to_pcd.launch"

    click BagToPcd "https://github.com/hku-mars/livox_camera_calib/blob/master/src/bag_to_pcd.cpp"
    click BagToPcdLaunch "https://github.com/hku-mars/livox_camera_calib/blob/master/launch/bag_to_pcd.launch"

    click SingleCalib "https://github.com/hku-mars/livox_camera_calib/blob/master/src/lidar_camera_calib.cpp"
    click SingleCalib "https://github.com/hku-mars/livox_camera_calib/blob/master/include/lidar_camera_calib.hpp"
    click SingleCalib "https://github.com/hku-mars/livox_camera_calib/blob/master/config/calib.yaml"
    click CalibLaunch "https://github.com/hku-mars/livox_camera_calib/blob/master/launch/calib.launch"

    click MultiCalib "https://github.com/hku-mars/livox_camera_calib/blob/master/src/lidar_camera_multi_calib.cpp"
    click MultiCalib "https://github.com/hku-mars/livox_camera_calib/blob/master/config/multi_calib.yaml"
    click MultiCalibLaunch "https://github.com/hku-mars/livox_camera_calib/blob/master/launch/multi_calib.launch"

    click ConfigStore "https://github.com/hku-mars/livox_camera_calib/blob/master/config/calib.yaml"
    click ConfigStore "https://github.com/hku-mars/livox_camera_calib/blob/master/config/config_indoor.yaml"
    click ConfigStore "https://github.com/hku-mars/livox_camera_calib/blob/master/config/config_outdoor.yaml"
    click ConfigStore "https://github.com/hku-mars/livox_camera_calib/blob/master/config/multi_calib.yaml"

    click RViz "https://github.com/hku-mars/livox_camera_calib/blob/master/rviz_cfg/calib.rviz"
    click RViz "https://github.com/hku-mars/livox_camera_calib/blob/master/rviz_cfg/calib_indoor.rviz"

    click DataStore "https://github.com/hku-mars/livox_camera_calib/tree/master/pics/"
    click DataStore "https://github.com/hku-mars/livox_camera_calib/blob/master/result/extrinsic.txt"

    click ExternalLibs "https://github.com/hku-mars/livox_camera_calib/blob/master/CMakeLists.txt"
    click ExternalLibs "https://github.com/hku-mars/livox_camera_calib/blob/master/package.xml"
    click ExternalLibs "https://github.com/hku-mars/livox_camera_calib/blob/master/include/common.h"
    click ExternalLibs "https://github.com/hku-mars/livox_camera_calib/blob/master/include/CustomMsg.h"
    click ExternalLibs "https://github.com/hku-mars/livox_camera_calib/blob/master/include/CustomPoint.h"
    click ExternalLibs "https://github.com/hku-mars/livox_camera_calib/blob/master/README.md"
    click ExternalLibs "https://github.com/hku-mars/livox_camera_calib/tree/master/LICENSE"

    %% Styles
    classDef middleware fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef processing fill:#D0FFD8,stroke:#333,stroke-width:1px
    classDef external fill:#FFE8A1,stroke:#333,stroke-width:1px
    classDef config fill:#E8E8E8,stroke:#333,stroke-width:1px
    classDef storage fill:#F0F0F0,stroke:#333,stroke-width:1px
```
