Toggle to allow Camera Below the Surface

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### ✨ Features and improvements
 - Support Vertical Perspective projection ([#5023](https://github.com/maplibre/maplibre-gl-js/pull/5023))
+- Toggle for Terrain Collision ([#5028](https://github.com/maplibre/maplibre-gl-js/pull/5028))
 - _...Add new stuff here..._
 
 ### 🐞 Bug fixes

src/ui/camera.ts

@@ -321,6 +321,13 @@ export abstract class Camera extends Evented {
      */
     _centerClampedToGround: boolean;
 
+    /**
+     * @internal
+     * Controls whether the camera should avoid going below terrain surface.
+     * When false, the camera can go under the terrain.
+     */
+    _terrainCollision?: boolean;
+
     abstract _requestRenderFrame(a: () => void): TaskID;
     abstract _cancelRenderFrame(_: TaskID): void;
 
@@ -333,6 +340,7 @@ export abstract class Camera extends Evented {
         this.transform = transform;
         this._bearingSnap = options.bearingSnap;
         this.cameraHelper = cameraHelper;
+        this._terrainCollision = true;
 
         this.on('moveend', () => {
             delete this._requestedCameraState;
@@ -423,6 +431,26 @@ export abstract class Camera extends Evented {
         this._centerClampedToGround = centerClampedToGround;
     }
 
+    /**
+     * Gets whether terrain collision detection is enabled.
+     *
+     * When true (default), camera will avoid going below terrain surface.
+     * When false, camera can go under the terrain.
+     */
+    getTerrainCollision(): boolean {
+        return this._terrainCollision;
+    }
+
+    /**
+     * Sets whether terrain collision detection is enabled.
+     *
+     * When true (default), camera will avoid going below terrain surface.
+     * When false, camera can go under the terrain.
+     */
+    setTerrainCollision(terrainCollision: boolean): void {
+        this._terrainCollision = terrainCollision;
+    }
+
     /**
      * Pans the map by the specified offset.
      *
@@ -1239,6 +1267,10 @@ export abstract class Camera extends Evented {
      * @param tr - The transform to check.
      */
     _elevateCameraIfInsideTerrain(tr: ITransform) : { pitch?: number; zoom?: number } {
+        if (!this._terrainCollision) {
+            return {};
+        }
+
         if (!this.terrain && tr.elevation >= 0 && tr.pitch <= 90) {
             return {};
         }

test/integration/render/tests/terrain/terrain-collision-off/style.json

@@ -0,0 +1,53 @@
+{
+  "version": 8,
+  "metadata": {
+    "test": {
+      "height": 256,
+      "width": 256,
+      "maxPitch": 180,
+      "operations": [
+          ["setTerrainCollision", false],
+          ["setCenterElevation", 10],
+          ["wait"]
+      ]
+    }
+  },
+  "center": [11.52517, 47.34487],
+  "zoom": 13,
+  "pitch": 100,
+  "sources": {
+    "terrain": {
+      "type": "raster-dem",
+      "tiles": ["local://tiles/terrain-shading/{z}-{x}-{y}.terrain.png"],
+      "maxzoom": 12,
+      "tileSize": 256
+    },
+    "osm": {
+      "type": "raster",
+      "tiles": ["local://tiles/number/{z}.png"],
+      "maxzoom": 17,
+      "tileSize": 256
+    }
+  },
+  "layers": [
+    {
+      "id": "background",
+      "type": "background",
+      "paint": {
+        "background-color": "white"
+      }
+    },
+    {
+      "id": "raster",
+      "type": "raster",
+      "source": "osm",
+      "paint": {
+        "raster-opacity": 1.0
+      }
+    }
+  ],
+  "terrain": {
+    "source": "terrain",
+    "exaggeration": 2
+  }
+}