refactor(path-following): clean MVVM architecture, custom 3D gesture engine, and modern UI controls

[dkhawk]

PR Description: Refactor Path Following Demo Across Kotlin Views, Java Views, and Compose

Target Branch: feature/new_features_with_0.2.2_sdk
Suggested Reviewer: @LoyalAbbas

---

🎯 Executive Summary

This PR updates the Path Following sample across all three supported application targets (Kotlin Views, Java Views, and Jetpack Compose).

It introduces a clean, testable MVVM architecture with clear separation of concerns, replaces the generic map gesture listener with a custom touch gesture controller tailored for tracking camera manipulation, and modernizes the control panel with Material 3 components, speed preset chips, sheet swipe gestures, and idle auto-fade.

---

💡 The "Why" (Motivation & Design Rationale)

1. Separation of Concerns & Clean Architecture

• The Motivation: Previously, kinematic progression math, lookahead heading trigonometry, altitude offset computations, dynamic polyline geometry generation, and Android UI lifecycle callbacks were co-located inside single Activity classes. This led to duplicated logic across Kotlin, Java, and Compose, increased potential for Binder IPC pressure, and precluded unit testing the core domain calculations without Android device dependencies.
• The Architectural Solution:
  • Pure Kotlin Domain State Machine (PathPlaybackController): Extracted all business logic, kinematic time integration, wrapping math, and state transformations into a pure, dependency-free Kotlin class.
  • MVVM State Layer (PathFollowingViewModel): Exposes an immutable PathPlaybackState flow (and LiveData for Java), ensuring unidirectional data flow and lifecycle safety.
  • Decoupled Progress Polyline Lifecycle: Progress polylines are driven strictly by time and kinematic distance along the route. Camera adjustments and touch gestures do not trigger polyline regeneration.
  • Hardware VSYNC Ticker: Replaced timer loops with Choreographer.FrameCallback in Views and withFrameMillis in Compose for smooth 60/120fps motion.

2. Custom Touch Gesture Controller (PathTouchHandler)

• The Motivation: The standard Google Maps gesture controller is designed for free-roaming 2D/3D map exploration. During path following, free panning detaches the camera from the vehicle tracking pose.
• The Solution: Disabled default map gestures in favor of a custom touch gesture handler tailored for following camera controls:
  • 1-Finger Vertical Sweep: Adjusts camera pitch/tilt ($0^\circ$ top-down to $85^\circ$ horizon) relative to the vehicle while keeping the camera locked onto the path.
  • 1-Finger Horizontal Sweep: Orbits camera heading around the path.
  • 2-Finger Pinch: Adjusts camera range ($20\text{m} - 5,000\text{m}$) with $0.65\times$ exponential damping to eliminate jumpiness.
  • Tiered Long-Press Acceleration: Holding the screen accelerates playback ($2\times$ at $0.5\text{s} \rightarrow 5\times$ Warp Speed at $2.0\text{s}$), reverting upon release.
  • Double-Tap Shuttle Controls:
    • Double-tap & hold Right $\rightarrow +5\times$ Fast-Forward along route.
    • Double-tap & hold Left $\rightarrow -5\times$ Rewind backwards along route.
    • Quick double-tap $\rightarrow$ Jumps $\pm 10%$ ahead or back along the path.

3. UI/UX Modernization & Controls

• Persistent Playback Header: Play/Pause and progress scrubbing remain permanently accessible in a slim top bar even when the settings panel is collapsed.
• 1-Tap Speed Preset Chips: Added [ 0.5x | 1x | 2x | 3x | 5x ] Material filter chips for instant speed adjustment without opening sliders.
• Touch Target Accessibility ($48\text{dp}$): Upgraded all buttons to standard $48\text{dp}\times 48\text{dp}$ touch targets, added a visual pill drag handle, and made the whole header clickable.
• Sheet Swipe Gestures: Added Swipe Down to Collapse and Swipe Up to Expand gestures on the control sheet.
• Window-Level 3.5s Idle Auto-Fade: The control panel smoothly fades down to $35%$ opacity when inactive, giving a clean full-screen view of the map, and instantly wakes to $100%$ on any touch.
• Comprehensive In-App Help Dialog: Accessible ? button with categorized instructions explaining camera gestures, speed controls, and sheet interactions.

---

📦 File Manifest (The "What")

Maps3DSamples/
├── ApiDemos/
│   ├── common/
│   │   ├── src/main/java/com/example/maps3d/common/
│   │   │   ├── PathData.kt                     # Shared Urban (SF) & Rural (Marin) GPS datasets
│   │   │   ├── PathEngine.kt                   # Mathematical utilities for distance & slicing
│   │   │   ├── PathPlaybackController.kt       # Pure domain state machine (kinematics, gestures, speeds)
│   │   │   ├── PathFollowingViewModel.kt       # MVVM ViewModel exposing immutable PathPlaybackState
│   │   │   └── PathTouchHandler.kt             # Custom Views touch gesture listener (tilt, orbit, zoom, shuttle)
│   │   ├── src/main/res/
│   │   │   ├── drawable/drag_handle_bar.xml    # Pill drag handle affordance
│   │   │   ├── drawable/help_outline_24px.xml  # Material help outline icon
│   │   │   ├── layout/activity_path_following.xml # Modernized layout with persistent bar & speed chips
│   │   │   └── values/strings.xml              # Help dialog strings and localized formats
│   │   └── src/test/java/com/example/maps3d/common/
│   │       └── PathPlaybackControllerTest.kt   # JVM unit tests (kinematics, rewind, skip, gestures)
│   ├── kotlin-app/
│   │   └── src/main/java/com/example/maps3dkotlin/pathfollowing/
│   │       └── PathFollowingActivity.kt        # Kotlin Views implementation with MVVM & PathTouchHandler
│   └── java-app/
│       └── src/main/java/com/example/maps3djava/pathfollowing/
│           └── PathFollowingActivity.java      # Java Views implementation with LiveData & PathTouchHandler
└── ComposeDemos/
    └── app/
        ├── build.gradle.kts                    # Desugaring & common dependency
        └── src/main/java/com/example/composedemos/pathfollowing/
            └── PathFollowingActivity.kt        # Jetpack Compose implementation with custom pointerInput gestures

---

🧪 Verification Matrix

• JVM Unit Tests: ./gradlew :Maps3DSamples:ApiDemos:common:testDebugUnitTest passes 100%.
• Spotless Formatting: Verified clean with ./gradlew spotlessApply.
• Live Device Testing: Verified and synchronized across Kotlin Views, Java Views, and Jetpack Compose on Pixel 6.

[LoyalAbbas]

LGTM