@deck.gl/core 9.3.0-alpha.1 → 9.3.0-alpha.3

package/src/controllers/orthographic-controller.ts

@@ -3,66 +3,442 @@
 // Copyright (c) vis.gl contributors
 
 import {clamp} from '@math.gl/core';
-import Controller from './controller';
-import {OrbitState} from './orbit-controller';
+import Controller, {ControllerProps} from './controller';
+import ViewState from './view-state';
+
+import type Viewport from '../viewports/viewport';
 import LinearInterpolator from '../transitions/linear-interpolator';
 
-class OrthographicState extends OrbitState {
-  zoomAxis: 'X' | 'Y' | 'all';
+export type OrthographicStateProps = {
+  width: number;
+  height: number;
+  target?: number[];
+  zoom?: number | number[];
+  zoomX?: number;
+  zoomY?: number;
+  zoomAxis?: 'X' | 'Y' | 'all';
+
+  /** Viewport constraints */
+  maxZoomX?: number;
+  minZoomX?: number;
+  maxZoomY?: number;
+  minZoomY?: number;
+
+  maxBounds?: ControllerProps['maxBounds'];
+};
+
+type OrthographicStateInternal = {
+  startPanPosition?: number[];
+  startZoomPosition?: number[];
+  startZoom?: number[];
+};
+
+function normalizeZoom({
+  zoom = 0,
+  zoomX,
+  zoomY
+}: {
+  zoom?: number | number[];
+  zoomX?: number;
+  zoomY?: number;
+}): {
+  zoomX: number;
+  zoomY: number;
+} {
+  zoomX = zoomX ?? (Array.isArray(zoom) ? zoom[0] : zoom);
+  zoomY = zoomY ?? (Array.isArray(zoom) ? zoom[1] : zoom);
+  return {zoomX, zoomY};
+}
+
+export class OrthographicState extends ViewState<
+  OrthographicState,
+  OrthographicStateProps,
+  OrthographicStateInternal
+> {
+  constructor(
+    options: OrthographicStateProps &
+      OrthographicStateInternal & {
+        maxZoom?: number;
+        minZoom?: number;
+        makeViewport: (props: Record<string, any>) => Viewport;
+      }
+  ) {
+    const {
+      /* Viewport arguments */
+      width, // Width of viewport
+      height, // Height of viewport
+      target = [0, 0, 0],
+      zoom = 0,
+      zoomAxis = 'all',
+
+      /* Viewport constraints */
+      minZoom = -Infinity,
+      maxZoom = Infinity,
+      minZoomX = minZoom,
+      maxZoomX = maxZoom,
+      minZoomY = minZoom,
+      maxZoomY = maxZoom,
+
+      maxBounds = null,
+
+      /** Interaction states, required to calculate change during transform */
+      // Model state when the pan operation first started
+      startPanPosition,
+      // Model state when the zoom operation first started
+      startZoomPosition,
+      startZoom
+    } = options;
+
+    const {zoomX, zoomY} = normalizeZoom(options);
+
+    super(
+      {
+        width,
+        height,
+        target,
+        zoom,
+        zoomX,
+        zoomY,
+        zoomAxis,
+        minZoomX,
+        maxZoomX,
+        minZoomY,
+        maxZoomY,
+        maxBounds
+      },
+      {
+        startPanPosition,
+        startZoomPosition,
+        startZoom
+      },
+      options.makeViewport
+    );
+  }
+
+  /**
+   * Start panning
+   * @param {[Number, Number]} pos - position on screen where the pointer grabs
+   */
+  panStart({pos}: {pos: [number, number]}): OrthographicState {
+    return this._getUpdatedState({
+      startPanPosition: this._unproject(pos)
+    });
+  }
+
+  /**
+   * Pan
+   * @param {[Number, Number]} pos - position on screen where the pointer is
+   */
+  pan({pos, startPosition}: {pos: [number, number]; startPosition?: number[]}): OrthographicState {
+    const startPanPosition = this.getState().startPanPosition || startPosition;
+
+    if (!startPanPosition) {
+      return this;
+    }
+
+    const viewport = this.makeViewport(this.getViewportProps());
+    const newProps = viewport.panByPosition(startPanPosition, pos);
+
+    return this._getUpdatedState(newProps);
+  }
+
+  /**
+   * End panning
+   * Must call if `panStart()` was called
+   */
+  panEnd(): OrthographicState {
+    return this._getUpdatedState({
+      startPanPosition: null
+    });
+  }
+
+  /**
+   * Start rotating
+   */
+  rotateStart(): OrthographicState {
+    return this;
+  }
+
+  /**
+   * Rotate
+   */
+  rotate(): OrthographicState {
+    return this;
+  }
+
+  /**
+   * End rotating
+   */
+  rotateEnd(): OrthographicState {
+    return this;
+  }
+
+  // shortest path between two view states
+  shortestPathFrom(viewState: OrthographicState): OrthographicStateProps {
+    const fromProps = viewState.getViewportProps();
+    const props = {...this.getViewportProps()};
+    return props;
+  }
+
+  /**
+   * Start zooming
+   * @param {[Number, Number]} pos - position on screen where the pointer grabs
+   */
+  zoomStart({pos}: {pos: [number, number]}): OrthographicState {
+    const {zoomX, zoomY} = this.getViewportProps();
+    return this._getUpdatedState({
+      startZoomPosition: this._unproject(pos),
+      startZoom: [zoomX, zoomY]
+    });
+  }
+
+  /**
+   * Zoom
+   * @param {[Number, Number]} pos - position on screen where the current target is
+   * @param {[Number, Number]} startPos - the target position at
+   *   the start of the operation. Must be supplied of `zoomStart()` was not called
+   * @param {Number} scale - a number between [0, 1] specifying the accumulated
+   *   relative scale.
+   */
+  zoom({
+    pos,
+    startPos,
+    scale
+  }: {
+    pos: [number, number];
+    startPos?: [number, number];
+    scale: number;
+  }): OrthographicState {
+    let {startZoom, startZoomPosition} = this.getState();
+    if (!startZoomPosition) {
+      // We have two modes of zoom:
+      // scroll zoom that are discrete events (transform from the current zoom level),
+      // and pinch zoom that are continuous events (transform from the zoom level when
+      // pinch started).
+      // If startZoom state is defined, then use the startZoom state;
+      // otherwise assume discrete zooming
+      const {zoomX, zoomY} = this.getViewportProps();
+      startZoom = [zoomX, zoomY];
+      startZoomPosition = this._unproject(startPos || pos);
+    }
+    if (!startZoomPosition) {
+      return this;
+    }
+    const newZoomProps = this._constrainZoom(this._calculateNewZoom({scale, startZoom}));
+    const zoomedViewport = this.makeViewport({...this.getViewportProps(), ...newZoomProps});
+
+    return this._getUpdatedState({
+      ...newZoomProps,
+      ...zoomedViewport.panByPosition(startZoomPosition, pos)
+    });
+  }
+
+  /**
+   * End zooming
+   * Must call if `zoomStart()` was called
+   */
+  zoomEnd(): OrthographicState {
+    return this._getUpdatedState({
+      startZoomPosition: null,
+      startZoom: null
+    });
+  }
+
+  zoomIn(speed: number = 2): OrthographicState {
+    return this._getUpdatedState(this._calculateNewZoom({scale: speed}));
+  }
+
+  zoomOut(speed: number = 2): OrthographicState {
+    return this._getUpdatedState(this._calculateNewZoom({scale: 1 / speed}));
+  }
+
+  moveLeft(speed: number = 50): OrthographicState {
+    return this._panFromCenter([-speed, 0]);
+  }
+
+  moveRight(speed: number = 50): OrthographicState {
+    return this._panFromCenter([speed, 0]);
+  }
+
+  moveUp(speed: number = 50): OrthographicState {
+    return this._panFromCenter([0, -speed]);
+  }
+
+  moveDown(speed: number = 50): OrthographicState {
+    return this._panFromCenter([0, speed]);
+  }
+
+  rotateLeft(speed: number = 15): OrthographicState {
+    return this;
+  }
+
+  rotateRight(speed: number = 15): OrthographicState {
+    return this;
+  }
+
+  rotateUp(speed: number = 10): OrthographicState {
+    return this;
+  }
+
+  rotateDown(speed: number = 10): OrthographicState {
+    return this;
+  }
 
-  constructor(props) {
-    super(props);
+  /* Private methods */
 
-    this.zoomAxis = props.zoomAxis || 'all';
+  _project(pos: number[]): number[] {
+    const viewport = this.makeViewport(this.getViewportProps());
+    return viewport.project(pos);
+  }
+  _unproject(pos: number[]): number[] {
+    const viewport = this.makeViewport(this.getViewportProps());
+    return viewport.unproject(pos);
   }
 
-  _calculateNewZoom({scale, startZoom}) {
-    const {maxZoom, minZoom} = this.getViewportProps();
+  // Calculates new zoom
+  _calculateNewZoom({scale, startZoom}: {scale: number; startZoom?: number[]}): {
+    zoomX: number;
+    zoomY: number;
+  } {
+    const {zoomX, zoomY, zoomAxis} = this.getViewportProps();
     if (startZoom === undefined) {
-      startZoom = this.getViewportProps().zoom;
+      startZoom = [zoomX, zoomY];
+    }
+    const deltaZoom = Math.log2(scale);
+    let [newZoomX, newZoomY] = startZoom;
+    switch (zoomAxis) {
+      case 'X':
+        // Scale x only
+        newZoomX += deltaZoom;
+        break;
+      case 'Y':
+        // Scale y only
+        newZoomY += deltaZoom;
+        break;
+      default:
+        // Lock aspect ratio
+        newZoomX += deltaZoom;
+        newZoomY += deltaZoom;
+    }
+    return {
+      zoomX: newZoomX,
+      zoomY: newZoomY
+    };
+  }
+
+  _panFromCenter(offset) {
+    const {target} = this.getViewportProps();
+    const center = this._project(target);
+    return this.pan({
+      startPosition: target,
+      pos: [center[0] + offset[0], center[1] + offset[1]]
+    });
+  }
+
+  _getUpdatedState(newProps): OrthographicState {
+    // @ts-ignore
+    return new this.constructor({
+      makeViewport: this.makeViewport,
+      ...this.getViewportProps(),
+      ...this.getState(),
+      ...newProps
+    });
+  }
+
+  // Apply any constraints (mathematical or defined by _viewportProps) to map state
+  applyConstraints(props: Required<OrthographicStateProps>): Required<OrthographicStateProps> {
+    // Ensure zoom is within specified range
+    const {zoomX, zoomY} = this._constrainZoom(props, props);
+    props.zoomX = zoomX;
+    props.zoomY = zoomY;
+    // Backward compatibility: update zoom to reflect new view state
+    // zoom will always be ignored when zoomX and zoomY are specified, but legacy apps may still read zoom in `onViewStateChange`
+    props.zoom =
+      Array.isArray(props.zoom) || props.zoomX !== props.zoomY
+        ? [props.zoomX, props.zoomY]
+        : props.zoomX;
+
+    const {maxBounds, target} = props;
+    if (maxBounds) {
+      // only calculate center and zoom ranges at rotation=0
+      // to maintain visual stability when rotating
+      const halfWidth = props.width / 2 / 2 ** zoomX;
+      const halfHeight = props.height / 2 / 2 ** zoomY;
+      const minX = maxBounds[0][0] + halfWidth;
+      const maxX = maxBounds[1][0] - halfWidth;
+      const minY = maxBounds[0][1] + halfHeight;
+      const maxY = maxBounds[1][1] - halfHeight;
+      const x = clamp(target[0], minX, maxX);
+      const y = clamp(target[1], minY, maxY);
+      if (x !== target[0] || y !== target[1]) {
+        props.target = target.slice();
+        props.target[0] = x;
+        props.target[1] = y;
+      }
     }
-    let deltaZoom = Math.log2(scale);
-    if (Array.isArray(startZoom)) {
-      let [newZoomX, newZoomY] = startZoom;
-      switch (this.zoomAxis) {
-        case 'X':
-          // Scale x only
-          newZoomX = clamp(newZoomX + deltaZoom, minZoom, maxZoom);
-          break;
-        case 'Y':
-          // Scale y only
-          newZoomY = clamp(newZoomY + deltaZoom, minZoom, maxZoom);
-          break;
-        default:
-          // Lock aspect ratio
-          let z = Math.min(newZoomX + deltaZoom, newZoomY + deltaZoom);
-          if (z < minZoom) {
-            deltaZoom += minZoom - z;
-          }
-          z = Math.max(newZoomX + deltaZoom, newZoomY + deltaZoom);
-          if (z > maxZoom) {
-            deltaZoom += maxZoom - z;
-          }
-          newZoomX += deltaZoom;
-          newZoomY += deltaZoom;
+    return props;
+  }
+
+  _constrainZoom(
+    {zoomX, zoomY}: {zoomX: number; zoomY: number},
+    props?: Required<OrthographicStateProps>
+  ): {zoomX: number; zoomY: number} {
+    props ||= this.getViewportProps();
+    const {zoomAxis, maxZoomX, maxZoomY, maxBounds} = props;
+    let {minZoomX, minZoomY} = props;
+    const shouldApplyMaxBounds = maxBounds !== null && props.width > 0 && props.height > 0;
+
+    if (shouldApplyMaxBounds) {
+      const bl = maxBounds[0];
+      const tr = 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) {
+        minZoomX = Math.max(minZoomX, Math.log2(props.width / w));
+        if (minZoomX > maxZoomX) minZoomX = maxZoomX;
       }
-      return [newZoomX, newZoomY];
+      if (Number.isFinite(h) && h > 0) {
+        minZoomY = Math.max(minZoomY, Math.log2(props.height / h));
+        if (minZoomY > maxZoomY) minZoomY = maxZoomY;
+      }
+    }
+
+    switch (zoomAxis) {
+      case 'X':
+        zoomX = clamp(zoomX, minZoomX, maxZoomX);
+        break;
+      case 'Y':
+        zoomY = clamp(zoomY, minZoomY, maxZoomY);
+        break;
+      default:
+        // Lock aspect ratio
+        let delta = Math.min(maxZoomX - zoomX, maxZoomY - zoomY, 0);
+        if (delta === 0) {
+          delta = Math.max(minZoomX - zoomX, minZoomY - zoomY, 0);
+        }
+        if (delta !== 0) {
+          zoomX += delta;
+          zoomY += delta;
+        }
     }
-    // Ignore `zoomAxis`
-    // `LinearTransitionInterpolator` does not support interpolation between a number and an array
-    // So if zoom is a number (legacy use case), new zoom still has to be a number
-    return clamp(startZoom + deltaZoom, minZoom, maxZoom);
+    return {zoomX, zoomY};
   }
 }
 
-export default class OrthographicController extends Controller<OrbitState> {
+export default class OrthographicController extends Controller<OrthographicState> {
   ControllerState = OrthographicState;
   transition = {
     transitionDuration: 300,
-    transitionInterpolator: new LinearInterpolator(['target', 'zoom'])
+    transitionInterpolator: new LinearInterpolator(['target', 'zoomX', 'zoomY'])
   };
   dragMode: 'pan' | 'rotate' = 'pan';
 
+  setProps(props: ControllerProps & OrthographicStateProps) {
+    Object.assign(props, normalizeZoom(props));
+    super.setProps(props);
+  }
+
   _onPanRotate() {
     // No rotation in orthographic view
     return false;

package/src/controllers/terrain-controller.ts

@@ -0,0 +1,146 @@
+// deck.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import MapController from './map-controller';
+import {MapState, MapStateProps} from './map-controller';
+import type {ControllerProps, InteractionState} from './controller';
+import type {MjolnirGestureEvent, MjolnirWheelEvent} from 'mjolnir.js';
+
+/**
+ * Controller that extends MapController with terrain-aware behavior.
+ * The camera smoothly follows terrain elevation during pan/zoom.
+ */
+export default class TerrainController extends MapController {
+  /** Cached terrain altitude from depth picking at viewport center (smoothed) */
+  private _terrainAltitude?: number = undefined;
+  /** Raw (unsmoothed) terrain altitude from latest pick */
+  private _terrainAltitudeTarget?: number = undefined;
+
+  setProps(
+    props: ControllerProps &
+      MapStateProps & {
+        rotationPivot?: 'center' | '2d' | '3d';
+        getAltitude?: (pos: [number, number]) => number | undefined;
+      }
+  ) {
+    super.setProps({rotationPivot: '3d', ...props});
+
+    // Drive smoothing animation when terrain altitude hasn't converged yet.
+    if (
+      this._terrainAltitude !== undefined &&
+      this._terrainAltitudeTarget !== undefined &&
+      Math.abs(this._terrainAltitudeTarget - this._terrainAltitude) > 0.01
+    ) {
+      this.updateViewport(
+        new this.ControllerState({
+          makeViewport: this.makeViewport,
+          ...this.props,
+          ...this.state
+        } as any)
+      );
+    }
+  }
+
+  protected updateViewport(
+    newControllerState: MapState,
+    extraProps: Record<string, any> | null = null,
+    interactionState: InteractionState = {}
+  ): void {
+    const SMOOTHING = 0.05;
+
+    // No interactions yet, do not update
+    if (this._terrainAltitudeTarget === undefined) return;
+
+    if (this._terrainAltitude === undefined) {
+      // First interaction, rebase to avoid jump
+      this._terrainAltitude = this._terrainAltitudeTarget;
+      extraProps = this._rebaseViewport(
+        this._terrainAltitudeTarget,
+        newControllerState,
+        extraProps
+      );
+    } else {
+      // Standard interaction, smoothly blend target into actual altitude
+      this._terrainAltitude += (this._terrainAltitudeTarget - this._terrainAltitude) * SMOOTHING;
+    }
+
+    const viewportProps = newControllerState.getViewportProps();
+    const pos = viewportProps.position || [0, 0, 0];
+    extraProps = {
+      ...extraProps,
+      position: [pos[0], pos[1], this._terrainAltitude]
+    };
+
+    super.updateViewport(newControllerState, extraProps, interactionState);
+  }
+
+  protected _onPanStart(event: MjolnirGestureEvent): boolean {
+    this._pickTerrainCenterAltitude();
+    return super._onPanStart(event);
+  }
+
+  protected _onWheel(event: MjolnirWheelEvent): boolean {
+    this._pickTerrainCenterAltitude();
+    return super._onWheel(event);
+  }
+
+  protected _onDoubleClick(event: MjolnirGestureEvent): boolean {
+    this._pickTerrainCenterAltitude();
+    return super._onDoubleClick(event);
+  }
+
+  private _pickTerrainCenterAltitude(): void {
+    // TODO use async picking?
+    if (!this.pickPosition) {
+      return;
+    }
+    const {x, y, width, height} = this.props;
+    const pickResult = this.pickPosition(x + width / 2, y + height / 2);
+    if (pickResult?.coordinate && pickResult.coordinate.length >= 3) {
+      this._terrainAltitudeTarget = pickResult.coordinate[2];
+    }
+  }
+
+  /**
+   * Utility function to return viewport that looks the same, but with
+   * a position shifted to [0, 0, altitude]
+   */
+  private _rebaseViewport(
+    altitude: number,
+    newControllerState: MapState,
+    extraProps: Record<string, any> | null
+  ): Record<string, any> | null {
+    const viewportProps = newControllerState.getViewportProps();
+    const oldViewport = this.makeViewport({...viewportProps, position: [0, 0, 0]});
+    const oldCameraPos = oldViewport.cameraPosition;
+
+    const centerZOffset = altitude * oldViewport.distanceScales.unitsPerMeter[2];
+    const cameraHeightAboveOldCenter = oldCameraPos[2];
+    const newCameraHeightAboveCenter = cameraHeightAboveOldCenter - centerZOffset;
+    if (newCameraHeightAboveCenter <= 0) {
+      return extraProps;
+    }
+
+    const zoomDelta = Math.log2(cameraHeightAboveOldCenter / newCameraHeightAboveCenter);
+    const newZoom = viewportProps.zoom + zoomDelta;
+
+    const newViewport = this.makeViewport({
+      ...viewportProps,
+      zoom: newZoom,
+      position: [0, 0, altitude]
+    });
+    const {width, height} = viewportProps;
+    const screenCenter: [number, number] = [width / 2, height / 2];
+    const worldPoint = oldViewport.unproject(screenCenter, {targetZ: altitude});
+    if (
+      worldPoint &&
+      'panByPosition3D' in newViewport &&
+      typeof newViewport.panByPosition3D === 'function'
+    ) {
+      const adjusted = newViewport.panByPosition3D(worldPoint, screenCenter);
+      return {...extraProps, position: [0, 0, altitude], zoom: newZoom, ...adjusted};
+    }
+    return extraProps;
+  }
+}

package/src/controllers/view-state.ts

@@ -13,7 +13,14 @@ export default abstract class ViewState<
   private _viewportProps: Required<Props>;
   private _state: State;
 
-  constructor(props: Required<Props>, state: State) {
+  makeViewport: (props: Record<string, any>) => Viewport;
+
+  constructor(
+    props: Required<Props>,
+    state: State,
+    makeViewport: (props: Record<string, any>) => Viewport
+  ) {
+    this.makeViewport = makeViewport;
     this._viewportProps = this.applyConstraints(props);
     this._state = state;
   }

package/src/debug/loggers.ts

@@ -123,7 +123,7 @@ export const getLoggers = (log: Log): Record<string, Function> => ({
   /* Render events */
 
   'deckRenderer.renderLayers': (deckRenderer, renderStats, opts) => {
-    const {pass, redrawReason, stats} = opts;
+    const {pass, redrawReason} = opts;
     for (const status of renderStats) {
       const {totalCount, visibleCount, compositeCount, pickableCount} = status;
       const primitiveCount = totalCount - compositeCount;
@@ -135,10 +135,6 @@ export const getLoggers = (log: Log): Record<string, Function> => ({
   ${visibleCount} (of ${totalCount} layers) to ${pass} because ${redrawReason} \
   (${hiddenCount} hidden, ${compositeCount} composite ${pickableCount} pickable)`
       )();
-
-      if (stats) {
-        stats.get('Redraw Layers').add(visibleCount);
-      }
     }
   }
 });