[LoyalAbbas]

Summary

Adds the Hilly & Undulating (Roller-Coaster) Road Early Alerts showcase sample with full 3-way parity across Kotlin Views, Java Views, and Jetpack Compose.

This sample demonstrates how 3D elevation route profiles (LatLngAltitude with explicit ABSOLUTE altitudes) can be analyzed ahead of a moving vehicle in real time to detect rapid crests, dips, blind summits, and sustained steep climbs/descents before the driver reaches them.

---

Key Features

• Lookahead Terrain & Grade Analysis (RoadTerrainAnalyzer):
  • Scans configurable lookahead horizons (250m, 500m, 750m) ahead of the vehicle to detect local elevation peaks (CREST) and troughs (DIP) using vertical prominence hysteresis (when (state) state machine).
  • Computes monotonic-clamped and lookahead-bounded road grades (Max Grade: +X.X% / -Y.Y%) and classifies upcoming hazards (UNDULATING_ROLLER_COASTER, BLIND_CREST, STEEP_CLIMB, STEEP_DESCENT, NONE) with CAUTION / WARNING severity escalation.
  • Calculates reference-only advisory speeds inspired by AASHTO Green Book vertical-curve (sight distance & comfort acceleration) and grade-adjusted braking equations (rounded to 5 km/h increments, with explicit reference-only documentation disclaimer).
• 3D Map Rendering & Smooth Adaptive Camera (HillyRoadAlertViewModel):
  • Renders the base 3D route polyline, dynamic hazard-zone highlight polyline (CAUTION amber / WARNING red), crest/dip 3D markers, and the 3D red car marker tracking the route.
  • Smoothly adapts camera altitude (lookahead terrain blending + grade-proportional height boost + EMA vertical smoothing) and optional crest camera pitch preview to prevent terrain clipping on steep transitions.
  • Defers playback and telemetry progression until the 3D map is ready (onMapReady) and gracefully handles offline launches (ACCESS_NETWORK_STATE) so the native Maps 3D offline prompt displays without crashing.
• Live HUD & Collapsible Controls:
  • Real-time HUD alert banner with upcoming hazard distance, crest/dip count, max uphill/downhill grade, reference advisory speed, and live lookahead elevation sparkline (ElevationSparklineView / Compose Canvas) with vehicle, crest, and dip indicators.
  • Compact collapsible Terrain Lookahead Controls bottom sheet with play/pause, route scrubber, Jump to Hills quick action, route preset chips (Roller-Coaster, Mountain Pass, Coastal), lookahead horizon selector, playback speed (0.5x–5x), and crest camera preview toggle.
• Externalized JSON Route Dataset (hilly_routes.json & HillyRouteData):
  • Stores the three 3D route coordinate traces in Maps3DSamples/ApiDemos/common/src/main/resources/hilly_routes.json and loads them lazily on first access to keep Kotlin sources and .dex static initialization lean.

---

Architecture & 3-Way Parity

• Shared Domain, Data & Presentation (:Maps3DSamples:ApiDemos:common):
  • RoadTerrainAnalyzer.kt — Pure Kotlin terrain, extrema, grade, sparkline, and advisory speed engine.
  • HillyRouteData.kt & resources/hilly_routes.json — Lazy-loaded 3D route presets.
  • HillyRoadAlertViewModel.kt — UDF presentation state machine exposing StateFlow (Kotlin/Compose) and LiveData via asLiveData() (Java) synchronized with hardware frame ticks.
  • ElevationSparklineView.kt & res/layout/activity_hilly_road_alerts.xml — Shared custom sparkline view and Material 3 layout for Kotlin & Java Views.
• Thin UI Implementations:
  • Kotlin Views: Maps3DSamples/ApiDemos/kotlin-app/.../hillyroadalerts/HillyRoadAlertsActivity.kt
  • Java Views: Maps3DSamples/ApiDemos/java-app/.../hillyroadalerts/HillyRoadAlertsActivity.java
  • Jetpack Compose: Maps3DSamples/ComposeDemos/app/.../hillyroadalerts/HillyRoadAlertsActivity.kt

---

Testing & Verification

• Added JVM unit tests in :Maps3DSamples:ApiDemos:common:
  • RoadTerrainAnalyzerTest.kt — Verifies flat/gentle control routes, early CAUTION → WARNING escalation on undulating terrain, stable crest/dip IDs and grade deltas, sustained climb/blind crest/descent classification, and zero-distance/duplicate-point guards.
  • HillyRoadAlertViewModelTest.kt — Verifies onMapReady gating, frame-tick progression, route preset switching, horizon updates, scrubbing, and Jump to Hills behavior.
• Verified ./gradlew spotlessApply, :Maps3DSamples:ApiDemos:common:testDebugUnitTest, and debug compilation across :Maps3DSamples:ApiDemos:kotlin-app, :Maps3DSamples:ApiDemos:java-app, and :Maps3DSamples:ComposeDemos:app.