fix(core): preserve GlobeView off-globe pan

Author: charlieforward9

modules/core/src/controllers/globe-controller.ts

@@ -6,9 +6,11 @@ import {clamp} from '@math.gl/core';
 import Controller from './controller';
 
 import {MapState, MapStateProps} from './map-controller';
+import type {MapStateInternal} from './map-controller';
 import {mod} from '../utils/math-utils';
 import LinearInterpolator from '../transitions/linear-interpolator';
 import {zoomAdjust, GLOBE_RADIUS} from '../viewports/globe-viewport';
+import type GlobeViewport from '../viewports/globe-viewport';
 
 import {MAX_LATITUDE} from '@math.gl/web-mercator';
 
@@ -26,18 +28,88 @@ function pixelsToDegrees(pixels: number, zoom: number = 0): number {
   return radians * RADIANS_TO_DEGREES;
 }
 
+type GlobeStateInternal = MapStateInternal & {
+  startPanPos?: [number, number];
+  startPanOnGlobe?: boolean;
+};
+
+function unprojectOnGlobe(
+  viewport: GlobeViewport,
+  pos?: [number, number]
+): [number, number] | undefined {
+  const lngLat = pos && viewport.unproject(pos, {fallback: false});
+  return lngLat ? [lngLat[0], lngLat[1]] : undefined;
+}
+
 class GlobeState extends MapState {
   constructor(
-    options: MapStateProps & {
-      makeViewport: (props: Record<string, any>) => any;
-    }
+    options: MapStateProps &
+      GlobeStateInternal & {
+        makeViewport: (props: Record<string, any>) => any;
+      }
   ) {
+    const {startPanPos, startPanOnGlobe, ...mapStateOptions} = options;
     // Disable MapState's default web-mercator bounds; globe covers the whole earth.
-    // Pan (panStart/pan/panEnd) is inherited from MapState so the grabbed lng/lat
-    // stays under the cursor — matching MapView. The old globe-specific delta-pan
-    // produced the wrong on-screen speed and yanked the center at zoom > 12 (where
-    // WebMercatorViewport takes over rendering but ignored the delta third-arg).
-    super({...options, normalize: false});
+    super({...mapStateOptions, normalize: false});
+
+    if (startPanPos !== undefined) {
+      (this as any)._state.startPanPos = startPanPos;
+    }
+    if (startPanOnGlobe !== undefined) {
+      (this as any)._state.startPanOnGlobe = startPanOnGlobe;
+    }
+  }
+
+  panStart({pos}: {pos: [number, number]}): GlobeState {
+    const {longitude, latitude, zoom} = this.getViewportProps();
+    const viewport = this.makeViewport(this.getViewportProps()) as GlobeViewport;
+    const startPanLngLat = unprojectOnGlobe(viewport, pos);
+
+    return this._getUpdatedState({
+      startPanLngLat: startPanLngLat || [longitude, latitude],
+      startPanPos: pos,
+      startPanOnGlobe: Boolean(startPanLngLat),
+      startZoom: zoom
+    }) as GlobeState;
+  }
+
+  pan({pos, startPos}: {pos: [number, number]; startPos?: [number, number]}): GlobeState {
+    const state = this.getState() as GlobeStateInternal;
+    const viewport = this.makeViewport(this.getViewportProps()) as GlobeViewport;
+    const startPanOnGlobe =
+      state.startPanOnGlobe ?? (startPos ? viewport.isPointOnGlobe(startPos) : true);
+
+    if (startPanOnGlobe) {
+      const startPanLngLat = state.startPanLngLat || unprojectOnGlobe(viewport, startPos);
+      if (!startPanLngLat) {
+        return this;
+      }
+      return this._getUpdatedState(viewport.panByLngLat(startPanLngLat, pos)) as GlobeState;
+    }
+
+    const startPanPos = state.startPanPos || startPos;
+    if (!startPanPos) {
+      return this;
+    }
+
+    const {longitude, latitude, zoom} = this.getViewportProps();
+    const startPanLngLat = state.startPanLngLat || [longitude, latitude];
+    const startZoom = state.startZoom ?? zoom;
+    const newProps = viewport.panByPosition(
+      [startPanLngLat[0], startPanLngLat[1], startZoom],
+      pos,
+      startPanPos
+    );
+    return this._getUpdatedState(newProps) as GlobeState;
+  }
+
+  panEnd(): GlobeState {
+    return this._getUpdatedState({
+      startPanLngLat: null,
+      startPanPos: null,
+      startPanOnGlobe: null,
+      startZoom: null
+    }) as GlobeState;
   }
 
   zoom({
@@ -50,10 +122,11 @@ class GlobeState extends MapState {
     scale: number;
   }): MapState {
     let {startZoom, startZoomLngLat} = this.getState();
+    const viewport = this.makeViewport(this.getViewportProps()) as GlobeViewport;
 
     if (!startZoomLngLat) {
       startZoom = this.getViewportProps().zoom;
-      startZoomLngLat = this._unproject(startPos) || this._unproject(pos);
+      startZoomLngLat = unprojectOnGlobe(viewport, startPos) || unprojectOnGlobe(viewport, pos);
     }
 
     const zoom = this._constrainZoom((startZoom as number) + Math.log2(scale));
@@ -63,10 +136,10 @@ class GlobeState extends MapState {
       return this._getUpdatedState({zoom});
     }
 
-    const zoomedViewport = this.makeViewport({...this.getViewportProps(), zoom});
+    const zoomedViewport = this.makeViewport({...this.getViewportProps(), zoom}) as GlobeViewport;
     return this._getUpdatedState({
       zoom,
-      ...zoomedViewport.panByPosition(startZoomLngLat, pos)
+      ...zoomedViewport.panByLngLat(startZoomLngLat, pos)
     });
   }
 

modules/core/src/viewports/globe-viewport.ts

@@ -191,10 +191,19 @@ export default class GlobeViewport extends Viewport {
     ];
   }
 
+  unproject(xyz: number[], options?: {topLeft?: boolean; targetZ?: number}): number[];
   unproject(
     xyz: number[],
-    {topLeft = true, targetZ}: {topLeft?: boolean; targetZ?: number} = {}
-  ): number[] {
+    options: {topLeft?: boolean; targetZ?: number; fallback: false}
+  ): number[] | null;
+  unproject(
+    xyz: number[],
+    {
+      topLeft = true,
+      targetZ,
+      fallback = true
+    }: {topLeft?: boolean; targetZ?: number; fallback?: boolean} = {}
+  ): number[] | null {
     const [x, y, z] = xyz;
 
     const y2 = topLeft ? y : this.height - y;
@@ -207,23 +216,21 @@ export default class GlobeViewport extends Viewport {
     } else {
       // since we don't know the correct projected z value for the point,
       // unproject two points to get a line and then find the point on that line that intersects with the sphere
-      const coord0 = transformVector(pixelUnprojectionMatrix, [x, y2, -1, 1]);
-      const coord1 = transformVector(pixelUnprojectionMatrix, [x, y2, 1, 1]);
-
-      const lt = ((targetZ || 0) / EARTH_RADIUS + 1) * GLOBE_RADIUS;
-      const lSqr = vec3.sqrLen(vec3.sub([], coord0, coord1));
-      const l0Sqr = vec3.sqrLen(coord0);
-      const l1Sqr = vec3.sqrLen(coord1);
-      const sSqr = (4 * l0Sqr * l1Sqr - (lSqr - l0Sqr - l1Sqr) ** 2) / 16;
-      const dSqr = (4 * sSqr) / lSqr;
-      const r0 = Math.sqrt(l0Sqr - dSqr);
-      const discriminant = lt * lt - dSqr;
+      const {coord0, coord1, lSqr, r0, discriminant} = this._getRaySphereIntersection(
+        x,
+        y2,
+        targetZ
+      );
 
       if (discriminant < 0) {
+        if (!fallback) {
+          return null;
+        }
         // Ray misses the sphere — project the closest-approach point onto the sphere surface
         const tClosest = r0 / Math.sqrt(lSqr);
         const closest = vec3.lerp([], coord0, coord1, tClosest);
         const len = vec3.len(closest);
+        const lt = ((targetZ || 0) / EARTH_RADIUS + 1) * GLOBE_RADIUS;
         coord = len > 0 ? vec3.scale([], closest, lt / len) : [0, 0, lt];
       } else {
         const dr = Math.sqrt(discriminant);
@@ -239,6 +246,15 @@ export default class GlobeViewport extends Viewport {
     return Number.isFinite(targetZ) ? [X, Y, targetZ as number] : [X, Y];
   }
 
+  isPointOnGlobe(
+    pixel: number[],
+    {topLeft = true, targetZ}: {topLeft?: boolean; targetZ?: number} = {}
+  ): boolean {
+    const [x, y] = pixel;
+    const y2 = topLeft ? y : this.height - y;
+    return this._getRaySphereIntersection(x, y2, targetZ).discriminant >= 0;
+  }
+
   projectPosition(xyz: number[]): [number, number, number] {
     const [lng, lat, Z = 0] = xyz;
     const lambda = lng * DEGREES_TO_RADIANS;
@@ -269,13 +285,35 @@ export default class GlobeViewport extends Viewport {
     return xyz as [number, number];
   }
 
+  /**
+   * Pan the globe using delta-based movement.
+   * Used when the pointer starts outside the globe so dragging spins the globe.
+   */
+  panByPosition(coords: number[], pixel: number[], startPixel?: number[]): GlobeViewportOptions {
+    if (!startPixel) {
+      return this.panByLngLat(coords, pixel);
+    }
+
+    const [startLng, startLat, startZoom] = coords;
+    // Scale rotation speed inversely with zoom to keep off-globe drags predictable.
+    const scale = Math.pow(2, this.zoom - zoomAdjust(this.latitude));
+    const rotationSpeed = 0.25 / scale;
+
+    const longitude = startLng + rotationSpeed * (startPixel[0] - pixel[0]);
+    const latitude = Math.max(
+      Math.min(startLat - rotationSpeed * (startPixel[1] - pixel[1]), MAX_LATITUDE),
+      -MAX_LATITUDE
+    );
+    const zoom = startZoom + zoomAdjust(latitude) - zoomAdjust(startLat);
+    return {longitude, latitude, zoom};
+  }
+
   /**
    * Pan the globe so that a geographic position appears at a given screen pixel.
-   * Shifts center by (coords - unproject(pixel)) — i.e. keeps the grabbed lng/lat
-   * under the cursor. Used for drag-pan and zoom-toward-cursor.
+   * Used for on-globe drag-pan and zoom-toward-cursor.
    */
-  panByPosition(coords: number[], pixel: number[]): GlobeViewportOptions {
-    const currentAtPixel = this.unproject(pixel);
+  panByLngLat(coords: number[], pixel: number[]): GlobeViewportOptions {
+    const currentAtPixel = this.unproject(pixel, {fallback: false});
     if (!currentAtPixel) {
       return {longitude: this.longitude, latitude: this.latitude};
     }
@@ -288,6 +326,20 @@ export default class GlobeViewport extends Viewport {
     const zoom = this.zoom + zoomAdjust(latitude) - zoomAdjust(this.latitude);
     return {longitude, latitude, zoom};
   }
+
+  private _getRaySphereIntersection(x: number, y: number, targetZ?: number) {
+    const coord0 = transformVector(this.pixelUnprojectionMatrix, [x, y, -1, 1]);
+    const coord1 = transformVector(this.pixelUnprojectionMatrix, [x, y, 1, 1]);
+    const lt = ((targetZ || 0) / EARTH_RADIUS + 1) * GLOBE_RADIUS;
+    const lSqr = vec3.sqrLen(vec3.sub([], coord0, coord1));
+    const l0Sqr = vec3.sqrLen(coord0);
+    const l1Sqr = vec3.sqrLen(coord1);
+    const sSqr = (4 * l0Sqr * l1Sqr - (lSqr - l0Sqr - l1Sqr) ** 2) / 16;
+    const dSqr = (4 * sSqr) / lSqr;
+    const r0 = Math.sqrt(l0Sqr - dSqr);
+
+    return {coord0, coord1, lSqr, r0, discriminant: lt * lt - dSqr};
+  }
 }
 
 export function zoomAdjust(latitude: number): number {

test/modules/core/controllers/view-states.spec.ts

@@ -8,6 +8,7 @@ import {
   OrbitController,
   FirstPersonController,
   _GlobeController as GlobeController,
+  _GlobeViewport as GlobeViewport,
   OrbitViewport,
   OrthographicController,
   Viewport
@@ -251,6 +252,36 @@ test('GlobeViewState#pitch and bearing constraints', () => {
   ).toBeTruthy();
 });
 
+test('GlobeViewState#pan starts outside globe with delta spin', () => {
+  const GlobeViewState = new GlobeController({} as any).ControllerState;
+  const makeViewport = (props: any) => new GlobeViewport(props);
+  const startPos: [number, number] = [0, 0];
+  const pos: [number, number] = [100, 0];
+  const startProps = {
+    width: 800,
+    height: 600,
+    longitude: 0,
+    latitude: 0,
+    zoom: 0,
+    makeViewport
+  };
+  const viewport = makeViewport(startProps);
+
+  expect(viewport.isPointOnGlobe(startPos), 'test starts off globe').toBe(false);
+  expect(viewport.isPointOnGlobe([startProps.width / 2, startProps.height / 2])).toBe(true);
+
+  const viewState = new GlobeViewState(startProps);
+  const pannedState = viewState.panStart({pos: startPos}).pan({pos});
+  const viewportProps = pannedState.getViewportProps();
+  const rotationSpeed = 0.25 / Math.pow(2, startProps.zoom - Math.log2(Math.PI));
+
+  expect(viewportProps.longitude, 'off-globe pan uses delta longitude').toBeCloseTo(
+    rotationSpeed * (startPos[0] - pos[0])
+  );
+  expect(viewportProps.latitude, 'horizontal off-globe pan keeps latitude').toBe(0);
+  expect(viewportProps.zoom, 'off-globe pan preserves zoom at the equator').toBe(0);
+});
+
 test('OrbitViewState', () => {
   const OrbitViewState = new OrbitController({} as any).ControllerState;
   const makeViewport = (props: any) => new OrbitViewport(props);

test/modules/core/viewports/globe-viewport.spec.ts

@@ -168,6 +168,21 @@ test('GlobeViewport#project, unproject', () => {
   config.EPSILON = oldEpsilon;
 });
 
+test('GlobeViewport#isPointOnGlobe', () => {
+  const viewport = new GlobeViewport({
+    width: 800,
+    height: 600,
+    latitude: 0,
+    longitude: 0,
+    zoom: 0
+  });
+
+  expect(viewport.isPointOnGlobe([viewport.width / 2, viewport.height / 2])).toBe(true);
+  expect(viewport.isPointOnGlobe([0, 0])).toBe(false);
+  expect(viewport.unproject([0, 0]), 'unproject falls back to a surface point').toBeTruthy();
+  expect(viewport.unproject([0, 0], {fallback: false}), 'fallback can be disabled').toBeNull();
+});
+
 test('GlobeViewport#getBounds', () => {
   for (const testCase of TEST_VIEWPORTS) {
     const bounds = new GlobeViewport(testCase).getBounds();