# we-autopilot/mapping-and-localization architecture

> Architecture diagram of the GitHub repository we-autopilot/mapping-and-localization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/we-autopilot/mapping-and-localization
- Repository: https://github.com/we-autopilot/mapping-and-localization

## Overview

This ROS 2 repository provides a bare-minimum mapping and localization pipeline: perception data is republished with short-term lane-boundary fallback, while optional Kitware SLAM outputs are bridged into AP1 localization and map outputs. A separate in-memory point registry serves planning/mapping clients. The README documents these capabilities; sampled source confirms the perception, SLAM bridge, map bridge, and registry behavior. The C++ package has no sampled runtime nodes, so it is not represented as a processing subsystem.

Main entry points: [`mapping_localization_python/launch/mapping_pipeline.launch.py`](https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/launch/mapping_pipeline.launch.py) (Pipeline Launch), [`mapping_localization_python/mapping_localization_python/slam_map_bridge_node.py`](https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/slam_map_bridge_node.py) (SLAM Map Bridge), [`mapping_localization_python/mapping_localization_python/slam_bridge_node.py`](https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/slam_bridge_node.py) (SLAM Bridge), [`mapping_localization_python/mapping_localization_python/perception_pipeline_node.py`](https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/perception_pipeline_node.py) (Perception Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_perception["Perception Pipeline"]
  node_synthetic["Synthetic Publisher"]
  node_pipeline["Perception Pipeline"]
end

subgraph group_localization["SLAM Localization"]
  node_slam["Kitware SLAM"]
  node_slam_bridge["SLAM Bridge"]
end

subgraph group_maps["Map Outputs"]
  node_map_bridge["SLAM Map Bridge"]
  node_cloud_utils["Point Cloud Utilities"]
end

subgraph group_registry["Point Registry"]
  node_point_registry["Stored Point Registry"]
end

node_perception_source(("Perception"))
node_mapping_clients(("Mapping / P&C"))
node_localization_clients(("Localization Consumers"))
node_slam_maps(("SLAM Keypoint Maps"))
node_map_clients(("Map Consumers"))
node_map_save_client(("Map Save Client"))
node_point_clients(("Planning / Mapping Clients"))
node_pipeline_launch["Pipeline Launch"]
node_tf_provider["TF Transforms"]

node_perception_source -->|"publishes entities / lanes"| node_pipeline
node_synthetic -.->|"publishes sample data"| node_pipeline
node_pipeline -->|"publishes mapped entities / lanes"| node_mapping_clients
node_slam -.->|"publishes odometry"| node_slam_bridge
node_slam_bridge -->|"publishes pose, odometry, distance"| node_localization_clients
node_slam_bridge -->|"looks up transforms"| node_tf_provider
node_slam_maps -.->|"publishes keypoint clouds"| node_map_bridge
node_map_bridge -->|"calls merge / grid helpers"| node_cloud_utils
node_map_bridge -->|"publishes merged map / grid"| node_map_clients
node_map_save_client -->|"calls save service"| node_map_bridge
node_map_bridge -.->|"calls upstream save service"| node_slam
node_point_clients -->|"calls create / delete / lookup"| node_point_registry
node_pipeline_launch -->|"starts"| node_pipeline
node_pipeline_launch -->|"starts"| node_point_registry
node_pipeline_launch -->|"starts"| node_slam_bridge
node_pipeline_launch -.->|"starts optionally"| node_map_bridge
node_pipeline_launch -.->|"starts optionally"| node_slam
node_pipeline_launch -.->|"starts optionally"| node_synthetic

click node_synthetic "https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/synthetic_perception_publisher_node.py"
click node_pipeline "https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/perception_pipeline_node.py"
click node_slam_bridge "https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/slam_bridge_node.py"
click node_map_bridge "https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/slam_map_bridge_node.py"
click node_cloud_utils "https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/point_cloud_utils.py"
click node_point_registry "https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/stored_point_registry_node.py"
click node_pipeline_launch "https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/launch/mapping_pipeline.launch.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_synthetic,node_pipeline,node_map_save_client,node_point_clients toneBlue
class node_slam,node_slam_bridge toneAmber
class node_map_bridge,node_cloud_utils toneMint
class node_point_registry toneRose
class node_perception_source,node_mapping_clients,node_localization_clients,node_slam_maps,node_map_clients,node_tf_provider toneIndigo
class node_pipeline_launch toneTeal
```

## Components

### Perception Pipeline

- [Synthetic Publisher](https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/synthetic_perception_publisher_node.py): `mapping_localization_python/mapping_localization_python/synthetic_perception_publisher_node.py`
- [Perception Pipeline](https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/perception_pipeline_node.py): `mapping_localization_python/mapping_localization_python/perception_pipeline_node.py`

### SLAM Localization

- **Kitware SLAM**
- [SLAM Bridge](https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/slam_bridge_node.py): `mapping_localization_python/mapping_localization_python/slam_bridge_node.py`

### Map Outputs

- [SLAM Map Bridge](https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/slam_map_bridge_node.py): `mapping_localization_python/mapping_localization_python/slam_map_bridge_node.py`
- [Point Cloud Utilities](https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/point_cloud_utils.py): `mapping_localization_python/mapping_localization_python/point_cloud_utils.py`

### Point Registry

- [Stored Point Registry](https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/mapping_localization_python/stored_point_registry_node.py): `mapping_localization_python/mapping_localization_python/stored_point_registry_node.py`

### Other components

- **Perception**
- **Mapping / P&C**
- **Localization Consumers**
- **SLAM Keypoint Maps**
- **Map Consumers**
- **Map Save Client**
- **Planning / Mapping Clients**
- [Pipeline Launch](https://github.com/we-autopilot/mapping-and-localization/blob/main/mapping_localization_python/launch/mapping_pipeline.launch.py): `mapping_localization_python/launch/mapping_pipeline.launch.py`
- **TF Transforms**

## Connections

- Perception → Perception Pipeline: publishes entities / lanes
- Synthetic Publisher → Perception Pipeline: publishes sample data
- Perception Pipeline → Mapping / P&C: publishes mapped entities / lanes
- Kitware SLAM → SLAM Bridge: publishes odometry
- SLAM Bridge → Localization Consumers: publishes pose, odometry, distance
- SLAM Bridge → TF Transforms: looks up transforms
- SLAM Keypoint Maps → SLAM Map Bridge: publishes keypoint clouds
- SLAM Map Bridge → Point Cloud Utilities: calls merge / grid helpers
- SLAM Map Bridge → Map Consumers: publishes merged map / grid
- Map Save Client → SLAM Map Bridge: calls save service
- SLAM Map Bridge → Kitware SLAM: calls upstream save service
- Planning / Mapping Clients → Stored Point Registry: calls create / delete / lookup
- Pipeline Launch → Perception Pipeline: starts
- Pipeline Launch → Stored Point Registry: starts
- Pipeline Launch → SLAM Bridge: starts
- Pipeline Launch → SLAM Map Bridge: starts optionally
- Pipeline Launch → Kitware SLAM: starts optionally
- Pipeline Launch → Synthetic Publisher: starts optionally