[maps-sdk-android] Expose new queryRenderedRasterValue API in Android SDK (#9435)

## Summary
Exposes the `queryRenderedRasterValues` API to allow querying raster
values at a specific screen coordinate. This enables developers to
retrieve raster layer data at any point on the rendered map.
## Changes
### Core API (`maps-sdk`)
- **MapboxMap**: Added `queryRenderedRasterValues()` method with
callback-based API
- **NativeMapImpl**: Implemented bridge to native map functionality
- **Coroutine Support**: Added suspend function extension in
`MapFeatureQueryDelegateExt.kt`
- **Delegate Interface**: Extended `MapFeatureQueryDelegate` with new
query method
- **Compose Integration (`extension-compose`)": **MapState** -- Added
`queryRenderedRasterValues()` suspend function for Jetpack Compose
integration
### API Surface
- All API tracking files updated (metalava.txt and .api files for both
`maps-sdk`, `sdk-base`, and `extension-compose`)
  - Marked as `@MapboxExperimental` to indicate experimental status

  ### Test
  - queryRenderedRasterValues() test added

cc @mapbox/maps-android

cc @mapbox/sdk-ci

cc @mapbox/sdk-platform

GitOrigin-RevId: f3c0b087743b438c124178dd9b52befa77dcbadf

Author: lyydikoi

CHANGELOG.md

@@ -9,6 +9,7 @@ Mapbox welcomes participation and contributions from everyone.
 ## Features ✨ and improvements 🏁
 * Introduce experimental `queryRenderedRasterValues` API for querying the rendered raster array value at a point on the map.
 * Introduce new `AnnotationConfig#slotName` property to allow to specify a slot to position annotation layer.
+* Introduce experimental `queryRenderedRasterValues` API for querying the rendered raster values on the map at a specific screen coordinate.
 
 ## Bug fixes 🐞
 * Fix rare scenario where map render surface size was wrong.

extension-compose/api/Release/metalava.txt

@@ -63,6 +63,7 @@ package com.mapbox.maps.extension.compose {
     method @com.mapbox.maps.MapboxExperimental public suspend <FF extends com.mapbox.maps.interactions.FeaturesetFeature<?>> Object? queryRenderedFeatures(com.mapbox.maps.interactions.TypedFeaturesetDescriptor<?,FF> descriptor, com.mapbox.maps.RenderedQueryGeometry? geometry = null, com.mapbox.maps.extension.style.expressions.generated.Expression? filter = null, kotlin.coroutines.Continuation<? super java.util.List<? extends FF>> = null);
     method @com.mapbox.maps.MapboxExperimental public suspend <FF extends com.mapbox.maps.interactions.FeaturesetFeature<?>> Object? queryRenderedFeatures(com.mapbox.maps.interactions.TypedFeaturesetDescriptor<?,FF> descriptor, com.mapbox.maps.RenderedQueryGeometry? geometry = null, kotlin.coroutines.Continuation<? super java.util.List<? extends FF>> = null);
     method @com.mapbox.maps.MapboxExperimental public suspend <FF extends com.mapbox.maps.interactions.FeaturesetFeature<?>> Object? queryRenderedFeatures(com.mapbox.maps.interactions.TypedFeaturesetDescriptor<?,FF> descriptor, kotlin.coroutines.Continuation<? super java.util.List<? extends FF>> = null);
+    method @com.mapbox.maps.MapboxExperimental public suspend Object? queryRenderedRasterValues(com.mapbox.maps.ScreenCoordinate coordinate, com.mapbox.maps.RenderedRasterQueryOptions options, kotlin.coroutines.Continuation<? super com.mapbox.bindgen.Expected<java.lang.String,com.mapbox.maps.QueriedRasterValues>>);
     method @com.mapbox.maps.MapboxExperimental public suspend <FS extends com.mapbox.maps.interactions.FeatureState, FSK extends com.mapbox.maps.interactions.FeatureStateKey<FS>> Object? removeFeatureState(com.mapbox.maps.interactions.FeaturesetFeature<FS> featuresetFeature, FSK? stateKey = null, kotlin.coroutines.Continuation<? super com.mapbox.bindgen.Expected<java.lang.String,com.mapbox.bindgen.None>> = null);
     method @com.mapbox.maps.MapboxExperimental public suspend <FS extends com.mapbox.maps.interactions.FeatureState, FSK extends com.mapbox.maps.interactions.FeatureStateKey<FS>> Object? removeFeatureState(com.mapbox.maps.interactions.FeaturesetFeature<FS> featuresetFeature, kotlin.coroutines.Continuation<? super com.mapbox.bindgen.Expected<java.lang.String,com.mapbox.bindgen.None>> = null);
     method @com.mapbox.maps.MapboxExperimental public suspend Object? resetFeatureStates(com.mapbox.maps.interactions.TypedFeaturesetDescriptor<?,?> descriptor, kotlin.coroutines.Continuation<? super com.mapbox.bindgen.Expected<java.lang.String,com.mapbox.bindgen.None>>);

extension-compose/api/extension-compose.api

@@ -86,6 +86,7 @@ public final class com/mapbox/maps/extension/compose/MapState {
 	public final fun queryRenderedFeatures (Lcom/mapbox/maps/interactions/TypedFeaturesetDescriptor;Lcom/mapbox/maps/RenderedQueryGeometry;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public final fun queryRenderedFeatures (Lcom/mapbox/maps/interactions/TypedFeaturesetDescriptor;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static synthetic fun queryRenderedFeatures$default (Lcom/mapbox/maps/extension/compose/MapState;Lcom/mapbox/maps/interactions/TypedFeaturesetDescriptor;Lcom/mapbox/maps/RenderedQueryGeometry;Lcom/mapbox/maps/extension/style/expressions/generated/Expression;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
+	public final fun queryRenderedRasterValues (Lcom/mapbox/maps/ScreenCoordinate;Lcom/mapbox/maps/RenderedRasterQueryOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public final fun removeFeatureState (Lcom/mapbox/maps/interactions/FeaturesetFeature;Lcom/mapbox/maps/interactions/FeatureStateKey;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public final fun removeFeatureState (Lcom/mapbox/maps/interactions/FeaturesetFeature;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static synthetic fun removeFeatureState$default (Lcom/mapbox/maps/extension/compose/MapState;Lcom/mapbox/maps/interactions/FeaturesetFeature;Lcom/mapbox/maps/interactions/FeatureStateKey;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;

extension-compose/src/main/java/com/mapbox/maps/extension/compose/MapState.kt

@@ -22,11 +22,13 @@ import com.mapbox.maps.MapOptions
 import com.mapbox.maps.MapView
 import com.mapbox.maps.MapboxExperimental
 import com.mapbox.maps.MapboxMap
+import com.mapbox.maps.QueriedRasterValues
 import com.mapbox.maps.QueriedRenderedFeature
 import com.mapbox.maps.RenderFrameFinished
 import com.mapbox.maps.RenderFrameStarted
 import com.mapbox.maps.RenderedQueryGeometry
 import com.mapbox.maps.RenderedQueryOptions
+import com.mapbox.maps.RenderedRasterQueryOptions
 import com.mapbox.maps.ResourceRequest
 import com.mapbox.maps.ScreenBox
 import com.mapbox.maps.ScreenCoordinate
@@ -44,6 +46,7 @@ import com.mapbox.maps.coroutine.mapIdleEvents
 import com.mapbox.maps.coroutine.mapLoadedEvents
 import com.mapbox.maps.coroutine.mapLoadingErrorEvents
 import com.mapbox.maps.coroutine.queryRenderedFeatures
+import com.mapbox.maps.coroutine.queryRenderedRasterValues
 import com.mapbox.maps.coroutine.renderFrameFinishedEvents
 import com.mapbox.maps.coroutine.renderFrameStartedEvents
 import com.mapbox.maps.coroutine.resourceRequestEvents
@@ -280,6 +283,21 @@ public class MapState internal constructor(initialGesturesSettings: GesturesSett
     }
   }
 
+  /**
+   * Queries the map for rendered raster values at a specific coordinate.
+   *
+   * @param coordinate The position on the screen to query.
+   * @param options The options for configuring the rendered raster value query.
+   *
+   * @return [QueriedRasterValues] containing raster values or a string describing an error.
+   */
+  @MapboxExperimental
+  public suspend fun queryRenderedRasterValues(
+    coordinate: ScreenCoordinate,
+    options: RenderedRasterQueryOptions
+  ): Expected<String, QueriedRasterValues> =
+    mapboxMapFlow.filterNotNull().first().queryRenderedRasterValues(coordinate, options)
+
   /**
    * Gets the state map of a feature from a featureset asynchronously.
    *

maps-sdk/api/Release/metalava.txt

@@ -260,6 +260,7 @@ package com.mapbox.maps {
     method @com.mapbox.maps.MapboxExperimental public <FF extends com.mapbox.maps.interactions.FeaturesetFeature<?>> com.mapbox.common.Cancelable queryRenderedFeatures(com.mapbox.maps.interactions.TypedFeaturesetDescriptor<?,FF> descriptor, com.mapbox.maps.RenderedQueryGeometry? geometry = null, com.mapbox.bindgen.Value? filter = null, com.mapbox.maps.interactions.QueryRenderedFeaturesetFeaturesCallback<FF> callback);
     method @com.mapbox.maps.MapboxExperimental public <FF extends com.mapbox.maps.interactions.FeaturesetFeature<?>> com.mapbox.common.Cancelable queryRenderedFeatures(com.mapbox.maps.interactions.TypedFeaturesetDescriptor<?,FF> descriptor, com.mapbox.maps.RenderedQueryGeometry? geometry = null, com.mapbox.maps.interactions.QueryRenderedFeaturesetFeaturesCallback<FF> callback);
     method @com.mapbox.maps.MapboxExperimental public <FF extends com.mapbox.maps.interactions.FeaturesetFeature<?>> com.mapbox.common.Cancelable queryRenderedFeatures(com.mapbox.maps.interactions.TypedFeaturesetDescriptor<?,FF> descriptor, com.mapbox.maps.interactions.QueryRenderedFeaturesetFeaturesCallback<FF> callback);
+    method @com.mapbox.maps.MapboxExperimental public com.mapbox.common.Cancelable queryRenderedRasterValues(com.mapbox.maps.ScreenCoordinate coordinate, com.mapbox.maps.RenderedRasterQueryOptions options, com.mapbox.maps.QueryRenderedRasterValuesCallback callback);
     method public com.mapbox.common.Cancelable querySourceFeatures(String sourceId, com.mapbox.maps.SourceQueryOptions options, com.mapbox.maps.QuerySourceFeaturesCallback callback);
     method public void reduceMemoryUse();
     method public com.mapbox.common.Cancelable removeFeatureState(String sourceId, String? sourceLayerId, String featureId, String? stateKey, com.mapbox.maps.FeatureStateOperationCallback callback);
@@ -570,6 +571,7 @@ package com.mapbox.maps.coroutine {
 
   public final class MapFeatureQueryDelegateExtKt {
     method @kotlin.jvm.JvmSynthetic public static suspend com.mapbox.bindgen.Expected<java.lang.String,java.util.List<? extends com.mapbox.maps.QueriedRenderedFeature>>! queryRenderedFeatures(com.mapbox.maps.plugin.delegates.MapFeatureQueryDelegate, com.mapbox.maps.RenderedQueryGeometry geometry, com.mapbox.maps.RenderedQueryOptions options);
+    method @com.mapbox.maps.MapboxExperimental @kotlin.jvm.JvmSynthetic public static suspend com.mapbox.bindgen.Expected<java.lang.String,com.mapbox.maps.QueriedRasterValues>! queryRenderedRasterValues(com.mapbox.maps.plugin.delegates.MapFeatureQueryDelegate, com.mapbox.maps.ScreenCoordinate coordinate, com.mapbox.maps.RenderedRasterQueryOptions options);
     method @kotlin.jvm.JvmSynthetic public static suspend com.mapbox.bindgen.Expected<java.lang.String,java.util.List<? extends com.mapbox.maps.QueriedSourceFeature>>! querySourceFeatures(com.mapbox.maps.plugin.delegates.MapFeatureQueryDelegate, String sourceId, com.mapbox.maps.SourceQueryOptions options);
   }
 
@@ -651,7 +653,7 @@ package com.mapbox.maps.renderer {
     method @com.mapbox.maps.renderer.RenderThread public void onFpsChanged(double fps);
   }
 
-  @kotlin.annotation.MustBeDocumented @kotlin.annotation.Retention(kotlin.annotation.AnnotationRetention.SOURCE) @kotlin.annotation.Target(allowedTargets={kotlin.annotation.AnnotationTarget.FUNCTION, kotlin.annotation.AnnotationTarget.PROPERTY_GETTER, kotlin.annotation.AnnotationTarget.PROPERTY_SETTER, kotlin.annotation.AnnotationTarget.CONSTRUCTOR, kotlin.annotation.AnnotationTarget.CLASS}) public @interface RenderThread {
+  @kotlin.annotation.MustBeDocumented @kotlin.annotation.Retention(kotlin.annotation.AnnotationRetention.SOURCE) @kotlin.annotation.Target(allowedTargets={kotlin.annotation.AnnotationTarget.FUNCTION, kotlin.annotation.AnnotationTarget.PROPERTY_GETTER, kotlin.annotation.AnnotationTarget.PROPERTY_SETTER, kotlin.annotation.AnnotationTarget.PROPERTY, kotlin.annotation.AnnotationTarget.CONSTRUCTOR, kotlin.annotation.AnnotationTarget.CLASS}) public @interface RenderThread {
   }
 
   @com.mapbox.maps.MapboxExperimental public final class RenderThreadStats {

maps-sdk/api/maps-sdk.api

@@ -270,6 +270,7 @@ public final class com/mapbox/maps/MapboxMap : com/mapbox/maps/MapboxStyleManage
 	public final fun queryRenderedFeatures (Lcom/mapbox/maps/interactions/TypedFeaturesetDescriptor;Lcom/mapbox/maps/RenderedQueryGeometry;Lcom/mapbox/maps/interactions/QueryRenderedFeaturesetFeaturesCallback;)Lcom/mapbox/common/Cancelable;
 	public final fun queryRenderedFeatures (Lcom/mapbox/maps/interactions/TypedFeaturesetDescriptor;Lcom/mapbox/maps/interactions/QueryRenderedFeaturesetFeaturesCallback;)Lcom/mapbox/common/Cancelable;
 	public static synthetic fun queryRenderedFeatures$default (Lcom/mapbox/maps/MapboxMap;Lcom/mapbox/maps/interactions/TypedFeaturesetDescriptor;Lcom/mapbox/maps/RenderedQueryGeometry;Lcom/mapbox/bindgen/Value;Lcom/mapbox/maps/interactions/QueryRenderedFeaturesetFeaturesCallback;ILjava/lang/Object;)Lcom/mapbox/common/Cancelable;
+	public fun queryRenderedRasterValues (Lcom/mapbox/maps/ScreenCoordinate;Lcom/mapbox/maps/RenderedRasterQueryOptions;Lcom/mapbox/maps/QueryRenderedRasterValuesCallback;)Lcom/mapbox/common/Cancelable;
 	public fun querySourceFeatures (Ljava/lang/String;Lcom/mapbox/maps/SourceQueryOptions;Lcom/mapbox/maps/QuerySourceFeaturesCallback;)Lcom/mapbox/common/Cancelable;
 	public final fun reduceMemoryUse ()V
 	public final fun removeFeatureState (Lcom/mapbox/maps/interactions/FeaturesetFeature;)Lcom/mapbox/common/Cancelable;
@@ -637,6 +638,7 @@ public final class com/mapbox/maps/coroutine/MapCameraManagerDelegateExtKt {
 
 public final class com/mapbox/maps/coroutine/MapFeatureQueryDelegateExtKt {
 	public static final synthetic fun queryRenderedFeatures (Lcom/mapbox/maps/plugin/delegates/MapFeatureQueryDelegate;Lcom/mapbox/maps/RenderedQueryGeometry;Lcom/mapbox/maps/RenderedQueryOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static final synthetic fun queryRenderedRasterValues (Lcom/mapbox/maps/plugin/delegates/MapFeatureQueryDelegate;Lcom/mapbox/maps/ScreenCoordinate;Lcom/mapbox/maps/RenderedRasterQueryOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static final synthetic fun querySourceFeatures (Lcom/mapbox/maps/plugin/delegates/MapFeatureQueryDelegate;Ljava/lang/String;Lcom/mapbox/maps/SourceQueryOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 }
 

maps-sdk/src/main/java/com/mapbox/maps/MapboxMap.kt

@@ -1362,6 +1362,24 @@ class MapboxMap :
     return nativeMap.querySourceFeatures(sourceId, options, callback)
   }
 
+  /**
+   * Queries the map for rendered raster values at a specific coordinate.
+   *
+   * @param coordinate The position on the screen to query.
+   * @param options The options for configuring the rendered raster value query.
+   * @param callback Callback invoked when the query completes
+   * @return A `cancelable` object that could be used to cancel the pending query.
+   */
+  @MapboxExperimental
+  override fun queryRenderedRasterValues(
+    coordinate: ScreenCoordinate,
+    options: RenderedRasterQueryOptions,
+    callback: QueryRenderedRasterValuesCallback
+  ): Cancelable {
+    checkNativeMap("queryRenderedRasterValues", false)
+    return nativeMap.queryRenderedRasterValues(coordinate, options, callback)
+  }
+
   /**
    * In some cases querying source / render features is expected to be a blocking operation
    * e.g. performing this action on map click. In this case in order to avoid deadlock on main

maps-sdk/src/main/java/com/mapbox/maps/NativeMapImpl.kt

@@ -496,6 +496,13 @@ internal class NativeMapImpl(val map: Map) {
     callback: QuerySourceFeaturesCallback
   ): Cancelable = map.querySourceFeatures(sourceId, options, callback)
 
+  @MapboxExperimental
+  fun queryRenderedRasterValues(
+    coordinate: ScreenCoordinate,
+    options: RenderedRasterQueryOptions,
+    callback: QueryRenderedRasterValuesCallback
+  ): Cancelable = map.queryRenderedRasterValues(coordinate, options, callback)
+
   fun queryFeatureExtensions(
     sourceIdentifier: String,
     feature: Feature,

maps-sdk/src/main/java/com/mapbox/maps/coroutine/MapFeatureQueryDelegateExt.kt

@@ -1,10 +1,14 @@
 package com.mapbox.maps.coroutine
 
 import com.mapbox.bindgen.Expected
+import com.mapbox.maps.MapboxExperimental
+import com.mapbox.maps.QueriedRasterValues
 import com.mapbox.maps.QueriedRenderedFeature
 import com.mapbox.maps.QueriedSourceFeature
 import com.mapbox.maps.RenderedQueryGeometry
 import com.mapbox.maps.RenderedQueryOptions
+import com.mapbox.maps.RenderedRasterQueryOptions
+import com.mapbox.maps.ScreenCoordinate
 import com.mapbox.maps.SourceQueryOptions
 import com.mapbox.maps.plugin.delegates.MapFeatureQueryDelegate
 import com.mapbox.maps.suspendMapboxCancellableCoroutine
@@ -45,4 +49,24 @@ suspend fun MapFeatureQueryDelegate.querySourceFeatures(
 ): Expected<String, List<QueriedSourceFeature>> =
   suspendMapboxCancellableCoroutine { continuation ->
     querySourceFeatures(sourceId, options, continuation::resume)
+  }
+
+/**
+ * Queries the map for rendered raster values at a specific coordinate.
+ *
+ * This is a suspend function variant of [MapFeatureQueryDelegate.queryRenderedRasterValues].
+ *
+ * @param coordinate The position on the screen to query.
+ * @param options The options for configuring the rendered raster value query.
+ *
+ * @return [QueriedRasterValues] containing raster values or a string describing an error.
+ */
+@MapboxExperimental
+@JvmSynthetic
+suspend fun MapFeatureQueryDelegate.queryRenderedRasterValues(
+  coordinate: ScreenCoordinate,
+  options: RenderedRasterQueryOptions,
+): Expected<String, QueriedRasterValues> =
+  suspendMapboxCancellableCoroutine { continuation ->
+    queryRenderedRasterValues(coordinate, options, continuation::resume)
   }

maps-sdk/src/test/java/com/mapbox/maps/MapboxMapTest.kt

@@ -1573,6 +1573,15 @@ class MapboxMapTest {
     verify { nativeMap.querySourceFeatures("id", querySourceOptions, querySourceCallback) }
   }
 
+  @Test
+  fun queryRenderedRasterValues() {
+    val coordinate = mockk<ScreenCoordinate>()
+    val options = mockk<RenderedRasterQueryOptions>()
+    val callback = mockk<QueryRenderedRasterValuesCallback>()
+    mapboxMap.queryRenderedRasterValues(coordinate, options, callback)
+    verify { nativeMap.queryRenderedRasterValues(coordinate, options, callback) }
+  }
+
   @Test
   fun queryRenderedFeaturesGeometry() {
     val queryCallback = mockk<QueryRenderedFeaturesCallback>()