# adlink-ros/apriltag_ros architecture

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

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

## Overview

##### Project type and purpose
- This is a ROS2 full-stack “node” component: it subscribes to sensor_msgs/Image topics, calls into the Apriltag C/C++ library for marker detection, then publishes detection messages and TF2 transforms.
- It consists of two ROS2 packages:
- apriltag_msgs – defines AprilTagDetection and AprilTagDetectionArray message types
- apriltag_ros – implements the AprilTagNode node, parameter loading, launch files, and configuration

a. Camera / Image source
b. ROS2 Middleware (rclcpp) – handles pub/sub, parameter server, node lifecycle
c. AprilTagNode (in apriltag_ros)
d. Apriltag detection library (external C/C++ library)
e. TF2 broadcaster (in node)
f. Message definitions (apriltag_msgs)
g. Configuration files (YAML under apriltag_ros/cfg)
h. Launch system (ros2 launch scripts)

- Camera → (sensor_msgs/Image topic) → AprilTagNode.subscribe
- Launch script loads parameters from cfg/*.yaml → populates node’s ROS2 parameter server
- AprilTagNode invokes Apriltag library APIs on each Image callback
- Apriltag library returns corner detections → AprilTagNode packages into AprilTagDetectionArray msg
- AprilTagNode.publish → AprilTagDetectionArray topic
- AprilTagNode.broadcast → tf2 frames (pose of each tag)
- Other ROS2 nodes / visualization tools subscribe to detection and TF topics

##### Architectural patterns and design principles
- Publisher–Subscriber pattern for data flow (ROS2 topics)
- Parameter-driven configuration (YAML + ROS2 parameter server)
- Separation of concerns:
- apriltag_msgs: message schema
- apriltag_ros: node implementation + launch/config
- External library: Apriltag core detection logic

##### Important technologies, frameworks, and libraries
- ROS2 (rclcpp, sensor_msgs, tf2_ros)
- AprilTag C/C++ library
- colcon / CMake build system (CMakeLists.txt + package.xml)
- YAML configuration files for tag families and sizes

- Component labels: e.g., “AprilTagNode (apriltag_ros)”
- Config file references: e.g., “tags_36h11_all.yaml”
- TF frame outputs: e.g., “/tag_xx → tf2 transform”

##### Detail level reminder
- Four sub-directories under apriltag_ros (cfg, include, launch, src) as functional groups
- Dependency on apriltag_msgs for message types
- Build/deploy step at a high level (launch scripts invoking node with parameters)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Nodes
    Camera["Camera/Image Source"]:::external
    ImageTopic((""/camera/color/image_raw\nsensor_msgs/Image"")):::topic
    AprilTagNode["AprilTagNode\n(apriltag_ros)"]:::rosnode
    DetectionTopic((""/tag_detections\nAprilTagDetectionArray"")):::topic
    TFBroadcaster["TF2 Broadcaster"]:::rosnode
    ParamServer[(Parameter Server)]:::config
    ApriltagLib(("Apriltag C/C++ Library")):::lib

    %% apriltag_msgs package
    subgraph "apriltag_msgs"
        ATD["AprilTagDetection.msg"]:::file
        ATDA["AprilTagDetectionArray.msg"]:::file
        AMETA["CMakeLists.txt & package.xml"]:::file
    end

    %% apriltag_ros package
    subgraph "apriltag_ros"
        subgraph include
            Header["AprilTagNode.hpp"]:::file
        end
        subgraph src
            Impl["AprilTagNode.cpp"]:::file
        end
        subgraph cfg
            CFG1["tags_16h5_all.yaml"]:::config
            CFG2["tags_16h5_filtered.yaml"]:::config
            CFG3["tags_36h11_all.yaml"]:::config
            CFG4["tags_36h11_filter.yaml"]:::config
        end
        subgraph launch
            L1["tag_gazebo.launch.py"]:::file
            L2["tag_realsense.launch.py"]:::file
        end
        META["CMakeLists.txt & package.xml"]:::file
    end

    %% Build / repo metadata
    LICENSE["LICENSE & README.md"]:::file

    %% Flows
    Camera -->|"/camera/color/image_raw"| ImageTopic
    ImageTopic -->|"subscribe"| AprilTagNode
    L1 -->|"launch"| ParamServer
    L2 -->|"launch"| ParamServer
    CFG1 -->|load params| ParamServer
    CFG2 -->|load params| ParamServer
    CFG3 -->|load params| ParamServer
    CFG4 -->|load params| ParamServer
    ParamServer -->|"parameters"| AprilTagNode
    AprilTagNode -->|"invoke detection"| ApriltagLib
    ApriltagLib -->|"corner detections"| AprilTagNode
    AprilTagNode -->|"/tag_detections"| DetectionTopic
    DetectionTopic -->|"uses msg types"| ATDA
    AprilTagNode -->|"broadcast tf2"| TFBroadcaster

    %% Click events
    click ATD "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_msgs/msg/AprilTagDetection.msg"
    click ATDA "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_msgs/msg/AprilTagDetectionArray.msg"
    click AMETA "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_msgs/CMakeLists.txt"
    click AMETA "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_msgs/package.xml"
    click Header "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_ros/include/AprilTagNode.hpp"
    click Impl "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_ros/src/AprilTagNode.cpp"
    click META "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_ros/CMakeLists.txt"
    click META "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_ros/package.xml"
    click CFG1 "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_ros/cfg/tags_16h5_all.yaml"
    click CFG2 "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_ros/cfg/tags_16h5_filtered.yaml"
    click CFG3 "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_ros/cfg/tags_36h11_all.yaml"
    click CFG4 "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_ros/cfg/tags_36h11_filter.yaml"
    click L1 "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_ros/launch/tag_gazebo.launch.py"
    click L2 "https://github.com/adlink-ros/apriltag_ros/blob/jazzy-devel/apriltag_ros/launch/tag_realsense.launch.py"

    %% Legend
    subgraph Legend
        direction LR
        RN["ROS2 Node"]:::rosnode
        TP(("Topic")):::topic
        CF[(Config/Param)]:::config
        LB(("Library")):::lib
    end

    %% Styles
    classDef rosnode fill:#cfe2f3,stroke:#437799,color:#0b2942;
    classDef topic fill:#d1e7dd,stroke:#2e7d32,color:#1b5e20;
    classDef config fill:#ffe5b4,stroke:#cc8400,color:#663c00;
    classDef lib fill:#e2d5f8,stroke:#5a32a3,color:#2e0854;
    classDef file fill:#f0f0f0,stroke:#999999,color:#333333;
    classDef external fill:#f8d7da,stroke:#b02a37,color:#721c24;
```
