nigig-org/crates/apps/valhalla

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/:

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)

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)

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:

TEST_TARGET=valhalla ./tools/test-rust-clean.sh

All 45 unit and integration parity tests must pass cleanly under rustfmt and clippy.