# luxonis/depthai-ros architecture

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

- Interactive diagram: https://gitdiagram.com/luxonis/depthai-ros
- Repository: https://github.com/luxonis/depthai-ros

## Overview

##### Project Type and Purpose
- This is a full ROS integration suite for DepthAI cameras.
- It includes hardware drivers, message definitions, data converters (bridges), URDF (description) files, example nodes, and various filters.
- The repository’s purpose is to provide a comprehensive ecosystem for interfacing OAK cameras with ROS, handling image, sensor, and detection data for robotics applications.

##### File Structure to Identify Main Components
- Multiple ROS packages exist as separate directories:
- depthai_ros_driver: Handles the communication with the hardware (camera) and manages sensor data streaming and pipeline generation.
- depthai_bridge: Contains converters that translate or adapt DepthAI outputs into ROS messages (publishing interfaces).
- depthai_ros_msgs: Defines custom ROS messages and services (topic formats, etc.) used for communication between nodes.
- depthai_descriptions: Provides URDF/xacro files and launch scripts for representing the physical configuration and mounting of cameras.
- depthai_examples: Offers sample launch files and nodes to demonstrate how to operate the system.
- depthai_filters: Implements filtering and processing for image/sensor data (e.g., overlays, segmentation).
- depthai-ros: Likely the high-level package that could bring together various components or provide additional integrations.
- Review the README which further confirms that this repository is dedicated to ROS-related code for DepthAI cameras.

##### Relationships and Data Flows
- Hardware (OAK cameras) is the starting point. The cameras provide raw sensor data.
- The depthai_ros_driver interacts directly with the camera hardware. It handles parameters (calibration, camera configuration) and launches nodes for image/sensor acquisition.
- The received sensor data is then processed by the depthai_bridge. Its converters (image, disparity, imu, etc.) transform the raw data into ROS-standard formats.
- Custom message definitions in depthai_ros_msgs ensure a consistent communication protocol between these nodes and any other ROS application nodes.
- Additional processing or enhancements may be applied by components in depthai_filters, which take incoming data and run overlays, segmentation, or apply other filters.
- The depthai_descriptions package provides URDF files that allow for integration into a robot model, and the launch files in both the descriptions and examples packages configure the runtime behavior.
- The depthai_examples package demonstrates how various modules interact and can be used for testing and educational purposes.

- A “Custom Messages” block (depthai_ros_msgs) that is used by both the driver and the bridge for consistency in data formats.
- A “Filters & Processing” component (depthai_filters) that optionally processes filtered data.
- An “URDF & Descriptions” block (depthai_descriptions) that ties into both simulation and physical integration by providing the robot model information.

##### Architectural Patterns and Technologies
- ROS node architecture—each package runs as one or more executables that communicate via published and subscribed topics.
- That many components follow the publisher/subscriber and service patterns common in ROS.
- Use of configuration files (YAML, launch scripts, package.xml) as essential for managing parameters and runtime settings.
- Mention that the system uses standard C++ (and possibly Python for some scripts) and is built using CMake, as seen by the presence of CMakeLists.txt across packages.
- The repository also includes CI/CD configuration files (.github/workflows) and containerized development support (.devcontainer), indicating modern development practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Hardware Layer
    HW["OAK Camera Hardware"]:::hardware

    %% Data Acquisition Layer
    subgraph "Data Acquisition Layer"
        RD["depthai_ros_driver - Sensor acquisition & pipeline management"]:::driver
    end

    %% Bridge & Message Processing Layer
    subgraph "Processing Layer"
        BR["depthai_bridge - ROS message converters"]:::bridge
        MS["depthai_ros_msgs - Custom messages & service definitions"]:::messages
        FL["depthai_filters - Filtering & processing"]:::filters
    end

    %% Description & Example Layer
    subgraph "Application & Integration Layer"
        DS["depthai_descriptions - URDF and robot descriptions"]:::descriptions
        EX["depthai_examples - Example applications and demo nodes"]:::examples
        HL["depthai-ros - High-level integration"]:::integration
    end

    %% Data Flow Connections
    HW -->|"rawSensorData"| RD
    RD -->|"processedData"| BR
    BR -->|"convertedMessages"| MS
    BR -->|"filteredData"| FL
    FL -->|"enhancedData"| MS
    RD -->|"cameraConfig"| DS
    MS -->|"consumedData"| EX
    DS -->|"integrationInfo"| EX

    %% High-Level Integration Connections
    RD -->|"integrationLink"| HL
    BR -->|"integrationLink"| HL
    MS -->|"integrationLink"| HL
    FL -->|"integrationLink"| HL
    DS -->|"integrationLink"| HL
    EX -->|"integrationLink"| HL
    HL -->|"UnifiedInterface"| EX

    %% Click Events for Component Mapping
    click RD "https://github.com/luxonis/depthai-ros/tree/humble/depthai_ros_driver/"
    click BR "https://github.com/luxonis/depthai-ros/tree/humble/depthai_bridge/"
    click MS "https://github.com/luxonis/depthai-ros/tree/humble/depthai_ros_msgs/"
    click FL "https://github.com/luxonis/depthai-ros/tree/humble/depthai_filters/"
    click DS "https://github.com/luxonis/depthai-ros/tree/humble/depthai_descriptions/"
    click EX "https://github.com/luxonis/depthai-ros/tree/humble/depthai_examples/"
    click HL "https://github.com/luxonis/depthai-ros/tree/humble/depthai-ros/"

    %% Class Definitions for Styles
    classDef hardware fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef driver fill:#66CCFF,stroke:#333,stroke-width:2px;
    classDef bridge fill:#66FF66,stroke:#333,stroke-width:2px;
    classDef messages fill:#FF99CC,stroke:#333,stroke-width:2px;
    classDef filters fill:#CCCCFF,stroke:#333,stroke-width:2px;
    classDef descriptions fill:#FF9966,stroke:#333,stroke-width:2px;
    classDef examples fill:#99FF99,stroke:#333,stroke-width:2px;
    classDef integration fill:#DDA0DD,stroke:#333,stroke-width:2px;
```
