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

package/src/lib/deck-picker.ts

@@ -11,7 +11,8 @@ import {
   getEmptyPickingInfo,
   PickingInfo
 } from './picking/pick-info';
-
+import type {RenderStats} from '../passes/layers-pass';
+import type {Stats} from '@probe.gl/stats';
 import type {Framebuffer} from '@luma.gl/core';
 import type {FilterContext, Rect} from '../passes/layers-pass';
 import type Layer from './layer';
@@ -52,6 +53,7 @@ export default class DeckPicker {
   depthFBO?: Framebuffer;
   pickLayersPass: PickLayersPass;
   layerFilter?: (context: FilterContext) => boolean;
+  stats?: Stats;
 
   /** Identifiers of the previously picked object, for callback tracking and auto highlight */
   lastPickedInfo: {
@@ -62,8 +64,9 @@ export default class DeckPicker {
 
   _pickable: boolean = true;
 
-  constructor(device: Device) {
+  constructor(device: Device, opts: {stats?: Stats} = {}) {
     this.device = device;
+    this.stats = opts.stats;
     this.pickLayersPass = new PickLayersPass(device);
     this.lastPickedInfo = {
       index: -1,
@@ -281,16 +284,17 @@ export default class DeckPicker {
       }
 
       let z;
-      if (pickInfo.pickedLayer && unproject3D && this.depthFBO) {
+      const depthLayers = this._getDepthLayers(pickInfo, pickableLayers, unproject3D);
+      if (depthLayers.length > 0) {
         const {pickedColors: pickedColors2} = this._drawAndSample(
           {
-            layers: [pickInfo.pickedLayer],
+            layers: depthLayers,
             views,
             viewports,
             onViewportActive,
             deviceRect: {
-              x: pickInfo.pickedX as number,
-              y: pickInfo.pickedY as number,
+              x: pickInfo.pickedX ?? devicePixel[0],
+              y: pickInfo.pickedY ?? devicePixel[1],
               width: 1,
               height: 1
             },
@@ -444,16 +448,17 @@ export default class DeckPicker {
       }
 
       let z;
-      if (pickInfo.pickedLayer && unproject3D && this.depthFBO) {
+      const depthLayers = this._getDepthLayers(pickInfo, pickableLayers, unproject3D);
+      if (depthLayers.length > 0) {
         const {pickedColors: pickedColors2} = this._drawAndSample(
           {
-            layers: [pickInfo.pickedLayer],
+            layers: depthLayers,
             views,
             viewports,
             onViewportActive,
             deviceRect: {
-              x: pickInfo.pickedX as number,
-              y: pickInfo.pickedY as number,
+              x: pickInfo.pickedX ?? devicePixel[0],
+              y: pickInfo.pickedY ?? devicePixel[1],
               width: 1,
               height: 1
             },
@@ -806,7 +811,8 @@ export default class DeckPicker {
       }
     }
 
-    const {decodePickingColor} = this.pickLayersPass.render(opts);
+    const {decodePickingColor, stats} = this.pickLayersPass.render(opts);
+    this._updateStats(stats);
 
     // Read from an already rendered picking buffer
     // Returns an Uint8ClampedArray of picked pixels
@@ -911,7 +917,8 @@ export default class DeckPicker {
       }
     }
 
-    const {decodePickingColor} = this.pickLayersPass.render(opts);
+    const {decodePickingColor, stats} = this.pickLayersPass.render(opts);
+    this._updateStats(stats);
 
     // Read from an already rendered picking buffer
     // Returns an Uint8ClampedArray of picked pixels
@@ -928,6 +935,34 @@ export default class DeckPicker {
     return {pickedColors, decodePickingColor};
   }
 
+  private _updateStats(source: RenderStats[]) {
+    if (!this.stats) return;
+    let layersCount = 0;
+    for (const {visibleCount} of source) {
+      layersCount += visibleCount;
+    }
+    this.stats.get('Layers picked').addCount(layersCount);
+  }
+
+  /**
+   * Determine which layers to use for the depth (pickZ) pass.
+   * - If a non-draped layer was picked, use just that layer.
+   * - If a draped layer was picked (geometry is at z=0) or no layer was picked
+   *   (e.g. no-FBO tiles at extreme zoom), fall back to terrain layers.
+   */
+  _getDepthLayers(pickInfo: PickedPixel, pickableLayers: Layer[], unproject3D?: boolean): Layer[] {
+    if (!unproject3D || !this.depthFBO) {
+      return [];
+    }
+    const {pickedLayer} = pickInfo;
+    const isDraped = pickedLayer?.state?.terrainDrawMode === 'drape';
+    if (pickedLayer && !isDraped) {
+      return [pickedLayer];
+    }
+    // For draped layers or when no layer was picked, use terrain layers for depth
+    return pickableLayers.filter(l => l.props.operation.includes('terrain'));
+  }
+
   /**
    * Calculate a picking rect centered on deviceX and deviceY and clipped to device
    * @returns null if pixel is outside of device

package/src/lib/deck-renderer.ts

@@ -7,7 +7,8 @@ import {Framebuffer} from '@luma.gl/core';
 import debug from '../debug/index';
 import DrawLayersPass from '../passes/draw-layers-pass';
 import PickLayersPass from '../passes/pick-layers-pass';
-
+import type {RenderStats} from '../passes/layers-pass';
+import type {Stats} from '@probe.gl/stats';
 import type Layer from './layer';
 import type Viewport from '../viewports/viewport';
 import type View from '../views/view';
@@ -24,14 +25,16 @@ export default class DeckRenderer {
   drawPickingColors: boolean;
   drawLayersPass: DrawLayersPass;
   pickLayersPass: PickLayersPass;
+  stats?: Stats;
 
   private renderCount: number;
   private _needsRedraw: string | false;
   private renderBuffers: Framebuffer[];
   private lastPostProcessEffect: string | null;
 
-  constructor(device: Device) {
+  constructor(device: Device, opts: {stats?: Stats} = {}) {
     this.device = device;
+    this.stats = opts.stats;
     this.layerFilter = null;
     this.drawPickingColors = false;
     this.drawLayersPass = new DrawLayersPass(device);
@@ -88,7 +91,8 @@ export default class DeckRenderer {
       renderOpts.clearColor = [0, 0, 0, 0];
       renderOpts.clearCanvas = true;
     }
-    const renderStats = layerPass.render({...renderOpts, target: outputBuffer});
+    const renderResult = layerPass.render({...renderOpts, target: outputBuffer});
+    const renderStats = 'stats' in renderResult ? renderResult.stats : renderResult;
 
     if (renderOpts.effects) {
       if (this.lastPostProcessEffect) {
@@ -102,6 +106,7 @@ export default class DeckRenderer {
     this.renderCount++;
 
     debug(TRACE_RENDER_LAYERS, this, renderStats, opts);
+    this._updateStats(renderStats);
   }
 
   needsRedraw(opts: {clearRedrawFlags: boolean} = {clearRedrawFlags: false}): string | false {
@@ -120,6 +125,15 @@ export default class DeckRenderer {
     renderBuffers.length = 0;
   }
 
+  private _updateStats(source: RenderStats[]) {
+    if (!this.stats) return;
+    let layersCount = 0;
+    for (const {visibleCount} of source) {
+      layersCount += visibleCount;
+    }
+    this.stats.get('Layers rendered').addCount(layersCount);
+  }
+
   private _preRender(effects: Effect[], opts: LayersPassRenderOptions) {
     this.lastPostProcessEffect = null;
     opts.preRenderStats = opts.preRenderStats || {};

package/src/lib/deck.ts

@@ -55,10 +55,15 @@ const getCursor = ({isDragging}) => (isDragging ? 'grabbing' : 'grab');
 export type DeckMetrics = {
   fps: number;
   setPropsTime: number;
+  layersCount: number;
+  drawLayersCount: number;
+  updateLayersCount: number;
   updateAttributesTime: number;
+  updateAttributesCount: number;
   framesRedrawn: number;
   pickTime: number;
   pickCount: number;
+  pickLayersCount: number;
   gpuTime: number;
   gpuTimePerFrame: number;
   cpuTime: number;
@@ -309,10 +314,15 @@ export default class Deck<ViewsT extends ViewOrViews = null> {
   protected metrics: DeckMetrics = {
     fps: 0,
     setPropsTime: 0,
+    layersCount: 0,
+    drawLayersCount: 0,
+    updateLayersCount: 0,
+    updateAttributesCount: 0,
     updateAttributesTime: 0,
     framesRedrawn: 0,
     pickTime: 0,
     pickCount: 0,
+    pickLayersCount: 0,
     gpuTime: 0,
     gpuTimePerFrame: 0,
     cpuTime: 0,
@@ -381,13 +391,9 @@ export default class Deck<ViewsT extends ViewOrViews = null> {
         _cachePipelines: true,
         ...this.props.deviceProps,
         onResize: (canvasContext, info) => {
-          // Manually sync drawing buffer dimensions (canvas is externally managed)
-          // TODO(v9.3): Use canvasContext.setDrawingBufferSize(width, height) when upgrading to luma 9.3+
+          // Sync drawing buffer dimensions with externally-managed canvas
           const {width, height} = canvasContext.canvas;
-          // @ts-ignore - accessing public properties to sync state
-          canvasContext.drawingBufferWidth = width;
-          // @ts-ignore
-          canvasContext.drawingBufferHeight = height;
+          canvasContext.setDrawingBufferSize(width, height);
 
           this._needsRedraw = 'Canvas resized';
           userOnResize?.(canvasContext, info);
@@ -678,6 +684,15 @@ export default class Deck<ViewsT extends ViewOrViews = null> {
     return this._pick('pickObjects', 'pickObjects Time', opts);
   }
 
+  /**
+   * Internal method used by controllers to pick 3D position at a screen coordinate
+   * @private
+   */
+  private _pickPositionForController(x: number, y: number): {coordinate?: number[]} | null {
+    const pickResult = this.pickObject({x, y, radius: 0, unproject3D: true});
+    return pickResult;
+  }
+
   /** Experimental
    * Add a global resource for sharing among layers
    */
@@ -1072,7 +1087,9 @@ export default class Deck<ViewsT extends ViewOrViews = null> {
     timeline.play();
     this.animationLoop.attachTimeline(timeline);
 
-    this.eventManager = new EventManager(this.props.parent || this.canvas, {
+    const eventRoot =
+      this.props.parent?.querySelector<HTMLDivElement>('.deck-events-root') || this.canvas;
+    this.eventManager = new EventManager(eventRoot, {
       touchAction: this.props.touchAction,
       recognizers: Object.keys(RECOGNIZERS).map((eventName: string) => {
         // Resolve recognizer settings
@@ -1101,6 +1118,7 @@ export default class Deck<ViewsT extends ViewOrViews = null> {
       eventManager: this.eventManager,
       onViewStateChange: this._onViewStateChange.bind(this),
       onInteractionStateChange: this._onInteractionStateChange.bind(this),
+      pickPosition: this._pickPositionForController.bind(this),
       views: this._getViews(),
       viewState: this._getViewState(),
       width: this.width,
@@ -1124,13 +1142,17 @@ export default class Deck<ViewsT extends ViewOrViews = null> {
       device: this.device
     });
 
-    this.deckRenderer = new DeckRenderer(this.device);
+    this.deckRenderer = new DeckRenderer(this.device, {stats: this.stats});
+
+    this.deckPicker = new DeckPicker(this.device, {stats: this.stats});
 
-    this.deckPicker = new DeckPicker(this.device);
+    const widgetParent =
+      this.props.parent?.querySelector<HTMLDivElement>('.deck-widgets-root') ||
+      this.canvas?.parentElement;
 
     this.widgetManager = new WidgetManager({
       deck: this,
-      parentElement: this.canvas?.parentElement
+      parentElement: widgetParent
     });
     this.widgetManager.addDefault(new TooltipWidget());
 
@@ -1337,13 +1359,19 @@ export default class Deck<ViewsT extends ViewOrViews = null> {
       stats.get('pickObjects Time').time;
     metrics.pickCount = stats.get('Pick Count').count;
 
+    metrics.layersCount = this.layerManager?.layers.length ?? 0;
+    metrics.drawLayersCount = stats.get('Layers rendered').lastSampleCount;
+    metrics.pickLayersCount = stats.get('Layers picked').lastSampleCount;
+    metrics.updateAttributesCount = stats.get('Layers updated').count;
+    metrics.updateAttributesCount = stats.get('Attributes updated').count;
+
     // Luma stats
     metrics.gpuTime = stats.get('GPU Time').time;
     metrics.cpuTime = stats.get('CPU Time').time;
     metrics.gpuTimePerFrame = stats.get('GPU Time').getAverageTime();
     metrics.cpuTimePerFrame = stats.get('CPU Time').getAverageTime();
 
-    const memoryStats = luma.stats.get('Memory Usage');
+    const memoryStats = luma.stats.get('GPU Time and Memory');
     metrics.bufferMemory = memoryStats.get('Buffer Memory').count;
     metrics.textureMemory = memoryStats.get('Texture Memory').count;
     metrics.renderbufferMemory = memoryStats.get('Renderbuffer Memory').count;

package/src/lib/layer.ts

@@ -96,9 +96,12 @@ const defaultProps: DefaultProps<LayerProps> = {
       if (signal) {
         loadOptions = {
           ...loadOptions,
-          fetch: {
-            ...loadOptions?.fetch,
-            signal
+          core: {
+            ...loadOptions?.core,
+            fetch: {
+              ...loadOptions?.core?.fetch,
+              signal
+            }
           }
         };
       }
@@ -966,6 +969,7 @@ export default abstract class Layer<PropsT extends {} = {}> extends Component<
     if (!stateNeedsUpdate) {
       return;
     }
+    this.context.stats.get('Layer updates').incrementCount();
 
     const currentProps = this.props;
     const context = this.context;

package/src/lib/view-manager.ts

@@ -43,6 +43,7 @@ type ViewManagerProps<ViewsT extends ViewOrViews> = {
   viewState: ViewStateObject<ViewsT> | null;
   onViewStateChange?: (params: ViewStateChangeParameters<AnyViewStateOf<ViewsT>>) => void;
   onInteractionStateChange?: (state: InteractionState) => void;
+  pickPosition?: (x: number, y: number) => {coordinate?: number[]} | null;
   width?: number;
   height?: number;
 };
@@ -65,6 +66,7 @@ export default class ViewManager<ViewsT extends View[]> {
     onViewStateChange?: (params: ViewStateChangeParameters) => void;
     onInteractionStateChange?: (state: InteractionState) => void;
   };
+  private _pickPosition?: (x: number, y: number) => {coordinate?: number[]} | null;
 
   constructor(
     props: ViewManagerProps<ViewsT> & {
@@ -92,6 +94,7 @@ export default class ViewManager<ViewsT extends View[]> {
       onViewStateChange: props.onViewStateChange,
       onInteractionStateChange: props.onInteractionStateChange
     };
+    this._pickPosition = props.pickPosition;
 
     Object.seal(this);
 
@@ -224,6 +227,10 @@ export default class ViewManager<ViewsT extends View[]> {
       this._setSize(props.width as number, props.height as number);
     }
 
+    if ('pickPosition' in props) {
+      this._pickPosition = props.pickPosition;
+    }
+
     // Important: avoid invoking _update() inside itself
     // Nested updates result in unexpected side effects inside _rebuildViewports()
     // when using auto control in pure-js
@@ -308,7 +315,8 @@ export default class ViewManager<ViewsT extends View[]> {
           viewState,
           width: this.width,
           height: this.height
-        })
+        }),
+      pickPosition: this._pickPosition
     });
 
     return controller;

package/src/lib/widget.ts

@@ -98,6 +98,20 @@ export abstract class Widget<
     }
   }
 
+  // VIEW STATE HELPERS
+
+  /** Returns the current view state for the given view */
+  protected getViewState(viewId: string): Record<string, unknown> {
+    // @ts-ignore viewManager is private
+    return this.deck?.viewManager?.getViewState(viewId) || {};
+  }
+
+  /** Updates the view state for the given view */
+  protected setViewState(viewId: string, viewState: Record<string, unknown>): void {
+    // @ts-ignore Using private method temporary until there's a public one
+    this.deck?._onViewStateChange({viewId, viewState, interactionState: {}});
+  }
+
   // @note empty method calls have an overhead in V8 but it is very low, ~1ns
 
   /**

package/src/passes/draw-layers-pass.ts

@@ -3,10 +3,15 @@
 // Copyright (c) vis.gl contributors
 
 import LayersPass from './layers-pass';
+import type {LayersPassRenderOptions, RenderStats} from './layers-pass';
 
 export default class DrawLayersPass extends LayersPass {
   shouldDrawLayer(layer) {
     const {operation} = layer.props;
     return operation.includes('draw') || operation.includes('terrain');
   }
+
+  render(options: LayersPassRenderOptions): RenderStats[] {
+    return this._render(options);
+  }
 }

package/src/passes/layers-pass.ts

@@ -65,9 +65,14 @@ export type RenderStats = {
 export default class LayersPass extends Pass {
   _lastRenderIndex: number = -1;
 
-  render(options: LayersPassRenderOptions): any {
-    // @ts-expect-error TODO - assuming WebGL context
-    const [width, height] = this.device.canvasContext.getDrawingBufferSize();
+  render(options: LayersPassRenderOptions): void {
+    this._render(options);
+  }
+
+  protected _render(options: LayersPassRenderOptions): RenderStats[] {
+    const canvasContext = this.device.canvasContext!;
+    const framebuffer = options.target ?? canvasContext.getCurrentFramebuffer();
+    const [width, height] = canvasContext.getDrawingBufferSize();
 
     // Explicitly specify clearColor and clearDepth, overriding render pass defaults.
     const clearCanvas = options.clearCanvas ?? true;
@@ -85,7 +90,7 @@ export default class LayersPass extends Pass {
     }
 
     const renderPass = this.device.beginRenderPass({
-      framebuffer: options.target,
+      framebuffer,
       parameters,
       clearColor: clearColor as NumberArray4,
       clearDepth,

package/src/passes/pick-layers-pass.ts

@@ -46,13 +46,17 @@ export default class PickLayersPass extends LayersPass {
     byAlpha: EncodedPickingColors[];
   } | null = null;
 
-  render(props: LayersPassRenderOptions | PickLayersPassRenderOptions) {
+  render(props: LayersPassRenderOptions | PickLayersPassRenderOptions): {
+    decodePickingColor: PickingColorDecoder | null;
+    stats: RenderStats[];
+  } {
     if ('pickingFBO' in props) {
       // When drawing into an off-screen buffer, use the alpha channel to encode layer index
       return this._drawPickingBuffer(props);
     }
     // When drawing to screen (debug mode), do not use the alpha channel so that result is always visible
-    return super.render(props);
+    const stats = super._render(props);
+    return {decodePickingColor: null, stats};
   }
 
   // Private
@@ -70,10 +74,11 @@ export default class PickLayersPass extends LayersPass {
     effects,
     pass = 'picking',
     pickZ,
-    shaderModuleProps
+    shaderModuleProps,
+    clearColor
   }: PickLayersPassRenderOptions): {
     decodePickingColor: PickingColorDecoder | null;
-    stats: RenderStats;
+    stats: RenderStats[];
   } {
     this.pickZ = pickZ;
     const colorEncoderState = this._resetColorEncoder(pickZ);
@@ -84,7 +89,7 @@ export default class PickLayersPass extends LayersPass {
     // Note that the callback here is called synchronously.
     // Set blend mode for picking
     // always overwrite existing pixel with [r,g,b,layerIndex]
-    const renderStatus = super.render({
+    const renderStatus = super._render({
       target: pickingFBO,
       layers,
       layerFilter,
@@ -96,7 +101,7 @@ export default class PickLayersPass extends LayersPass {
       pass,
       isPicking: true,
       shaderModuleProps,
-      clearColor: [0, 0, 0, 0],
+      clearColor: clearColor ?? [0, 0, 0, 0],
       colorMask: 0xf,
       scissorRect
     });
@@ -145,6 +150,13 @@ export default class PickLayersPass extends LayersPass {
       pickParameters.blend = true;
       // TODO: blendColor no longer part of luma.gl API
       pickParameters.blendColor = encodeColor(this._colorEncoderState, layer, viewport);
+      if (operation.includes('terrain') && layer.state?._hasPickingCover) {
+        // For terrain+draw layers with a valid cover FBO, the terrain shader outputs the
+        // cover FBO pixel which already has correctly encoded alpha from the cover encoder.
+        // Use srcFactor 'one' to pass through the cover alpha without double-encoding.
+        // Without a cover FBO, keep 'constant' so the layer's own picking colors encode correctly.
+        pickParameters.blendAlphaSrcFactor = 'one';
+      }
     } else if (operation.includes('terrain')) {
       // Pure terrain layers (without 'draw') don't need picking colors
       pickParameters.blend = false;

package/src/shaderlib/project/project.glsl.ts

@@ -265,6 +265,9 @@ vec2 project_pixel_size_to_clipspace(vec2 pixels) {
 float project_size_to_pixel(float meters) {
   return project_size(meters) * project.scale;
 }
+vec2 project_size_to_pixel(vec2 meters) {
+  return project_size(meters) * project.scale;
+}
 float project_size_to_pixel(float size, int unit) {
   if (unit == UNIT_METERS) return project_size_to_pixel(size);
   if (unit == UNIT_COMMON) return size * project.scale;

package/src/utils/deep-merge.ts

@@ -0,0 +1,33 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Merge two viewstates, except `id`
+ * For position arrays such as `target`, only override the components that are defined.
+ */
+export function deepMergeViewState<ViewStateT extends Record<string, any>>(
+  a: ViewStateT,
+  b: ViewStateT
+): ViewStateT {
+  const result = {...a};
+  for (const key in b) {
+    if (key === 'id') continue;
+    if (Array.isArray(result[key]) && Array.isArray(b[key])) {
+      result[key] = mergeNumericArray(result[key], b[key]) as any;
+    } else {
+      result[key] = b[key];
+    }
+  }
+  return result;
+}
+
+function mergeNumericArray(target: number[], source: number[]): number[] {
+  target = target.slice();
+  for (let i = 0; i < source.length; i++) {
+    const v = source[i];
+    if (Number.isFinite(v)) {
+      target[i] = v;
+    }
+  }
+  return target;
+}

package/src/utils/math-utils.ts

@@ -26,6 +26,18 @@ export function getCameraPosition(
   return [viewMatrixInverse[12], viewMatrixInverse[13], viewMatrixInverse[14]];
 }
 
+export function getProjectionParameters(projectionMatrix: Matrix4 | NumericArray): {
+  near: number;
+  far: number;
+} {
+  const m22 = projectionMatrix[10];
+  const m23 = projectionMatrix[14];
+  return {
+    near: m23 / (m22 - 1),
+    far: m23 / (m22 + 1)
+  };
+}
+
 export type FrustumPlane = {
   distance: number;
   normal: Vector3;

package/src/utils/texture.ts

@@ -57,7 +57,9 @@ export function createTexture(
     },
     mipLevels: device.getMipLevelCount(width, height)
   });
-  texture.generateMipmapsWebGL();
+  if (device.type === 'webgl') {
+    texture.generateMipmapsWebGL();
+  }
 
   // Track this texture
   internalTextures[texture.id] = owner;

package/src/viewports/globe-viewport.ts

@@ -13,7 +13,7 @@ import {vec3, vec4} from '@math.gl/core';
 const DEGREES_TO_RADIANS = Math.PI / 180;
 const RADIANS_TO_DEGREES = 180 / Math.PI;
 const EARTH_RADIUS = 6370972;
-const GLOBE_RADIUS = 256;
+export const GLOBE_RADIUS = 256;
 
 function getDistanceScales() {
   const unitsPerMeter = GLOBE_RADIUS / EARTH_RADIUS;

package/src/viewports/orbit-viewport.ts

@@ -6,6 +6,7 @@ import Viewport from '../viewports/viewport';
 
 import {Matrix4} from '@math.gl/core';
 import {pixelsToWorld, fovyToAltitude} from '@math.gl/web-mercator';
+import {getProjectionParameters} from '../utils/math-utils';
 
 const DEGREES_TO_RADIANS = Math.PI / 180;
 
@@ -150,9 +151,14 @@ export default class OrbitViewport extends Viewport {
 
   panByPosition(coords: number[], pixel: number[], startPixel?: number[]): OrbitViewportOptions {
     const p0 = this.project(coords);
+    const {near, far} = getProjectionParameters(this.projectionMatrix);
+    const pz = (near * far) / (far - p0[2] * (far - near));
+    const centerZ = (near * far) / (far - this.projectedCenter[2] * (far - near));
+    const shiftScale = pz / centerZ;
+
     const nextCenter = [
-      this.width / 2 + p0[0] - pixel[0],
-      this.height / 2 + p0[1] - pixel[1],
+      this.width / 2 + (p0[0] - pixel[0]) * shiftScale,
+      this.height / 2 + (p0[1] - pixel[1]) * shiftScale,
       this.projectedCenter[2]
     ];
     return {

package/src/viewports/orthographic-viewport.ts

@@ -48,6 +48,10 @@ function getProjectionMatrix({
   });
 }
 
+/** independent zoom levels for X and Y axes
+ * @deprecated use `zoomX` and `zoomY` instead */
+type Deprecated2DZoom = [number, number];
+
 export type OrthographicViewportOptions = {
   /** Name of the viewport */
   id?: string;
@@ -62,8 +66,10 @@ export type OrthographicViewportOptions = {
   /** The world position at the center of the viewport. Default `[0, 0, 0]`. */
   target?: [number, number, number] | [number, number];
   /**  The zoom level of the viewport. `zoom: 0` maps one unit distance to one pixel on screen, and increasing `zoom` by `1` scales the same object to twice as large.
-   *   To apply independent zoom levels to the X and Y axes, supply an array `[zoomX, zoomY]`. Default `0`. */
-  zoom?: number | [number, number];
+   *   To apply independent zoom levels to the X and Y axes, use `zoomX` and `zoomY`.
+   * @default 0
+   */
+  zoom?: number | Deprecated2DZoom;
   /** Independent zoom along the X axis. Overrides `zoom`. */
   zoomX?: number;
   /** Independent zoom along the Y axis. Overrides `zoom`. */

package/src/viewports/web-mercator-viewport.ts

@@ -285,6 +285,16 @@ export default class WebMercatorViewport extends Viewport {
     return {longitude, latitude};
   }
 
+  /**
+   * Returns a new longitude and latitude that keeps a 3D world coordinate at a given screen pixel
+   * This version handles the z-component (altitude) properly for cameras positioned above ground
+   */
+  panByPosition3D(coords: number[], pixel: number[]): WebMercatorViewportOptions {
+    const targetZ = coords[2] || 0;
+    const deltaLngLat = vec2.sub([], coords, this.unproject(pixel, {targetZ}));
+    return {longitude: this.longitude + deltaLngLat[0], latitude: this.latitude + deltaLngLat[1]};
+  }
+
   getBounds(options: {z?: number} = {}): [number, number, number, number] {
     // @ts-ignore
     const corners = getBounds(this, options.z || 0);