[MAPS3D-2179] Add new line-elevation-ground-scale property to scale elevated lines with terrain exaggeration (#9440)

Closes https://mapbox.atlassian.net/browse/MAPS3D-2179

This PR adds a new layout property `line-elevation-ground-scale`, which
allows scaling line elevation data with terrain exaggeration for lines
that use `line-elevation-reference: "sea"`. Previously such lines were
always rendered at the exact elevation provided by the source data while
ignoring the terrain exaggeration value. This worked correctly as long
as terrain exaggeration was `1`. Disabling terrain by transitioning
terrain elevation to `0` would cause the elevated line to lose any
connection it had with the ground. Here's an example:

https://github.com/user-attachments/assets/a1b7e691-d850-491c-81e0-a7473810b765

With the new property it's possible to scale elevation values with
terrain exaggeration, either for the entire length of the line or for
parts of it only. For flight paths good results can be had by
interpolating at the start and end of the line. Here is an example of
using the property to keep the start and end of the flight path
connected with the ground:
```
"line-elevation-ground-scale": [
    "interpolate",
    [
        "linear"
    ],
    [
        "line-progress"
    ],
    0,
    1,
    0.1,
    0,
    0.9,
    0,
    1,
    1
]
```

https://github.com/user-attachments/assets/92485a5c-b974-45e3-b0bb-67f1c38df68f

```
<public>
Add `line-elevation-ground-scale` property to scale elevated lines with terrain exaggeration (#9440)
</public>
```

cc @mapbox/gl-js
cc @mapbox/gl-native
cc @mapbox/maps-ios
cc @mapbox/maps-android

cc @mapbox/sdk-platform

---------

Co-authored-by: Changelog autocreator bot <actions@github.com>
GitOrigin-RevId: 5513c0747c841d28a588be8c8441d9fa0339f1fd

Author: 2 people

CHANGELOG.md

@@ -11,6 +11,7 @@ Mapbox welcomes participation and contributions from everyone.
 * 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.
 * Introduce `StyleAttributionsChanged` event for detecting map attributions changes
+* Introduce new `LineLayer.lineElevationGroundScale` property to scale elevated lines with terrain exaggeration.
 
 ## Bug fixes 🐞
 * Fix rare scenario where map render surface size was wrong.

app/src/androidTest/java/com/mapbox/maps/testapp/annotation/generated/PolylineAnnotationManagerAndroidTest.kt

@@ -976,6 +976,7 @@ package com.mapbox.maps.extension.compose.annotation.generated {
     method public Double? getLineCutoutOpacity();
     method public java.util.List<java.lang.Double>? getLineDasharray();
     method public Double? getLineDepthOcclusionFactor();
+    method public Double? getLineElevationGroundScale();
     method public com.mapbox.maps.extension.style.layers.properties.generated.LineElevationReference? getLineElevationReference();
     method public Double? getLineEmissiveStrength();
     method public Double? getLineGapWidth();
@@ -1013,6 +1014,7 @@ package com.mapbox.maps.extension.compose.annotation.generated {
     method public void setLineCutoutOpacity(Double?);
     method public void setLineDasharray(java.util.List<java.lang.Double>?);
     method public void setLineDepthOcclusionFactor(Double?);
+    method public void setLineElevationGroundScale(Double?);
     method public void setLineElevationReference(com.mapbox.maps.extension.style.layers.properties.generated.LineElevationReference?);
     method public void setLineEmissiveStrength(Double?);
     method public void setLineGapWidth(Double?);
@@ -1050,6 +1052,7 @@ package com.mapbox.maps.extension.compose.annotation.generated {
     property public final Double? lineCutoutOpacity;
     property public final java.util.List<java.lang.Double>? lineDasharray;
     property public final Double? lineDepthOcclusionFactor;
+    property public final Double? lineElevationGroundScale;
     property public final com.mapbox.maps.extension.style.layers.properties.generated.LineElevationReference? lineElevationReference;
     property public final Double? lineEmissiveStrength;
     property public final Double? lineGapWidth;
@@ -1117,6 +1120,7 @@ package com.mapbox.maps.extension.compose.annotation.generated {
     method public Double? getLineBorderWidth();
     method public androidx.compose.ui.graphics.Color? getLineColor();
     method public String? getLineColorUseTheme();
+    method public Double? getLineElevationGroundScale();
     method public Double? getLineEmissiveStrength();
     method public Double? getLineGapWidth();
     method public com.mapbox.maps.extension.style.layers.properties.generated.LineJoin? getLineJoin();
@@ -1132,6 +1136,7 @@ package com.mapbox.maps.extension.compose.annotation.generated {
     method public void setLineBorderWidth(Double?);
     method public void setLineColor(androidx.compose.ui.graphics.Color?);
     method public void setLineColorUseTheme(String?);
+    method public void setLineElevationGroundScale(Double?);
     method public void setLineEmissiveStrength(Double?);
     method public void setLineGapWidth(Double?);
     method public void setLineJoin(com.mapbox.maps.extension.style.layers.properties.generated.LineJoin?);
@@ -1147,6 +1152,7 @@ package com.mapbox.maps.extension.compose.annotation.generated {
     property public final Double? lineBorderWidth;
     property public final androidx.compose.ui.graphics.Color? lineColor;
     property public final String? lineColorUseTheme;
+    property public final Double? lineElevationGroundScale;
     property public final Double? lineEmissiveStrength;
     property public final Double? lineGapWidth;
     property public final com.mapbox.maps.extension.style.layers.properties.generated.LineJoin? lineJoin;
@@ -2905,6 +2911,8 @@ package com.mapbox.maps.extension.compose.style.layers.generated {
     method public com.mapbox.maps.extension.compose.style.DoubleListValue getLineDasharray();
     method public com.mapbox.maps.extension.compose.style.DoubleValue getLineDepthOcclusionFactor();
     method public com.mapbox.maps.extension.compose.style.Transition getLineDepthOcclusionFactorTransition();
+    method public com.mapbox.maps.extension.compose.style.DoubleValue getLineElevationGroundScale();
+    method public com.mapbox.maps.extension.compose.style.Transition getLineElevationGroundScaleTransition();
     method public com.mapbox.maps.extension.compose.style.layers.generated.LineElevationReferenceValue getLineElevationReference();
     method public com.mapbox.maps.extension.compose.style.DoubleValue getLineEmissiveStrength();
     method public com.mapbox.maps.extension.compose.style.Transition getLineEmissiveStrengthTransition();
@@ -2961,6 +2969,8 @@ package com.mapbox.maps.extension.compose.style.layers.generated {
     method public void setLineDasharray(com.mapbox.maps.extension.compose.style.DoubleListValue);
     method public void setLineDepthOcclusionFactor(com.mapbox.maps.extension.compose.style.DoubleValue);
     method public void setLineDepthOcclusionFactorTransition(com.mapbox.maps.extension.compose.style.Transition);
+    method public void setLineElevationGroundScale(com.mapbox.maps.extension.compose.style.DoubleValue);
+    method public void setLineElevationGroundScaleTransition(com.mapbox.maps.extension.compose.style.Transition);
     method public void setLineElevationReference(com.mapbox.maps.extension.compose.style.layers.generated.LineElevationReferenceValue);
     method public void setLineEmissiveStrength(com.mapbox.maps.extension.compose.style.DoubleValue);
     method public void setLineEmissiveStrengthTransition(com.mapbox.maps.extension.compose.style.Transition);
@@ -3017,6 +3027,8 @@ package com.mapbox.maps.extension.compose.style.layers.generated {
     property public final com.mapbox.maps.extension.compose.style.DoubleListValue lineDasharray;
     property public final com.mapbox.maps.extension.compose.style.DoubleValue lineDepthOcclusionFactor;
     property public final com.mapbox.maps.extension.compose.style.Transition lineDepthOcclusionFactorTransition;
+    property public final com.mapbox.maps.extension.compose.style.DoubleValue lineElevationGroundScale;
+    property public final com.mapbox.maps.extension.compose.style.Transition lineElevationGroundScaleTransition;
     property public final com.mapbox.maps.extension.compose.style.layers.generated.LineElevationReferenceValue lineElevationReference;
     property public final com.mapbox.maps.extension.compose.style.DoubleValue lineEmissiveStrength;
     property public final com.mapbox.maps.extension.compose.style.Transition lineEmissiveStrengthTransition;

extension-compose/api/Release/metalava.txt

@@ -781,6 +781,7 @@ public final class com/mapbox/maps/extension/compose/annotation/generated/Polyli
 	public final fun getLineCutoutOpacity ()Ljava/lang/Double;
 	public final fun getLineDasharray ()Ljava/util/List;
 	public final fun getLineDepthOcclusionFactor ()Ljava/lang/Double;
+	public final fun getLineElevationGroundScale ()Ljava/lang/Double;
 	public final fun getLineElevationReference ()Lcom/mapbox/maps/extension/style/layers/properties/generated/LineElevationReference;
 	public final fun getLineEmissiveStrength ()Ljava/lang/Double;
 	public final fun getLineGapWidth ()Ljava/lang/Double;
@@ -818,6 +819,7 @@ public final class com/mapbox/maps/extension/compose/annotation/generated/Polyli
 	public final fun setLineCutoutOpacity (Ljava/lang/Double;)V
 	public final fun setLineDasharray (Ljava/util/List;)V
 	public final fun setLineDepthOcclusionFactor (Ljava/lang/Double;)V
+	public final fun setLineElevationGroundScale (Ljava/lang/Double;)V
 	public final fun setLineElevationReference (Lcom/mapbox/maps/extension/style/layers/properties/generated/LineElevationReference;)V
 	public final fun setLineEmissiveStrength (Ljava/lang/Double;)V
 	public final fun setLineGapWidth (Ljava/lang/Double;)V
@@ -880,6 +882,7 @@ public final class com/mapbox/maps/extension/compose/annotation/generated/Polyli
 	public final fun getLineBorderWidth ()Ljava/lang/Double;
 	public final fun getLineColor-QN2ZGVo ()Landroidx/compose/ui/graphics/Color;
 	public final fun getLineColorUseTheme ()Ljava/lang/String;
+	public final fun getLineElevationGroundScale ()Ljava/lang/Double;
 	public final fun getLineEmissiveStrength ()Ljava/lang/Double;
 	public final fun getLineGapWidth ()Ljava/lang/Double;
 	public final fun getLineJoin ()Lcom/mapbox/maps/extension/style/layers/properties/generated/LineJoin;
@@ -895,6 +898,7 @@ public final class com/mapbox/maps/extension/compose/annotation/generated/Polyli
 	public final fun setLineBorderWidth (Ljava/lang/Double;)V
 	public final fun setLineColor-Y2TPw74 (Landroidx/compose/ui/graphics/Color;)V
 	public final fun setLineColorUseTheme (Ljava/lang/String;)V
+	public final fun setLineElevationGroundScale (Ljava/lang/Double;)V
 	public final fun setLineEmissiveStrength (Ljava/lang/Double;)V
 	public final fun setLineGapWidth (Ljava/lang/Double;)V
 	public final fun setLineJoin (Lcom/mapbox/maps/extension/style/layers/properties/generated/LineJoin;)V
@@ -2460,6 +2464,8 @@ public final class com/mapbox/maps/extension/compose/style/layers/generated/Line
 	public final fun getLineDasharray ()Lcom/mapbox/maps/extension/compose/style/DoubleListValue;
 	public final fun getLineDepthOcclusionFactor ()Lcom/mapbox/maps/extension/compose/style/DoubleValue;
 	public final fun getLineDepthOcclusionFactorTransition ()Lcom/mapbox/maps/extension/compose/style/Transition;
+	public final fun getLineElevationGroundScale ()Lcom/mapbox/maps/extension/compose/style/DoubleValue;
+	public final fun getLineElevationGroundScaleTransition ()Lcom/mapbox/maps/extension/compose/style/Transition;
 	public final fun getLineElevationReference ()Lcom/mapbox/maps/extension/compose/style/layers/generated/LineElevationReferenceValue;
 	public final fun getLineEmissiveStrength ()Lcom/mapbox/maps/extension/compose/style/DoubleValue;
 	public final fun getLineEmissiveStrengthTransition ()Lcom/mapbox/maps/extension/compose/style/Transition;
@@ -2516,6 +2522,8 @@ public final class com/mapbox/maps/extension/compose/style/layers/generated/Line
 	public final fun setLineDasharray (Lcom/mapbox/maps/extension/compose/style/DoubleListValue;)V
 	public final fun setLineDepthOcclusionFactor (Lcom/mapbox/maps/extension/compose/style/DoubleValue;)V
 	public final fun setLineDepthOcclusionFactorTransition (Lcom/mapbox/maps/extension/compose/style/Transition;)V
+	public final fun setLineElevationGroundScale (Lcom/mapbox/maps/extension/compose/style/DoubleValue;)V
+	public final fun setLineElevationGroundScaleTransition (Lcom/mapbox/maps/extension/compose/style/Transition;)V
 	public final fun setLineElevationReference (Lcom/mapbox/maps/extension/compose/style/layers/generated/LineElevationReferenceValue;)V
 	public final fun setLineEmissiveStrength (Lcom/mapbox/maps/extension/compose/style/DoubleValue;)V
 	public final fun setLineEmissiveStrengthTransition (Lcom/mapbox/maps/extension/compose/style/Transition;)V