# isthisit123/ai-valet-parking-rover architecture

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

- Interactive diagram: https://gitdiagram.com/isthisit123/ai-valet-parking-rover
- Repository: https://github.com/isthisit123/ai-valet-parking-rover

## Overview

Q-ROVER’s implemented product is the map-processing and route-planning portion of an AI valet-parking rover, not the planned rover-control system. The principal workflow detects roads in a parking-map image, builds a pixel-weighted road graph, attaches labeled facilities and parking spaces, selects a space by preference, then exports route images and pixel waypoints. Calibration supports converting measured hints to image pixels. Edges reflect README-documented stage inputs and sampled calls; rover control, camera localization, and YOLO occupancy are planned or parallel work, not implemented here.

Main entry points: [`src/map_processing/map_reader.py`](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/map_reader.py) (Road Detection), [`src/map_processing/semantic_mapper.py`](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/semantic_mapper.py) (Facility Mapping), [`src/map_processing/map_config.py`](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/map_config.py) (Map Configuration), [`src/map_processing/graph_exporter.py`](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/graph_exporter.py) (Road Graph Export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_map_input["Map Input"]
  node_map_files["Map and Labels"]
  node_map_config["Map Configuration<br/>[map_config.py]"]
  node_road_detection["Road Detection<br/>[map_reader.py]"]
end

subgraph group_map_model["Map Modeling"]
  node_skeleton_nodes["Road Skeleton<br/>[graph_builder.py]"]
  node_road_graph["Road Graph Export<br/>[graph_exporter.py]"]
  node_graph_data["Road Graph JSON<br/>[graph.json]"]
  node_semantic_map["Facility Mapping<br/>[semantic_mapper.py]"]
  node_semantic_data["Semantic Map JSON<br/>[semantic.json]"]
end

subgraph group_parking_route["Parking Routes"]
  node_parking_selection["Space Selection"]
  node_route_export["Route Export<br/>[path_visualizer.py]"]
  node_route_files["Route Waypoints"]
end

subgraph group_calibration["Planar Calibration"]
  node_calibration["Homography Calibration"]
end

node_operator(("Map Operator"))
node_rover(("Q-ROVER"))
node_occupancy_service(("YOLO Occupancy"))

node_operator -->|"selects map"| node_map_config
node_map_files -->|"supplies image"| node_road_detection
node_map_config -->|"configures input"| node_road_detection
node_road_detection -->|"provides mask"| node_skeleton_nodes
node_skeleton_nodes -->|"provides skeleton"| node_road_graph
node_road_detection -->|"provides road mask"| node_road_graph
node_map_config -->|"configures output"| node_road_graph
node_road_graph -->|"writes graph"| node_graph_data
node_graph_data -->|"reads graph"| node_semantic_map
node_map_files -->|"supplies labels"| node_semantic_map
node_map_config -->|"configures paths"| node_semantic_map
node_calibration -->|"converts hints"| node_semantic_map
node_semantic_map -->|"writes semantics"| node_semantic_data
node_semantic_data -->|"loads map"| node_parking_selection
node_parking_selection -->|"selects destination"| node_route_export
node_semantic_data -->|"loads map"| node_route_export
node_road_detection -->|"checks road mask"| node_route_export
node_route_export -->|"writes routes"| node_route_files
node_route_files -.->|"planned waypoints"| node_rover
node_occupancy_service -.->|"planned occupancy"| node_parking_selection

click node_map_files "https://github.com/isthisit123/ai-valet-parking-rover/tree/main/assets/maps"
click node_map_config "https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/map_config.py"
click node_road_detection "https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/map_reader.py"
click node_skeleton_nodes "https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/graph_builder.py"
click node_road_graph "https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/graph_exporter.py"
click node_graph_data "https://github.com/isthisit123/ai-valet-parking-rover/blob/main/data/maps/parking_map_real/graph.json"
click node_semantic_map "https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/semantic_mapper.py"
click node_semantic_data "https://github.com/isthisit123/ai-valet-parking-rover/blob/main/data/maps/parking_map_real/semantic.json"
click node_calibration "https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/planar_calibration.py"
click node_parking_selection "https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/parking_selector.py"
click node_route_export "https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/path_visualizer.py"
click node_route_files "https://github.com/isthisit123/ai-valet-parking-rover/tree/main/data/maps/parking_map_real/routes"

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_map_files,node_map_config,node_road_detection toneBlue
class node_skeleton_nodes,node_road_graph,node_graph_data,node_semantic_map,node_semantic_data toneAmber
class node_parking_selection,node_route_export,node_route_files toneMint
class node_calibration toneRose
class node_operator,node_rover,node_occupancy_service toneIndigo
```

## Components

### Map Input

- [Map and Labels](https://github.com/isthisit123/ai-valet-parking-rover/tree/main/assets/maps): `assets/maps`
- [Map Configuration](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/map_config.py): `src/map_processing/map_config.py`
- [Road Detection](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/map_reader.py): `src/map_processing/map_reader.py`

### Map Modeling

- [Road Skeleton](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/graph_builder.py): `src/map_processing/graph_builder.py`
- [Road Graph Export](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/graph_exporter.py): `src/map_processing/graph_exporter.py`
- [Road Graph JSON](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/data/maps/parking_map_real/graph.json): `data/maps/parking_map_real/graph.json`
- [Facility Mapping](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/semantic_mapper.py): `src/map_processing/semantic_mapper.py`
- [Semantic Map JSON](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/data/maps/parking_map_real/semantic.json): `data/maps/parking_map_real/semantic.json`

### Parking Routes

- [Space Selection](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/parking_selector.py): `src/map_processing/parking_selector.py`
- [Route Export](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/path_visualizer.py): `src/map_processing/path_visualizer.py`
- [Route Waypoints](https://github.com/isthisit123/ai-valet-parking-rover/tree/main/data/maps/parking_map_real/routes): `data/maps/parking_map_real/routes`

### Planar Calibration

- [Homography Calibration](https://github.com/isthisit123/ai-valet-parking-rover/blob/main/src/map_processing/planar_calibration.py): `src/map_processing/planar_calibration.py`

### Other components

- **Map Operator**
- **Q-ROVER**
- **YOLO Occupancy**

## Connections

- Map Operator → Map Configuration: selects map (evidence: `README.md`)
- Map and Labels → Road Detection: supplies image (evidence: `README.md`)
- Map Configuration → Road Detection: configures input (evidence: `src/map_processing/map_reader.py`)
- Road Detection → Road Skeleton: provides mask (evidence: `src/map_processing/graph_builder.py`)
- Road Skeleton → Road Graph Export: provides skeleton (evidence: `src/map_processing/graph_exporter.py`)
- Road Detection → Road Graph Export: provides road mask (evidence: `src/map_processing/graph_exporter.py`)
- Map Configuration → Road Graph Export: configures output (evidence: `src/map_processing/graph_exporter.py`)
- Road Graph Export → Road Graph JSON: writes graph (evidence: `README.md`)
- Road Graph JSON → Facility Mapping: reads graph (evidence: `README.md`)
- Map and Labels → Facility Mapping: supplies labels (evidence: `README.md`)
- Map Configuration → Facility Mapping: configures paths (evidence: `src/map_processing/semantic_mapper.py`)
- Homography Calibration → Facility Mapping: converts hints (evidence: `src/map_processing/semantic_mapper.py`)
- Facility Mapping → Semantic Map JSON: writes semantics (evidence: `README.md`)
- Semantic Map JSON → Space Selection: loads map (evidence: `src/map_processing/parking_selector.py`)
- Space Selection → Route Export: selects destination (evidence: `src/map_processing/path_visualizer.py`)
- Semantic Map JSON → Route Export: loads map (evidence: `src/map_processing/path_visualizer.py`)
- Road Detection → Route Export: checks road mask (evidence: `src/map_processing/path_visualizer.py`)
- Route Export → Route Waypoints: writes routes (evidence: `README.md`)
- Route Waypoints → Q-ROVER: planned waypoints (evidence: `README.md`)
- YOLO Occupancy → Space Selection: planned occupancy (evidence: `README.md`)