Prevent pitching when zooming into terrain

src/geo/transform.js

@@ -231,7 +231,7 @@ class Transform {
             this._updateCameraOnTerrain();
         }
         if (constrainCameraOverTerrain || centerAltitudeChanged) {
-            this._constrainCameraAltitude();
+            this._constrainCamera();
         }
         this._calcMatrices();
     }
@@ -1586,7 +1586,7 @@ class Transform {
         }
     }
 
-    _constrainCameraAltitude() {
+    _constrainCamera() {
         if (!this._elevation)
             return;
 
@@ -1599,7 +1599,7 @@ class Transform {
         const pos = this._computeCameraPosition(mercPixelsPerMeter);
 
         const elevationAtCamera = elevation.getAtPointOrZero(new MercatorCoordinate(...pos));
-        const minHeight = this._minimumHeightOverTerrain() * Math.cos(degToRad(this._maxPitch));
+        const minHeight = this._minimumHeightOverTerrain() * Math.cos(degToRad(85));
         const terrainElevation = this.pixelsPerMeter / this.worldSize * elevationAtCamera;
         const cameraHeight = this._camera.position[2] - terrainElevation;
 
@@ -1611,15 +1611,13 @@ class Transform {
             // Adjust the camera vector so that the camera is placed above the terrain.
             // Distance between the camera and the center point is kept constant.
             cameraToCenter[2] -= (minHeight - cameraHeight) / this._pixelsPerMercatorPixel;
-
             const newDistToCamera = vec3.length(cameraToCenter);
+
             if (newDistToCamera === 0)
                 return;
 
             vec3.scale(cameraToCenter, cameraToCenter, prevDistToCamera / newDistToCamera * this._pixelsPerMercatorPixel);
             this._camera.position = [center.x - cameraToCenter[0], center.y - cameraToCenter[1], center.z * this._pixelsPerMercatorPixel - cameraToCenter[2]];
-
-            this._camera.orientation = orientationFromFrame(cameraToCenter, this._camera.up());
             this._updateStateFromCamera();
         }
     }
@@ -1681,7 +1679,7 @@ class Transform {
             this.zoom += this.scaleZoom(s);
         }
 
-        this._constrainCameraAltitude();
+        this._constrainCamera();
         this._unmodified = unmodified;
         this._constraining = false;
     }
@@ -1968,10 +1966,10 @@ class Transform {
 
     _minimumHeightOverTerrain(): number {
         // Determine minimum height for the camera over the terrain related to current zoom.
-        // Values above than 2 allow max-pitch camera closer to e.g. top of the hill, exposing
+        // Values above than 4 allow max-pitch camera closer to e.g. top of the hill, exposing
         // drape raster overscale artifacts or cut terrain (see under it) as it gets clipped on
         // near plane. Returned value is in mercator coordinates.
-        const MAX_DRAPE_OVERZOOM = 2;
+        const MAX_DRAPE_OVERZOOM = 4;
         const zoom = Math.min((this._seaLevelZoom != null ? this._seaLevelZoom : this._zoom) + MAX_DRAPE_OVERZOOM, this._maxZoom);
         return this._mercatorZfromZoom(zoom);
     }

src/render/painter.js

@@ -188,15 +188,15 @@ class Painter {
         this._backgroundTiles = {};
     }
 
-    updateTerrain(style: Style, cameraChanging: boolean) {
+    updateTerrain(style: Style, isZooming: boolean) {
         const enabled = !!style && !!style.terrain && this.transform.projection.supportsTerrain;
         if (!enabled && (!this._terrain || !this._terrain.enabled)) return;
         if (!this._terrain) {
             this._terrain = new Terrain(this, style);
         }
         const terrain: Terrain = this._terrain;
         this.transform.elevation = enabled ? terrain : null;
-        terrain.update(style, this.transform, cameraChanging);
+        terrain.update(style, this.transform, isZooming);
     }
 
     _updateFog(style: Style) {

src/terrain/terrain.js

@@ -284,9 +284,8 @@ export class Terrain extends Elevation {
      * Validate terrain and update source cache used for elevation.
      * Explicitly pass transform to update elevation (Transform.updateElevation)
      * before using transform for source cache update.
-     * cameraChanging is true when camera is zooming, panning or orbiting.
      */
-    update(style: Style, transform: Transform, cameraChanging: boolean) {
+    update(style: Style, transform: Transform, isZooming: boolean) {
         if (style && style.terrain) {
             if (this._style !== style) {
                 this.style = style;
@@ -323,9 +322,9 @@ export class Terrain extends Elevation {
             }
 
             updateSourceCache();
-            // Camera, when changing, gets constrained over terrain. Issue constrainCameraOverTerrain = true
-            // here to cover potential under terrain situation on data or style change.
-            transform.updateElevation(!cameraChanging);
+            // Camera, when zooming, gets constrained over terrain. Issue constrainCameraOverTerrain = true
+            // here to cover potential under terrain situation on data, style, or other camera changes.
+            transform.updateElevation(!isZooming);
 
             // Reset tile lookup cache and update draped tiles coordinates.
             this.resetTileLookupCache(this.proxySourceCache.id);

src/ui/map.js

@@ -3392,7 +3392,7 @@ class Map extends Camera {
     _updateTerrain() {
         // Recalculate if enabled/disabled and calculate elevation cover. As camera is using elevation tiles before
         // render (and deferred update after zoom recalculation), this needs to be called when removing terrain source.
-        this.painter.updateTerrain(this.style, this.isMoving() || this.isRotating() || this.isZooming());
+        this.painter.updateTerrain(this.style, this.isZooming());
     }
 
     _calculateSpeedIndex(): number {

test/integration/render-tests/debug/terrain/camera-collides-with-terrain/style.json

@@ -0,0 +1,48 @@
+{
+  "version": 8,
+  "metadata": {
+    "test": {
+      "height": 256,
+      "width": 256
+    }
+  },
+  "center": [
+    -104.93611234965806,
+    38.85724324489064
+  ],
+  "zoom": 22,
+  "pitch": 85,
+  "bearing": -79,
+  "terrain": {
+    "source": "rgbterrain",
+    "exaggeration": 1
+  },
+  "sources": {
+    "rgbterrain": {
+      "type": "raster-dem",
+      "tiles": [
+        "local://tiles/12-759-1609.terrain.png"
+      ],
+      "maxzoom": 11,
+      "tileSize": 256
+    }
+  },
+  "glyphs": "local://glyphs/{fontstack}/{range}.pbf",
+  "layers": [
+    {
+      "id": "background",
+      "type": "background",
+      "paint": {
+        "background-color": "gray"
+      }
+    },
+    {
+      "id": "hillshade-translucent",
+      "type": "hillshade",
+      "source": "rgbterrain",
+      "paint": {
+        "hillshade-exaggeration": 1
+      }
+    }
+  ]
+}

test/unit/geo/transform.test.js

@@ -5,7 +5,7 @@ import LngLat from '../../../src/geo/lng_lat.js';
 import {OverscaledTileID, CanonicalTileID} from '../../../src/source/tile_id.js';
 import {fixedNum, fixedLngLat, fixedCoord, fixedPoint, fixedVec3, fixedVec4} from '../../util/fixed.js';
 import {FreeCameraOptions} from '../../../src/ui/free_camera.js';
-import MercatorCoordinate, {mercatorZfromAltitude, MAX_MERCATOR_LATITUDE} from '../../../src/geo/mercator_coordinate.js';
+import MercatorCoordinate, {mercatorZfromAltitude, altitudeFromMercatorZ, MAX_MERCATOR_LATITUDE} from '../../../src/geo/mercator_coordinate.js';
 import {vec3, quat} from 'gl-matrix';
 import LngLatBounds from '../../../src/geo/lng_lat_bounds.js';
 import {degToRad, radToDeg} from '../../../src/util/util.js';
@@ -714,13 +714,12 @@ test('transform', (t) => {
         };
     };
 
-    test('Constrained camera height over terrain', (t) => {
+    test('Pitch does not change when camera collides with terrain', (t) => {
         const transform = new Transform();
         transform.resize(200, 200);
         transform.maxPitch = 85;
 
         transform.elevation = createCollisionElevation(10);
-        transform.constantCameraHeight = false;
         transform.bearing = -45;
         transform.pitch = 85;
 
@@ -729,13 +728,36 @@ test('transform', (t) => {
         const zoom = transform._zoomFromMercatorZ(altitudeZ);
         transform.zoom = zoom;
 
-        // Pitch should have been adjusted so that the camera isn't under the terrain
-        const pixelsPerMeter = mercatorZfromAltitude(1, transform.center.lat) * transform.worldSize;
-        const updatedAltitude = transform.cameraToCenterDistance / pixelsPerMeter * Math.cos(degToRad(transform.pitch));
+        const cameraAltitude = altitudeFromMercatorZ(transform.getFreeCameraOptions().position.z, transform.getFreeCameraOptions().position.y);
+        transform.updateElevation(false);
+
+        t.ok(cameraAltitude > 10);
+        t.equal(fixedNum(transform.bearing), -45);
+        t.equal(fixedNum(transform.pitch), 85);
+
+        t.end();
+    });
+
+    test('Camera height is above terrain with constant elevation', (t) => {
+        const transform = new Transform();
+        transform.resize(200, 200);
+        transform.maxPitch = 85;
+
+        transform.elevation = createConstantElevation(10);
+        transform.bearing = -45;
+        transform.pitch = 85;
+
+        // Set camera altitude to 5 meters
+        const altitudeZ = mercatorZfromAltitude(5, transform.center.lat) / Math.cos(degToRad(85));
+        const zoom = transform._zoomFromMercatorZ(altitudeZ);
+        transform.zoom = zoom;
+
+        const cameraAltitude = altitudeFromMercatorZ(transform.getFreeCameraOptions().position.z, transform.getFreeCameraOptions().position.y);
 
-        t.true(updatedAltitude > 10);
+        t.ok(cameraAltitude > 10);
         t.equal(fixedNum(transform.zoom), fixedNum(zoom));
         t.equal(fixedNum(transform.bearing), -45);
+        t.equal(fixedNum(transform.pitch), 85);
 
         t.end();
     });
@@ -763,31 +785,38 @@ test('transform', (t) => {
 
         t.equal(fixedNum(cameraAltitude()), 5);
         t.equal(transform._centerAltitude, 0);
+
         // increase exaggeration to lift the center (and camera that follows it) up.
         transform.elevation._exaggeration = 1;
         transform.updateElevation(false);
         t.equal(transform._centerAltitude, 10);
+
         const cameraAltitudeAfterLift = cameraAltitude();
         t.equal(fixedNum(cameraAltitudeAfterLift), 15);
+
         transform.elevation._exaggeration = 15;
         transform.updateElevation(false);
         t.equal(transform._centerAltitude, 150);
         t.equal(fixedNum(cameraAltitude()), 155);
+
         transform.elevation._exaggeration = 0;
         transform.updateElevation(false);
         t.equal(fixedNum(cameraAltitude()), 5);
+
         // zoom out to 10 meters and back to 5
         transform.zoom = transform._zoomFromMercatorZ(altitudeZ * 2);
         t.equal(fixedNum(cameraAltitude()), 10);
         transform.zoom = zoom;
         t.equal(fixedNum(cameraAltitude()), 5);
+        t.equal(fixedNum(transform.pitch), 85);
 
         transform.elevation = null;
         t.ok(cameraAltitude() < 10);
 
         // collision elevation keeps center at 0 but pushes camera up.
         const elevation1 = createCollisionElevation(10);
         elevation1._exaggeration = 0;
+
         transform.elevation = elevation1;
         transform.updateElevation(false);
         t.equal(transform._centerAltitude, 0);
@@ -796,7 +825,8 @@ test('transform', (t) => {
         elevation1._exaggeration = 1;
         transform.updateElevation(false);
         t.equal(transform._centerAltitude, 0);
-        t.ok(cameraAltitude() > 11 && cameraAltitude() < 12);
+        t.ok(cameraAltitude() > 10);
+        t.equal(fixedNum(transform.pitch), 85);
 
         t.end();
     });
@@ -1058,6 +1088,8 @@ test('transform', (t) => {
             tilesDefaultElevation = null;
             centerElevation = 1600;
             tileElevation[new OverscaledTileID(14, 0, 14, 3413, 6218).key] = 1600;
+            transform.pitch = 0;
+            transform.bearing = 0;
             transform.resize(768, 768);
             transform.zoom = options.maxzoom = 22;
             transform.center = {lng: -104.99813327, lat: 39.72784465999999};

test/unit/terrain/terrain.test.js

@@ -378,19 +378,19 @@ test('Elevation', (t) => {
                 changed = map._updateAverageElevation(timestamp);
                 t.true(changed);
                 t.true(map._averageElevation.isEasing(timestamp));
-                assertAlmostEqual(t, map.transform.averageElevation, 154.15083854452925);
+                assertAlmostEqual(t, map.transform.averageElevation, -17.781004493268256);
 
                 timestamp += AVERAGE_ELEVATION_EASE_TIME * 0.5;
                 changed = map._updateAverageElevation(timestamp);
                 t.true(changed);
                 t.true(map._averageElevation.isEasing(timestamp));
-                assertAlmostEqual(t, map.transform.averageElevation, 308.3016770890585);
+                assertAlmostEqual(t, map.transform.averageElevation, -35.56200898653651);
 
                 timestamp += AVERAGE_ELEVATION_SAMPLING_INTERVAL;
                 changed = map._updateAverageElevation(timestamp);
                 t.false(changed);
                 t.false(map._averageElevation.isEasing(timestamp));
-                assertAlmostEqual(t, map.transform.averageElevation, 308.3016770890585);
+                assertAlmostEqual(t, map.transform.averageElevation, -35.56200898653651);
 
                 t.end();
             });