# christianrauch/apriltag_ros architecture

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

- Interactive diagram: https://gitdiagram.com/christianrauch/apriltag_ros
- Repository: https://github.com/christianrauch/apriltag_ros

## Overview

##### Project Type and Purpose
- This is an open-source ROS 2 node named `apriltag_ros` that detects AprilTag markers in camera images.
- It subscribes to image and camera info topics, runs tag detection & pose estimation using the AprilTag C library, and publishes TF transforms and detection arrays.
- It can run as a standalone executable or as a composable node in a container for zero‐copy intra-process communication.

##### File Structure Analysis
- Top-level build and CI:
- CMakeLists.txt, package.xml → ROS 2 build & package metadata
- .github/workflows/ci.yml → continuous integration for Linux/macOS builds & tests
- Source code (`src/`):
- AprilTagNode.cpp → ROS 2 node entrypoint (subscription, callbacks)
- tag_functions.{cpp,hpp} → thin wrappers around the AprilTag library detector
- pose_estimation.{cpp,hpp} → compute 3D pose from homography & camera intrinsics
- conversion.cpp → convert raw detection data into ROS 2 messages (`TFMessage`, `AprilTagDetectionArray`)
- Configuration (`cfg/`): YAML files defining ROS 2 parameters (e.g. families, ids, sizes)
- Launch (`launch/`): YAML launch definitions for composite node setups with camera_ros

##### README Insights
- Subscriptions:
- image_transport::CameraSubscriber → `image_rect` + `camera_info`
- Publishers:
- `/tf` (TFMessage)
- `detections` (AprilTagDetectionArray)
- Two modes:
- standalone (`ros2 run apriltag_ros apriltag_node`)
- composable node (`AprilTagNode` loaded in a container with `camera::CameraNode`)
- Parameterization via ROS 2 YAML parameter files

##### Diagramming the System Architecture
a. Main Components
1. ROS 2 Middleware (DDS)
2. Camera Source Node (e.g. `camera::CameraNode`)
3. AprilTagNode
– Image Transport Subscriber
– AprilTag Detector (native C library)
– Pose Estimation Module
– Conversion & Publisher Module
4. TF2 Broadcaster
5. Detection Message Publisher
6. Configuration Loader (YAML parameters)
7. (Optional) Container Node for composable execution
b. Relationships & Data Flow
- Camera Node → publishes `image_rect` + `camera_info` → AprilTagNode
- AprilTagNode → runs detection → computes poses
- AprilTagNode → publishes `/tf` transforms → TF2 ecosystem
- AprilTagNode → publishes `detections` topic → downstream consumers
- Parameter Server/Loader → configures AprilTagNode at startup
- In composable mode: Camera Node and AprilTagNode share memory inside a single process
c. Architectural Patterns & Principles
- Modular ROS 2 node design (separation of concerns: subscription, detection, pose, messaging)
- Intraprocess communication for performance (zero-copy)
- Parameter-driven behavior (YAML config for families, sizes, detection tuning)
- Clear pub/sub boundary for loose coupling
d. Key Technologies & Libraries
- ROS 2 (rclcpp, image_transport, tf2, component infrastructure)
- AprilTag C library (detector algorithms, homography)
- CMake, ament_cmake (build system)
- YAML for parameter configuration
- DDS (underlying pub/sub transport)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & CI
    subgraph "Build & CI" 
        direction TB
        CMake["CMakeLists.txt"]:::build
        PackageXML["package.xml"]:::build
        CIWorkflow[".github/workflows/ci.yml"]:::build
    end

    %% Configuration & Launch
    subgraph "Configuration & Launch" 
        direction TB
        ParamYAML["cfg/tags_36h11.yaml"]:::config
        LaunchYAML["launch/camera_36h11.launch.yml"]:::config
    end

    %% ROS 2 Middleware
    DDS("ROS 2 Middleware (DDS)"):::middleware

    %% Nodes
    subgraph "ROS 2 Nodes" 
        direction TB
        CameraNode["camera::CameraNode"]:::rosnode
        subgraph "AprilTagNode"
            direction TB
            ATSubscriber["ImageTransport Subscriber"]:::rosnode
            Detector["AprilTag Detector"]:::library
            Estimator["Pose Estimation Module"]:::library
            Converter["Conversion & Publisher Module"]:::rosnode
        end
    end

    %% External Libraries
    AprilTagLib["AprilTag C Library"]:::library

    %% Data Stores
    Params("Parameter Server"):::config

    %% Data Flow
    ParamYAML -->|loads parameters| Params
    LaunchYAML -->|starts nodes| CameraNode
    LaunchYAML -->|starts nodes| AprilTagNode
    CameraNode -->|"image_rect + camera_info"| ATSubscriber
    ATSubscriber -->|raw image data| Detector
    Detector -->|tag detections| Estimator
    Estimator -->|pose data| Converter
    Converter -->|TFMessage on /tf| TF2Broadcaster["TF2 Broadcaster"]:::rosnode
    Converter -->|AprilTagDetectionArray on detections| DetectionPub["Detection Publisher"]:::rosnode
    Converter -->|frame_id, timestamp| DDS
    CameraNode -->|topic transport| DDS
    DDS -->|in composable mode| ATSubscriber

    Converter -->|uses| AprilTagLib

    %% Click Events
    click CMake "https://github.com/christianrauch/apriltag_ros/blob/master/CMakeLists.txt"
    click PackageXML "https://github.com/christianrauch/apriltag_ros/blob/master/package.xml"
    click CIWorkflow "https://github.com/christianrauch/apriltag_ros/blob/master/.github/workflows/ci.yml"
    click ParamYAML "https://github.com/christianrauch/apriltag_ros/blob/master/cfg/tags_36h11.yaml"
    click LaunchYAML "https://github.com/christianrauch/apriltag_ros/blob/master/launch/camera_36h11.launch.yml"
    click ATSubscriber "https://github.com/christianrauch/apriltag_ros/blob/master/src/AprilTagNode.cpp"
    click Detector "https://github.com/christianrauch/apriltag_ros/blob/master/src/tag_functions.cpp"
    click Detector "https://github.com/christianrauch/apriltag_ros/blob/master/src/tag_functions.hpp"
    click Estimator "https://github.com/christianrauch/apriltag_ros/blob/master/src/pose_estimation.cpp"
    click Estimator "https://github.com/christianrauch/apriltag_ros/blob/master/src/pose_estimation.hpp"
    click Converter "https://github.com/christianrauch/apriltag_ros/blob/master/src/conversion.cpp"

    %% Styles
    classDef build fill:#f9f,stroke:#333,stroke-width:1px
    classDef config fill:#fcf,stroke:#333,stroke-width:1px
    classDef middleware fill:#ccf,stroke:#333,stroke-width:1px
    classDef rosnode fill:#bbf,stroke:#333,stroke-width:1px
    classDef library fill:#bfb,stroke:#333,stroke-width:1px
```
