# dcmlr/groundgrid architecture

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

- Interactive diagram: https://gitdiagram.com/dcmlr/groundgrid
- Repository: https://github.com/dcmlr/groundgrid

## Overview

##### Project Type and Purpose
- This is a ROS (Robot Operating System) perception package (“groundgrid”) written in C++ and Python.

##### High-Level Architecture
- ROS Master: the central coordinator for topics, services, and parameters.
- Data Ingestion
- scripts/kitti_data_publisher.py – “KITTIPlayback” node: reads raw Velodyne packets or point clouds, publishes sensor_msgs/PointCloud2 on /velodyne_points.
- Processing
- Nodelet Manager (one container process; see nodelet_plugins.xml)
– groundgrid/GroundGridNodelet: subscribes to /velodyne_points, runs GroundGrid::segment() & GroundSegmentation modules, publishes:
· segmented point clouds (ground vs. nonground)
· grid_map_msgs/GridMap (terrain elevation map)
– groundgrid/GroundGridNode (standalone node alternative)
- Dynamic Reconfigure Server: enables runtime tuning of segmentation parameters.
- Service Server: NextCloud.srv – allows external nodes/scripts to request the next segmented cloud on demand.
- Visualization
- grid_map_rviz_plugin for visualizing 2D grid maps.
- Evaluation & Utilities
- scripts/eval_groundpoint_classifier.py – “KITTIEvaluate” node: replays clouds, collects classification stats, prints metrics.
- launch files (launch/*.launch): groups nodes, sets ROS params, ties in dynamic_reconfigure, directs topics to RViz or evaluation script.

##### Components & Interactions
[KITTI Publisher Node]  →  publishes “/velodyne_points”
[Nodelet Manager]
├─ [GroundGridNodelet]
│     • subscribes “/velodyne_points”
│     • calls GroundGrid/ GroundSegmentation libraries
│     • publishes “/ground_points” & “/grid_map”
│     • offers “NextCloud” service
└─ [Dynamic Reconfigure Server]
- External scripts/nodes may call the NextCloud service or subscribe to output topics.
- RViz: subscribes to outputs, displays point clouds and grid map overlays.
- Evaluation script: subscribes to same topics, logs metrics.

##### Architectural Patterns & Design Principles
- Nodelet plugin pattern (zero-copy intra-process transport).
- Clear separation: Data Ingestion → Processing → Visualization/Evaluation.
- Service-oriented for on-demand processing.
- Dynamic reconfigure for runtime parameter tuning.
- Uses grid_map for 2D terrain representation, PCL for point processing, cv_bridge for image conversions if needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion
    KP["KITTIPlayback Node"]:::ingest
    click KP "https://github.com/dcmlr/groundgrid/blob/main/scripts/kitti_data_publisher.py"
    VP[("/velodyne_points\nsensor_msgs/PointCloud2")]:::data

    KP -->|"publishes"| VP

    %% Processing Layer
    subgraph "Nodelet Manager"
        direction TB
        NGNodelet["GroundGridNodelet"]:::process
        click NGNodelet "https://github.com/dcmlr/groundgrid/blob/main/src/GroundGridNodelet.cpp"
        DynamicReconf["Dynamic Reconfigure\nServer"]:::process
        click DynamicReconf "https://github.com/dcmlr/groundgrid/blob/main/cfg/GroundGrid.cfg"
        GGridCPP["GroundGrid Algorithm"]:::process
        click GGridCPP "https://github.com/dcmlr/groundgrid/blob/main/src/GroundGrid.cpp"
        GSegCPP["GroundSegmentation Module"]:::process
        click GSegCPP "https://github.com/dcmlr/groundgrid/blob/main/src/GroundSegmentation.cpp"
    end

    %% Standalone Node Alternative
    GGNode["GroundGridNode\n(standalone)"]:::process
    click GGNode "https://github.com/dcmlr/groundgrid/blob/main/src/GroundGridNode.cpp"

    %% Topics and Service
    GP[("/ground_points\nsensor_msgs/PointCloud2")]:::data
    GM[("/grid_map\ngrid_map_msgs/GridMap")]:::data
    NextCloudSrv["NextCloud Service"]:::data
    click NextCloudSrv "https://github.com/dcmlr/groundgrid/blob/main/srv/NextCloud.srv"

    %% Visualization & Evaluation
    RViz["RViz"]:::viz
    click RViz "https://github.com/dcmlr/groundgrid/blob/main/rviz/groundgrid.rviz"
    Eval["KITTIEvaluate Node"]:::eval
    click Eval "https://github.com/dcmlr/groundgrid/blob/main/scripts/eval_groundpoint_classifier.py"

    %% Flows for Nodelet
    VP --> NGNodelet
    NGNodelet -->|"publishes"| GP
    NGNodelet -->|"publishes"| GM
    NGNodelet -->|"offers"| NextCloudSrv
    NGNodelet --> GGridCPP
    NGNodelet --> GSegCPP
    DynamicReconf --> NGNodelet

    %% Flows for Standalone Node
    VP --> GGNode
    GGNode -->|"publishes"| GP
    GGNode -->|"publishes"| GM
    GGNode -->|"offers"| NextCloudSrv

    %% Visualization/Evaluation flows
    GP --> RViz
    GM --> RViz
    GP --> Eval
    GM --> Eval

    %% Legend
    subgraph Legend
        direction TB
        I["Data Ingestion Nodes"]:::ingest
        P["Processing Nodes/Plugins"]:::process
        D["Topics/Services"]:::data
        V["Visualization Nodes"]:::viz
        E["Evaluation Nodes"]:::eval
    end

    %% Styling
    classDef ingest fill:#b7e4c7,stroke:#2d6a4f,color:#073b4c;
    classDef process fill:#caf0f8,stroke:#0077b6,color:#03045e;
    classDef data fill:#ffec99,stroke:#ffba08,color:#92400e;
    classDef viz fill:#f3c4fb,stroke:#9d4edd,color:#5a189a;
    classDef eval fill:#ffc9c9,stroke:#d00000,color:#9b2226;
```
