# acfr/cam_lidar_calibration architecture

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

- Interactive diagram: https://gitdiagram.com/acfr/cam_lidar_calibration
- Repository: https://github.com/acfr/cam_lidar_calibration

## Overview

##### Project Type and Purpose
- This is a ROS (Robot Operating System) catkin package for estimating extrinsic calibration between a monocular camera and a 3D LiDAR.
- It provides an interactive sample-capture GUI, background subtraction, chessboard feature extraction, an optimisation engine, and a post-hoc assessment/visualisation phase.

##### High-Level Components
a. Sensors & ROS Master
- Camera (publishes `/camera/image` & `/camera/camera_info`)
- LiDAR (publishes `/lidar/points` as `sensor_msgs/PointCloud2` with ring info)
- ROS Master (name service, parameter server, topic router)
b. Configuration
- `cfg/params.yaml` – camera & LiDAR topics, board specs, ROI bounds
- Dynamic Reconfigure via ROS
c. Nodes & Nodelets
- `feature_extraction_node` (src/feature_extraction_node.cpp) – subscribes to image+pointcloud, does background subtraction & chessboard extraction
- `cam_lidar_panel` nodelet (src/cam_lidar_panel.cpp + nodelet_definition.xml) – RQt GUI panel for “Capture Background”, “Capture Sample”, “Discard Sample”, “Optimise” buttons
- `optimiser` node (src/optimiser.cpp & action/RunOptimise.action) – triggered by UI, reads samples from disk, runs VOQ-based optimisation, writes CSV outputs
- `assess_calibration` node (src/assess_calibration.cpp) – consumes CSV, computes reprojection errors, optionally publishes markers for RViz
d. Services & Actions
- `Optimise.srv` – synchronous request to trigger optimisation
- `RunOptimise.action` – asynchronous action for longer-running optimisation tasks
e. Launch & Visualization
- `launch/run_optimiser.launch` – brings up the UI panel, feature extraction, and optimiser hooks
- `launch/assess_results.launch` – loads the assessment node and RViz config for showing reprojection error histograms and overlays
- `rviz/*.rviz` – prebuilt RViz configurations for live preview and projection overlays
f. Scripts & Utilities
- `scripts/visualise_results.py` – standalone Python script to plot histograms and wrap angles
g. Data & Persistence
- `data/YYYY-MM-DD_HH-MM-SS/` – stores PCDs, PNGs, `poses.csv`, `calibration_*.csv`

##### Relationships & Data Flows
- Sensors → ROS Topics → FeatureExtractionNode
- FeatureExtractionNode → (publishes sample files to disk + sample metadata over a ROS topic)
- UI Panel → user commands → calls ROS Service/Action → Optimiser Node
- Optimiser Node → reads sample files → writes `calibration_*.csv` → publishes completion status
- Assessment Node (or script) → reads `calibration_*.csv` → computes errors → publishes RViz markers or plots

##### Architectural Patterns & Design Principles
- ROS Pub/Sub for streaming sensor data
- ROS Services & Actions for control flows (start optimisation, get results)
- Modular separation:
- Per-frame feature extraction (real-time)
- Sample management & storage
- Batch optimisation engine
- Post-processing assessment
- Reuse of standard ROS packages: `tf2`, `pcl_ros`, `sensor_msgs`, `dynamic_reconfigure`
- Docker container for reproducible builds (docker/Dockerfile + build/run scripts)

##### Key Points to Capture
- Real-time feature extraction vs. batch optimisation (two distinct phases).
- UI panel’s tight coupling with dynamic reconfigure & sample management.
- File-based handshake between capture phase and optimisation phase (samples saved to disk).
- Post-hoc assessment overlays in RViz or script-based plots.
- Docker boundary around the entire ROS system for reproducible deployment.

##### and segregates runtime (nodes + topics) from build/deploy (Docker, CMake, catkin).
This will give any new engineer or stakeholder an immediate, accurate snapshot of the Camera-LiDAR Calibration pipeline’s architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Container"
        direction TB

        subgraph "Sensors & Master"
            direction TB
            Cam["Camera"]:::external
            LiDAR["LiDAR"]:::external
            Master["ROS Master"]:::external
        end

        subgraph "Configuration"
            direction TB
            cfgParams["params.yaml"]:::config
            cameraInfo["camera_info.yaml"]:::config
            boundsCfg["bounds.cfg"]:::config
        end

        subgraph "ROS Nodes"
            direction TB
            FE["FeatureExtractionNode"]:::rosnode
            Panel["Cam-LiDAR Panel Nodelet"]:::rosnode
            Opt["OptimiserNode"]:::rosnode
            Assess["AssessmentNode"]:::rosnode
        end

        subgraph "Services & Actions"
            direction TB
            OptSvc["/cam_lidar/optimise (Optimise.srv)"]:::service
            OptAct["/run_optimiser (RunOptimise.action)"]:::service
        end

        subgraph "Data Storage"
            direction TB
            CSV["Calibration CSVs"]:::data
            PCD["PCDs & PNGs"]:::data
            Images["Sample Images"]:::data
        end

        subgraph "Scripts & Visualization"
            direction TB
            Vis["visualise_results.py"]:::external
            RViz1["cam_lidar_calibration.rviz"]:::external
            RViz2["projection.rviz"]:::external
        end

        Cam -->|"image, camera_info"| Master
        LiDAR -->|"points"| Master
        Master -->|"subscribes"| FE
        FE -->|"saves samples to disk"| CSV
        FE -->|"publishes metadata"| Panel
        Panel -->|"calls service"| OptSvc
        Panel -->|"sends goal"| OptAct
        OptSvc -->|"triggers optimisation"| Opt
        OptAct -->|"runs optimisation"| Opt
        Opt -->|"reads samples"| CSV
        Opt -->|"writes calibration_*.csv"| CSV
        Opt -->|"publishes status"| Panel
        Assess -->|"reads calibration CSV"| CSV
        Assess -->|"publishes RViz markers"| Master
        Vis -->|"reads CSV & images"| CSV
        Vis -->|"plots histograms"| Vis
    end

    classDef rosnode fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef config fill:#f4f142,stroke:#333,stroke-width:1px
    classDef data fill:#85b2f3,stroke:#333,stroke-width:1px
    classDef service fill:#f2a65a,stroke:#333,stroke-width:1px
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px

    click cfgParams "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/cfg/params.yaml"
    click cameraInfo "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/cfg/camera_info.yaml"
    click boundsCfg "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/cfg/bounds.cfg"
    click featSrc "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/src/feature_extraction_node.cpp"
    click featImpl "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/src/feature_extractor.cpp"
    click featHdr "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/include/cam_lidar_calibration/feature_extractor.h"
    click pointHdr "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/include/cam_lidar_calibration/point_xyzir.h"
    click panelSrc "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/src/cam_lidar_panel.cpp"
    click panelHdr "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/src/cam_lidar_panel.h"
    click nodeletDef "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/nodelet_definition.xml"
    click pluginDesc "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/plugin_description.xml"
    click optSrc "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/src/optimiser.cpp"
    click optHdr "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/include/cam_lidar_calibration/optimiser.h"
    click optimiseSrv "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/srv/Optimise.srv"
    click optimiseAct "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/action/RunOptimise.action"
    click assessSrc "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/src/assess_calibration.cpp"
    click launchOpt "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/launch/run_optimiser.launch"
    click launchAssess "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/launch/assess_results.launch"
    click rviz1 "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/rviz/cam_lidar_calibration.rviz"
    click rviz2 "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/rviz/projection.rviz"
    click visScript "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/scripts/visualise_results.py"
    click dataPoses "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/data/vlp/poses.csv"
    click dataCal "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/data/vlp/calibration_*.csv"
    click dataImg "https://github.com/acfr/cam_lidar_calibration/tree/calib-v2/data/vlp/images/"
    click dockerfile "https://github.com/acfr/cam_lidar_calibration/tree/calib-v2/docker/Dockerfile"
    click buildSh "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/docker/build.sh"
    click runSh "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/docker/run.sh"
    click entrySh "https://github.com/acfr/cam_lidar_calibration/blob/calib-v2/docker/entrypoint.sh"
    click deps "https://github.com/acfr/cam_lidar_calibration/tree/calib-v2/docker/dependencies"
```
