# nvidia-isaac-ros/isaac_perceptor architecture

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

- Interactive diagram: https://gitdiagram.com/nvidia-isaac-ros/isaac_perceptor
- Repository: https://github.com/nvidia-isaac-ros/isaac_perceptor

## Overview

This project is a ROS (Robot Operating System) bringup package named “Isaac Perceptor.” Its primary purpose is to integrate various sensor drivers and perception algorithms into a unified launch environment for robotic perception tasks. Based on the file tree and README, the architecture consists of dedicated launch files for drivers and algorithms (e.g., sensor-specific launch files under the “drivers” subdirectory and algorithm processing launch files under the “algorithms” subdirectory), parameter configuration files, and a set of Python utilities that support common functions across these modules.

##### Main Components
- Launch Orchestrator: Represent the overall ROS2 bringup package that ties together the various nodes.
- Sensor Drivers: Group together components under “isaac_ros_perceptor_bringup/launch/drivers” which include drivers for Hawk cameras, Hesai lidar, joystick, etc.
- Perception Algorithms: Illustrate nodes from “isaac_ros_perceptor_bringup/launch/algorithms” that handle different perception tasks (e.g., hawks_processing, lidar_processing, nvblox, occupancy grid localization, etc.).
- Visualization/Tools: Include secondary modules like the Foxglove Bridge, RViz, and visualization utilities found under “isaac_ros_perceptor_bringup/launch/tools.”
- Parameters and Configuration: Have a component representing the “params” folder where configuration files (YAMLs) are stored and influence the behavior of the sensor and perception nodes.
- Python Utilities: Represent “isaac_ros_perceptor_python_utils” as a set of utility libraries that provide functions (constants, launch_utils, etc.) to multiple nodes.

##### Architectural Patterns and Design Principles
- Modularity: The clear separation between sensor drivers, algorithm processing, and visualization tools emphasizes modularity, a key ROS design principle.
- Configuration-Driven Setup: The heavy use of YAML parameter files and separate launch files reflects a configuration-driven system.
- Utility Abstraction: The Python utilities demonstrate the reuse of common functions across disparate modules, promoting DRY (Don't Repeat Yourself) principles.
- Decoupled Communication: Since these components are typical ROS nodes, they interact using ROS topics, services, and actions, ensuring loosely-coupled and scalable integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    LO["Launch Orchestrator"]:::orchestrator
    SD["Sensor Drivers – Hawk, Hesai, etc."]:::driver
    PA["Perception Algorithms – Lidar, VSLAM, Occupancy Mapping"]:::algorithm
    VT["Visualization/Tools – Foxglove, RViz"]:::visualization
    PC["Parameters & Configuration (YAMLs)"]:::params
    PU["Python Utilities"]:::utilities

    LO -->|"launches"| SD
    LO -->|"launches"| PA
    LO -->|"orchestrates"| VT
    SD -->|"dataFlow"| PA
    PA -->|"visualization"| VT
    PC -->|"configures"| SD
    PC -->|"configures"| PA
    PU -->|"supports"| SD
    PU -->|"supports"| PA

    click LO "https://github.com/nvidia-isaac-ros/isaac_perceptor/blob/main/isaac_ros_perceptor_bringup/launch/perceptor_general.launch.py"
    click SD "https://github.com/nvidia-isaac-ros/isaac_perceptor/tree/main/isaac_ros_perceptor_bringup/launch/drivers"
    click PA "https://github.com/nvidia-isaac-ros/isaac_perceptor/tree/main/isaac_ros_perceptor_bringup/launch/algorithms"
    click VT "https://github.com/nvidia-isaac-ros/isaac_perceptor/tree/main/isaac_ros_perceptor_bringup/launch/tools"
    click PC "https://github.com/nvidia-isaac-ros/isaac_perceptor/tree/main/isaac_ros_perceptor_bringup/params"
    click PU "https://github.com/nvidia-isaac-ros/isaac_perceptor/tree/main/isaac_ros_perceptor_python_utils"

    classDef orchestrator fill:#FDD835,stroke:#333,stroke-width:2px;
    classDef driver fill:#64B5F6,stroke:#333,stroke-width:2px;
    classDef algorithm fill:#81C784,stroke:#333,stroke-width:2px;
    classDef visualization fill:#BA68C8,stroke:#333,stroke-width:2px;
    classDef params fill:#FFD54F,stroke:#333,stroke-width:2px;
    classDef utilities fill:#4FC3F7,stroke:#333,stroke-width:2px;
```
