# unmannedlab/g-vom architecture

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

- Interactive diagram: https://gitdiagram.com/unmannedlab/g-vom
- Repository: https://github.com/unmannedlab/g-vom

## Overview

##### Project Type and Purpose
- This is a ROS-based Python package for GPU-accelerated off-road 3D voxel mapping using pointcloud data from lidar sensors.
- The primary purpose is to process pointcloud inputs (from sensors on vehicles) into a voxel representation, eventually generating 2D maps for navigation (including obstacle and roughness maps).

##### Analyzing the File Structure
- Top-level files like CMakeLists.txt, package.xml, and LICENSE are typical of a ROS package.
- The “scripts” directory contains the core Python files:
- gvom.py: Contains the main class with functions to process pointclouds, maintain a mapping buffer, and combine maps.
- gvom_ros.py: Provides an example ROS implementation dealing with subscriptions from PointCloud2 and Odometry topics.
- The “launch” directory includes a launch file (gvom_node.launch) to start the ROS node.
- “images” holds example outputs and reference images for documentation purposes.
- Other files such as .gitignore and README.md support development and documentation.

##### Insights from the README
- The README details the usage, prerequisites (Python 3, ROS Noetic, Numba CUDA for GPU acceleration), and function descriptions.
- It highlights the two primary functions: process_pointcloud and combine_maps, emphasizing that the mapping is designed for asynchronous processing.

##### Main Components
a. Data Ingestion & Interface:
- ROS Node (gvom_ros.py) that subscribes to sensor topics (PointCloud2 and Odometry) and manages the tf tree.
- The ROS launch file (gvom_node.launch) to initiate the node.
b. Core Mapping Engine:
- The G-VOM Class defined in gvom.py, which includes:
- Initialization (setting up mapping parameters and connections to GPU processing via Numba CUDA)
- Process_Pointcloud functionality: Converts pointcloud data into a 3D voxel map.
- Combine_Maps functionality: Merges buffered maps into 2D output maps.
- A mapping buffer to collect intermediate voxel maps (supporting asynchronous calls and multiple sensors).
c. GPU Acceleration:
- Integration with Numba CUDA for high-performance computation.
- This component should be annotated to indicate that the intensive data processing (e.g., 3D array lookup and voxel computations) is offloaded to the GPU.
d. External Technologies and Frameworks:
- ROS Noetic for message passing and real-time integration.
- Python 3, with dependencies on Numba and CUDA for GPU operations.
- Underlying sensor integration (e.g., Ouster lidars) indicated in the README.

##### Relationships and Flow
- Data flows from the sensor inputs (external, through ROS subscribers) → into the ROS Node (gvom_ros.py).
- The ROS node passes the data to the G-VOM class’s process_pointcloud function.
- Processed data is stored within an internal mapping buffer and, when requested, combined by combine_maps into output maps.
- The output maps (e.g., positive/negative obstacles, roughness) are then either published via ROS or used internally for navigation and off-road planning.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Distinguish between the ROS interface (handling message subscriptions, transformations, and launch initialization) and the core mapping algorithm.
- GPU Offloading: Clearly mark the GPU processing section (Numba CUDA enabled functions) to highlight performance-critical operations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Interface
    subgraph "Data Ingestion & Interface"
        RL["ROS Launch (gvom_node.launch)"]:::ros
        RN["ROS Node (gvom_ros.py)"]:::ros
    end

    %% Mapping & Processing
    subgraph "Mapping & Processing"
        ME["Mapping Engine (gvom.py)"]:::engine
        GPU["GPU Processing (Numba CUDA)"]:::gpu
        MB["Mapping Buffer"]:::buffer
        OM["2D Output Maps"]:::output
    end

    %% External Sensor Input
    Sensor["Sensor Data Input"]:::sensor

    %% Data Flow
    Sensor -->|"subscribe"| RN
    RL -->|"start"| RN
    RN -->|"calls_process_pointcloud"| ME
    ME -->|"offloads_tasks"| GPU
    ME -->|"stores_voxels_async"| MB
    MB -->|"combines_data"| ME
    ME -->|"produces_maps"| OM

    %% Click Events
    click RN "https://github.com/unmannedlab/g-vom/blob/main/scripts/gvom_ros.py"
    click ME "https://github.com/unmannedlab/g-vom/blob/main/scripts/gvom.py"
    click RL "https://github.com/unmannedlab/g-vom/blob/main/launch/gvom_node.launch"

    %% Styles
    classDef sensor fill:#AED6F1,stroke:#000,stroke-width:2px;
    classDef ros fill:#F5B041,stroke:#000,stroke-width:2px;
    classDef engine fill:#82E0AA,stroke:#000,stroke-width:2px;
    classDef gpu fill:#F1948A,stroke:#000,stroke-width:2px;
    classDef buffer fill:#D2B4DE,stroke:#000,stroke-width:2px;
    classDef output fill:#F7DC6F,stroke:#000,stroke-width:2px;
```
