# digesaremarco/forest_semantic_navigation architecture

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

- Interactive diagram: https://gitdiagram.com/digesaremarco/forest_semantic_navigation
- Repository: https://github.com/digesaremarco/forest_semantic_navigation

## Overview

This repository implements traversability mapping and frontier-based navigation for a Spot robot. The main workflow accepts RGB-D frames and camera pose, runs SegFormer inference, builds a semantic point cloud, fuses observations into a grid, and computes traversability costs; a separate planning interface consumes a cost layer and robot pose to produce waypoints and decide when to replan. Calibration, frame pairing, visualization, and Spot extrinsics querying are additional capabilities. Relationships below follow the pipeline excerpts, SOURCE INDEX references, or explicit module descriptions; unsampled subsystem links are omitted where the caller is not shown.

Main entry points: [`pipeline/planning_pipeline.py`](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/pipeline/planning_pipeline.py) (Planning pipeline), [`pipeline/traversability_pipeline.py`](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/pipeline/traversability_pipeline.py) (Traversability pipeline), [`fusion/pointcloud_builder.py`](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/fusion/pointcloud_builder.py) (Point-cloud builder), [`mapping/grid_map.py`](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/mapping/grid_map.py) (Semantic grid map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_perception["Perception and fusion"]
  node_traversability["Traversability pipeline"]
  node_segformer["SegFormer inference"]
  node_class_reducer["Class reduction<br/>[class_reducer.py]"]
  node_pointcloud["Point-cloud builder"]
  node_calibration["Camera calibration"]
  node_frame_pairing["Frame pairing<br/>[frame_pairing.py]"]
  node_pose_pairing["Frame-pose pairing"]
  node_geometry["Geometry utilities<br/>[geometry_utils.py]"]
end

subgraph group_mapping["Mapping and costs"]
  node_grid[("Semantic grid map<br/>[grid_map.py]")]
  node_geometric["Geometric cost<br/>[geometric_cost.py]"]
  node_semantic["Semantic cost<br/>[semantic_cost.py]"]
  node_cost_fusion["Cost fusion<br/>[cost_fusion.py]"]
  node_traversability_config["Cost configuration"]
  node_grid_config["Grid configuration"]
  node_cost_layer["Traversability cost layer"]
end

subgraph group_navigation["Navigation planning"]
  node_planning_pipeline["Planning pipeline"]
  node_frontier_detector["Frontier detection"]
  node_frontier_refiner["Frontier refinement"]
  node_frontier_selector["Frontier selection"]
  node_obstacle_inflation["Obstacle inflation"]
  node_path_planner["A-star planner<br/>[path_planner.py]"]
  node_path_smoother["Path smoothing<br/>[path_smoother.py]"]
  node_waypoint_generator["Waypoint generation"]
  node_replanning["Replanning trigger"]
  node_blacklist["Target blacklist"]
  node_planning_config["Planning configuration"]
end

subgraph group_robot["Robot and diagnostics"]
  node_visualizer["Grid visualization"]
  node_planning_visualizer["Planning visualization"]
  node_spot_extrinsics["Spot extrinsics query"]
end

node_rgbd(("RGB-D frames"))
node_planning_input(("Cost and robot pose"))
node_waypoints["Waypoints"]

node_rgbd -->|"updates with"| node_traversability
node_traversability -->|"builds points"| node_pointcloud
node_pointcloud -->|"runs inference"| node_segformer
node_pointcloud -->|"reduces classes"| node_class_reducer
node_pointcloud -->|"reads parameters"| node_calibration
node_traversability -->|"constructs"| node_class_reducer
node_traversability -->|"fuses points"| node_grid
node_traversability -->|"computes cost"| node_geometric
node_traversability -.->|"computes cost"| node_semantic
node_traversability -->|"combines costs"| node_cost_fusion
node_grid -.->|"provides elevation"| node_geometric
node_grid -.->|"provides probabilities"| node_semantic
node_geometric -.->|"returns cost"| node_traversability
node_semantic -.->|"returns cost"| node_traversability
node_cost_fusion -->|"returns fused cost"| node_traversability
node_traversability -->|"provides layer"| node_cost_layer
node_planning_input -->|"plans with"| node_planning_pipeline
node_planning_pipeline -->|"detects frontiers"| node_frontier_detector
node_planning_pipeline -->|"refines frontiers"| node_frontier_refiner
node_planning_pipeline -->|"selects target"| node_frontier_selector
node_planning_pipeline -->|"inflates obstacles"| node_obstacle_inflation
node_planning_pipeline -->|"plans path"| node_path_planner
node_planning_pipeline -->|"smooths path"| node_path_smoother
node_planning_pipeline -->|"generates waypoints"| node_waypoint_generator
node_planning_pipeline -->|"checks replanning"| node_replanning
node_planning_pipeline -->|"manages targets"| node_blacklist
node_planning_pipeline -.->|"returns"| node_waypoints
node_frame_pairing -.->|"pairs frames"| node_pose_pairing
node_pose_pairing -->|"uses geometry"| node_geometry
node_pose_pairing -->|"reads calibration"| node_calibration
node_visualizer -->|"visualizes"| node_grid
node_planning_visualizer -->|"uses plots"| node_visualizer

click node_traversability "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/pipeline/traversability_pipeline.py"
click node_segformer "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/perception/segformer_inference.py"
click node_class_reducer "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/perception/class_reducer.py"
click node_pointcloud "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/fusion/pointcloud_builder.py"
click node_calibration "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/fusion/camera_calibration_loader.py"
click node_frame_pairing "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/fusion/frame_pairing.py"
click node_pose_pairing "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/fusion/frame_pose_pairing.py"
click node_geometry "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/fusion/geometry_utils.py"
click node_grid "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/mapping/grid_map.py"
click node_geometric "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/costmap/geometric_cost.py"
click node_semantic "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/costmap/semantic_cost.py"
click node_cost_fusion "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/costmap/cost_fusion.py"
click node_traversability_config "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/costmap/costmap_config_loader.py"
click node_grid_config "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/mapping/grid_map_config_loader.py"
click node_planning_pipeline "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/pipeline/planning_pipeline.py"
click node_frontier_detector "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/frontier_detector.py"
click node_frontier_refiner "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/frontier_refiner.py"
click node_frontier_selector "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/frontier_selector.py"
click node_obstacle_inflation "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/obstacle_inflation.py"
click node_path_planner "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/path_planner.py"
click node_path_smoother "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/path_smoother.py"
click node_waypoint_generator "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/waypoint_generator.py"
click node_replanning "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/replanning_trigger.py"
click node_blacklist "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/target_blacklist.py"
click node_planning_config "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/planning_config_loader.py"
click node_visualizer "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/mapping/grid_map_visualizer.py"
click node_planning_visualizer "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/planning_visualizer.py"
click node_spot_extrinsics "https://github.com/digesaremarco/forest_semantic_navigation/blob/master/spot/query_camera_extrinsics.py"

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_traversability,node_segformer,node_class_reducer,node_pointcloud,node_calibration,node_frame_pairing,node_pose_pairing,node_geometry toneBlue
class node_grid,node_geometric,node_semantic,node_cost_fusion,node_traversability_config,node_grid_config,node_cost_layer toneAmber
class node_planning_pipeline,node_frontier_detector,node_frontier_refiner,node_frontier_selector,node_obstacle_inflation,node_path_planner,node_path_smoother,node_waypoint_generator,node_replanning,node_blacklist,node_planning_config toneMint
class node_visualizer,node_planning_visualizer,node_spot_extrinsics toneRose
class node_rgbd,node_planning_input,node_waypoints toneIndigo
```

## Components

### Perception and fusion

- [Traversability pipeline](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/pipeline/traversability_pipeline.py): `pipeline/traversability_pipeline.py`
- [SegFormer inference](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/perception/segformer_inference.py): `perception/segformer_inference.py`
- [Class reduction](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/perception/class_reducer.py): `perception/class_reducer.py`
- [Point-cloud builder](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/fusion/pointcloud_builder.py): `fusion/pointcloud_builder.py`
- [Camera calibration](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/fusion/camera_calibration_loader.py): `fusion/camera_calibration_loader.py`
- [Frame pairing](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/fusion/frame_pairing.py): `fusion/frame_pairing.py`
- [Frame-pose pairing](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/fusion/frame_pose_pairing.py): `fusion/frame_pose_pairing.py`
- [Geometry utilities](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/fusion/geometry_utils.py): `fusion/geometry_utils.py`

### Mapping and costs

- [Semantic grid map](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/mapping/grid_map.py): `mapping/grid_map.py`
- [Geometric cost](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/costmap/geometric_cost.py): `costmap/geometric_cost.py`
- [Semantic cost](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/costmap/semantic_cost.py): `costmap/semantic_cost.py`
- [Cost fusion](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/costmap/cost_fusion.py): `costmap/cost_fusion.py`
- [Cost configuration](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/costmap/costmap_config_loader.py): `costmap/costmap_config_loader.py`
- [Grid configuration](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/mapping/grid_map_config_loader.py): `mapping/grid_map_config_loader.py`
- **Traversability cost layer**

### Navigation planning

- [Planning pipeline](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/pipeline/planning_pipeline.py): `pipeline/planning_pipeline.py`
- [Frontier detection](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/frontier_detector.py): `planning/frontier_detector.py`
- [Frontier refinement](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/frontier_refiner.py): `planning/frontier_refiner.py`
- [Frontier selection](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/frontier_selector.py): `planning/frontier_selector.py`
- [Obstacle inflation](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/obstacle_inflation.py): `planning/obstacle_inflation.py`
- [A-star planner](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/path_planner.py): `planning/path_planner.py`
- [Path smoothing](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/path_smoother.py): `planning/path_smoother.py`
- [Waypoint generation](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/waypoint_generator.py): `planning/waypoint_generator.py`
- [Replanning trigger](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/replanning_trigger.py): `planning/replanning_trigger.py`
- [Target blacklist](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/target_blacklist.py): `planning/target_blacklist.py`
- [Planning configuration](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/planning_config_loader.py): `planning/planning_config_loader.py`

### Robot and diagnostics

- [Grid visualization](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/mapping/grid_map_visualizer.py): `mapping/grid_map_visualizer.py`
- [Planning visualization](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/planning/planning_visualizer.py): `planning/planning_visualizer.py`
- [Spot extrinsics query](https://github.com/digesaremarco/forest_semantic_navigation/blob/master/spot/query_camera_extrinsics.py): `spot/query_camera_extrinsics.py`

### Other components

- **RGB-D frames**
- **Cost and robot pose**
- **Waypoints**

## Connections

- RGB-D frames → Traversability pipeline: updates with (evidence: `pipeline/traversability_pipeline.py`)
- Traversability pipeline → Point-cloud builder: builds points (evidence: `pipeline/traversability_pipeline.py`)
- Point-cloud builder → SegFormer inference: runs inference (evidence: `fusion/pointcloud_builder.py`)
- Point-cloud builder → Class reduction: reduces classes (evidence: `fusion/pointcloud_builder.py`)
- Point-cloud builder → Camera calibration: reads parameters (evidence: `fusion/pointcloud_builder.py`)
- Traversability pipeline → Class reduction: constructs (evidence: `pipeline/traversability_pipeline.py`)
- Traversability pipeline → Semantic grid map: fuses points (evidence: `pipeline/traversability_pipeline.py`)
- Traversability pipeline → Geometric cost: computes cost (evidence: `pipeline/traversability_pipeline.py`)
- Traversability pipeline → Semantic cost: computes cost (evidence: `pipeline/traversability_pipeline.py`)
- Traversability pipeline → Cost fusion: combines costs (evidence: `pipeline/traversability_pipeline.py`)
- Semantic grid map → Geometric cost: provides elevation
- Semantic grid map → Semantic cost: provides probabilities
- Geometric cost → Traversability pipeline: returns cost (evidence: `pipeline/traversability_pipeline.py`)
- Semantic cost → Traversability pipeline: returns cost (evidence: `pipeline/traversability_pipeline.py`)
- Cost fusion → Traversability pipeline: returns fused cost (evidence: `pipeline/traversability_pipeline.py`)
- Traversability pipeline → Traversability cost layer: provides layer (evidence: `pipeline/traversability_pipeline.py`)
- Cost and robot pose → Planning pipeline: plans with (evidence: `pipeline/planning_pipeline.py`)
- Planning pipeline → Frontier detection: detects frontiers (evidence: `pipeline/planning_pipeline.py`)
- Planning pipeline → Frontier refinement: refines frontiers (evidence: `pipeline/planning_pipeline.py`)
- Planning pipeline → Frontier selection: selects target (evidence: `pipeline/planning_pipeline.py`)
- Planning pipeline → Obstacle inflation: inflates obstacles (evidence: `pipeline/planning_pipeline.py`)
- Planning pipeline → A-star planner: plans path (evidence: `pipeline/planning_pipeline.py`)
- Planning pipeline → Path smoothing: smooths path (evidence: `pipeline/planning_pipeline.py`)
- Planning pipeline → Waypoint generation: generates waypoints (evidence: `pipeline/planning_pipeline.py`)
- Planning pipeline → Replanning trigger: checks replanning (evidence: `pipeline/planning_pipeline.py`)
- Planning pipeline → Target blacklist: manages targets (evidence: `pipeline/planning_pipeline.py`)
- Planning pipeline → Waypoints: returns
- Frame pairing → Frame-pose pairing: pairs frames
- Frame-pose pairing → Geometry utilities: uses geometry (evidence: `fusion/frame_pose_pairing.py`)
- Frame-pose pairing → Camera calibration: reads calibration (evidence: `fusion/frame_pose_pairing.py`)
- Grid visualization → Semantic grid map: visualizes (evidence: `mapping/grid_map_visualizer.py`)
- Planning visualization → Grid visualization: uses plots (evidence: `planning/planning_visualizer.py`)
