# lardemua/atom architecture

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

- Interactive diagram: https://gitdiagram.com/lardemua/atom
- Repository: https://github.com/lardemua/atom

## Overview

##### Project type and purpose
- ATOM Calibration is a ROS-based multi-package framework for robotic multi-sensor, multi-modal calibration. It comprises libraries, calibration engines, batch execution, evaluation scripts, message definitions, RViz plugins, simulation worlds, and examples.

##### Architectural overview
- All packages live in a single Catkin/CMake workspace. They build into ROS nodes, libraries, message/service definitions, and plugins.
- Core abstraction: the ROS middleware bus—topics, services, parameters—connects sensor data, calibration engines, evaluation scripts, and visualization tools.

##### Main components
A. atom_core (Python/C++ library)
- Provides atomic transformation math, dataset I/O, utilities (cache, drawing, geometry, optimization helpers).
- Used by atom_calibration, atom_batch_execution, atom_evaluation.
B. atom_msgs (ROS msgs & services)
- Defines custom messages (DepthLabels, Lidar3DLabels, etc.) and services for dataset retrieval, interactive markers, saving/loading collections.
- Acts as the contract between nodes and scripts.
C. atom_calibration (Calibration engine & CLI)
- Contains ROS nodes/scripts that implement calibration routines (objective functions, TF estimation, initial guesses, transform correction).
- Subdirectories: collect (data collectors), calibration (optimizer), dataset_playback (replay), initial_estimate, odometry_inspector, transform_corrector.
- Inputs: raw sensor data (rosbags), pattern definitions. Outputs: optimized transformations, YAML/JSON result files.
D. atom_batch_execution
- Automates running multiple calibration experiments (templates, data files, batch scripts).
- Produces CSV and JSON result sets.
E. atom_evaluation
- Scripts for quantitative evaluation of calibration results (RGB-to-RGB, LiDAR-to-Depth, etc.).
- Reads JSON/YAML calibration outputs, computes error metrics, exports CSV.
F. atom_rviz_plugins
- RViz plugin (selected_points_publisher) for interactive pattern selection in point clouds/images.
- Loaded into RViz for manual data collection steps.
G. atom_worlds
- Gazebo worlds, pattern models (charuco, chessboard), and launch files for simulation-based data collection and calibration.
H. atom_examples
- Bringup, calibration, visualization launch files and URDFs for reference robots (rrbot, softbot, mrbot, etc.).
- Provide end-to-end demonstrations.
I. External tools
- ROS core (roscore, rosbag), Gazebo, RViz.

##### Component interactions and data flow
1. Launch Gazebo world (atom_worlds) via ROS → simulated sensor topics
2. Run dataset recording node/scripts (atom_calibration/collect) → rosbag files
3. Replay dataset with dataset_playback (atom_calibration) → inputs to optimizer
4. Run calibration node (atom_calibration/calibration) → writes optimized TFs (YAML/JSON)
5. Optionally run transform_corrector or odometry_inspector for refinement
6. Run evaluation scripts (atom_evaluation) on results → CSV error reports

Batch mode: atom_batch_execution orchestrates steps 2–5 automatically over multiple datasets.

##### Architectural patterns and principles
- Modular ROS packages with clear separation of concerns (core library vs. calibration logic vs. batch orchestration vs. evaluation vs. visualization).
- Publish-subscribe / request-reply (services) interactions over ROS.
- Template-based launch/parameter configuration using Jinja2 templates (.j2 files).
- Data flow: raw data → processing → optimization → evaluation → visualization.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "atom_core"
        core["atom_core"]:::core
    end
    subgraph "atom_msgs"
        msgs["atom_msgs"]:::core
    end
    subgraph "atom_calibration"
        coll["collect (node)"]:::process
        playback["dataset_playback"]:::process
        calib["calibration"]:::process
    end
    subgraph "atom_batch_execution"
        batch["atom_batch_execution"]:::orchestrator
    end
    subgraph "atom_evaluation"
        eval["atom_evaluation"]:::process
    end
    subgraph "atom_rviz_plugins"
        rviz_plg["selected_points_publisher"]:::viz
    end
    subgraph "atom_worlds"
        worlds["atom_worlds"]:::viz
    end
    subgraph "atom_examples"
        examples["atom_examples"]:::viz
    end

    extgaz["Gazebo"]:::viz_ext
    extrviz["RViz"]:::viz_ext
    ROSbus(["ROS Middleware"]):::bus
    rosbag["rosbag (bag files)"]:::data
    results["YAML/JSON results"]:::data
    csv["CSV reports"]:::data

    extgaz -->|"sensor topics"| ROSbus
    ROSbus -->|"subscribe"| coll
    coll -->|"write"| rosbag
    rosbag -->|"play"| playback
    playback -->|"feed"| calib
    calib -->|"output"| results
    results -->|"eval input"| eval
    eval -->|"export"| csv
    results -->|"visualize"| ROSbus
    extrviz -->|"plugin"| rviz_plg
    rviz_plg -->|"collect control"| coll
    batch -->|"orchestrate"| coll
    batch -->|"orchestrate"| playback
    batch -->|"orchestrate"| calib
    examples -->|"use"| calib
    examples -->|"use"| core

    classDef core fill:#AED6F1,stroke:#21618C,color:#1B4F72
    classDef process fill:#ABEBC6,stroke:#239B56,color:#1D8348
    classDef orchestrator fill:#F9E79F,stroke:#B7950B,color:#7D6608
    classDef viz fill:#D2B4DE,stroke:#6C3483,color:#4A235A
    classDef viz_ext fill:#D7BDE2,stroke:#7D3C98,color:#512E5F
    classDef data fill:#D5D8DC,stroke:#566573,color:#1C2833
    classDef bus stroke-dasharray: 5 5

    click core "https://github.com/lardemua/atom/blob/noetic-devel/atom_core/CMakeLists.txt"
    click msgs "https://github.com/lardemua/atom/blob/noetic-devel/atom_msgs/CMakeLists.txt"
    click coll "https://github.com/lardemua/atom/tree/noetic-devel/atom_calibration/scripts/collect_data"
    click playback "https://github.com/lardemua/atom/tree/noetic-devel/atom_calibration/scripts/dataset_playback"
    click calib "https://github.com/lardemua/atom/tree/noetic-devel/atom_calibration/scripts/calibrate"
    click batch "https://github.com/lardemua/atom/tree/noetic-devel/atom_batch_execution/scripts/batch_execution"
    click eval "https://github.com/lardemua/atom/tree/noetic-devel/atom_evaluation/scripts/"
    click rviz_plg "https://github.com/lardemua/atom/blob/noetic-devel/atom_rviz_plugins/selected_points_publisher/CMakeLists.txt"
    click worlds "https://github.com/lardemua/atom/tree/noetic-devel/atom_worlds/launch/"
    click examples "https://github.com/lardemua/atom/tree/noetic-devel/atom_examples/rrbot/"
```
