# arghyachatterjee/april-tag-based-autonomous-navigation-in-ros architecture

> Architecture diagram of the GitHub repository arghyachatterjee/april-tag-based-autonomous-navigation-in-ros, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros
- Repository: https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros

## Overview

##### Project Type and Purpose
- This is a ROS (Robot Operating System) package for landmark-based autonomous navigation.
- It uses AprilTag fiducials as predefined landmarks, detected via a camera, to generate TF transforms and navigation goals that avoid obstacles.
- Provides three primary ROS nodes:
- landmark_manager (CLI tool to define and save landmarks)
- landmark_finder (uses camera + AprilTag detector to locate landmarks and publish TFs)
- tf_map_to_landmark (bridges fixed “map” frame to user-defined “landmarks” frame)

##### File Structure Analysis
- Top-level files:
- CMakeLists.txt, package.xml, setup.py — ROS build & package metadata
- README.md — project overview, usage, launch arguments
- Directories:
- images/ — sample screenshots for documentation
- landmarks/ — YAML config (landmarks/landmarks.yaml) defining each landmark’s ID, mounted flag, offsets
- launch/ — ROS launch files (.launch) for each node with parameter definitions
- scripts/ — executable Python scripts: landmark_manager, landmark_finder, tf_map_to_landmark
- src/interbotix_landmark_modules/landmark.py — core classes: Landmark, LandmarkCollection

##### Core Components
- Perception Module: apriltag detector (from interbotix_perception_modules) that subscribes to camera streams
- Processing Nodes:
- landmark_finder: subscribes to AprilTag detections, computes landmark poses, publishes static TF transforms under namespace “landmarks”
- tf_map_to_landmark: publishes transform from “map” → “landmarks” to integrate with global TF tree
- landmark_manager: interactive CLI; reads/writes landmarks.yaml; instantiates LandmarkCollection to manage landmark definitions
- Data Store: landmarks.yaml (persistent record of defined landmarks)
- Configuration & Launch: launch/*.launch files — define ROS parameters (e.g., apriltag_ns, camera_color_topic, fixed_frame, obs_frame, use_cam) and orchestrate node startup

##### Relationships & Data Flow
2. apriltag detector node (in apriltag namespace) → processes images → publishes detected tag poses
3. landmark_finder → subscribes to tag detections → uses LandmarkCollection API → publishes static TFs for each observed landmark
4. tf_map_to_landmark → reads specified fixed_frame (map) and landmark root frame → publishes map→landmarks transform
5. Navigation stack (move_base or custom) → consumes TF tree and landmark goal requests to navigate

##### Architectural Patterns & Principles
- Modular ROS nodes with clear single responsibility
- Separation of concerns: perception (tag detection) vs. landmark management vs. TF bridging
- Configuration-driven design: YAML files + ROS parameters enable extensibility without code changes
- Use of TF tree for decoupled transform management

##### Final Recommendations
- Be exhaustive: include every major node, config file, and data flow path
- Validate with the actual launch file parameters to ensure labels are accurate

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Sensor Layer
    subgraph "Sensor Layer"
        Camera["Camera\n(topic: /camera/color/image_raw,\n/camera/color/camera_info)"]:::external
    end

    %% Perception Layer
    subgraph "Perception Module"
        AprilTag["AprilTag Detector\n(namespace: apriltag)"]:::perception
    end

    %% Processing Layer
    subgraph "Processing Nodes"
        LMF["landmark_finder Node\nlaunch: landmark.launch\nparams: apriltag_ns,\ncamera_color_topic"]:::node
        TFM["tf_map_to_landmark Node\nlaunch: tf_map_to_landmark.launch\nparams: fixed_frame,\nobs_frame,use_cam"]:::node
        LMM["landmark_manager CLI\nlaunch: landmark_manager.launch\nparams: none"]:::node
    end

    %% Config & Launch
    subgraph "Launch/Config"
        Params["Parameter Server"]:::server
        YAML["landmarks.yaml\n(fields: id, mounted,\noffset, label)"]:::config
        LaunchFiles["Launch Files\n(launch/*.launch)"]:::config
    end

    %% TF Tree
    TFTree["TF Tree"]:::tf

    %% Navigation
    Nav["Navigation Consumer\n(e.g., move_base)"]:::external

    %% Data Store & Docs
    subgraph "Documentation & Metadata"
        README["README.md"]:::doc
        Metadata["CMakeLists.txt\npackage.xml\nsetup.py"]:::doc
        Images["images/"]:::doc
    end

    %% Connections
    Camera -->|"image_raw,\ncamera_info"| AprilTag
    AprilTag -->|"tag detections"| LMF
    LMF -->|"- publishes static TFs\nunder 'landmarks' frame"| TFTree
    TFM -->|"- publishes map→landmarks\ntransform"| TFTree
    TFTree -->|"TF frames"| Nav
    LMM -->|read/write| YAML
    Params -->|provides params| LMF
    Params -->|provides params| TFM
    Params -->|provides params| LMM
    LaunchFiles -->|starts nodes| LMF
    LaunchFiles -->|starts nodes| TFM
    LaunchFiles -->|starts nodes| LMM

    %% Legend
    subgraph Legend
        direction LR
        A[rectangles: ROS Nodes]:::node
        B[Cylinder: Config/TF/Server]:::config
        C[Cloud: TF Tree]:::tf
        D[External: Sensor/Navigation]:::external
        E[Documents: Docs/Metadata]:::doc
    end

    %% Click Events
    click LMM "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros/tree/main/scripts/landmark_manager"
    click LMF "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros/tree/main/scripts/landmark_finder"
    click TFM "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros/tree/main/scripts/tf_map_to_landmark"
    click LMM "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros/blob/main/launch/landmark_manager.launch"
    click LMF "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros/blob/main/launch/landmark.launch"
    click TFM "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros/blob/main/launch/tf_map_to_landmark.launch"
    click YAML "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros/blob/main/landmarks/landmarks.yaml"
    click Metadata "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros/blob/main/CMakeLists.txt"
    click Metadata "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros/blob/main/package.xml"
    click Metadata "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros/blob/main/setup.py"
    click README "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros/blob/main/README.md"
    click Images "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation-in-ros/tree/main/images/"

    %% Styles
    classDef node fill:#AED6F1,stroke:#21618C,color:#1B4F72
    classDef perception fill:#D6EAF8,stroke:#5193C3,color:#21618C
    classDef external fill:#FADBD8,stroke:#CD6155,color:#922B21
    classDef config fill:#FCF3CF,stroke:#F7DC6F,color:#7D6608
    classDef server fill:#FDEDEC,stroke:#E74C3C,color:#641E16
    classDef tf fill:#E8F8F5,stroke:#45B39D,color:#186A3B
    classDef doc fill:#EAECEE,stroke:#ABB2B9,color:#424949
```
