@deck.gl/core 9.2.11 → 9.3.0-alpha.2

package/package.json

@@ -3,7 +3,7 @@
   "description": "deck.gl core library",
   "license": "MIT",
   "type": "module",
-  "version": "9.2.11",
+  "version": "9.3.0-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -40,13 +40,13 @@
     "prepublishOnly": "npm run build-debugger && npm run build-bundle && npm run build-bundle -- --env=dev"
   },
   "dependencies": {
-    "@loaders.gl/core": "~4.3.4",
-    "@loaders.gl/images": "~4.3.4",
-    "@luma.gl/constants": "~9.2.6",
-    "@luma.gl/core": "~9.2.6",
-    "@luma.gl/engine": "~9.2.6",
-    "@luma.gl/shadertools": "~9.2.6",
-    "@luma.gl/webgl": "~9.2.6",
+    "@loaders.gl/core": "^4.4.0-alpha.18",
+    "@loaders.gl/images": "^4.4.0-alpha.18",
+    "@luma.gl/constants": "^9.3.0-alpha.6",
+    "@luma.gl/core": "^9.3.0-alpha.6",
+    "@luma.gl/engine": "^9.3.0-alpha.6",
+    "@luma.gl/shadertools": "^9.3.0-alpha.6",
+    "@luma.gl/webgl": "^9.3.0-alpha.6",
     "@math.gl/core": "^4.1.0",
     "@math.gl/sun": "^4.1.0",
     "@math.gl/types": "^4.1.0",
@@ -58,5 +58,5 @@
     "gl-matrix": "^3.0.0",
     "mjolnir.js": "^3.0.0"
   },
-  "gitHead": "35adca6c8646a5125517cbccb99ce1b733b02235"
+  "gitHead": "135d329f4a4b596ae2c16e4eb801eda30252f3bc"
 }

package/src/controllers/controller.ts

@@ -7,6 +7,7 @@ import TransitionManager, {TransitionProps} from './transition-manager';
 import LinearInterpolator from '../transitions/linear-interpolator';
 import {IViewState} from './view-state';
 import {ConstructorOf} from '../types/types';
+import {deepEqual} from '../utils/deep-equal';
 
 import type Viewport from '../viewports/viewport';
 
@@ -65,6 +66,8 @@ export type ControllerOptions = {
   dragMode?: 'pan' | 'rotate';
   /** Enable inertia after panning/pinching. If a number is provided, indicates the duration of time over which the velocity reduces to zero, in milliseconds. Default `false`. */
   inertia?: boolean | number;
+  /** Bounding box of content that the controller is constrained in */
+  maxBounds?: [min: [number, number], max: [number, number]] | [min: [number, number, number], max: [number, number, number]] | null;
 };
 
 export type ControllerProps = {
@@ -92,6 +95,8 @@ export type InteractionState = {
   isRotating?: boolean;
   /** If the view is being zoomed, either from user input or transition */
   isZooming?: boolean;
+  /** World coordinate [lng, lat, altitude] of rotation pivot point when rotating */
+  rotationPivotPosition?: [number, number, number];
 }
 
 /** Parameters passed to the onViewStateChange callback */
@@ -119,7 +124,8 @@ export default abstract class Controller<ControllerState extends IViewState<Cont
   protected eventManager: EventManager;
   protected onViewStateChange: (params: ViewStateChangeParameters) => void;
   protected onStateChange: (state: InteractionState) => void;
-  protected makeViewport: (opts: Record<string, any>) => Viewport
+  protected makeViewport: (opts: Record<string, any>) => Viewport;
+  protected pickPosition?: (x: number, y: number) => {coordinate?: number[]} | null;
 
   private _controllerState?: ControllerState;
   private _events: Record<string, boolean> = {};
@@ -154,6 +160,7 @@ export default abstract class Controller<ControllerState extends IViewState<Cont
     makeViewport: (opts: Record<string, any>) => Viewport;
     onViewStateChange: (params: ViewStateChangeParameters) => void;
     onStateChange: (state: InteractionState) => void;
+    pickPosition?: (x: number, y: number) => {coordinate?: number[]} | null;
   }) {
     this.transitionManager = new TransitionManager<ControllerState>({
       ...opts,
@@ -168,6 +175,7 @@ export default abstract class Controller<ControllerState extends IViewState<Cont
     this.onViewStateChange = opts.onViewStateChange || (() => {});
     this.onStateChange = opts.onStateChange || (() => {});
     this.makeViewport = opts.makeViewport;
+    this.pickPosition = opts.pickPosition;
   }
 
   set events(customEvents) {
@@ -237,7 +245,7 @@ export default abstract class Controller<ControllerState extends IViewState<Cont
       ...this.props,
       ...this.state
     });
-    return this._controllerState ;
+    return this._controllerState;
   }
 
   getCenter(event: MjolnirGestureEvent | MjolnirWheelEvent) : [number, number] {
@@ -288,6 +296,7 @@ export default abstract class Controller<ControllerState extends IViewState<Cont
     if (props.dragMode) {
       this.dragMode = props.dragMode;
     }
+    const oldProps = this.props;
     this.props = props;
 
     if (!('transitionInterpolator' in props)) {
@@ -329,6 +338,19 @@ export default abstract class Controller<ControllerState extends IViewState<Cont
     this.touchZoom = touchZoom;
     this.touchRotate = touchRotate;
     this.keyboard = keyboard;
+
+    // Normalize view state if maxBounds is defined
+    const dimensionChanged = !oldProps || oldProps.height !== props.height || oldProps.width !== props.width || oldProps.maxBounds !== props.maxBounds;
+    if (dimensionChanged && props.maxBounds) {
+      // Dimensions changed, try re-normalize the props
+      const controllerState = new this.ControllerState({...props, makeViewport: this.makeViewport});
+      const normalizedProps = controllerState.getViewportProps();
+      const changed = Object.keys(normalizedProps).some(key => !deepEqual(normalizedProps[key], props[key], 1));
+      if (changed) {
+        // some props are updated after normalization
+        this.updateViewport(controllerState);
+      }
+    }
   }
 
   updateTransition() {
@@ -396,6 +418,7 @@ export default abstract class Controller<ControllerState extends IViewState<Cont
       // invertPan is replaced by props.dragMode, keeping for backward compatibility
       alternateMode = !alternateMode;
     }
+
     const newControllerState = this.controllerState[alternateMode ? 'panStart' : 'rotateStart']({
       pos
     });

package/src/controllers/first-person-controller.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import Controller from './controller';
+import Controller, {ControllerProps} from './controller';
 import ViewState from './view-state';
 import {mod} from '../utils/math-utils';
 import type Viewport from '../viewports/viewport';
@@ -27,6 +27,8 @@ type FirstPersonStateProps = {
 
   maxPitch?: number;
   minPitch?: number;
+
+  maxBounds?: ControllerProps['maxBounds'];
 };
 
 type FirstPersonStateInternal = {
@@ -43,8 +45,6 @@ class FirstPersonState extends ViewState<
   FirstPersonStateProps,
   FirstPersonStateInternal
 > {
-  makeViewport: (props: Record<string, any>) => Viewport;
-
   constructor(
     options: FirstPersonStateProps &
       FirstPersonStateInternal & {
@@ -69,6 +69,8 @@ class FirstPersonState extends ViewState<
       maxPitch = 90,
       minPitch = -90,
 
+      maxBounds = null,
+
       // Model state when the rotate operation first started
       startRotatePos,
       startBearing,
@@ -88,7 +90,8 @@ class FirstPersonState extends ViewState<
         longitude,
         latitude,
         maxPitch,
-        minPitch
+        minPitch,
+        maxBounds
       },
       {
         startRotatePos,
@@ -97,10 +100,9 @@ class FirstPersonState extends ViewState<
         startZoomPosition,
         startPanPos,
         startPanPosition
-      }
+      },
+      options.makeViewport
     );
-
-    this.makeViewport = options.makeViewport;
   }
 
   /* Public API */
@@ -366,7 +368,7 @@ class FirstPersonState extends ViewState<
   // Apply any constraints (mathematical or defined by _viewportProps) to map state
   applyConstraints(props: Required<FirstPersonStateProps>): Required<FirstPersonStateProps> {
     // Ensure pitch and zoom are within specified range
-    const {pitch, maxPitch, minPitch, longitude, bearing} = props;
+    const {pitch, maxPitch, minPitch, longitude, position, bearing, maxBounds} = props;
     props.pitch = clamp(pitch, minPitch, maxPitch);
 
     // Normalize degrees
@@ -376,6 +378,14 @@ class FirstPersonState extends ViewState<
     if (bearing < -180 || bearing > 180) {
       props.bearing = mod(bearing + 180, 360) - 180;
     }
+    if (maxBounds) {
+      const x = clamp(position[0], maxBounds[0][0], maxBounds[1][0]);
+      const y = clamp(position[1], maxBounds[0][1], maxBounds[1][1]);
+      const z = clamp(position[2] ?? 0, maxBounds[0][2] ?? 0, maxBounds[1][2] ?? 0);
+      if (x !== position[0] || y !== position[1] || z !== position[2]) {
+        props.position = [x, y, z];
+      }
+    }
 
     return props;
   }

package/src/controllers/globe-controller.ts

@@ -9,10 +9,24 @@ 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} from '../viewports/globe-viewport';
+import {zoomAdjust, GLOBE_RADIUS} from '../viewports/globe-viewport';
 
 import {MAX_LATITUDE} from '@math.gl/web-mercator';
 
+const DEGREES_TO_RADIANS = Math.PI / 180;
+const RADIANS_TO_DEGREES = 180 / Math.PI;
+
+function degreesToPixels(angle: number, zoom: number = 0): number {
+  const radians = Math.min(180, angle) * DEGREES_TO_RADIANS;
+  const size = GLOBE_RADIUS * 2 * Math.sin(radians / 2);
+  return size * Math.pow(2, zoom);
+}
+function pixelsToDegrees(pixels: number, zoom: number = 0): number {
+  const size = pixels / Math.pow(2, zoom);
+  const radians = Math.asin(Math.min(1, size / GLOBE_RADIUS / 2)) * 2;
+  return radians * RADIANS_TO_DEGREES;
+}
+
 type GlobeStateInternal = MapStateInternal & {
   startPanPos?: [number, number];
 };
@@ -25,6 +39,7 @@ class GlobeState extends MapState {
       }
   ) {
     const {startPanPos, ...mapStateOptions} = options;
+    mapStateOptions.normalize = false; // disable MapState default normalization
     super(mapStateOptions);
 
     if (startPanPos !== undefined) {
@@ -71,19 +86,88 @@ class GlobeState extends MapState {
 
   applyConstraints(props: Required<MapStateProps>): Required<MapStateProps> {
     // Ensure zoom is within specified range
-    const {longitude, latitude, maxZoom, minZoom, zoom} = props;
+    const {longitude, latitude, maxBounds} = props;
 
-    const ZOOM0 = zoomAdjust(0);
-    const zoomAdjustment = zoomAdjust(latitude) - ZOOM0;
-    props.zoom = clamp(zoom, minZoom + zoomAdjustment, maxZoom + zoomAdjustment);
+    props.zoom = this._constrainZoom(props.zoom, props);
 
     if (longitude < -180 || longitude > 180) {
       props.longitude = mod(longitude + 180, 360) - 180;
     }
     props.latitude = clamp(latitude, -MAX_LATITUDE, MAX_LATITUDE);
+    if (maxBounds) {
+      props.longitude = clamp(props.longitude, maxBounds[0][0], maxBounds[1][0]);
+      props.latitude = clamp(props.latitude, maxBounds[0][1], maxBounds[1][1]);
+    }
+
+    if (maxBounds) {
+      // calculate center and zoom ranges at pitch=0 and bearing=0
+      // to maintain visual stability when rotating
+      const effectiveZoom = props.zoom - zoomAdjust(latitude);
+      const lngSpan = maxBounds[1][0] - maxBounds[0][0];
+      const latSpan = maxBounds[1][1] - maxBounds[0][1];
+      if (latSpan > 0 && latSpan < MAX_LATITUDE * 2) {
+        const halfHeightDegrees =
+          Math.min(pixelsToDegrees(props.height, effectiveZoom), latSpan) / 2;
+        props.latitude = clamp(
+          props.latitude,
+          maxBounds[0][1] + halfHeightDegrees,
+          maxBounds[1][1] - halfHeightDegrees
+        );
+      }
+      if (lngSpan > 0 && lngSpan < 360) {
+        const halfWidthDegrees =
+          Math.min(
+            pixelsToDegrees(
+              props.width / Math.cos(props.latitude * DEGREES_TO_RADIANS),
+              effectiveZoom
+            ),
+            lngSpan
+          ) / 2;
+        props.longitude = clamp(
+          props.longitude,
+          maxBounds[0][0] + halfWidthDegrees,
+          maxBounds[1][0] - halfWidthDegrees
+        );
+      }
+    }
+    if (props.latitude !== latitude) {
+      props.zoom += zoomAdjust(props.latitude) - zoomAdjust(latitude);
+    }
 
     return props;
   }
+
+  _constrainZoom(zoom: number, props?: Required<MapStateProps>): number {
+    props ||= this.getViewportProps();
+    const {latitude, maxZoom, maxBounds} = props;
+    let {minZoom} = props;
+    const ZOOM0 = zoomAdjust(0);
+    const zoomAdjustment = zoomAdjust(latitude) - ZOOM0;
+
+    const shouldApplyMaxBounds = maxBounds !== null && props.width > 0 && props.height > 0;
+    if (shouldApplyMaxBounds) {
+      const minLatitude = maxBounds[0][1];
+      const maxLatitude = maxBounds[1][1];
+      // latitude at which the bounding box is the widest
+      const fitLatitude =
+        Math.sign(minLatitude) === Math.sign(maxLatitude)
+          ? Math.min(Math.abs(minLatitude), Math.abs(maxLatitude))
+          : 0;
+      const w =
+        degreesToPixels(maxBounds[1][0] - maxBounds[0][0]) *
+        Math.cos(fitLatitude * DEGREES_TO_RADIANS);
+      const h = degreesToPixels(maxBounds[1][1] - maxBounds[0][1]);
+      if (w > 0) {
+        minZoom = Math.max(minZoom, Math.log2(props.width / w) + ZOOM0);
+      }
+      if (h > 0) {
+        minZoom = Math.max(minZoom, Math.log2(props.height / h) + ZOOM0);
+      }
+      if (minZoom > maxZoom) minZoom = maxZoom;
+    }
+
+    return clamp(zoom, minZoom + zoomAdjustment, maxZoom + zoomAdjustment);
+  }
 }
 
 export default class GlobeController extends Controller<MapState> {

package/src/controllers/map-controller.ts

@@ -3,16 +3,36 @@
 // Copyright (c) vis.gl contributors
 
 import {clamp} from '@math.gl/core';
-import Controller, {ControllerProps} from './controller';
+import Controller, {ControllerProps, InteractionState} from './controller';
 import ViewState from './view-state';
-import {normalizeViewportProps} from '@math.gl/web-mercator';
+import {worldToLngLat, lngLatToWorld as _lngLatToWorld} from '@math.gl/web-mercator';
 import assert from '../utils/assert';
+import {mod} from '../utils/math-utils';
 
 import LinearInterpolator from '../transitions/linear-interpolator';
 import type Viewport from '../viewports/viewport';
 
 const PITCH_MOUSE_THRESHOLD = 5;
 const PITCH_ACCEL = 1.2;
+const WEB_MERCATOR_TILE_SIZE = 512;
+const WEB_MERCATOR_MAX_BOUNDS = [
+  [-Infinity, -90],
+  [Infinity, 90]
+] satisfies ControllerProps['maxBounds'];
+
+/** The web mercator utility `lngLatToWorld` throws if invalid coordinates are provided.
+ * This wrapper clamps user input to calculate common positions safely. */
+function lngLatToWorld([lng, lat]: number[]): number[] {
+  if (Math.abs(lat) > 90) {
+    lat = Math.sign(lat) * 90;
+  }
+  if (Number.isFinite(lng)) {
+    const [x, y] = _lngLatToWorld([lng, lat]);
+    return [x, clamp(y, 0, WEB_MERCATOR_TILE_SIZE)];
+  }
+  const [, y] = _lngLatToWorld([0, lat]);
+  return [lng, clamp(y, 0, WEB_MERCATOR_TILE_SIZE)];
+}
 
 export type MapStateProps = {
   /** Mapbox viewport properties */
@@ -47,6 +67,8 @@ export type MapStateProps = {
 
   /** Normalize viewport props to fit map height into viewport. Default `true` */
   normalize?: boolean;
+
+  maxBounds?: ControllerProps['maxBounds'];
 };
 
 export type MapStateInternal = {
@@ -57,6 +79,8 @@ export type MapStateInternal = {
   startZoomLngLat?: [number, number];
   /* Pointer position when rotation started */
   startRotatePos?: [number, number];
+  /* The lng/lat/altitude point at the rotation pivot (where rotation started) */
+  startRotateLngLat?: [number, number, number];
   /** Bearing when current perspective rotate operation started */
   startBearing?: number;
   /** Pitch when current perspective rotate operation started */
@@ -68,12 +92,18 @@ export type MapStateInternal = {
 /* Utils */
 
 export class MapState extends ViewState<MapState, MapStateProps, MapStateInternal> {
-  makeViewport: (props: Record<string, any>) => Viewport;
+  /* get optional altitude for rotation pivot
+   *   - undefined: rotate around viewport center (no pivot point)
+   *   - 0: rotate around pointer position at ground level
+   *   - other value: rotate around pointer position at specified altitude
+   */
+  getAltitude?: (pos: [number, number]) => number | undefined;
 
   constructor(
     options: MapStateProps &
       MapStateInternal & {
         makeViewport: (props: Record<string, any>) => Viewport;
+        getAltitude?: (pos: [number, number]) => number | undefined;
       }
   ) {
     const {
@@ -114,6 +144,8 @@ export class MapState extends ViewState<MapState, MapStateProps, MapStateInterna
       startZoomLngLat,
       /* Pointer position when rotation started */
       startRotatePos,
+      /* The lng/lat point at the rotation pivot (where rotation started) */
+      startRotateLngLat,
       /** Bearing when current perspective rotate operation started */
       startBearing,
       /** Pitch when current perspective rotate operation started */
@@ -129,6 +161,8 @@ export class MapState extends ViewState<MapState, MapStateProps, MapStateInterna
     assert(Number.isFinite(latitude)); // `latitude` must be supplied
     assert(Number.isFinite(zoom)); // `zoom` must be supplied
 
+    const maxBounds = options.maxBounds || (normalize ? WEB_MERCATOR_MAX_BOUNDS : null);
+
     super(
       {
         width,
@@ -144,19 +178,22 @@ export class MapState extends ViewState<MapState, MapStateProps, MapStateInterna
         maxPitch,
         minPitch,
         normalize,
-        position
+        position,
+        maxBounds
       },
       {
         startPanLngLat,
         startZoomLngLat,
         startRotatePos,
+        startRotateLngLat,
         startBearing,
         startPitch,
         startZoom
-      }
+      },
+      options.makeViewport
     );
 
-    this.makeViewport = options.makeViewport;
+    this.getAltitude = options.getAltitude;
   }
 
   /**
@@ -203,8 +240,11 @@ export class MapState extends ViewState<MapState, MapStateProps, MapStateInterna
    * @param {[Number, Number]} pos - position on screen where the center is
    */
   rotateStart({pos}: {pos: [number, number]}): MapState {
+    const altitude = this.getAltitude?.(pos);
+
     return this._getUpdatedState({
       startRotatePos: pos,
+      startRotateLngLat: altitude !== undefined ? this._unproject3D(pos, altitude) : undefined,
       startBearing: this.getViewportProps().bearing,
       startPitch: this.getViewportProps().pitch
     });
@@ -223,7 +263,7 @@ export class MapState extends ViewState<MapState, MapStateProps, MapStateInterna
     deltaAngleX?: number;
     deltaAngleY?: number;
   }): MapState {
-    const {startRotatePos, startBearing, startPitch} = this.getState();
+    const {startRotatePos, startRotateLngLat, startBearing, startPitch} = this.getState();
 
     if (!startRotatePos || startBearing === undefined || startPitch === undefined) {
       return this;
@@ -237,6 +277,21 @@ export class MapState extends ViewState<MapState, MapStateProps, MapStateInterna
         pitch: startPitch + deltaAngleY
       };
     }
+
+    // If we have a pivot point, adjust the camera position to keep the pivot point fixed
+    if (startRotateLngLat) {
+      const rotatedViewport = this.makeViewport({
+        ...this.getViewportProps(),
+        ...newRotation
+      });
+      // Use panByPosition3D if available (WebMercatorViewport), otherwise fall back to panByPosition
+      const panMethod = 'panByPosition3D' in rotatedViewport ? 'panByPosition3D' : 'panByPosition';
+      return this._getUpdatedState({
+        ...newRotation,
+        ...rotatedViewport[panMethod](startRotateLngLat, startRotatePos)
+      });
+    }
+
     return this._getUpdatedState(newRotation);
   }
 
@@ -246,6 +301,8 @@ export class MapState extends ViewState<MapState, MapStateProps, MapStateInterna
    */
   rotateEnd(): MapState {
     return this._getUpdatedState({
+      startRotatePos: null,
+      startRotateLngLat: null,
       startBearing: null,
       startPitch: null
     });
@@ -296,10 +353,7 @@ export class MapState extends ViewState<MapState, MapStateProps, MapStateInterna
       return this;
     }
 
-    const {maxZoom, minZoom} = this.getViewportProps();
-    let zoom = (startZoom as number) + Math.log2(scale);
-    zoom = clamp(zoom, minZoom, maxZoom);
-
+    const zoom = this._constrainZoom((startZoom as number) + Math.log2(scale));
     const zoomedViewport = this.makeViewport({...this.getViewportProps(), zoom});
 
     return this._getUpdatedState({
@@ -384,18 +438,33 @@ export class MapState extends ViewState<MapState, MapStateProps, MapStateInterna
 
   // Apply any constraints (mathematical or defined by _viewportProps) to map state
   applyConstraints(props: Required<MapStateProps>): Required<MapStateProps> {
-    // Ensure zoom is within specified range
-    const {maxZoom, minZoom, zoom} = props;
-    props.zoom = clamp(zoom, minZoom, maxZoom);
-
     // Ensure pitch is within specified range
-    const {maxPitch, minPitch, pitch} = props;
-    props.pitch = clamp(pitch, minPitch, maxPitch);
+    const {maxPitch, minPitch, pitch, longitude, bearing, normalize, maxBounds} = props;
 
-    // Normalize viewport props to fit map height into viewport
-    const {normalize = true} = props;
     if (normalize) {
-      Object.assign(props, normalizeViewportProps(props));
+      if (longitude < -180 || longitude > 180) {
+        props.longitude = mod(longitude + 180, 360) - 180;
+      }
+      if (bearing < -180 || bearing > 180) {
+        props.bearing = mod(bearing + 180, 360) - 180;
+      }
+    }
+    props.pitch = clamp(pitch, minPitch, maxPitch);
+
+    props.zoom = this._constrainZoom(props.zoom, props);
+
+    if (maxBounds) {
+      const bl = lngLatToWorld(maxBounds[0]);
+      const tr = lngLatToWorld(maxBounds[1]);
+      // calculate center and zoom ranges at pitch=0 and bearing=0
+      // to maintain visual stability when rotating
+      const scale = 2 ** props.zoom;
+      const halfWidth = props.width / 2 / scale;
+      const halfHeight = props.height / 2 / scale;
+      const [minLng, minLat] = worldToLngLat([bl[0] + halfWidth, bl[1] + halfHeight]);
+      const [maxLng, maxLat] = worldToLngLat([tr[0] - halfWidth, tr[1] - halfHeight]);
+      props.longitude = clamp(props.longitude, minLng, maxLng);
+      props.latitude = clamp(props.latitude, minLat, maxLat);
     }
 
     return props;
@@ -403,6 +472,30 @@ export class MapState extends ViewState<MapState, MapStateProps, MapStateInterna
 
   /* Private methods */
 
+  _constrainZoom(zoom: number, props?: Required<MapStateProps>): number {
+    props ||= this.getViewportProps();
+    const {maxZoom, maxBounds} = props;
+
+    const shouldApplyMaxBounds = maxBounds !== null && props.width > 0 && props.height > 0;
+    let {minZoom} = props;
+
+    if (shouldApplyMaxBounds) {
+      const bl = lngLatToWorld(maxBounds[0]);
+      const tr = lngLatToWorld(maxBounds[1]);
+      const w = tr[0] - bl[0];
+      const h = tr[1] - bl[1];
+      // ignore bound size of 0 or Infinity
+      if (Number.isFinite(w) && w > 0) {
+        minZoom = Math.max(minZoom, Math.log2(props.width / w));
+      }
+      if (Number.isFinite(h) && h > 0) {
+        minZoom = Math.max(minZoom, Math.log2(props.height / h));
+      }
+      if (minZoom > maxZoom) minZoom = maxZoom;
+    }
+    return clamp(zoom, minZoom, maxZoom);
+  }
+
   _zoomFromCenter(scale) {
     const {width, height} = this.getViewportProps();
     return this.zoom({
@@ -435,6 +528,11 @@ export class MapState extends ViewState<MapState, MapStateProps, MapStateInterna
     return pos && viewport.unproject(pos);
   }
 
+  _unproject3D(pos: [number, number], altitude: number): [number, number, number] {
+    const viewport = this.makeViewport(this.getViewportProps());
+    return viewport.unproject(pos, {targetZ: altitude}) as [number, number, number];
+  }
+
   _getNewRotation(
     pos: [number, number],
     startPos: [number, number],
@@ -502,22 +600,66 @@ export default class MapController extends Controller<MapState> {
 
   dragMode: 'pan' | 'rotate' = 'pan';
 
-  setProps(props: ControllerProps & MapStateProps) {
+  /**
+   * Rotation pivot behavior:
+   * - 'center': Rotate around viewport center (default)
+   * - '2d': Rotate around pointer position at ground level (z=0)
+   * - '3d': Rotate around 3D picked point (requires pickPosition callback)
+   */
+  protected rotationPivot: 'center' | '2d' | '3d' = 'center';
+
+  setProps(
+    props: ControllerProps &
+      MapStateProps & {
+        rotationPivot?: 'center' | '2d' | '3d';
+        getAltitude?: (pos: [number, number]) => number | undefined;
+      }
+  ) {
+    if ('rotationPivot' in props) {
+      this.rotationPivot = props.rotationPivot || 'center';
+    }
+    // this will be passed to MapState constructor
+    props.getAltitude = this._getAltitude;
     props.position = props.position || [0, 0, 0];
-    const oldProps = this.props;
+    props.maxBounds =
+      props.maxBounds || (props.normalize === false ? null : WEB_MERCATOR_MAX_BOUNDS);
 
     super.setProps(props);
+  }
 
-    const dimensionChanged = !oldProps || oldProps.height !== props.height;
-    if (dimensionChanged) {
-      // Dimensions changed, normalize the props
-      this.updateViewport(
-        new this.ControllerState({
-          makeViewport: this.makeViewport,
-          ...props,
-          ...this.state
-        })
-      );
+  protected updateViewport(
+    newControllerState: MapState,
+    extraProps: Record<string, any> | null = null,
+    interactionState: InteractionState = {}
+  ): void {
+    // Inject rotation pivot position during rotation for visual feedback
+    const state = newControllerState.getState();
+    if (interactionState.isDragging && state.startRotateLngLat) {
+      interactionState = {
+        ...interactionState,
+        rotationPivotPosition: state.startRotateLngLat
+      };
+    } else if (interactionState.isDragging === false) {
+      // Clear pivot when drag ends
+      interactionState = {...interactionState, rotationPivotPosition: undefined};
     }
+
+    super.updateViewport(newControllerState, extraProps, interactionState);
   }
+
+  /** Add altitude to rotateStart params based on rotationPivot mode */
+  protected _getAltitude = (pos: [number, number]): number | undefined => {
+    if (this.rotationPivot === '2d') {
+      return 0;
+    } else if (this.rotationPivot === '3d') {
+      if (this.pickPosition) {
+        const {x, y} = this.props;
+        const pickResult = this.pickPosition(x + pos[0], y + pos[1]);
+        if (pickResult && pickResult.coordinate && pickResult.coordinate.length >= 3) {
+          return pickResult.coordinate[2];
+        }
+      }
+    }
+    return undefined;
+  };
 }