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

> Architecture diagram of the GitHub repository arghyachatterjee/april-tag-based-autonomous-navigation, 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
- Repository: https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation

## Overview

##### Project type and purpose
- This is a ROS (Robot Operating System) package for AR-tag (AprilTag) based autonomous navigation.
- Purpose: allow a robot with a camera to detect AprilTag landmarks, publish their poses into the TF tree, and support runtime management of those landmarks for navigation and obstacle avoidance.

##### File structure
- Top-level ROS build files: CMakeLists.txt, package.xml, setup.py
- Directories:
- launch/ : ROS launch files to bring up each node
- scripts/ : executable Python scripts for three ROS nodes
- landmarks/ : YAML config for defining tag‐based landmarks
- images/ : screenshots for README documentation
- Key scripts:
- landmark_finder
- landmark_manager
- tf_map_to_landmark
- Config:
- landmarks/landmarks.yaml
- launch/*.launch take args to parameterize topics, frames, config paths

##### README for additional insights
- Architecture is modular:
- Landmark and LandmarkCollection modules handle data structures and transform math
- Three ROS nodes offer CLI management, vision‐based detection, and TF publishing
- Integration points:
- AprilTag detection library from interbotix_perception_modules
- ROS TF tree for coordinate transforms
- Dynamic reconfiguration through YAML + parameters

a. Main components
1. Robot camera (sensor)
2. landmark_finder node
3. tf_map_to_landmark node
4. landmark_manager node
5. landmarks.yaml (configuration store)
6. ROS Master & Parameter Server
7. TF Tree (map → landmarks → robot base_link)
8. AprilTag detection module (external library)
b. Relationships & data flow
- Camera publishes raw images & camera_info → landmark_finder subscribes
- landmark_finder runs AprilTag detector → publishes detected tag poses into /tf
- tf_map_to_landmark reads landmarks.yaml & subscribes to tag frames → computes & publishes map→landmark transforms into /tf
- landmark_manager reads/writes landmarks.yaml via CLI → updates Parameter Server or writes file on disk
- Navigation stack (external) reads TF tree to plan paths to landmarks
c. Architectural patterns & design principles
- ROS node separation: sensing, transform management, and configuration kept in separate processes
- TF‐centric architecture: all coordinate transforms flow through a common TF tree
- Configuration as code: YAML files and ROS parameters for dynamic re‐configuration
d. Key technologies & libraries
- ROS (rospy, tf2_ros, dynamic_reconfigure)
- AprilTag module from interbotix_perception_modules
- YAML for landmark definitions
- ROS launch system for composition

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "ROS Core"
    Master["ROS Master & Parameter Server"]:::data
  end

  subgraph "Configuration"
    LMManager["landmark_manager Node"]:::node
    YAML["landmarks.yaml"]:::data
    LMManager -->|"reads/writes"| YAML
    LMManager -->|"updates params"| Master
  end

  subgraph "Perception"
    Camera["Robot Camera (sensor)"]:::node
    Finder["landmark_finder Node"]:::node
    AprilTag["AprilTag Library"]:::external
    Camera -->|"camera/color/image_raw"| Finder
    Finder -->|"calls detection API"| AprilTag
    Finder -->|"publishes tag_<id> frames to TF"| tfTree
  end

  subgraph "TF Management"
    TFMGR["tf_map_to_landmark Node"]:::node
    TFMGR -->|"reads landmarks.yaml"| YAML
    TFMGR -->|"subscribes tag_<id> frames"| tfTree
    TFMGR -->|"publishes map→tag_<id> transforms"| tfTree
  end

  subgraph "TF Tree"
    tfTree["TF Tree (map → landmarks → base_link)"]:::external
  end

  subgraph "Navigation"
    Nav["Navigation Stack"]:::external
    tfTree -->|"transforms lookup"| Nav
  end

  subgraph "Launch Files"
    L1["landmark.launch"]:::file
    L2["landmark_manager.launch"]:::file
    L3["tf_map_to_landmark.launch"]:::file
  end

  subgraph "Project Files"
    CM["CMakeLists.txt"]:::file
    PKG["package.xml"]:::file
    SETUP["setup.py"]:::file
    README["README.md"]:::file
    IMGS["images/"]:::file
  end

  click Finder "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation/tree/main/scripts/landmark_finder"
  click LMManager "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation/tree/main/scripts/landmark_manager"
  click TFMGR "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation/tree/main/scripts/tf_map_to_landmark"
  click YAML "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation/blob/main/landmarks/landmarks.yaml"
  click L1 "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation/blob/main/launch/landmark.launch"
  click L2 "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation/blob/main/launch/landmark_manager.launch"
  click L3 "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation/blob/main/launch/tf_map_to_landmark.launch"
  click CM "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation/blob/main/CMakeLists.txt"
  click PKG "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation/blob/main/package.xml"
  click SETUP "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation/blob/main/setup.py"
  click IMGS "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation/tree/main/images/"
  click README "https://github.com/arghyachatterjee/april-tag-based-autonomous-navigation/blob/main/README.md"

  classDef node fill:#DAE8FC,stroke:#6C8EBF,color:#000;
  classDef data fill:#D5E8D4,stroke:#82B366,color:#000;
  classDef external fill:#FFE6CC,stroke:#D79B00,color:#000;
  classDef file fill:#F5F5F5,stroke:#999999,color:#000;
  class Finder,LMManager,TFMGR,Camera node
  class YAML,Master data
  class AprilTag,tfTree,Nav external
  class CM,PKG,SETUP,README,IMGS,L1,L2,L3 file
```
