# socone-tintran/perception architecture

> Architecture diagram of the GitHub repository socone-tintran/perception, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/socone-tintran/perception
- Repository: https://github.com/socone-tintran/perception

## Overview

##### Main Components
a. Sensor input modules (although not directly in this repo, the modules process data from sensors such as lidar, radar, camera, and map information).
b. Core perception modules – each package (e.g., autoware_bytetrack, autoware_cluster_merger, autoware_compare_map_segmentation, autoware_ground_segmentation, etc.) represents a building block in the perception pipeline.
c. Data fusion and transformation nodes – packages such as autoware_image_projection_based_fusion, autoware_lidar_transfusion, and autoware_multi_object_tracker.
d. Object validation, tracking, and filtering – many packages offer filtering (e.g., occupancy grid map filters, noise filters), data association, and multi-object tracking.
e. Utility libraries – shared utilities such as in perception_utils and common include folders that coordinate message conversion, data synchronization, and more.

##### Relationships and Interactions
b. Subsequent branches for segmentation, clustering, object detection, instance segmentation, and fusion.
c. The outputs of these nodes are provided to trackers and object merger modules, with further processing like validation and filtering.
e. Additionally, configuration and launch directories indicate that the system is deployed using ROS launch files, so you may want to include an “orchestration layer” showing how the nodes are launched and interconnect.

##### Architectural Patterns and Principles
a. Modularity: Each package is self-contained with its own configuration, libraries, schema, and tests. This emphasizes a microservices-like architecture.
c. Separation of concerns: Different packages handle specific tasks (e.g., segmentation vs. tracking vs. fusion vs. noise filtering). This separation is key in the design.
d. Extensibility and configuration-driven paradigms: Many packages include param.yaml, schema files, and launch files. Note these as dynamic configuration and design-time plug points.

##### Additional Guidance
a. A high-level view (sensor inputs → preprocessing → perception modules → fusion/tracking → output) and then add layers of detail about which package provides which functionality.

## Diagram (Mermaid)

```mermaid
graph TD
    Orchestration["Orchestration & Launch (ROS Launch Files)"]:::orchestration
    Utility["Utility Libraries (perception_utils & commons)"]:::utility
    SensorInputs["Sensor Inputs (Camera, LiDAR, Radar, Map)"]:::sensor

    %% Preprocessing Modules
    EuclideanCluster["Euclidean Cluster (autoware_euclidean_cluster)"]:::preprocess
    RadarCluster["Radar Object Clustering (autoware_radar_object_clustering)"]:::preprocess
    MapSegmentation["Map-Based Segmentation (autoware_compare_map_segmentation)"]:::segmentation
    GroundSegmentation["Ground Segmentation (autoware_ground_segmentation)"]:::segmentation
    PreprocOut["Preprocessed Sensor Data"]:::preprocess

    %% Data Fusion and Transformation
    ImageProjectionFusion["Image Projection Fusion (autoware_image_projection_based_fusion)"]:::fusion
    LidarTransfusion["Lidar Transfusion (autoware_lidar_transfusion)"]:::fusion
    RadarFusion["Radar Fusion to Detected Object (autoware_radar_fusion_to_detected_object)"]:::fusion
    FusionOut["Fused Object Data"]:::fusion

    %% Object Validation, Filtering and Association
    DetectedValidation["Detected Object Validation (autoware_detected_object_validation)"]:::validation
    ObjectMerger["Object Merger (autoware_object_merger)"]:::validation
    ObjectRangeSplitter["Object Range Splitter (autoware_object_range_splitter)"]:::validation
    ValidationOut["Validated Object Data"]:::validation

    %% Multi-Object Tracking and Data Association
    Bytetrack["Bytetrack (autoware_bytetrack)"]:::tracking
    MultiObjectTracker["Multi-Object Tracker (autoware_multi_object_tracker)"]:::tracking
    RadarTracker["Radar Object Tracker (autoware_radar_object_tracker)"]:::tracking
    TrackingOut["Final Tracked Objects"]:::tracking

    %% Orchestration connections
    Orchestration -->|"launch"| SensorInputs
    Orchestration -->|"launch"| PreprocOut
    Orchestration -->|"launch"| FusionOut
    Orchestration -->|"launch"| ValidationOut
    Orchestration -->|"launch"| TrackingOut

    %% Utility support
    Utility -->|"libs"| PreprocOut

    %% Sensor Input to Preprocessing Modules
    SensorInputs --> EuclideanCluster
    SensorInputs --> RadarCluster
    SensorInputs --> MapSegmentation
    SensorInputs --> GroundSegmentation

    %% Preprocessing Modules to Aggregator
    EuclideanCluster --> PreprocOut
    RadarCluster --> PreprocOut
    MapSegmentation --> PreprocOut
    GroundSegmentation --> PreprocOut

    %% Preprocessed data to Data Fusion Modules
    PreprocOut --> ImageProjectionFusion
    PreprocOut --> LidarTransfusion
    PreprocOut --> RadarFusion

    %% Data Fusion Modules to Fusion Aggregator
    ImageProjectionFusion --> FusionOut
    LidarTransfusion --> FusionOut
    RadarFusion --> FusionOut

    %% Fusion Data to Object Validation Modules
    FusionOut --> DetectedValidation
    FusionOut --> ObjectMerger
    FusionOut --> ObjectRangeSplitter

    %% Object Validation to Aggregator
    DetectedValidation --> ValidationOut
    ObjectMerger --> ValidationOut
    ObjectRangeSplitter --> ValidationOut

    %% Validation Data to Tracking Modules
    ValidationOut --> Bytetrack
    ValidationOut --> MultiObjectTracker
    ValidationOut --> RadarTracker

    %% Tracking Modules to Final Output
    Bytetrack --> TrackingOut
    MultiObjectTracker --> TrackingOut
    RadarTracker --> TrackingOut

    %% Click Events
    click EuclideanCluster "https://github.com/socone-tintran/perception/blob/main/autoware_euclidean_cluster/src/euclidean_cluster_node.cpp"
    click RadarCluster "https://github.com/socone-tintran/perception/blob/main/autoware_radar_object_clustering/src/radar_object_clustering_node.cpp"
    click MapSegmentation "https://github.com/socone-tintran/perception/blob/main/autoware_compare_map_segmentation/src/compare_elevation_map_filter/node.cpp"
    click GroundSegmentation "https://github.com/socone-tintran/perception/blob/main/autoware_ground_segmentation/src/ransac_ground_filter/node.cpp"
    click ImageProjectionFusion "https://github.com/socone-tintran/perception/blob/main/autoware_image_projection_based_fusion/src/fusion_node.cpp"
    click LidarTransfusion "https://github.com/socone-tintran/perception/blob/main/autoware_lidar_transfusion/src/lidar_transfusion_node.cpp"
    click RadarFusion "https://github.com/socone-tintran/perception/blob/main/autoware_radar_fusion_to_detected_object/src/node.cpp"
    click DetectedValidation "https://github.com/socone-tintran/perception/blob/main/autoware_detected_object_validation/src/lanelet_filter/lanelet_filter.cpp"
    click ObjectMerger "https://github.com/socone-tintran/perception/blob/main/autoware_object_merger/src/object_association_merger_node.cpp"
    click ObjectRangeSplitter "https://github.com/socone-tintran/perception/blob/main/autoware_object_range_splitter/src/object_range_splitter_node.cpp"
    click Bytetrack "https://github.com/socone-tintran/perception/blob/main/autoware_bytetrack/src/bytetrack_node.cpp"
    click MultiObjectTracker "https://github.com/socone-tintran/perception/blob/main/autoware_multi_object_tracker/src/multi_object_tracker_node.cpp"
    click RadarTracker "https://github.com/socone-tintran/perception/blob/main/autoware_radar_object_tracker/src/radar_object_tracker_node.cpp"
    click Utility "https://github.com/socone-tintran/perception/blob/main/perception_utils/include/perception_utils/prime_synchronizer.hpp"
    click Orchestration "https://github.com/socone-tintran/perception/blob/main/autoware_bytetrack/launch/bytetrack.launch.xml"

    %% Styles
    classDef sensor fill:#FAD,stroke:#333,stroke-width:2px;
    classDef preprocess fill:#BBF,stroke:#333,stroke-width:2px;
    classDef segmentation fill:#AAF,stroke:#333,stroke-width:2px;
    classDef fusion fill:#AFA,stroke:#333,stroke-width:2px;
    classDef validation fill:#FFA,stroke:#333,stroke-width:2px;
    classDef tracking fill:#FAB,stroke:#333,stroke-width:2px;
    classDef utility fill:#EEF,stroke:#333,stroke-width:2px;
    classDef orchestration fill:#DDD,stroke:#333,stroke-width:2px;
```
