# amslabtech/rwrc26 architecture

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

- Interactive diagram: https://gitdiagram.com/amslabtech/rwrc26
- Repository: https://github.com/amslabtech/rwrc26

## Overview

PlaceNav builds an ordered image topological map from a robot trajectory, then localizes incoming camera frames against that map, selects a subgoal, and predicts waypoints for robot motion. The graph also preserves the documented WHILL safety, diagnostics, and visualization branches. Source excerpts show navigation-to-recognition/model wiring; README documents several ROS and robot integrations whose implementation details were not sampled, so those links are cited to the README.

Main entry points: [`src/placenav/navigate.py`](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/navigate.py) (ROS navigator), [`src/placenav/place_recognition/extract_database.py`](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/place_recognition/extract_database.py) (Descriptor export), [`src/placenav/place_recognition/feature_extractor.py`](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/place_recognition/feature_extractor.py) (Feature extractor), [`src/placenav/place_recognition/bayesian_querier.py`](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/place_recognition/bayesian_querier.py) (Bayesian localizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mapping["Map creation"]
  node_topomap_builder["Topomap builder<br/>[create_topomap.py]"]
  node_topomap_store[("Topological maps")]
end

subgraph group_recognition["Place recognition"]
  node_feature_export["Descriptor export"]
  node_feature_db[("Descriptor database<br/>[gallery_db.py]")]
  node_feature_extractor["Feature extractor"]
  node_cosplace["CosPlace model"]
  node_pr_base["Recognition model API<br/>[base_model.py]"]
  node_bayesian["Bayesian localizer"]
  node_sliding["Sliding-window matcher"]
end

subgraph group_inference["Navigation inference"]
  node_navigator["ROS navigator<br/>[navigate.py]"]
  node_arguments["Navigation options<br/>[parser.py]"]
  node_gnm["GNM waypoint model<br/>[gnm.py]"]
  node_mobilenet["MobileNet encoder"]
  node_ros_utils["ROS image utilities<br/>[utils.py]"]
end

subgraph group_robot["Robot integration"]
  node_teleop["Joystick teleoperation<br/>[joy_teleop.py]"]
  node_pd_controller["PD controller<br/>[pd_controller.py]"]
  node_safety["Velocity safety filter<br/>[safety_filter.py]"]
end

subgraph group_observability["Visualization diagnostics"]
  node_viz_node["Visualization node"]
  node_viz_messages["Visualization messages"]
end

node_operator(("Operator"))
node_robot(("Mobile robot"))

node_operator -.->|"records trajectory"| node_topomap_builder
node_topomap_builder -.->|"writes map"| node_topomap_store
node_topomap_store -.->|"provides map images"| node_feature_export
node_feature_export -->|"loads model"| node_feature_extractor
node_feature_export -.->|"writes descriptors"| node_feature_db
node_feature_extractor -->|"loads model API"| node_pr_base
node_cosplace -.->|"implements API"| node_pr_base
node_navigator -->|"uses options"| node_arguments
node_navigator -->|"builds map database"| node_feature_export
node_navigator -->|"initializes extractor"| node_feature_extractor
node_navigator -->|"localizes frames"| node_bayesian
node_navigator -->|"selects matcher"| node_sliding
node_bayesian -->|"encodes query"| node_feature_extractor
node_bayesian -->|"reads descriptors"| node_feature_db
node_sliding -->|"reads gallery"| node_feature_db
node_navigator -.->|"predicts waypoints"| node_gnm
node_gnm -->|"uses encoder"| node_mobilenet
node_navigator -->|"uses image transforms"| node_ros_utils
node_robot -.->|"sends camera frames"| node_navigator
node_navigator -.->|"publishes motion commands"| node_robot
node_operator -.->|"sends joystick input"| node_teleop
node_teleop -.->|"teleoperates"| node_robot
node_pd_controller -.->|"filters velocity"| node_safety
node_safety -.->|"limits commands"| node_robot
node_navigator -.->|"publishes visualization data"| node_viz_node
node_navigator -.->|"publishes diagnostics"| node_viz_messages
node_viz_node -.->|"consumes messages"| node_viz_messages

click node_topomap_builder "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/create_topomap.py"
click node_topomap_store "https://github.com/amslabtech/rwrc26/tree/main/src/topomaps"
click node_feature_export "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/place_recognition/extract_database.py"
click node_feature_db "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/place_recognition/gallery_db.py"
click node_feature_extractor "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/place_recognition/feature_extractor.py"
click node_cosplace "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/models/pr_models/cosplace_model/cosplace_network.py"
click node_pr_base "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/models/pr_models/base_model.py"
click node_bayesian "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/place_recognition/bayesian_querier.py"
click node_sliding "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/place_recognition/sliding_window_querier.py"
click node_navigator "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/navigate.py"
click node_arguments "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/parser.py"
click node_gnm "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/models/wp_models/gnm/gnm.py"
click node_mobilenet "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/models/wp_models/gnm/modified_mobilenetv2.py"
click node_ros_utils "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/utils.py"
click node_teleop "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/joy_teleop.py"
click node_pd_controller "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/pd_controller.py"
click node_safety "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/safety_filter.py"
click node_viz_node "https://github.com/amslabtech/rwrc26/blob/main/src/placenav/visualization_node.py"
click node_viz_messages "https://github.com/amslabtech/rwrc26/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_builder,node_topomap_store toneBlue
class node_feature_export,node_feature_db,node_feature_extractor,node_cosplace,node_pr_base,node_bayesian,node_sliding toneAmber
class node_navigator,node_arguments,node_gnm,node_mobilenet,node_ros_utils toneMint
class node_teleop,node_pd_controller,node_safety toneRose
class node_viz_node,node_viz_messages,node_operator,node_robot toneIndigo
```

## Components

### Map creation

- [Topomap builder](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/create_topomap.py): `src/placenav/create_topomap.py`
- [Topological maps](https://github.com/amslabtech/rwrc26/tree/main/src/topomaps): `src/topomaps`

### Place recognition

- [Descriptor export](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/place_recognition/extract_database.py): `src/placenav/place_recognition/extract_database.py`
- [Descriptor database](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/place_recognition/gallery_db.py): `src/placenav/place_recognition/gallery_db.py`
- [Feature extractor](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/place_recognition/feature_extractor.py): `src/placenav/place_recognition/feature_extractor.py`
- [CosPlace model](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/models/pr_models/cosplace_model/cosplace_network.py): `src/placenav/models/pr_models/cosplace_model/cosplace_network.py`
- [Recognition model API](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/models/pr_models/base_model.py): `src/placenav/models/pr_models/base_model.py`
- [Bayesian localizer](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/place_recognition/bayesian_querier.py): `src/placenav/place_recognition/bayesian_querier.py`
- [Sliding-window matcher](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/place_recognition/sliding_window_querier.py): `src/placenav/place_recognition/sliding_window_querier.py`

### Navigation inference

- [ROS navigator](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/navigate.py): `src/placenav/navigate.py`
- [Navigation options](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/parser.py): `src/placenav/parser.py`
- [GNM waypoint model](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/models/wp_models/gnm/gnm.py): `src/placenav/models/wp_models/gnm/gnm.py`
- [MobileNet encoder](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/models/wp_models/gnm/modified_mobilenetv2.py): `src/placenav/models/wp_models/gnm/modified_mobilenetv2.py`
- [ROS image utilities](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/utils.py): `src/placenav/utils.py`

### Robot integration

- [Joystick teleoperation](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/joy_teleop.py): `src/placenav/joy_teleop.py`
- [PD controller](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/pd_controller.py): `src/placenav/pd_controller.py`
- [Velocity safety filter](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/safety_filter.py): `src/placenav/safety_filter.py`

### Visualization diagnostics

- [Visualization node](https://github.com/amslabtech/rwrc26/blob/main/src/placenav/visualization_node.py): `src/placenav/visualization_node.py`
- [Visualization messages](https://github.com/amslabtech/rwrc26/tree/main/src/placenav_viz_msgs/src/placenav_viz_msgs/msg): `src/placenav_viz_msgs/src/placenav_viz_msgs/msg`

### Other components

- **Operator**
- **Mobile robot**

## Connections

- Operator → Topomap builder: records trajectory (evidence: `README.md`)
- Topomap builder → Topological maps: writes map (evidence: `README.md`)
- Topological maps → Descriptor export: provides map images (evidence: `README.md`)
- Descriptor export → Feature extractor: loads model (evidence: `src/placenav/place_recognition/extract_database.py`)
- Descriptor export → Descriptor database: writes descriptors (evidence: `README.md`)
- Feature extractor → Recognition model API: loads model API (evidence: `src/placenav/place_recognition/feature_extractor.py`)
- CosPlace model → Recognition model API: implements API
- ROS navigator → Navigation options: uses options (evidence: `src/placenav/navigate.py`)
- ROS navigator → Descriptor export: builds map database (evidence: `src/placenav/navigate.py`)
- ROS navigator → Feature extractor: initializes extractor (evidence: `src/placenav/navigate.py`)
- ROS navigator → Bayesian localizer: localizes frames (evidence: `src/placenav/navigate.py`)
- ROS navigator → Sliding-window matcher: selects matcher (evidence: `src/placenav/navigate.py`)
- Bayesian localizer → Feature extractor: encodes query (evidence: `src/placenav/place_recognition/bayesian_querier.py`)
- Bayesian localizer → Descriptor database: reads descriptors (evidence: `src/placenav/place_recognition/bayesian_querier.py`)
- Sliding-window matcher → Descriptor database: reads gallery (evidence: `src/placenav/place_recognition/sliding_window_querier.py`)
- ROS navigator → GNM waypoint model: predicts waypoints (evidence: `README.md`)
- GNM waypoint model → MobileNet encoder: uses encoder (evidence: `src/placenav/models/wp_models/gnm/gnm.py`)
- ROS navigator → ROS image utilities: uses image transforms (evidence: `src/placenav/navigate.py`)
- Mobile robot → ROS navigator: sends camera frames (evidence: `README.md`)
- ROS navigator → Mobile robot: publishes motion commands (evidence: `README.md`)
- Operator → Joystick teleoperation: sends joystick input (evidence: `README.md`)
- Joystick teleoperation → Mobile robot: teleoperates (evidence: `README.md`)
- PD controller → Velocity safety filter: filters velocity (evidence: `README.md`)
- Velocity safety filter → Mobile robot: limits commands (evidence: `README.md`)
- ROS navigator → Visualization node: publishes visualization data (evidence: `README.md`)
- ROS navigator → Visualization messages: publishes diagnostics (evidence: `README.md`)
- Visualization node → Visualization messages: consumes messages (evidence: `README.md`)
