Add constrain parameter to ITransform.apply(); constrain when migrating projections (#6917)

* Draft fix #6892: Add constrain to ITransform.apply

* Test map.setProjection() constrains zoom, center

* Add CHANGELOG entry

* Remove constrain param camera.migrateProjection()

Always call constrain=true on newTransform.apply()

* Require `constrain` param for `ITransform.apply()`

* Add @param tags to `ITransform.apply()`

Author: larsmaxfield

CHANGELOG.md

@@ -9,6 +9,7 @@
 - Fix setting visibility on custom layer ([#6883](https://github.com/maplibre/maplibre-gl-js/issues/6883) (by [melitele](https://github.com/melitele))
 - Hide leading and trailing control characters in `format` expressions ([#6907](https://github.com/maplibre/maplibre-gl-js/pull/6907)) (by [1ec5](https://github.com/1ec5))
 - Fix image sources being clipped at -180 and 180 longitude when terrain is enabled ([#4088](https://github.com/maplibre/maplibre-gl-js/issues/4088)) (by [pstaszek](https://github.com/pstaszek))
+- Fix map not immediately constraining to a valid zoom and center when changing projections ([#6892](https://github.com/maplibre/maplibre-gl-js/issues/6892)) (by [larsmaxfield](https://github.com/larsmaxfield))
 - _...Add new stuff here..._
 
 ## 5.15.0

src/geo/projection/globe_transform.test.ts

@@ -598,7 +598,7 @@ describe('GlobeTransform', () => {
             const globeTransform = createGlobeTransform();
             globeTransform.setRenderWorldCopies(true);
             const mercator = new MercatorTransform({minZoom: 0, maxZoom: 1, minPitch: 2, maxPitch: 3, renderWorldCopies: false});
-            mercator.apply(globeTransform);
+            mercator.apply(globeTransform, false);
 
             expect(mercator.renderWorldCopies).toBeTruthy();
         });

src/geo/projection/globe_transform.ts

@@ -267,14 +267,14 @@ export class GlobeTransform implements ITransform {
         const clone = new GlobeTransform();
         clone._globeness = this._globeness;
         clone._globeLatitudeErrorCorrectionRadians = this._globeLatitudeErrorCorrectionRadians;
-        clone.apply(this);
+        clone.apply(this, false);
         return clone;
     }
 
-    public apply(that: IReadonlyTransform): void {
-        this._helper.apply(that);
-        this._mercatorTransform.apply(this);
-        this._verticalPerspectiveTransform.apply(this, this._globeLatitudeErrorCorrectionRadians);
+    public apply(that: IReadonlyTransform, constrain: boolean): void {
+        this._helper.apply(that, constrain);
+        this._mercatorTransform.apply(this, false);
+        this._verticalPerspectiveTransform.apply(this, false, this._globeLatitudeErrorCorrectionRadians);
     }
 
     public get projectionMatrix(): mat4 { return this.currentTransform.projectionMatrix; }
@@ -332,7 +332,7 @@ export class GlobeTransform implements ITransform {
         // - if autoCalculateNearFarZ is true then it computes globe Z values
         // - if autoCalculateNearFarZ is false then it inherits our Z values
         // In either case, its Z values are consistent with out settings and we want to copy its Z values to our helper.
-        this._verticalPerspectiveTransform.apply(this, this._globeLatitudeErrorCorrectionRadians);
+        this._verticalPerspectiveTransform.apply(this, false, this._globeLatitudeErrorCorrectionRadians);
         this._helper._nearZ = this._verticalPerspectiveTransform.nearZ;
         this._helper._farZ = this._verticalPerspectiveTransform.farZ;
 
@@ -418,11 +418,11 @@ export class GlobeTransform implements ITransform {
     setLocationAtPoint(lnglat: LngLat, point: Point): void {
         if (!this.isGlobeRendering) {
             this._mercatorTransform.setLocationAtPoint(lnglat, point);
-            this.apply(this._mercatorTransform);
+            this.apply(this._mercatorTransform, false);
             return;
         }
         this._verticalPerspectiveTransform.setLocationAtPoint(lnglat, point);
-        this.apply(this._verticalPerspectiveTransform);
+        this.apply(this._verticalPerspectiveTransform, false);
         return;
     }
 

src/geo/projection/mercator_transform.ts

@@ -253,11 +253,11 @@ export class MercatorTransform implements ITransform {
 
     public clone(): ITransform {
         const clone = new MercatorTransform();
-        clone.apply(this);
+        clone.apply(this, false);
         return clone;
     }
 
-    public apply(that: IReadonlyTransform, constrain?: boolean, forceOverrideZ?: boolean): void {
+    public apply(that: IReadonlyTransform, constrain: boolean, forceOverrideZ?: boolean): void {
         this._helper.apply(that, constrain, forceOverrideZ);
     }
 

src/geo/projection/vertical_perspective_transform.ts

@@ -268,13 +268,13 @@ export class VerticalPerspectiveTransform implements ITransform {
 
     clone(): ITransform {
         const clone = new VerticalPerspectiveTransform();
-        clone.apply(this);
+        clone.apply(this, false);
         return clone;
     }
 
-    public apply(that: IReadonlyTransform, globeLatitudeErrorCorrectionRadians?: number): void {
+    public apply(that: IReadonlyTransform, constrain: boolean, globeLatitudeErrorCorrectionRadians?: number): void {
         this._globeLatitudeErrorCorrectionRadians = globeLatitudeErrorCorrectionRadians || 0;
-        this._helper.apply(that);
+        this._helper.apply(that, constrain);
     }
 
     public get projectionMatrix(): mat4 { return this._projectionMatrix; }

src/geo/transform_helper.test.ts

@@ -39,7 +39,7 @@ describe('TransformHelper', () => {
         original.setZoom(2.3);
 
         const cloned = new TransformHelper(emptyCallbacks);
-        cloned.apply(original);
+        cloned.apply(original, false);
 
         // Check all getters from the ITransformGetters interface
         expect(cloned.constrainOverride).toEqual(original.constrainOverride);

src/geo/transform_helper.ts

@@ -184,7 +184,7 @@ export class TransformHelper implements ITransformGetters {
         this._autoCalculateNearFarZ = true;
     }
 
-    public apply(thatI: ITransformGetters, constrain?: boolean, forceOverrideZ?: boolean): void {
+    public apply(thatI: ITransformGetters, constrain: boolean, forceOverrideZ?: boolean): void {
         this._constrainOverride = thatI.constrainOverride;
         this._latRange = thatI.latRange;
         this._lngRange = thatI.lngRange;

src/geo/transform_interface.ts

@@ -106,7 +106,12 @@ export interface ITransformGetters {
 interface ITransformMutators {
     clone(): ITransform;
 
-    apply(that: IReadonlyTransform): void;
+    /**
+     * Applies a transform to the current transform.
+     * @param that - The transform to apply to the current transform.
+     * @param constrain - Whether to constrain the transform's center and zoom and recompute internal matricies once applied.
+     */
+    apply(that: IReadonlyTransform, constrain: boolean): void;
 
     /**
      * Sets the transform's minimal allowed zoom level.

src/ui/camera.ts

@@ -346,7 +346,7 @@ export abstract class Camera extends Evented {
      * When the style's projection is changed (or first set), this function should be called.
      */
     migrateProjection(newTransform: ITransform, newCameraHelper: ICameraHelper) {
-        newTransform.apply(this.transform);
+        newTransform.apply(this.transform, true);
         this.transform = newTransform;
         this.cameraHelper = newCameraHelper;
     }
@@ -1293,9 +1293,9 @@ export abstract class Camera extends Evented {
             if (roll !== undefined) nextTransform.setRoll(roll);
             if (pitch !== undefined) nextTransform.setPitch(pitch);
             if (bearing !== undefined) nextTransform.setBearing(bearing);
-            finalTransform.apply(nextTransform);
+            finalTransform.apply(nextTransform, false);
         }
-        this.transform.apply(finalTransform);
+        this.transform.apply(finalTransform, false);
     }
 
     _fireMoveEvents(eventData?: any) {

src/ui/map_tests/map_transform_constrains.test.ts

@@ -84,6 +84,16 @@ test('Creating a map with style defining globe projection uses Globe transform c
     expect(fixedNum(map.getZoom(), 3)).toBe(-2);
 });
 
+test('Changing a map projection to Mercator constrains the zoom and center to valid values', async () => {
+    const map = createMap( {zoom: -2, center: [0, 90], style: {version: 8, sources: {}, layers: [], projection: {type: 'globe'}}});
+
+    await map.once('style.load');
+    map.setProjection({type: 'mercator'});
+
+    expect(fixedNum(map.getZoom(), 3)).toBe(-1.356);
+    expect(fixedLngLat(map.getCenter(), 4)).toEqual({lng: 0, lat: 0});
+});
+
 describe('transformConstrain', () => {
 
     test('Creating a single-copy map with an identity transform constrain allows the map to underzoom and overpan', () => {