Add experimental LocationPuck3D.modelElevationReference property. (#2906)

Author: pengdev

CHANGELOG.md

@@ -13,6 +13,7 @@ Mapbox welcomes participation and contributions from everyone.
 ## Bug fixes 🐞
 * Mark `BackgroundLayer.backgroundPitchAlignment` as experimental.
 * Skip any map scroll (panning) if shove gesture is already in progress preventing camera flying away.
+* Introduce experimental `LocationPuck3D.modelElevationReference` property.
 
 # 11.9.0 December 18, 2024
 ## Breaking changes ⚠️

plugin-locationcomponent/src/main/java/com/mapbox/maps/plugin/locationcomponent/LayerSourceProvider.kt

@@ -45,7 +45,8 @@ internal object LayerSourceProvider {
       modelColor = locationModelLayerOptions.modelColor,
       modelColorExpression = locationModelLayerOptions.modelColorExpression?.let { Value.fromJson(it).take() },
       modelColorMixIntensity = locationModelLayerOptions.modelColorMixIntensity.toDouble(),
-      modelColorMixIntensityExpression = locationModelLayerOptions.modelColorMixIntensityExpression?.let { Value.fromJson(it).take() }
+      modelColorMixIntensityExpression = locationModelLayerOptions.modelColorMixIntensityExpression?.let { Value.fromJson(it).take() },
+      modelElevationReference = locationModelLayerOptions.modelElevationReference
     )
 
   fun getLocationIndicatorLayer() = LocationIndicatorLayerWrapper(LOCATION_INDICATOR_LAYER)

plugin-locationcomponent/src/main/java/com/mapbox/maps/plugin/locationcomponent/ModelLayerWrapper.kt

@@ -4,6 +4,7 @@ import androidx.annotation.RestrictTo
 import com.mapbox.bindgen.Value
 import com.mapbox.maps.MapboxExperimental
 import com.mapbox.maps.extension.style.utils.ColorUtils.colorIntToRgbaExpression
+import com.mapbox.maps.plugin.ModelElevationReference
 import com.mapbox.maps.plugin.ModelScaleMode
 
 @OptIn(MapboxExperimental::class)
@@ -26,6 +27,7 @@ internal class ModelLayerWrapper(
   modelColorExpression: Value?,
   modelColorMixIntensity: Double,
   modelColorMixIntensityExpression: Value?,
+  modelElevationReference: ModelElevationReference,
 ) : LocationLayerWrapper(layerId) {
   init {
     layerProperties["id"] = Value(layerId)
@@ -44,6 +46,7 @@ internal class ModelLayerWrapper(
     layerProperties["model-emissive-strength"] = modelEmissiveStrengthExpression ?: Value(modelEmissiveStrength)
     layerProperties["model-color"] = modelColorExpression ?: colorIntToRgbaExpression(modelColor)
     layerProperties["model-color-mix-intensity"] = modelColorMixIntensityExpression ?: Value(modelColorMixIntensity)
+    layerProperties["model-elevation-reference"] = Value(modelElevationReference.value)
   }
 
   private fun buildTransition(delay: Long, duration: Long): Value {
@@ -65,5 +68,7 @@ internal class ModelLayerWrapper(
 
   fun modelScaleMode(modelScaleMode: ModelScaleMode) = updateProperty("model-scale-mode", Value(modelScaleMode.value))
 
+  fun modelElevationReference(modelElevationReference: ModelElevationReference) = updateProperty("model-elevation-reference", Value(modelElevationReference.value))
+
   fun slot(slot: String?) = updateProperty("slot", Value(slot ?: ""))
 }

plugin-locationcomponent/src/main/java/com/mapbox/maps/plugin/locationcomponent/generated/LocationComponentAttributeParser.kt

@@ -100,5 +100,7 @@
     <public name="mapbox_locationComponentLocationPuckLocationPuck3DMaterialOverrides" type="attr" />
     <!-- The node overrides for the model. Default value: []. -->
     <public name="mapbox_locationComponentLocationPuckLocationPuck3DNodeOverrides" type="attr" />
+    <!-- Selects the base of the model. Some modes might require precomputed elevation data in the tileset. Default value: "ground". -->
+    <public name="mapbox_locationComponentLocationPuckLocationPuck3DModelElevationReference" type="attr" />
 </resources>
 <!-- End of generated file. -->

plugin-locationcomponent/src/main/res-public/values/public.xml

@@ -80,7 +80,12 @@
         <!-- Enable/Disable shadow receiving for the 3D location puck. Default value: true. -->
         <attr name="mapbox_locationComponentLocationPuckLocationPuck3DModelReceiveShadows" format="boolean"/>
         <!-- Defines scaling mode. Only applies to location-indicator type layers. Default value: "map". -->
-        <attr name="mapbox_locationComponentLocationPuckLocationPuck3DModelScaleMode" format="enum"/>
+        <attr name="mapbox_locationComponentLocationPuckLocationPuck3DModelScaleMode" format="enum">
+          <!-- Model is scaled so that it's always the same size relative to other map features. The property model-scale specifies how many meters each unit in the model file should cover. -->
+          <enum name="map" value="0"/>
+          <!-- Model is scaled so that it's always the same size on the screen. The property model-scale specifies how many pixels each unit in model file should cover. -->
+          <enum name="viewport" value="1"/>
+        </attr>
         <!-- Strength of the emission. There is no emission for value 0. For value 1.0, only emissive component (no shading) is displayed and values above 1.0 produce light contribution to surrounding area, for some of the parts (e.g. doors). Expressions that depend on measure-light are only supported as a global layer value (and not for each feature) when using GeoJSON or vector tile as the model layer source. Default value: 1. Value range: [0, 5] -->
         <attr name="mapbox_locationComponentLocationPuckLocationPuck3DModelEmissiveStrength" format="float"/>
         <!-- The emissive strength expression of the model, which will overwrite the default model emissive strength. -->
@@ -101,6 +106,13 @@
         <attr name="mapbox_locationComponentLocationPuckLocationPuck3DMaterialOverrides" format="reference"/>
         <!-- The node overrides for the model. Default value: []. -->
         <attr name="mapbox_locationComponentLocationPuckLocationPuck3DNodeOverrides" format="reference"/>
+        <!-- Selects the base of the model. Some modes might require precomputed elevation data in the tileset. Default value: "ground". -->
+        <attr name="mapbox_locationComponentLocationPuckLocationPuck3DModelElevationReference" format="enum">
+          <!-- Elevated rendering is enabled. Use this mode to elevate lines relative to the sea level. -->
+          <enum name="sea" value="0"/>
+          <!-- Elevated rendering is enabled. Use this mode to elevate lines relative to the ground's height below them. -->
+          <enum name="ground" value="1"/>
+        </attr>
     </declare-styleable>
 </resources>
 <!-- End of generated file. -->

plugin-locationcomponent/src/main/res/values/attrs.xml

@@ -70,6 +70,7 @@ class LayerSourceProviderTest {
         "model-cast-shadows" to true,
         "model-scale-transition" to hashMapOf("duration" to 0, "delay" to 0),
         "model-rotation-transition" to hashMapOf("duration" to 0, "delay" to 0),
+        "model-elevation-reference" to "ground",
         "model-emissive-strength" to 1.0,
         "model-color" to listOf("rgba", 255, 255, 255, 1.0),
         "model-color-mix-intensity" to 0.0,

plugin-locationcomponent/src/test/java/com/mapbox/maps/plugin/locationcomponent/LayerSourceProviderTest.kt

@@ -9,6 +9,7 @@ import com.mapbox.maps.MapboxExperimental
 import com.mapbox.maps.MapboxStyleManager
 import com.mapbox.maps.extension.style.utils.ColorUtils.colorIntToRgbaExpression
 import com.mapbox.maps.logE
+import com.mapbox.maps.plugin.ModelElevationReference
 import com.mapbox.maps.plugin.ModelScaleMode
 import com.mapbox.maps.plugin.locationcomponent.utils.take
 import io.mockk.Runs
@@ -47,7 +48,8 @@ class ModelLayerWrapperTest {
     modelColor = INITIAL_MODEL_COLOR,
     modelColorExpression = null,
     modelColorMixIntensity = INITIAL_MODEL_COLOR_MIX_INTENSITY,
-    modelColorMixIntensityExpression = null
+    modelColorMixIntensityExpression = null,
+    modelElevationReference = INITIAL_MODEL_ELEVATION_REFERENCE,
   )
   private val layerWithExpression = ModelLayerWrapper(
     layerId = MODEL_LAYER_ID,
@@ -66,7 +68,8 @@ class ModelLayerWrapperTest {
     modelColor = INITIAL_MODEL_COLOR,
     modelColorExpression = INITIAL_MODEL_COLOR_EXPRESSION,
     modelColorMixIntensity = INITIAL_MODEL_COLOR_MIX_INTENSITY,
-    modelColorMixIntensityExpression = INITIAL_MODEL_COLOR_MIX_INTENSITY_EXPRESSION
+    modelColorMixIntensityExpression = INITIAL_MODEL_COLOR_MIX_INTENSITY_EXPRESSION,
+    modelElevationReference = INITIAL_MODEL_ELEVATION_REFERENCE,
   )
   private val expected: Expected<String, None> = mockk(relaxed = true)
 
@@ -105,6 +108,7 @@ class ModelLayerWrapperTest {
         "model-emissive-strength" to INITIAL_MODEL_EMISSIVE_STENGTH,
         "model-color" to colorIntToRgbaExpression(INITIAL_MODEL_COLOR),
         "model-color-mix-intensity" to INITIAL_MODEL_COLOR_MIX_INTENSITY,
+        "model-elevation-reference" to INITIAL_MODEL_ELEVATION_REFERENCE.value,
       ).toValue(),
       layer.toValue(),
     )
@@ -130,6 +134,7 @@ class ModelLayerWrapperTest {
         "model-emissive-strength" to INITIAL_MODEL_EMISSIVE_STENGTH_EXPRESSION,
         "model-color" to INITIAL_MODEL_COLOR_EXPRESSION,
         "model-color-mix-intensity" to INITIAL_MODEL_COLOR_MIX_INTENSITY_EXPRESSION,
+        "model-elevation-reference" to INITIAL_MODEL_ELEVATION_REFERENCE.value,
       ).toValue(),
       layerWithExpression.toValue(),
     )
@@ -241,11 +246,26 @@ class ModelLayerWrapperTest {
     setModelScaleMode(ModelScaleMode.MAP)
   }
 
+  @Test
+  fun testModelElevationReferenceGround() {
+    setModelElevationReference(ModelElevationReference.GROUND)
+  }
+
+  @Test
+  fun testModelElevationReferenceSea() {
+    setModelElevationReference(ModelElevationReference.SEA)
+  }
+
   private fun setModelScaleMode(mode: ModelScaleMode) {
     layer.modelScaleMode(mode)
     verify { style.setStyleLayerProperty(MODEL_LAYER_ID, "model-scale-mode", Value(mode.value)) }
   }
 
+  private fun setModelElevationReference(reference: ModelElevationReference) {
+    layer.modelElevationReference(reference)
+    verify { style.setStyleLayerProperty(MODEL_LAYER_ID, "model-elevation-reference", Value(reference.value)) }
+  }
+
   companion object {
     private const val MODEL_LAYER_ID = "modelLayerId"
     private const val MODEL_SOURCE_ID = "modelSourceId"
@@ -266,6 +286,7 @@ class ModelLayerWrapperTest {
     """.trimIndent()
     ).take()
     private val INITIAL_SCALE_MODE = ModelScaleMode.VIEWPORT
+    private val INITIAL_MODEL_ELEVATION_REFERENCE = ModelElevationReference.GROUND
     private val INITIAL_MODEL_EMISSIVE_STENGTH = 1.0
     private val INITIAL_MODEL_EMISSIVE_STENGTH_EXPRESSION = Value.fromJson(
       """

plugin-locationcomponent/src/test/java/com/mapbox/maps/plugin/locationcomponent/ModelLayerWrapperTest.kt

@@ -1088,6 +1088,7 @@ package com.mapbox.maps.plugin {
   }
 
   public final class LocationPuck3D extends com.mapbox.maps.plugin.LocationPuck {
+    ctor public LocationPuck3D(String modelUri, java.util.List<java.lang.Float> position = listOf(0.0, 0.0), float modelOpacity = 1f, java.util.List<java.lang.Float> modelScale = listOf(1.0, 1.0, 1.0), String? modelScaleExpression = null, java.util.List<java.lang.Float> modelTranslation = listOf(0.0, 0.0, 0.0), java.util.List<java.lang.Float> modelRotation = listOf(0.0, 0.0, 90.0), @com.mapbox.maps.MapboxExperimental boolean modelCastShadows = true, @com.mapbox.maps.MapboxExperimental boolean modelReceiveShadows = true, @com.mapbox.maps.MapboxExperimental com.mapbox.maps.plugin.ModelScaleMode modelScaleMode = com.mapbox.maps.plugin.ModelScaleMode.VIEWPORT, float modelEmissiveStrength = 1f, String? modelEmissiveStrengthExpression = null, String? modelOpacityExpression = null, String? modelRotationExpression = null, int modelColor = Color.parseColor("#ffffff"), String? modelColorExpression = null, float modelColorMixIntensity = 0f, String? modelColorMixIntensityExpression = null, @com.mapbox.maps.MapboxExperimental java.util.List<java.lang.String> materialOverrides = emptyList(), @com.mapbox.maps.MapboxExperimental java.util.List<java.lang.String> nodeOverrides = emptyList(), @com.mapbox.maps.MapboxExperimental com.mapbox.maps.plugin.ModelElevationReference modelElevationReference = com.mapbox.maps.plugin.ModelElevationReference.GROUND);
     ctor public LocationPuck3D(String modelUri, java.util.List<java.lang.Float> position = listOf(0.0, 0.0), float modelOpacity = 1f, java.util.List<java.lang.Float> modelScale = listOf(1.0, 1.0, 1.0), String? modelScaleExpression = null, java.util.List<java.lang.Float> modelTranslation = listOf(0.0, 0.0, 0.0), java.util.List<java.lang.Float> modelRotation = listOf(0.0, 0.0, 90.0), @com.mapbox.maps.MapboxExperimental boolean modelCastShadows = true, @com.mapbox.maps.MapboxExperimental boolean modelReceiveShadows = true, @com.mapbox.maps.MapboxExperimental com.mapbox.maps.plugin.ModelScaleMode modelScaleMode = com.mapbox.maps.plugin.ModelScaleMode.VIEWPORT, float modelEmissiveStrength = 1f, String? modelEmissiveStrengthExpression = null, String? modelOpacityExpression = null, String? modelRotationExpression = null, int modelColor = Color.parseColor("#ffffff"), String? modelColorExpression = null, float modelColorMixIntensity = 0f, String? modelColorMixIntensityExpression = null, @com.mapbox.maps.MapboxExperimental java.util.List<java.lang.String> materialOverrides = emptyList(), @com.mapbox.maps.MapboxExperimental java.util.List<java.lang.String> nodeOverrides = emptyList());
     ctor public LocationPuck3D(String modelUri, java.util.List<java.lang.Float> position = listOf(0.0, 0.0), float modelOpacity = 1f, java.util.List<java.lang.Float> modelScale = listOf(1.0, 1.0, 1.0), String? modelScaleExpression = null, java.util.List<java.lang.Float> modelTranslation = listOf(0.0, 0.0, 0.0), java.util.List<java.lang.Float> modelRotation = listOf(0.0, 0.0, 90.0), @com.mapbox.maps.MapboxExperimental boolean modelCastShadows = true, @com.mapbox.maps.MapboxExperimental boolean modelReceiveShadows = true, @com.mapbox.maps.MapboxExperimental com.mapbox.maps.plugin.ModelScaleMode modelScaleMode = com.mapbox.maps.plugin.ModelScaleMode.VIEWPORT, float modelEmissiveStrength = 1f, String? modelEmissiveStrengthExpression = null, String? modelOpacityExpression = null, String? modelRotationExpression = null, int modelColor = Color.parseColor("#ffffff"), String? modelColorExpression = null, float modelColorMixIntensity = 0f, String? modelColorMixIntensityExpression = null, @com.mapbox.maps.MapboxExperimental java.util.List<java.lang.String> materialOverrides = emptyList());
     ctor public LocationPuck3D(String modelUri, java.util.List<java.lang.Float> position = listOf(0.0, 0.0), float modelOpacity = 1f, java.util.List<java.lang.Float> modelScale = listOf(1.0, 1.0, 1.0), String? modelScaleExpression = null, java.util.List<java.lang.Float> modelTranslation = listOf(0.0, 0.0, 0.0), java.util.List<java.lang.Float> modelRotation = listOf(0.0, 0.0, 90.0), @com.mapbox.maps.MapboxExperimental boolean modelCastShadows = true, @com.mapbox.maps.MapboxExperimental boolean modelReceiveShadows = true, @com.mapbox.maps.MapboxExperimental com.mapbox.maps.plugin.ModelScaleMode modelScaleMode = com.mapbox.maps.plugin.ModelScaleMode.VIEWPORT, float modelEmissiveStrength = 1f, String? modelEmissiveStrengthExpression = null, String? modelOpacityExpression = null, String? modelRotationExpression = null, int modelColor = Color.parseColor("#ffffff"), String? modelColorExpression = null, float modelColorMixIntensity = 0f, String? modelColorMixIntensityExpression = null);
@@ -1121,20 +1122,22 @@ package com.mapbox.maps.plugin {
     method public java.util.List<java.lang.String> component19();
     method public java.util.List<java.lang.Float> component2();
     method public java.util.List<java.lang.String> component20();
+    method public com.mapbox.maps.plugin.ModelElevationReference component21();
     method public float component3();
     method public java.util.List<java.lang.Float> component4();
     method public String? component5();
     method public java.util.List<java.lang.Float> component6();
     method public java.util.List<java.lang.Float> component7();
     method public boolean component8();
     method public boolean component9();
-    method public com.mapbox.maps.plugin.LocationPuck3D copy(String modelUri, java.util.List<java.lang.Float> position, float modelOpacity, java.util.List<java.lang.Float> modelScale, String? modelScaleExpression, java.util.List<java.lang.Float> modelTranslation, java.util.List<java.lang.Float> modelRotation, boolean modelCastShadows, boolean modelReceiveShadows, com.mapbox.maps.plugin.ModelScaleMode modelScaleMode, float modelEmissiveStrength, String? modelEmissiveStrengthExpression, String? modelOpacityExpression, String? modelRotationExpression, int modelColor, String? modelColorExpression, float modelColorMixIntensity, String? modelColorMixIntensityExpression, java.util.List<java.lang.String> materialOverrides, java.util.List<java.lang.String> nodeOverrides);
+    method public com.mapbox.maps.plugin.LocationPuck3D copy(String modelUri, java.util.List<java.lang.Float> position, float modelOpacity, java.util.List<java.lang.Float> modelScale, String? modelScaleExpression, java.util.List<java.lang.Float> modelTranslation, java.util.List<java.lang.Float> modelRotation, boolean modelCastShadows, boolean modelReceiveShadows, com.mapbox.maps.plugin.ModelScaleMode modelScaleMode, float modelEmissiveStrength, String? modelEmissiveStrengthExpression, String? modelOpacityExpression, String? modelRotationExpression, int modelColor, String? modelColorExpression, float modelColorMixIntensity, String? modelColorMixIntensityExpression, java.util.List<java.lang.String> materialOverrides, java.util.List<java.lang.String> nodeOverrides, com.mapbox.maps.plugin.ModelElevationReference modelElevationReference);
     method public java.util.List<java.lang.String> getMaterialOverrides();
     method public boolean getModelCastShadows();
     method public int getModelColor();
     method public String? getModelColorExpression();
     method public float getModelColorMixIntensity();
     method public String? getModelColorMixIntensityExpression();
+    method public com.mapbox.maps.plugin.ModelElevationReference getModelElevationReference();
     method public float getModelEmissiveStrength();
     method public String? getModelEmissiveStrengthExpression();
     method public float getModelOpacity();
@@ -1155,6 +1158,7 @@ package com.mapbox.maps.plugin {
     method public void setModelColorExpression(String?);
     method public void setModelColorMixIntensity(float);
     method public void setModelColorMixIntensityExpression(String?);
+    method public void setModelElevationReference(com.mapbox.maps.plugin.ModelElevationReference);
     method public void setModelEmissiveStrength(float);
     method public void setModelEmissiveStrengthExpression(String?);
     method public void setModelOpacity(float);
@@ -1175,6 +1179,7 @@ package com.mapbox.maps.plugin {
     property public final String? modelColorExpression;
     property public final float modelColorMixIntensity;
     property public final String? modelColorMixIntensityExpression;
+    property public final com.mapbox.maps.plugin.ModelElevationReference modelElevationReference;
     property public final float modelEmissiveStrength;
     property public final String? modelEmissiveStrengthExpression;
     property public final float modelOpacity;
@@ -1209,6 +1214,13 @@ package com.mapbox.maps.plugin {
     method public void onStyleChanged(com.mapbox.maps.MapboxStyleManager style);
   }
 
+  @com.mapbox.maps.MapboxExperimental public enum ModelElevationReference {
+    method public final String! getValue();
+    property public final String! value;
+    enum_constant public static final com.mapbox.maps.plugin.ModelElevationReference GROUND;
+    enum_constant public static final com.mapbox.maps.plugin.ModelElevationReference SEA;
+  }
+
   @com.mapbox.maps.MapboxExperimental public enum ModelScaleMode {
     method public final String! getValue();
     property public final String! value;