feat: Add timeout to waitUntilTheMapIsSteady animation step

This commit enhances the `waitUntilTheMapIsSteady` animation step by adding an optional timeout parameter. This prevents an animation from getting stuck indefinitely if the map never reaches a steady state.

Key changes:

- **`WaitUntilTheMapIsSteadyStep`:** Converted from a `data object` to a `data class` to accept a `timeoutMillis` parameter. The animation string command is now `waitUntilTheMapIsSteady=timeout=<milliseconds>`.
- **`Map3dViewModel`:** The `awaitMapSteady()` function now takes a `timeoutMillis` argument and uses `withTimeout` to enforce the limit, logging a warning if the timeout is exceeded.
- **`ScenarioMapper`:** The animation parser is updated to read the optional `timeout` value for the `waitUntilTheMapIsSteady` command. The parameterless version is still supported and will wait indefinitely.
- **`ScenarioData`:** Updated existing scenarios to use a 1000ms timeout for the `waitUntilTheMapIsSteady` step.

Author: dkhawk

Maps3DSamples/advanced/app/src/main/java/com/example/advancedmaps3dsamples/common/Map3dViewModel.kt

@@ -44,12 +44,14 @@ import kotlinx.coroutines.channels.awaitClose
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.TimeoutCancellationException
 import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.callbackFlow
 import kotlinx.coroutines.flow.filterNotNull
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.withTimeout
 import kotlin.time.Duration
 
 abstract class Map3dViewModel : ViewModel() {
@@ -304,10 +306,22 @@ abstract class Map3dViewModel : ViewModel() {
    * Suspends until the map has entered a steady state, meaning it is not moving and has
    * finished loading. This is useful to ensure that camera animations start from a stable
    * and predictable state.
+   *
+   * @param timeoutMillis The maximum time to wait in milliseconds. A value of 0 means no timeout.
    */
-  suspend fun awaitMapSteady() {
-    Log.d("Map3dViewModel", "awaitMapSteady: start")
-    isMapSteady.first { it }
+  suspend fun awaitMapSteady(timeoutMillis: Long) {
+    Log.d("Map3dViewModel", "awaitMapSteady: start with timeout $timeoutMillis")
+    if (timeoutMillis > 0) {
+      try {
+        withTimeout(timeoutMillis) {
+          isMapSteady.first { it }
+        }
+      } catch (e: TimeoutCancellationException) {
+        Log.w("Map3dViewModel", "awaitMapSteady timed out after $timeoutMillis ms")
+      }
+    } else {
+      isMapSteady.first { it }
+    }
     Log.d("Map3dViewModel", "awaitMapSteady: done")
   }
 

Maps3DSamples/advanced/app/src/main/java/com/example/advancedmaps3dsamples/scenarios/Animations.kt

@@ -31,10 +31,12 @@ data class DelayStep(val durationMillis: Long) : AnimationStep {
 /**
  * An [AnimationStep] that waits until the map is fully loaded and idle before proceeding
  * to the next step in the animation sequence.
+ *
+ * @param timeoutMillis The maximum time to wait in milliseconds. A value of 0 means no timeout.
  */
-data object WaitUntilTheMapIsSteadyStep : AnimationStep {
+data class WaitUntilTheMapIsSteadyStep(val timeoutMillis: Long = 0) : AnimationStep {
   override suspend fun invoke(viewModel: ScenariosViewModel) {
-    viewModel.awaitMapSteady()
+    viewModel.awaitMapSteady(timeoutMillis)
   }
 }
 

Maps3DSamples/advanced/app/src/main/java/com/example/advancedmaps3dsamples/scenarios/ScenarioData.kt

@@ -290,11 +290,10 @@ val scenarios =
             initialState =
                 "mode=satellite;camera=lat=36.10145879,lng=-112.10555998,alt=774.39,hdg=33.198,tilt=74.036,range=9180.62",
             animationString =
-                "waitUntilTheMapIsSteady;" +
+                "waitUntilTheMapIsSteady=3000;" +
                 "delay=dur=3000;" +
                         "flyTo=lat=38.743502,lng=-109.499374,alt=1467,hdg=-10.4,tilt=58.1,range=138.2,dur=3500;" +
-                        "delay=dur=2000;" +
-                        "waitUntilTheMapIsSteady;" +
+                        "waitUntilTheMapIsSteady=timeout=3000;" +
                         "flyAround=lat=38.743502,lng=-109.499374,alt=1467,hdg=-10.4,tilt=58.1,range=138.2,dur=6000,count=2;" +
                         "delay=dur=2000",
         ),
@@ -356,7 +355,7 @@ val scenarios =
                         "waitUntilTheMapIsSteady;" +
                         "flyTo=lat=21.306388,lng=-157.859271,alt=6.0,hdg=63,tilt=58,range=689,dur=2500;" +
                         "delay=dur=750;" +
-                        "waitUntilTheMapIsSteady;" +
+                        "waitUntilTheMapIsSteady=timeout=1000;" +
                         "flyTo=lat=21.276715,lng=-157.827153,alt=63.3,hdg=16,tilt=65,range=2121,dur=3500;" +
                         "delay=dur=1000;" +
                         "waitUntilTheMapIsSteady;" +

Maps3DSamples/advanced/app/src/main/java/com/example/advancedmaps3dsamples/scenarios/ScenarioMapper.kt

@@ -167,14 +167,16 @@ fun String.toAnimation(): List<AnimationStep> {
                     "flyto" -> add(FlyToStep(value.toFlyTo()))
                     "delay" -> add(DelayStep(value.toDelay()))
                     "flyaround" -> add(FlyAroundStep(value.toFlyAround()))
-
+                    "waitUntilTheMapIsSteady" -> {
+                        add(WaitUntilTheMapIsSteadyStep(value.toLong()))
+                    }
                     else -> Log.w(TAG, "Unsupported animation step type: $key")
                 }
             } else {
                 when (trimmedStep.lowercase()) {
                     "waituntilthemapissteady" -> {
                         Log.d("ScenarioMapper", "add(WaitUntilTheMapIsSteadyStep)")
-                        add(WaitUntilTheMapIsSteadyStep)
+                        add(WaitUntilTheMapIsSteadyStep(0L))
                     }
                     else -> Log.w(TAG, "Ignoring invalid animation step format: $step")
                 }