113 lines
7.2 KiB
Markdown
113 lines
7.2 KiB
Markdown
# Valhalla Pure Rust Engine, `nigig-map`, and `nigig-rider` Integration Plan
|
|
## End-to-End Architectural Specification & Implementation Roadmap
|
|
|
|
**Date:** July 28, 2026
|
|
**Target Application:** `nigig-rider` (Riding App) & `nigig-map` (Map Renderer)
|
|
**Routing Engine:** `valhalla` (`crates/apps/valhalla/*`)
|
|
**GPS Tracking:** `robius-location`
|
|
|
|
---
|
|
|
|
## 1. Executive Summary & Integration Architecture
|
|
|
|
With the completion of the Pure Rust **Valhalla Routing Engine (`valhalla-rs`)**, this plan specifies the exact technical architecture to connect the routing engine with the **Makepad Map Renderer (`nigig-map`)** and the **Rider Riding Application (`nigig-rider`)**.
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────────────┐
|
|
│ nigig-rider App │
|
|
│ │
|
|
│ 1. `RiderBookPage` (Search / Pin Drop) │
|
|
│ 2. `RiderTrackPage` (Live Navigation HUD & Driver Tracking) │
|
|
└───────────────────┬────────────────────────────────┬───────────────────┘
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────────────────────┐ ┌──────────────────────────────┐
|
|
│ valhalla::ValhallaActor │ │ valhalla::DriverGuidance │
|
|
│ (A* Route & Matrix Engine) │ │ Controller (HMM GPS Snapper) │
|
|
└──────────────┬───────────────┘ └──────────────┬───────────────┘
|
|
│ │
|
|
└────────────────┬───────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────┐
|
|
│ nigig-map Map Renderer │
|
|
│ │
|
|
│ • RouteRenderPass (StrokePass) │
|
|
│ • Waypoint Marker Pass │
|
|
└─────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Key Technical Integration Points
|
|
|
|
### 2.1 Route Overlay Pass in `nigig-map` (`RouteRenderPass`)
|
|
`nigig-map` uses a modular `RenderGraph` pipeline with explicit pass ordering:
|
|
- `PassType::Background` ($z=0$)
|
|
- `PassType::Fill` ($z=100$)
|
|
- `PassType::Stroke` ($z=200$)
|
|
- `PassType::Poi` ($z=300$)
|
|
- `PassType::Label` ($z=400$)
|
|
- `PassType::Selection` ($z=500$)
|
|
|
|
**Action:** Add a custom `RouteRenderPass` ($z=250$, between road stroke and POI) implementing `RenderPass` in `crates/apps/map/src/render_graph.rs`:
|
|
- Reads route shape points (`Vec<PointLL>`) from `valhalla::ui::RouteOverlay`.
|
|
- Converts geographic coordinates (`PointLL`) to Mercator screen space using `lon_lat_to_normalized(lng, lat) * world_size + map_offset`.
|
|
- Tessellates route polylines into GPU stroke vertices with navigation-blue casing (`#3b82f6`) and 6px stroke width.
|
|
|
|
### 2.2 `RiderBookPage` Integration (`crates/apps/nigig-rider/src/rider_frame/pages/book.rs`)
|
|
- On destination search or location row tap:
|
|
1. Retrieve origin coordinate (current GPS position or map center: $36.8219, -1.2921$).
|
|
2. Issue route request: `actor.route(origin, destination, "auto")`.
|
|
3. Extract `RouteResponse` polyline shape and pass to `NigigMapView::set_route_overlay()`.
|
|
4. Display ETA summary card (total distance in km, travel duration in minutes).
|
|
|
|
### 2.3 `RiderTrackPage` Integration (`crates/apps/nigig-rider/src/rider_frame/pages/track.rs`)
|
|
- On live GPS updates from `robius-location`:
|
|
1. Feed location to `DriverGuidanceController::on_location_update(coord, "auto")`.
|
|
2. Update `NavigationHudData` UI card (current turn maneuver instruction, distance to turn, next turn arrow).
|
|
3. On `GuidanceEvent::Rerouted(new_route)` ($>25\text{m}$ off-route threshold): update map route overlay line and recalculate ETA automatically.
|
|
|
|
---
|
|
|
|
## 3. Step-by-Step Execution Roadmap
|
|
|
|
```
|
|
┌────────────────────────────────────────────────────────────────────────┐
|
|
│ 5-STEP IMPLEMENTATION ROADMAP │
|
|
│ │
|
|
│ STEP 1: Add `RouteRenderPass` to `nigig-map` RenderGraph │
|
|
│ STEP 2: Add `set_route_overlay()` API to `NigigMapView` │
|
|
│ STEP 3: Wire `ValhallaActor` into `RiderBookPage` (`book.rs`) │
|
|
│ STEP 4: Wire Guidance HUD & `robius-location` into `track.rs` │
|
|
│ STEP 5: Validate via `tools/test-rust-clean.sh` & Push to Gitdab │
|
|
└────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Step 1: Add `RouteRenderPass` to `nigig-map`
|
|
- **File:** `crates/apps/map/src/render_graph.rs`
|
|
- Add `PassType::Route` ($z=250$) and implement `RenderPass` for `RoutePass` rendering polyline strokes over road networks.
|
|
|
|
### Step 2: Add `set_route_overlay()` API to `NigigMapView`
|
|
- **File:** `crates/apps/map/src/view.rs`
|
|
- Add `pub fn set_route_overlay(&mut self, cx: &mut Cx, overlay: Option<valhalla::ui::RouteOverlay>)` to update active route overlays and trigger `redraw(cx)`.
|
|
|
|
### Step 3: Wire `ValhallaActor` into `RiderBookPage`
|
|
- **File:** `crates/apps/nigig-rider/src/rider_frame/pages/book.rs`
|
|
- Instantiate `ValhallaActor` on page load, attach destination tap handler, and render ETA card on route completion.
|
|
|
|
### Step 4: Wire Guidance HUD into `RiderTrackPage`
|
|
- **File:** `crates/apps/nigig-rider/src/rider_frame/pages/track.rs`
|
|
- Instantiate `DriverGuidanceController`, bind location stream, and update navigation HUD cards.
|
|
|
|
### Step 5: Verification & Testing
|
|
- Test using `TEST_TARGET=valhalla` and `cargo check -p nigig-rider` to ensure clean compilation.
|
|
|
|
---
|
|
|
|
## 4. Expected User Experience Outcome
|
|
|
|
When complete:
|
|
1. **Interactive Route Planning:** Tapping any location in `nigig-rider` instantly renders a smooth blue route overlay line along the road network on `NigigMapView`.
|
|
2. **Turn-by-Turn Guidance HUD:** Displays upcoming maneuvers (*"Turn right onto Uhuru Highway in 200m"*).
|
|
3. **Live GPS Tracking & Auto-Rerouting:** Snaps driver location to road network and automatically recalculates routes if the driver takes a wrong turn ($>25\text{m}$ deviation).
|