# zwandering/sysnav architecture

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

- Interactive diagram: https://gitdiagram.com/zwandering/sysnav
- Repository: https://github.com/zwandering/sysnav

## Overview

SysNav is a multi-level object-navigation system for a wheeled robot and Unity simulation on this branch. Its documented workflow is semantic guidance from vision-language models, room-based navigation, classical in-room exploration, and motion control. The tree also shows SLAM, perception, route-graph, autonomy, and simulation components. README statements support the high-level workflow; source excerpts do not expose wiring among most of these runtime components, so those connections are omitted rather than inferred.

Main entry points: [`src/exploration_planner/tare_planner`](https://github.com/zwandering/sysnav/tree/main/src/exploration_planner/tare_planner) (Room Exploration), [`src/base_autonomy/local_planner/src/localPlanner.cpp`](https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/local_planner/src/localPlanner.cpp) (Local Planner), [`src/semantic_mapping/semantic_mapping/single_object_new.py`](https://github.com/zwandering/sysnav/blob/main/src/semantic_mapping/semantic_mapping/single_object_new.py) (Semantic Mapping), [`src/vlm_node/vlm_node/vlm_reasoning_node.py`](https://github.com/zwandering/sysnav/blob/main/src/vlm_node/vlm_node/vlm_reasoning_node.py) (VLM Reasoning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_perception["Perception and Mapping"]
  node_slam["SLAM"]
  node_semantic_map["Semantic Mapping"]
  node_sam2["Video Segmentation"]
end

subgraph group_reasoning["Semantic Guidance"]
  node_vlm["VLM Reasoning"]
  node_keyboard["Keyboard Input<br/>[keyboard_input.py]"]
end

subgraph group_planning["Navigation Planning"]
  node_boundary["Boundary Graph"]
  node_graph_decoder["Graph Decoder<br/>[decoder_node.cpp]"]
  node_tare["Room Exploration"]
  node_viewpoints["Viewpoint Manager"]
end

subgraph group_autonomy["Motion and Autonomy"]
  node_terrain["Terrain Analysis"]
  node_terrain_ext["Extended Terrain"]
  node_local_planner["Local Planner<br/>[localPlanner.cpp]"]
  node_path_follower["Path Follower<br/>[pathFollower.cpp]"]
  node_waypoint["Waypoint Example"]
end

subgraph group_platform["Robot and Simulation"]
  node_vehicle["Vehicle Simulator"]
  node_visualization["Visualization Tools"]
end

node_operator(("Navigation Request"))
node_sensors(("Lidar and Camera"))
node_robot(("Wheeled Robot"))
node_unity(("Unity Simulation"))

node_operator -.->|"requests target"| node_vlm
node_sensors -.->|"provides scans"| node_slam
node_sensors -.->|"provides imagery"| node_semantic_map
node_semantic_map -.->|"uses segmentation"| node_sam2
node_vlm -->|"guides navigation"| node_tare
node_tare -->|"plans motion"| node_local_planner
node_local_planner -.->|"controls path"| node_path_follower
node_local_planner -.->|"drives robot"| node_robot
node_vehicle -.->|"simulates vehicle"| node_unity
node_tare -.->|"manages viewpoints"| node_viewpoints
node_boundary -.->|"extracts graph"| node_graph_decoder

click node_slam "https://github.com/zwandering/sysnav/blob/main/src/slam/arise_slam_mid360/include/arise_slam_mid360/LidarProcess/PointCloudStorage.h"
click node_semantic_map "https://github.com/zwandering/sysnav/blob/main/src/semantic_mapping/semantic_mapping/single_object_new.py"
click node_sam2 "https://github.com/zwandering/sysnav/blob/main/src/semantic_mapping/semantic_mapping/external/sam2/sam2/sam2_video_predictor.py"
click node_vlm "https://github.com/zwandering/sysnav/blob/main/src/vlm_node/vlm_node/vlm_reasoning_node.py"
click node_keyboard "https://github.com/zwandering/sysnav/blob/main/src/vlm_node/vlm_node/keyboard_input.py"
click node_boundary "https://github.com/zwandering/sysnav/blob/main/src/route_planner/boundary_handler/src/graph_extractor.cpp"
click node_graph_decoder "https://github.com/zwandering/sysnav/blob/main/src/route_planner/graph_decoder/src/decoder_node.cpp"
click node_tare "https://github.com/zwandering/sysnav/tree/main/src/exploration_planner/tare_planner"
click node_viewpoints "https://github.com/zwandering/sysnav/blob/main/src/exploration_planner/tare_planner/src/viewpoint_manager/viewpoint_manager.cpp"
click node_terrain "https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/terrain_analysis/src/terrainAnalysis.cpp"
click node_terrain_ext "https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/terrain_analysis_ext/src/terrainAnalysisExt.cpp"
click node_local_planner "https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/local_planner/src/localPlanner.cpp"
click node_path_follower "https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/local_planner/src/pathFollower.cpp"
click node_waypoint "https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/waypoint_example/src/waypointExample.cpp"
click node_vehicle "https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/vehicle_simulator/src/vehicleSimulator.cpp"
click node_visualization "https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/visualization_tools/src/visualizationTools.cpp"

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_slam,node_semantic_map,node_sam2 toneBlue
class node_vlm,node_keyboard toneAmber
class node_boundary,node_graph_decoder,node_tare,node_viewpoints,node_operator toneMint
class node_terrain,node_terrain_ext,node_local_planner,node_path_follower,node_waypoint toneRose
class node_vehicle,node_visualization,node_sensors,node_robot,node_unity toneIndigo
```

## Components

### Perception and Mapping

- [SLAM](https://github.com/zwandering/sysnav/blob/main/src/slam/arise_slam_mid360/include/arise_slam_mid360/LidarProcess/PointCloudStorage.h): `src/slam/arise_slam_mid360/include/arise_slam_mid360/LidarProcess/PointCloudStorage.h`
- [Semantic Mapping](https://github.com/zwandering/sysnav/blob/main/src/semantic_mapping/semantic_mapping/single_object_new.py): `src/semantic_mapping/semantic_mapping/single_object_new.py`
- [Video Segmentation](https://github.com/zwandering/sysnav/blob/main/src/semantic_mapping/semantic_mapping/external/sam2/sam2/sam2_video_predictor.py): `src/semantic_mapping/semantic_mapping/external/sam2/sam2/sam2_video_predictor.py`

### Semantic Guidance

- [VLM Reasoning](https://github.com/zwandering/sysnav/blob/main/src/vlm_node/vlm_node/vlm_reasoning_node.py): `src/vlm_node/vlm_node/vlm_reasoning_node.py`
- [Keyboard Input](https://github.com/zwandering/sysnav/blob/main/src/vlm_node/vlm_node/keyboard_input.py): `src/vlm_node/vlm_node/keyboard_input.py`

### Navigation Planning

- [Boundary Graph](https://github.com/zwandering/sysnav/blob/main/src/route_planner/boundary_handler/src/graph_extractor.cpp): `src/route_planner/boundary_handler/src/graph_extractor.cpp`
- [Graph Decoder](https://github.com/zwandering/sysnav/blob/main/src/route_planner/graph_decoder/src/decoder_node.cpp): `src/route_planner/graph_decoder/src/decoder_node.cpp`
- [Room Exploration](https://github.com/zwandering/sysnav/tree/main/src/exploration_planner/tare_planner): `src/exploration_planner/tare_planner`
- [Viewpoint Manager](https://github.com/zwandering/sysnav/blob/main/src/exploration_planner/tare_planner/src/viewpoint_manager/viewpoint_manager.cpp): `src/exploration_planner/tare_planner/src/viewpoint_manager/viewpoint_manager.cpp`

### Motion and Autonomy

- [Terrain Analysis](https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/terrain_analysis/src/terrainAnalysis.cpp): `src/base_autonomy/terrain_analysis/src/terrainAnalysis.cpp`
- [Extended Terrain](https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/terrain_analysis_ext/src/terrainAnalysisExt.cpp): `src/base_autonomy/terrain_analysis_ext/src/terrainAnalysisExt.cpp`
- [Local Planner](https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/local_planner/src/localPlanner.cpp): `src/base_autonomy/local_planner/src/localPlanner.cpp`
- [Path Follower](https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/local_planner/src/pathFollower.cpp): `src/base_autonomy/local_planner/src/pathFollower.cpp`
- [Waypoint Example](https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/waypoint_example/src/waypointExample.cpp): `src/base_autonomy/waypoint_example/src/waypointExample.cpp`

### Robot and Simulation

- [Vehicle Simulator](https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/vehicle_simulator/src/vehicleSimulator.cpp): `src/base_autonomy/vehicle_simulator/src/vehicleSimulator.cpp`
- [Visualization Tools](https://github.com/zwandering/sysnav/blob/main/src/base_autonomy/visualization_tools/src/visualizationTools.cpp): `src/base_autonomy/visualization_tools/src/visualizationTools.cpp`

### Other components

- **Navigation Request**
- **Lidar and Camera**
- **Wheeled Robot**
- **Unity Simulation**

## Connections

- Navigation Request → VLM Reasoning: requests target
- Lidar and Camera → SLAM: provides scans
- Lidar and Camera → Semantic Mapping: provides imagery
- Semantic Mapping → Video Segmentation: uses segmentation
- VLM Reasoning → Room Exploration: guides navigation
- Room Exploration → Local Planner: plans motion
- Local Planner → Path Follower: controls path
- Local Planner → Wheeled Robot: drives robot
- Vehicle Simulator → Unity Simulation: simulates vehicle
- Room Exploration → Viewpoint Manager: manages viewpoints (evidence: `src/exploration_planner/tare_planner/src/viewpoint_manager/viewpoint_manager.cpp`)
- Boundary Graph → Graph Decoder: extracts graph
