99 lines
3.5 KiB
Markdown
99 lines
3.5 KiB
Markdown
# Valhalla Pure Rust Routing Engine (`valhalla-rs`)
|
|
## Native Makepad Integration Guide & Architecture Overview
|
|
|
|
`valhalla-rs` is a Pure Rust port and architectural rewrite of the **Valhalla Routing Engine**, designed specifically for cross-platform **Makepad UI Framework** applications (`nigig-rider`, `nigig-delivery`, `nigig-tow`, `nigig-mobility`).
|
|
|
|
---
|
|
|
|
## 1. Crate Architecture
|
|
|
|
The suite is organized into modular pure Rust crates under `crates/apps/valhalla/`:
|
|
|
|
```text
|
|
crates/apps/valhalla/
|
|
├── valhalla # Top-level unified facade crate
|
|
├── valhalla-core # Midgard geometry & Baldr GraphTile binary bitfield reader
|
|
├── valhalla-cost # Auto, Bicycle, Pedestrian, Truck, & Transit costing profiles
|
|
├── valhalla-path # DoubleBucketQueue, A*, Bidi A*, Matrix, & MultiModal A*
|
|
├── valhalla-search # Location snapping & candidate edge locator (Loki)
|
|
├── valhalla-match # HMM Viterbi trajectory map matcher (Meili)
|
|
├── valhalla-narrative # Maneuver builder, NarrativeDictionary, & VerbalTextFormatter
|
|
├── valhalla-service # Tyr ValhallaActor service API
|
|
├── valhalla-makepad # Makepad UI overlay & DriverGuidanceController
|
|
├── valhalla-builder # OSM PBF tag parser, PbfReader, TileGenerator & shortcuts
|
|
└── valhalla-diff # Golden differential parity test harness
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Quickstart & Integration Usage
|
|
|
|
### 2.1 Basic Route Query (`ValhallaActor`)
|
|
|
|
```rust
|
|
use valhalla::{ValhallaActor, PointLL};
|
|
|
|
// Initialize actor with loaded GraphTiles
|
|
let actor = ValhallaActor::new(tile_buffers);
|
|
|
|
let origin = PointLL::new(36.8219, -1.2921); // Nairobi CBD
|
|
let destination = PointLL::new(36.8050, -1.2650); // Westlands
|
|
|
|
// Calculate route response
|
|
let response = actor.route(origin, destination, "auto");
|
|
|
|
if response.status == 200 {
|
|
println!("Total Distance: {} meters", response.directions.total_distance_meters);
|
|
println!("Total Time: {} seconds", response.directions.total_time_secs);
|
|
|
|
for maneuver in &response.directions.maneuvers {
|
|
println!("Instruction: {}", maneuver.instruction);
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2.2 Live Driver Navigation & Off-Route Auto-Rerouting (`DriverGuidanceController`)
|
|
|
|
```rust
|
|
use valhalla::{DriverGuidanceController, ValhallaActor, PointLL, GuidanceEvent};
|
|
|
|
let actor = ValhallaActor::new(tile_buffers);
|
|
let mut controller = DriverGuidanceController::new(actor);
|
|
|
|
// Set calculated route
|
|
controller.set_active_route(route_response);
|
|
|
|
// On GPS location update from robius-location
|
|
let gps_coord = PointLL::new(36.8220, -1.2915);
|
|
let events = controller.on_location_update(gps_coord, "auto");
|
|
|
|
for event in events {
|
|
match event {
|
|
GuidanceEvent::UpdatedHud(hud_data) => {
|
|
println!("HUD Step: {}", hud_data.current_instruction);
|
|
println!("Distance to turn: {}m", hud_data.distance_to_next_maneuver_meters);
|
|
}
|
|
GuidanceEvent::Rerouted(new_route) => {
|
|
println!("Off-route detected! Auto-rerouted along new path.");
|
|
}
|
|
GuidanceEvent::ArrivedAtDestination => {
|
|
println!("Arrived at destination!");
|
|
}
|
|
}
|
|
}
|
|
|
|
// Generate GPU stroke overlay for nigig-map
|
|
let overlay = controller.get_route_overlay();
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Testing & CI Verification
|
|
|
|
Run the isolated test harness across all 10 Valhalla subcrates:
|
|
|
|
```bash
|
|
TEST_TARGET=valhalla ./tools/test-rust-clean.sh
|
|
```
|
|
|
|
All 45 unit and integration parity tests must pass cleanly under `rustfmt` and `clippy`.
|