# gmoustri/dwal_planner architecture

> Architecture diagram of the GitHub repository gmoustri/dwal_planner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gmoustri/dwal_planner
- Repository: https://github.com/gmoustri/dwal_planner

## Overview

DWAL Planner is a ROS 2 motion-cluster generator. Odometry and an occupancy grid feed trajectory sampling: admissible curved paths are simulated against the costmap, then published as sampled paths and markers. A clustering node groups free paths by configured level and publishes cluster groups and visualizations; it also supports level toggles and directional slicing. The graph distinguishes the trajectory-generation library from its ROS orchestration. Generator-to-clustering transport is documented in the README; source excerpts show costmap conversion, sampling, and clustering behavior. Service wiring is documented but not visible in the excerpts.

Main entry points: [`src/trajectory_generator.cpp`](https://github.com/gmoustri/dwal_planner/blob/main/src/trajectory_generator.cpp) (Generator Node), [`src/clustering.cpp`](https://github.com/gmoustri/dwal_planner/blob/main/src/clustering.cpp) (Level Clustering), [`include/dwal_planner/libdwal_cluster.h`](https://github.com/gmoustri/dwal_planner/blob/main/include/dwal_planner/libdwal_cluster.h) (Costmap Adapter), [`src/libdwal_cluster.cpp`](https://github.com/gmoustri/dwal_planner/blob/main/src/libdwal_cluster.cpp) (Trajectory Sampler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Robot Inputs"]
end

subgraph group_generation["Trajectory Generation"]
  node_generator["Generator Node"]
  node_costmap["Costmap Adapter<br/>[libdwal_cluster.h]"]
  node_trajectory["Trajectory Sampler"]
end

subgraph group_clustering["Path Clustering"]
  node_cluster_node["Clustering Node<br/>[clustering.cpp]"]
  node_cluster_logic["Level Clustering<br/>[clustering.cpp]"]
  node_slice["Directional Slicing<br/>[clustering.cpp]"]
end

subgraph group_interfaces["ROS Interfaces"]
  node_sampled["Sampled Paths<br/>[SampledCluster.msg]"]
  node_path_markers["Path Markers"]
  node_cluster_groups["Motion Clusters<br/>[ClusterGroup.msg]"]
  node_cluster_markers["Cluster Markers<br/>[clustering.cpp]"]
  node_level_toggle["Level Toggle<br/>[ToggleClusters.srv]"]
  node_slice_toggle["Slice Toggle<br/>[ToggleSlice.srv]"]
end

node_robot(("Robot Odometry"))
node_occupancy(("Occupancy Grid"))
node_service_caller(("Service Caller"))

node_robot -->|"supplies odometry"| node_generator
node_occupancy -->|"updates grid"| node_costmap
node_generator -->|"subscribes via"| node_costmap
node_generator -->|"initializes and samples"| node_trajectory
node_trajectory -->|"checks collisions"| node_costmap
node_generator -->|"publishes paths"| node_sampled
node_generator -->|"publishes markers"| node_path_markers
node_sampled -->|"delivers path bundle"| node_cluster_node
node_cluster_node -->|"runs per level"| node_cluster_logic
node_cluster_logic -->|"publishes groups"| node_cluster_groups
node_cluster_logic -->|"publishes visualization"| node_cluster_markers
node_cluster_logic -->|"applies slicing"| node_slice
node_service_caller -->|"requests toggle"| node_level_toggle
node_service_caller -->|"requests toggle"| node_slice_toggle
node_level_toggle -.->|"controls levels"| node_cluster_node
node_slice_toggle -.->|"controls slicing"| node_slice

click node_generator "https://github.com/gmoustri/dwal_planner/blob/main/src/trajectory_generator.cpp"
click node_costmap "https://github.com/gmoustri/dwal_planner/blob/main/include/dwal_planner/libdwal_cluster.h"
click node_trajectory "https://github.com/gmoustri/dwal_planner/blob/main/src/libdwal_cluster.cpp"
click node_sampled "https://github.com/gmoustri/dwal_planner/blob/main/msg/SampledCluster.msg"
click node_path_markers "https://github.com/gmoustri/dwal_planner/blob/main/src/trajectory_generator.cpp"
click node_cluster_node "https://github.com/gmoustri/dwal_planner/blob/main/src/clustering.cpp"
click node_cluster_logic "https://github.com/gmoustri/dwal_planner/blob/main/src/clustering.cpp"
click node_slice "https://github.com/gmoustri/dwal_planner/blob/main/src/clustering.cpp"
click node_cluster_groups "https://github.com/gmoustri/dwal_planner/blob/main/msg/ClusterGroup.msg"
click node_cluster_markers "https://github.com/gmoustri/dwal_planner/blob/main/src/clustering.cpp"
click node_level_toggle "https://github.com/gmoustri/dwal_planner/blob/main/srv/ToggleClusters.srv"
click node_slice_toggle "https://github.com/gmoustri/dwal_planner/blob/main/srv/ToggleSlice.srv"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_generator,node_costmap,node_trajectory toneAmber
class node_cluster_node,node_cluster_logic,node_slice toneMint
class node_sampled,node_path_markers,node_cluster_groups,node_cluster_markers,node_level_toggle,node_slice_toggle toneRose
class node_robot,node_occupancy,node_service_caller toneIndigo
```

## Components

### Trajectory Generation

- [Generator Node](https://github.com/gmoustri/dwal_planner/blob/main/src/trajectory_generator.cpp): `src/trajectory_generator.cpp`
- [Costmap Adapter](https://github.com/gmoustri/dwal_planner/blob/main/include/dwal_planner/libdwal_cluster.h): `include/dwal_planner/libdwal_cluster.h`
- [Trajectory Sampler](https://github.com/gmoustri/dwal_planner/blob/main/src/libdwal_cluster.cpp): `src/libdwal_cluster.cpp`

### Path Clustering

- [Clustering Node](https://github.com/gmoustri/dwal_planner/blob/main/src/clustering.cpp): `src/clustering.cpp`
- [Level Clustering](https://github.com/gmoustri/dwal_planner/blob/main/src/clustering.cpp): `src/clustering.cpp`
- [Directional Slicing](https://github.com/gmoustri/dwal_planner/blob/main/src/clustering.cpp): `src/clustering.cpp`

### ROS Interfaces

- [Sampled Paths](https://github.com/gmoustri/dwal_planner/blob/main/msg/SampledCluster.msg): `msg/SampledCluster.msg`
- [Path Markers](https://github.com/gmoustri/dwal_planner/blob/main/src/trajectory_generator.cpp): `src/trajectory_generator.cpp`
- [Motion Clusters](https://github.com/gmoustri/dwal_planner/blob/main/msg/ClusterGroup.msg): `msg/ClusterGroup.msg`
- [Cluster Markers](https://github.com/gmoustri/dwal_planner/blob/main/src/clustering.cpp): `src/clustering.cpp`
- [Level Toggle](https://github.com/gmoustri/dwal_planner/blob/main/srv/ToggleClusters.srv): `srv/ToggleClusters.srv`
- [Slice Toggle](https://github.com/gmoustri/dwal_planner/blob/main/srv/ToggleSlice.srv): `srv/ToggleSlice.srv`

### Other components

- **Robot Odometry**
- **Occupancy Grid**
- **Service Caller**

## Connections

- Robot Odometry → Generator Node: supplies odometry (evidence: `src/trajectory_generator.cpp`)
- Occupancy Grid → Costmap Adapter: updates grid (evidence: `include/dwal_planner/libdwal_cluster.h`)
- Generator Node → Costmap Adapter: subscribes via (evidence: `src/trajectory_generator.cpp`)
- Generator Node → Trajectory Sampler: initializes and samples (evidence: `src/trajectory_generator.cpp`)
- Trajectory Sampler → Costmap Adapter: checks collisions (evidence: `src/libdwal_cluster.cpp`)
- Generator Node → Sampled Paths: publishes paths (evidence: `src/trajectory_generator.cpp`)
- Generator Node → Path Markers: publishes markers (evidence: `src/trajectory_generator.cpp`)
- Sampled Paths → Clustering Node: delivers path bundle (evidence: `README.md`)
- Clustering Node → Level Clustering: runs per level (evidence: `src/clustering.cpp`)
- Level Clustering → Motion Clusters: publishes groups (evidence: `src/clustering.cpp`)
- Level Clustering → Cluster Markers: publishes visualization (evidence: `src/clustering.cpp`)
- Level Clustering → Directional Slicing: applies slicing (evidence: `src/clustering.cpp`)
- Service Caller → Level Toggle: requests toggle (evidence: `README.md`)
- Service Caller → Slice Toggle: requests toggle (evidence: `README.md`)
- Level Toggle → Clustering Node: controls levels (evidence: `README.md`)
- Slice Toggle → Directional Slicing: controls slicing (evidence: `README.md`)