ar-navigation-flow

"/home/yossef/notes/git/projects/inguide/flows/ar-navigation-flow.md"

path: inguide/flows/ar-navigation-flow.md

- **fileName**: ar-navigation-flow
- **Created on**: 2026-06-16 00:48:42

cs# ar-navigation-flow

Purpose: AR screen lifecycle — camera, positioning, state machine, overlay rendering.

Screen Lifecycle

User opens AR tab
  → ArNavigationScreen composable mounts
    → Permission check (CAMERA)
      → If granted: setReady() → PositionStatus.Acquiring
      → If denied: show error
    → IndoorPositioningService collects currentPositionGeo
    → connectGps() → FusedLocationProviderClient starts 5s interval
    → startStalenessWatch() → 10s timeout → error if no position
    → Position updates arrive
      → Magnetic fingerprint match (if available)
      → GPS fallback (if magnetic missing or low confidence)
    → updatePosition(geo) → PositionStatus.Reliable or LowConfidence
    → Anchor set on first position received

Position Status States

Idle → Acquiring → Reliable (confidence ≥ 0.5)
                 → LowConfidence (confidence < 0.5, GPS fallback)
                 → OutOfRange (>200m from building center)
                 → Unavailable (permanent failure)

State Machine

Loading → setReady() → Tracking → setRoute() → Navigating → arrive() → Arrived
         → initialRouteData → Navigating (skip Tracking)
         └→ setError() → Error
Tracking → setRoute() → Navigating
Navigating → clearRoute() → Tracking
Navigating → arrive() → Arrived
Any → setError() → Error

Overlay Layers (bottom to top)

CameraX PreviewView — live camera feed
Compose Canvas — waypoint circles + route lines (scaled to AR offsets)
Position status overlay — OutOfRange/Unavailable center message
Top bar — back button + position confidence badge
Bottom card — distance remaining + next waypoint label + transition info

Coordinate Registration

On first position received:
  anchorOrigin = (lng₀, lat₀)
For each waypoint W(lng, lat):
  Δeast = haversine(lat₀, lng₀, lat₀, lng)
  Δnorth = haversine(lat₀, lng₀, lat, lng₀)
  AR position = (Δeast, floorIndex × 3m, -Δnorth)
Reanchor if user moves >2m from anchor origin

continue:[[]]
before:[[]]