Avoid constraining with Mercator transform when Globe is used (#5186)

* Lazily constrain hash values on map constructor

* Add tests

* Add Changelog entry

* Fix tests

* Simplify condition

* Remove duplicated code

* Deconstruct array

---------

Co-authored-by: Harel M <[email protected]>

CHANGELOG.md

@@ -7,6 +7,7 @@
 
 - Fix holes at the poles when terrain is used with globe ([#5232](https://github.com/maplibre/maplibre-gl-js/pull/5232))
 - Fix geometry artifacts when globe terrain is zoomed out too much ([#5232](https://github.com/maplibre/maplibre-gl-js/pull/5232))
+- Fix center being incorrectly constrained when using globe ([#5186](https://github.com/maplibre/maplibre-gl-js/pull/5186))
 - Fix atmosphere improperly blending into the background ([#5235](https://github.com/maplibre/maplibre-gl-js/pull/5235))
 - _...Add new stuff here..._
 

src/geo/projection/globe_transform.ts

@@ -99,8 +99,8 @@ export class GlobeTransform implements ITransform {
     isPaddingEqual(padding: PaddingOptions): boolean {
         return this._helper.isPaddingEqual(padding);
     }
-    resize(width: number, height: number): void {
-        this._helper.resize(width, height);
+    resize(width: number, height: number, constrainTransform: boolean = true): void {
+        this._helper.resize(width, height, constrainTransform);
     }
     getMaxBounds(): LngLatBounds {
         return this._helper.getMaxBounds();

src/geo/projection/mercator_transform.ts

@@ -98,8 +98,8 @@ export class MercatorTransform implements ITransform {
     isPaddingEqual(padding: PaddingOptions): boolean {
         return this._helper.isPaddingEqual(padding);
     }
-    resize(width: number, height: number): void {
-        this._helper.resize(width, height);
+    resize(width: number, height: number, constrain: boolean = true): void {
+        this._helper.resize(width, height, constrain);
     }
     getMaxBounds(): LngLatBounds {
         return this._helper.getMaxBounds();

src/geo/transform_helper.ts

@@ -425,10 +425,10 @@ export class TransformHelper implements ITransformGetters {
         this._calcMatrices();
     }
 
-    resize(width: number, height: number) {
+    resize(width: number, height: number, constrain: boolean = true): void {
         this._width = width;
         this._height = height;
-        this._constrain();
+        if (constrain) this._constrain();
         this._calcMatrices();
     }
 

src/geo/transform_interface.ts

@@ -163,7 +163,7 @@ interface ITransformMutators {
     /**
      * Sets the transform's width and height and recomputes internal matrices.
      */
-    resize(width: number, height: number): void;
+    resize(width: number, height: number, constrainTransform: boolean): void;
     /**
      * Helper method to update edge-insets in place
      *

src/ui/map.ts

@@ -720,7 +720,11 @@ export class Map extends Camera {
             }
         }
 
-        this.resize();
+        // When no style is set or it's using something other than the globe projection, we can constrain the camera.
+        // When a style is set with other projections though, we can't constrain the camera until the style is loaded
+        // and the correct transform is used. Otherwise, valid points in the desired projection could be rejected
+        const shouldConstrainUsingMercatorTransform = typeof resolvedOptions.style === 'string' || !(resolvedOptions.style?.projection?.type === 'globe');
+        this.resize(null, shouldConstrainUsingMercatorTransform);
 
         this._localIdeographFontFamily = resolvedOptions.localIdeographFontFamily;
         this._validateStyle = resolvedOptions.validateStyle;
@@ -734,6 +738,8 @@ export class Map extends Camera {
             this.addControl(new LogoControl(), resolvedOptions.logoPosition);
 
         this.on('style.load', () => {
+            // If we didn't constrain the camera before, we do it now
+            if (!shouldConstrainUsingMercatorTransform) this._resizeTransform();
             if (this.transform.unmodified) {
                 const coercedOptions = pick(this.style.stylesheet, ['center', 'zoom', 'bearing', 'pitch', 'roll']) as CameraOptions;
                 this.jumpTo(coercedOptions);
@@ -873,10 +879,8 @@ export class Map extends Camera {
      * if (mapDiv.style.visibility === true) map.resize();
      * ```
      */
-    resize(eventData?: any): Map {
-        const dimensions = this._containerDimensions();
-        const width = dimensions[0];
-        const height = dimensions[1];
+    resize(eventData?: any, constrainTransform = true): Map {
+        const [width, height] = this._containerDimensions();
 
         const clampedPixelRatio = this._getClampedPixelRatio(width, height);
         this._resizeCanvas(width, height, clampedPixelRatio);
@@ -892,8 +896,7 @@ export class Map extends Camera {
             this.painter.resize(width, height, clampedPixelRatio);
         }
 
-        this.transform.resize(width, height);
-        this._requestedCameraState?.resize(width, height);
+        this._resizeTransform(constrainTransform);
 
         const fireMoving = !this._moving;
         if (fireMoving) {
@@ -909,6 +912,13 @@ export class Map extends Camera {
         return this;
     }
 
+    _resizeTransform(constrainTransform = true) {
+        const [width, height] = this._containerDimensions();
+
+        this.transform.resize(width, height, constrainTransform);
+        this._requestedCameraState?.resize(width, height, constrainTransform);
+    }
+
     /**
      * @internal
      * Return the map's pixel ratio eventually scaled down to respect maxCanvasSize.

src/ui/map_tests/map_style.test.ts

@@ -116,7 +116,7 @@ describe('#setStyle', () => {
     test('style transform overrides unmodified map transform', () => new Promise<void>(done => {
         const map = new Map({container: window.document.createElement('div')} as any as MapOptions);
         map.transform.setMaxBounds(new LngLatBounds([-120, -60], [140, 80]));
-        map.transform.resize(600, 400);
+        map.transform.resize(600, 400, true);
         expect(map.transform.zoom).toBe(0.6983039737971013);
         expect(map.transform.unmodified).toBeTruthy();
         map.setStyle(createStyle());

src/ui/map_tests/map_transform_constrains.test.ts

@@ -0,0 +1,85 @@
+import {beforeEach, test, expect} from 'vitest';
+import {createMap, beforeMapTest} from '../../util/test/util';
+import {fixedLngLat, fixedNum} from '../../../test/unit/lib/fixed';
+
+beforeEach(() => {
+    beforeMapTest();
+    global.fetch = null;
+});
+
+test('Creating a map without style constrains invalid hash values to valid Mercator transform values', () => {
+    const container = window.document.createElement('div');
+    Object.defineProperty(container, 'offsetWidth', {value: 512});
+    Object.defineProperty(container, 'offsetHeight', {value: 512});
+
+    const map = createMap({container, center: [-180, -90], zoom: -2});
+
+    expect(fixedLngLat(map.getCenter(), 4)).toEqual({lng: 180, lat: 0});
+    expect(fixedNum(map.getZoom(), 3)).toBe(-0.771);
+});
+
+test('Creating a map without style keeps valid hash values as Mercator transform values', () => {
+    const container = window.document.createElement('div');
+    Object.defineProperty(container, 'offsetWidth', {value: 512});
+    Object.defineProperty(container, 'offsetHeight', {value: 512});
+
+    const map = createMap({container, center: [15, 30], zoom: 3});
+
+    expect(fixedLngLat(map.getCenter(), 4)).toEqual({lng: 15, lat: 30});
+    expect(fixedNum(map.getZoom(), 3)).toBe(3);
+});
+
+test('Creating a map with style but no projection uses Mercator transform constrains', () => {
+    const container = window.document.createElement('div');
+    Object.defineProperty(container, 'offsetWidth', {value: 512});
+    Object.defineProperty(container, 'offsetHeight', {value: 512});
+
+    const map = createMap({container, center: [-180, -90], zoom: -2, style: {version: 8, sources: {}, layers: []}});
+
+    expect(fixedLngLat(map.getCenter(), 4)).toEqual({lng: 180, lat: 0});
+    expect(fixedNum(map.getZoom(), 3)).toBe(-0.771);
+});
+
+test('Creating a map with style but no projection does not constrain valid values', () => {
+    const container = window.document.createElement('div');
+    Object.defineProperty(container, 'offsetWidth', {value: 512});
+    Object.defineProperty(container, 'offsetHeight', {value: 512});
+
+    const map = createMap({container, center: [15, 30], zoom: 3, style: {version: 8, sources: {}, layers: []}});
+
+    expect(fixedLngLat(map.getCenter(), 4)).toEqual({lng: 15, lat: 30});
+    expect(fixedNum(map.getZoom(), 3)).toBe(3);
+});
+
+test('Creating a map with style defining mercator projection uses Mercator transform constrains', () => {
+    const container = window.document.createElement('div');
+    Object.defineProperty(container, 'offsetWidth', {value: 512});
+    Object.defineProperty(container, 'offsetHeight', {value: 512});
+
+    const map = createMap({container, center: [-180, -90], zoom: -2, style: {version: 8, sources: {}, layers: [], projection: {type: 'mercator'}}});
+
+    expect(fixedLngLat(map.getCenter(), 4)).toEqual({lng: 180, lat: 0});
+    expect(fixedNum(map.getZoom(), 3)).toBe(-0.771);
+});
+
+test('Creating a map with style defining mercator projection does not constrain valid values', () => {
+    const container = window.document.createElement('div');
+    Object.defineProperty(container, 'offsetWidth', {value: 512});
+    Object.defineProperty(container, 'offsetHeight', {value: 512});
+
+    const map = createMap({container, center: [15, 30], zoom: 3, style: {version: 8, sources: {}, layers: [], projection: {type: 'mercator'}}});
+
+    expect(fixedLngLat(map.getCenter(), 4)).toEqual({lng: 15, lat: 30});
+    expect(fixedNum(map.getZoom(), 3)).toBe(3);
+});
+
+test('Creating a map with style defining globe projection uses Globe transform constrains', () => {
+    const container = window.document.createElement('div');
+    Object.defineProperty(container, 'offsetWidth', {value: 512});
+    Object.defineProperty(container, 'offsetHeight', {value: 512});
+
+    const map = createMap({container, center: [65.7, -38.2], zoom: -2, style: {version: 8, sources: {}, layers: [], projection: {type: 'globe'}}});
+
+    expect(fixedLngLat(map.getCenter(), 4)).toEqual({lng: 65.7, lat: -38.2});
+    expect(fixedNum(map.getZoom(), 3)).toBe(-2);
+});