refactor(samples): polish 0.2.2 showcase samples with collapsible UI, auto-fade, and literate docs

[dkhawk]

Note

Stacked PR: This pull request is branched off of and targets PR #50 (feature/new_features_with_0.2.2_sdk). It contains reviews, UX refinements, and literate programming enhancements for the 0.2.2 showcase samples.

Summary

This pull request provides comprehensive polish, UI consistency, and literate programming documentation across the Google Maps 3D 0.2.2 showcase samples in Java and Kotlin:

1. Routes API (RoutesActivity):

   • Converted to standard control_panel_routes.xml overlay on activity_common_map.xml.
   • Added animated card expand/collapse (TransitionManager), 3-second touch-aware idle auto-fade, and toValidCamera bounds enforcement.
   • Comprehensive literate docstrings explaining background directions fetching, polyline decoding, 3D glTF model heading updates, and 60fps tracking loop.

2. Roadmap Mode (RoadmapModeActivity):

   • Standardized collapsible header layout for Map Mode selection (ROADMAP, HYBRID, SATELLITE).
   • Integrated touch-aware auto-fade timer and literate documentation.
   • Verified on device.

3. Field of View (FieldOfViewActivity) & Data Visualization (DataVisualizationActivity):

   • FOV: Optical dolly-zoom physics (15° to 120°), focal length presets, collapsible header, auto-fade. Verified on device.
   • Data Viz: Multi-tier elevation palette for coastal flood simulation with extruded 3D polygons, play/pause scrub controls, and auto-fade.

4. Advanced Camera Animation (AdvancedCameraAnimationActivity) & Path Following (PathFollowingActivity):

   • Camera Animation: Modular step engine (FlyToStep, DwellStep, OrbitStep, KeyframeStep), collapsible status card.
   • Path Following: Drone perspective flight, clamped-to-ground defaults, dual polyline elevation layering (inner route on top of base route), and auto-fade.

---

Code Health & Verification

• Spotless Formatting: Fully verified via ./gradlew spotlessCheck.
• Compilation: Verified via ./gradlew test assembleDebug.

[kikoso]

See inline comments below.

[kikoso]

Assuming a fixed 16ms (frameDurationMs) can cause speed drift under frame drops or on displays with variable/higher refresh rates (90Hz / 120Hz).

Consider measuring actual elapsed wall-clock delta time dt = (now - lastTime) / 1000.0 (as done in RoutesActivity.kt):

val now = System.currentTimeMillis()
val dt = (now - lastTime) / 1000.0
lastTime = now
elapsedDistance += followSpeedMps * dt

[dkhawk]

Fixed in 4e290f3! Integrated wall-clock delta time (dt = (now - lastTime) / 1000.0) across both Kotlin and Java PathFollowingActivity implementations.

[kikoso]

When pauseTour() is called here and the user later clicks Play to unpause, startOrResumeTour() invokes tourAnimator.start(googleMap3D, ...) which resets currentStepIndex = 0 and restarts the tour from Step 1 instead of resuming.

Consider checking whether to resume or start:

if (tourAnimator == null) {
  tourAnimator = buildTourAnimator();
  tourAnimator.start(googleMap3D, animatorListener);
} else if (tourAnimator.getCurrentStepIndex() < tourAnimator.getSteps().size()) {
  tourAnimator.resume();
} else {
  tourAnimator.start(googleMap3D, animatorListener);
}

[dkhawk]

Fixed in 4e290f3! Updated startOrResumeTour() to resume an in-progress tour via tourAnimator.resume() instead of restarting from Step 1.

[kikoso]

Consider adding onPause() to call stopSimulation() and fadeHandler.removeCallbacks(fadeOutRunnable).

Currently, if the user backgrounds the app, answers a phone call, or locks the device, the simulation coroutine loop continues running and triggering 3D polygon redraws in the background until the Activity is destroyed.

[dkhawk]

Fixed in 4e290f3! Added onPause() override in both Kotlin and Java DataVisualizationActivity implementations to stop the simulation and clean up fade callbacks.

[kikoso]

In FieldOfViewActivity and RoadmapModeActivity, collapsing is handled smoothly via TransitionManager.beginDelayedTransition(card) and toggling content.visibility = GONE / VISIBLE.

Consider adopting the same approach here instead of calculating translationY and display density manually. It simplifies the code and automatically adapts to varying screen sizes.

[dkhawk]

Fixed in 4e290f3! Standardized to TransitionManager.beginDelayedTransition(card) and cardContent.visibility = GONE / VISIBLE across both Kotlin and Java DataVisualizationActivity.