# aika-kawase/placenav architecture

> Architecture diagram of the GitHub repository aika-kawase/placenav, 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/aika-kawase/placenav
- Repository: https://github.com/aika-kawase/placenav

## Overview

PlaceNav builds an ordered image topological map from a robot trajectory, then uses camera observations to localize within that map, select a subgoal, predict waypoints, and command a robot. The graph also preserves documented WHILL capabilities for adaptive map sampling, safety filtering, diagnostics, and visualization. Navigation-to-model and navigation-to-recognition relationships are visible in the source index or excerpts; some ROS wiring and map-generation details are documented only at a high level, so uncertain runtime links are omitted.

Main entry points: [`src/placenav/navigate.py`](https://github.com/aika-kawase/placenav/blob/main/src/placenav/navigate.py) (Navigation Node), [`src/placenav/place_recognition/bayesian_querier.py`](https://github.com/aika-kawase/placenav/blob/main/src/placenav/place_recognition/bayesian_querier.py) (Bayesian Localizer), [`src/placenav/create_topomap.py`](https://github.com/aika-kawase/placenav/blob/main/src/placenav/create_topomap.py) (Topomap Creator), [`src/placenav/place_recognition/extract_database.py`](https://github.com/aika-kawase/placenav/blob/main/src/placenav/place_recognition/extract_database.py) (Descriptor Export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mapping["Map Creation"]
  node_topomap_creator["Topomap Creator<br/>[create_topomap.py]"]
  node_topomap[("Topological Map")]
end

subgraph group_recognition["Place Recognition"]
  node_descriptor_export["Descriptor Export"]
  node_descriptor_store[("Descriptor Database<br/>[gallery_db.py]")]
  node_feature_extractor["Feature Extractor"]
  node_cosplace["CosPlace Model"]
  node_bayesian_filter["Bayesian Localizer"]
  node_sliding_filter["Sliding Localizer"]
end

subgraph group_navigation["Navigation Inference"]
  node_navigator["Navigation Node<br/>[navigate.py]"]
  node_waypoint_model["GNM Waypoint Model<br/>[gnm.py]"]
  node_image_encoder["MobileNet Encoder"]
end

subgraph group_robot["Robot Interface"]
  node_teleop["Joystick Teleop<br/>[joy_teleop.py]"]
  node_pd_controller["PD Controller<br/>[pd_controller.py]"]
  node_safety_filter["Safety Filter<br/>[safety_filter.py]"]
  node_robot_base["Robot Base<br/>[robots.yaml]"]
end

subgraph group_observability["Diagnostics and Visualization"]
  node_viz_node["Visualization Node"]
  node_viz_messages["ROS Visualization Messages"]
end

node_operator(("Operator"))
node_robot_sensor(("Robot Sensors"))

node_operator -.->|"records trajectory"| node_topomap_creator
node_robot_sensor -.->|"provides images and odometry"| node_topomap_creator
node_topomap_creator -.->|"creates map"| node_topomap
node_topomap -.->|"supplies map images"| node_descriptor_export
node_descriptor_export -.->|"writes descriptors"| node_descriptor_store
node_navigator -->|"builds map descriptors"| node_descriptor_export
node_navigator -->|"initializes extractor"| node_feature_extractor
node_feature_extractor -->|"loads model"| node_cosplace
node_bayesian_filter -->|"loads descriptors"| node_descriptor_store
node_bayesian_filter -->|"extracts query features"| node_feature_extractor
node_navigator -->|"uses localizer"| node_bayesian_filter
node_navigator -->|"supports alternate filter"| node_sliding_filter
node_navigator -->|"runs waypoint inference"| node_waypoint_model
node_waypoint_model -->|"encodes images"| node_image_encoder
node_robot_sensor -.->|"provides camera observations"| node_navigator
node_navigator -.->|"publishes waypoints"| node_pd_controller
node_operator -.->|"steers robot"| node_teleop
node_pd_controller -.->|"passes nominal commands"| node_safety_filter
node_safety_filter -.->|"limits velocity"| node_robot_base
node_navigator -->|"publishes diagnostics"| node_viz_messages
node_navigator -.->|"publishes visualization data"| node_viz_node
node_viz_messages -.->|"provides message types"| node_viz_node

click node_topomap_creator "https://github.com/aika-kawase/placenav/blob/main/src/placenav/create_topomap.py"
click node_topomap "https://github.com/aika-kawase/placenav/tree/main/src/topomaps"
click node_descriptor_export "https://github.com/aika-kawase/placenav/blob/main/src/placenav/place_recognition/extract_database.py"
click node_descriptor_store "https://github.com/aika-kawase/placenav/blob/main/src/placenav/place_recognition/gallery_db.py"
click node_feature_extractor "https://github.com/aika-kawase/placenav/blob/main/src/placenav/place_recognition/feature_extractor.py"
click node_cosplace "https://github.com/aika-kawase/placenav/blob/main/src/placenav/models/pr_models/cosplace_model/cosplace_network.py"
click node_bayesian_filter "https://github.com/aika-kawase/placenav/blob/main/src/placenav/place_recognition/bayesian_querier.py"
click node_sliding_filter "https://github.com/aika-kawase/placenav/blob/main/src/placenav/place_recognition/sliding_window_querier.py"
click node_navigator "https://github.com/aika-kawase/placenav/blob/main/src/placenav/navigate.py"
click node_waypoint_model "https://github.com/aika-kawase/placenav/blob/main/src/placenav/models/wp_models/gnm/gnm.py"
click node_image_encoder "https://github.com/aika-kawase/placenav/blob/main/src/placenav/models/wp_models/gnm/modified_mobilenetv2.py"
click node_teleop "https://github.com/aika-kawase/placenav/blob/main/src/placenav/joy_teleop.py"
click node_pd_controller "https://github.com/aika-kawase/placenav/blob/main/src/placenav/pd_controller.py"
click node_safety_filter "https://github.com/aika-kawase/placenav/blob/main/src/placenav/safety_filter.py"
click node_robot_base "https://github.com/aika-kawase/placenav/blob/main/src/config/robots.yaml"
click node_viz_node "https://github.com/aika-kawase/placenav/blob/main/src/placenav/visualization_node.py"
click node_viz_messages "https://github.com/aika-kawase/placenav/tree/main/src/placenav_viz_msgs/src/placenav_viz_msgs/msg"

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_topomap_creator,node_topomap toneBlue
class node_descriptor_export,node_descriptor_store,node_feature_extractor,node_cosplace,node_bayesian_filter,node_sliding_filter toneAmber
class node_navigator,node_waypoint_model,node_image_encoder toneMint
class node_teleop,node_pd_controller,node_safety_filter,node_robot_base toneRose
class node_viz_node,node_viz_messages,node_operator,node_robot_sensor toneIndigo
```

## Components

### Map Creation

- [Topomap Creator](https://github.com/aika-kawase/placenav/blob/main/src/placenav/create_topomap.py): `src/placenav/create_topomap.py`
- [Topological Map](https://github.com/aika-kawase/placenav/tree/main/src/topomaps): `src/topomaps`

### Place Recognition

- [Descriptor Export](https://github.com/aika-kawase/placenav/blob/main/src/placenav/place_recognition/extract_database.py): `src/placenav/place_recognition/extract_database.py`
- [Descriptor Database](https://github.com/aika-kawase/placenav/blob/main/src/placenav/place_recognition/gallery_db.py): `src/placenav/place_recognition/gallery_db.py`
- [Feature Extractor](https://github.com/aika-kawase/placenav/blob/main/src/placenav/place_recognition/feature_extractor.py): `src/placenav/place_recognition/feature_extractor.py`
- [CosPlace Model](https://github.com/aika-kawase/placenav/blob/main/src/placenav/models/pr_models/cosplace_model/cosplace_network.py): `src/placenav/models/pr_models/cosplace_model/cosplace_network.py`
- [Bayesian Localizer](https://github.com/aika-kawase/placenav/blob/main/src/placenav/place_recognition/bayesian_querier.py): `src/placenav/place_recognition/bayesian_querier.py`
- [Sliding Localizer](https://github.com/aika-kawase/placenav/blob/main/src/placenav/place_recognition/sliding_window_querier.py): `src/placenav/place_recognition/sliding_window_querier.py`

### Navigation Inference

- [Navigation Node](https://github.com/aika-kawase/placenav/blob/main/src/placenav/navigate.py): `src/placenav/navigate.py`
- [GNM Waypoint Model](https://github.com/aika-kawase/placenav/blob/main/src/placenav/models/wp_models/gnm/gnm.py): `src/placenav/models/wp_models/gnm/gnm.py`
- [MobileNet Encoder](https://github.com/aika-kawase/placenav/blob/main/src/placenav/models/wp_models/gnm/modified_mobilenetv2.py): `src/placenav/models/wp_models/gnm/modified_mobilenetv2.py`

### Robot Interface

- [Joystick Teleop](https://github.com/aika-kawase/placenav/blob/main/src/placenav/joy_teleop.py): `src/placenav/joy_teleop.py`
- [PD Controller](https://github.com/aika-kawase/placenav/blob/main/src/placenav/pd_controller.py): `src/placenav/pd_controller.py`
- [Safety Filter](https://github.com/aika-kawase/placenav/blob/main/src/placenav/safety_filter.py): `src/placenav/safety_filter.py`
- [Robot Base](https://github.com/aika-kawase/placenav/blob/main/src/config/robots.yaml): `src/config/robots.yaml`

### Diagnostics and Visualization

- [Visualization Node](https://github.com/aika-kawase/placenav/blob/main/src/placenav/visualization_node.py): `src/placenav/visualization_node.py`
- [ROS Visualization Messages](https://github.com/aika-kawase/placenav/tree/main/src/placenav_viz_msgs/src/placenav_viz_msgs/msg): `src/placenav_viz_msgs/src/placenav_viz_msgs/msg`

### Other components

- **Operator**
- **Robot Sensors**

## Connections

- Operator → Topomap Creator: records trajectory (evidence: `README.md`)
- Robot Sensors → Topomap Creator: provides images and odometry (evidence: `README.md`)
- Topomap Creator → Topological Map: creates map (evidence: `README.md`)
- Topological Map → Descriptor Export: supplies map images (evidence: `README.md`)
- Descriptor Export → Descriptor Database: writes descriptors (evidence: `src/placenav/place_recognition/extract_database.py`)
- Navigation Node → Descriptor Export: builds map descriptors (evidence: `src/placenav/navigate.py`)
- Navigation Node → Feature Extractor: initializes extractor (evidence: `src/placenav/navigate.py`)
- Feature Extractor → CosPlace Model: loads model (evidence: `src/placenav/place_recognition/feature_extractor.py`)
- Bayesian Localizer → Descriptor Database: loads descriptors (evidence: `src/placenav/place_recognition/bayesian_querier.py`)
- Bayesian Localizer → Feature Extractor: extracts query features (evidence: `src/placenav/place_recognition/bayesian_querier.py`)
- Navigation Node → Bayesian Localizer: uses localizer (evidence: `src/placenav/navigate.py`)
- Navigation Node → Sliding Localizer: supports alternate filter (evidence: `src/placenav/navigate.py`)
- Navigation Node → GNM Waypoint Model: runs waypoint inference (evidence: `src/placenav/navigate.py`)
- GNM Waypoint Model → MobileNet Encoder: encodes images (evidence: `src/placenav/models/wp_models/gnm/gnm.py`)
- Robot Sensors → Navigation Node: provides camera observations (evidence: `README.md`)
- Navigation Node → PD Controller: publishes waypoints (evidence: `README.md`)
- Operator → Joystick Teleop: steers robot (evidence: `README.md`)
- PD Controller → Safety Filter: passes nominal commands (evidence: `README.md`)
- Safety Filter → Robot Base: limits velocity (evidence: `README.md`)
- Navigation Node → ROS Visualization Messages: publishes diagnostics (evidence: `src/placenav/navigate.py`)
- Navigation Node → Visualization Node: publishes visualization data (evidence: `README.md`)
- ROS Visualization Messages → Visualization Node: provides message types (evidence: `README.md`)