@cesium/engine 26.1.0 → 26.3.0

package/Source/Scene/Controllers/Controller.js

@@ -0,0 +1,63 @@
+import DeveloperError from "../../Core/DeveloperError.js";
+
+/**
+ * An interface for a camera controller that can be registered with the scene to handle input events, camera animations, and other interactions. Implementations of this interface are expected to be registered with the scene via a {@link ControllerHost}.
+ * This type describes an
+ * interface and is not intended to be instantiated directly.
+ * @class
+ * @abstract
+ * @see {@link HybridScreenSpacePanCameraController}
+ * @see {@link ScreenSpaceElevatorCameraController}
+ * @see {@link ScreenSpaceMapCameraController}
+ * @see {@link ScreenSpaceTiltOrbitCameraController}
+ */
+class Controller {
+  /**
+   * Determines if the controller is enabled and should be updated by the host scene.
+   * @type {boolean}
+   */
+  get enabled() {
+    return DeveloperError.throwInstantiationError();
+  }
+  set enabled(value) {
+    DeveloperError.throwInstantiationError();
+  }
+
+  /**
+   * Invoked when the controller is added to the DOM. Implement <code>connectedCallback</code> to set up any DOM event listeners.
+   * @param {HTMLElement} element The DOM element containing the Cesium scene.
+   */
+  connectedCallback(element) {
+    DeveloperError.throwInstantiationError();
+  }
+
+  /**
+   * Invoked when the controller is removed from the DOM. Implement <code>disconnectedCallback</code> to tear down any DOM event listeners.
+   * @param {HTMLElement} element The DOM element containing the Cesium scene.
+   */
+  disconnectedCallback(element) {
+    DeveloperError.throwInstantiationError();
+  }
+
+  /**
+   * Invoked once per frame. Implement <code>update</code> to modify the camera or other parts of the scene.
+   * @see {@link https://cesium.com/blog/2018/01/24/cesium-scene-rendering-performance/#updaterender-cycle-events|Update/Render Cycle Events}
+   * @param {Scene} scene
+   * @param {JulianDate} time The current simulation time.
+   */
+  update(scene, time) {
+    DeveloperError.throwInstantiationError();
+  }
+
+  /**
+   * Invoked when the controller is being updated the first time, immediately before <code>update</code> is called. Implement <code>firstUpdate</code> to perform one-time work after the relevant scene has begun its render loop. Some examples might include initializing simulation time values or adding a primitive to the scene.
+   * @see Controller#update
+   * @param {Scene} scene
+   * @param {JulianDate} time The current simulation time.
+   */
+  firstUpdate(scene, time) {
+    DeveloperError.throwInstantiationError();
+  }
+}
+
+export default Controller;

package/Source/Scene/Controllers/ControllerHost.js

@@ -0,0 +1,78 @@
+/**
+ * Collects an array of Controller objects that can be registered with the scene to handle input events, camera animations, and other interactions.
+ * @class
+ * @see {@link Controller}
+ * @see {@link Scene#controllerHost}
+ */
+class ControllerHost {
+  /**
+   * Creates an instance of a <code>ControllerHost</code>. Typically, a <code>ControllerHost</code> is created by the Scene constructor and accessed via {@link Scene#controllerHost}.
+   * @see {@link Scene#controllerHost}
+   */
+  constructor() {
+    /**
+     * @type {Controller[]}
+     * @private
+     */
+    this._controllers = [];
+    this._needsUpdate = new Set();
+  }
+
+  /**
+   * The number of controllers registered to this host.
+   * @type {number}
+   * @readonly
+   */
+  get controllerCount() {
+    return this._controllers.length;
+  }
+
+  /**
+   * Registers a controller implementation with this host.
+   * @param {Controller} controller An implementation of the Controller interface to register with this host.
+   * @param {HTMLElement} element The DOM element containing the Cesium scene.
+   * @param {number} [priority=0] An index, less than or equal to the current count of registed controllers, that defines the precedence of the new controller relative to those previously registered. A priority of <code>0</code> would mean the new controller would apply its updates before any other controller. As subsequent controllers are updated, their effects are applied on top of any previous update effects. If omitted, the new controller becomes the highest priority, i.e., its updates are applied after all other controllers.
+   */
+  registerController(controller, element, priority) {
+    const index = priority ?? this.controllerCount;
+    this._controllers.splice(index, 0, controller);
+    this._needsUpdate.add(controller);
+    controller.connectedCallback(element);
+  }
+
+  /**
+   * Unregisters a controller implementation from this host.
+   * @param {Controller} controller An implementation of the Controller interface to unregister from this host.
+   * @param {HTMLElement} element The DOM element containing the Cesium scene.
+   */
+  unregisterController(controller, element) {
+    const controllers = this._controllers;
+    const index = controllers.indexOf(controller);
+    if (index !== -1) {
+      controllers.splice(index, 1);
+      controller.disconnectedCallback(element);
+    }
+  }
+
+  /**
+   * Invoked once per frame by the host scene. Updates all registered controllers in order of their priority.
+   * @param {Scene} scene The host scene.
+   * @param {JulianDate} time The current simulation time.
+   */
+  update(scene, time) {
+    for (const controller of this._controllers) {
+      if (!controller.enabled) {
+        continue;
+      }
+
+      if (this._needsUpdate.has(controller)) {
+        controller.firstUpdate(scene, time);
+        this._needsUpdate.delete(controller);
+      }
+
+      controller.update(scene, time);
+    }
+  }
+}
+
+export default ControllerHost;

package/Source/Scene/Controllers/HybridScreenSpacePanCameraController.js

@@ -0,0 +1,106 @@
+import ScreenSpaceElevatorCameraController from "./ScreenSpaceElevatorCameraController.js";
+import ScreenSpaceMapCameraController from "./ScreenSpaceMapCameraController.js";
+import Cartesian3 from "../../Core/Cartesian3.js";
+import CesiumMath from "../../Core/Math.js";
+
+/**
+ * A contextual camera controller that combines screenspace map panning and screenspace elevator panning. The controller automatically switches between the two based on the camera's angle relative to nadir. If the camera is looking mostly down (within angleThreshold of nadir), <code>ScreenSpaceMapCameraController</code> is used.
+ * If the camera is looking towards the horizon (beyond angleThreshold from nadir), the <code>ScreenSpaceElevatorCameraController</code> is used.
+ * @implements Controller
+ * @example
+ * viewer.scene.screenSpaceCameraController.enableInputs = false;
+ * viewer.scene.screenSpaceCameraController.enableCollisionDetection = false;
+ *
+ * const hybridController = new HybridScreenSpacePanCameraController();
+ * viewer.addController(hybridController);
+ */
+class HybridScreenSpacePanCameraController {
+  constructor() {
+    this._elevatorController = new ScreenSpaceElevatorCameraController();
+    this._mapController = new ScreenSpaceMapCameraController();
+
+    this._enabled = true;
+    this._ellipsoidNormal = new Cartesian3();
+
+    /**
+     * The angle threshold in radians that determines which controller is used. If the camera is looking within this angle of nadir, the map controller is used. Otherwise, the elevator controller is used.
+     * @type {number}
+     * @default CesiumMath.toRadians(125)
+     */
+    this.angleThreshold = CesiumMath.toRadians(125);
+  }
+
+  get enabled() {
+    return this._enabled;
+  }
+
+  set enabled(value) {
+    this._enabled = value;
+  }
+
+  /**
+   * The controller that is used when the camera is looking more horizontally (beyond angleThreshold from nadir).
+   * @type {ScreenSpaceElevatorCameraController}
+   * @readonly
+   */
+  get elevatorController() {
+    return this._elevatorController;
+  }
+
+  /**
+   * The controller that is used when the camera is looking mostly down (within angleThreshold of nadir).
+   * @type {ScreenSpaceMapCameraController}
+   * @readonly
+   */
+  get mapController() {
+    return this._mapController;
+  }
+
+  /**
+   * @inheritdoc
+   * @param {HTMLElement} element The DOM element containing the Cesium scene.
+   */
+  connectedCallback(element) {
+    this._elevatorController.connectedCallback(element);
+    this._mapController.connectedCallback(element);
+  }
+
+  /**
+   * @inheritdoc
+   * @param {HTMLElement} element The DOM element containing the Cesium scene.
+   */
+  disconnectedCallback(element) {
+    this._elevatorController.disconnectedCallback(element);
+    this._mapController.disconnectedCallback(element);
+  }
+
+  /**
+   * @inheritdoc
+   */
+  firstUpdate() {
+    this._elevatorController.firstUpdate();
+    this._mapController.firstUpdate();
+  }
+
+  /**
+   * @inheritdoc
+   * @param {Scene} scene
+   */
+  update(scene) {
+    const camera = scene.camera;
+    const normal = scene.ellipsoid.geodeticSurfaceNormal(
+      camera.positionWC,
+      this._ellipsoidNormal,
+    );
+
+    const angle = Math.abs(Cartesian3.angleBetween(normal, camera.directionWC));
+    const activeController =
+      angle < this.angleThreshold && angle > Math.PI - this.angleThreshold
+        ? this._elevatorController
+        : this._mapController;
+
+    activeController.update(scene);
+  }
+}
+
+export default HybridScreenSpacePanCameraController;

package/Source/Scene/Controllers/MouseButton.js

@@ -0,0 +1,32 @@
+// @ts-check
+
+/**
+ * This enumerated type is for classifying mouse buttons: left, middle, and right.
+ * @enum {number}
+ */
+const MouseButton = {
+  /**
+   * Represents a mouse left button.
+   * @type {number}
+   * @constant
+   */
+  LEFT: 0,
+
+  /**
+   * Represents a mouse middle button.
+   * @type {number}
+   * @constant
+   */
+  MIDDLE: 1,
+
+  /**
+   * Represents a mouse right button.
+   * @type {number}
+   * @constant
+   */
+  RIGHT: 2,
+};
+
+Object.freeze(MouseButton);
+
+export default MouseButton;

package/Source/Scene/Controllers/ScreenSpaceElevatorCameraController.js

@@ -0,0 +1,295 @@
+import Cartesian2 from "../../Core/Cartesian2.js";
+import Cartesian3 from "../../Core/Cartesian3.js";
+import defined from "../../Core/defined.js";
+import Frozen from "../../Core/Frozen.js";
+import getTimestamp from "../../Core/getTimestamp.js";
+import CesiumMath from "../../Core/Math.js";
+import ScreenSpaceEventHandler from "../../Core/ScreenSpaceEventHandler.js";
+import TimeConstants from "../../Core/TimeConstants.js";
+import defaultPickWorldPosition from "./defaultPickWorldPosition.js";
+import ScreenSpaceInputBindings from "./ScreenSpaceInputBindings.js";
+import MouseButton from "./MouseButton.js";
+
+/**
+ * @typedef {object} ControllerOptions
+ * @memberof ScreenSpaceElevatorCameraController
+ * @property {ScreenSpaceInputBindings.InputBinding[]} [dragInputs] The drag input bindings that control panning.
+ */
+
+/**
+ * A camera controller that allows panning the camera tangential to the ellipsoid, i.e., up and down relative to the ellipsoid normal, in screen space
+ * by clicking and dragging the mouse.
+ * @class
+ * @implements Controller
+ * @example
+ * viewer.scene.screenSpaceCameraController.enableInputs = false;
+ * viewer.scene.screenSpaceCameraController.enableCollisionDetection = false;
+ *
+ * const elevatorCameraController = new Cesium.ScreenSpaceElevatorCameraController();
+ * viewer.addController(elevatorCameraController);
+ *
+ * @example
+ * // Configure the controller to use the right mouse button for panning instead of the default left mouse button.
+ * const elevatorCameraController = new Cesium.ScreenSpaceElevatorCameraController({
+ *  dragInputs: [{ button: Cesium.MouseButton.RIGHT}]
+ * });
+ * viewer.addController(elevatorCameraController);
+ */
+class ScreenSpaceElevatorCameraController {
+  /**
+   * @private
+   * @returns {ScreenSpaceInputBindings.InputBinding[]} The default drag input bindings.
+   */
+  static _getDefaultDragInputs() {
+    return [
+      Object.freeze({
+        button: MouseButton.LEFT,
+      }),
+    ];
+  }
+
+  /**
+   * Creates an instance of a ScreenSpaceElevatorCameraController.
+   * @param {ScreenSpaceElevatorCameraController.ControllerOptions} [options] The options for configuring the controller.
+   */
+  constructor(options = Frozen.EMPTY_OBJECT) {
+    this._enabled = true;
+    this._handler = undefined;
+    this._lastUpdateTime = undefined;
+
+    /**
+     * The drag input bindings that control vertical panning. Each binding is a combination of the mouse button
+     * and an optional keyboard modifier.
+     * @type {ScreenSpaceInputBindings.InputBinding[]}
+     * @see ScreenSpaceEventHandler
+     */
+    this.dragInputs =
+      options.dragInputs ??
+      ScreenSpaceElevatorCameraController._getDefaultDragInputs();
+
+    this._dragInputState = undefined;
+    this._panDelta = new Cartesian2();
+    this._panPosition = new Cartesian2();
+
+    /**
+     * A callback function used to pick the world position from which to pan. The function is called with {@link Scene}, the {@link Cartesian2} screen space position, and a {@link Cartesian3} instance to store the result. The function should return the {@link Cartesian3} world position from which to pan, or <code>undefined</code> if no position could be picked. If <code>undefined</code> is returned, the camera will pan relative to the ellipsoid surface below the camera.
+     * @type {Function(Scene, Cartesian2, Cartesian3): Cartesian3|undefined}
+     * @default defaultPickWorldPosition
+     * @example
+     * const elevatorCameraController = new Cesium.ScreenSpaceElevatorCameraController();
+     * elevatorCameraController.pickWorldPosition = function (scene, windowPosition, result) {
+     *   // Pick the world position from the depth buffer
+     *   return scene.pickPosition(windowPosition, result);
+     * };
+     * viewer.addController(elevatorCameraController);
+     */
+    this.pickWorldPosition = defaultPickWorldPosition;
+
+    this._ellipsoidNormal = new Cartesian3();
+    this._ellipsoidSurfacePosition = new Cartesian3();
+    this._panDirectionX = new Cartesian3();
+    this._panDirectionY = new Cartesian3();
+    this._pixelSize = new Cartesian2();
+    this._panVelocity = new Cartesian2();
+
+    /**
+     * The speed in meters per pixel at which the camera pans.
+     * @type {number}
+     * @default 1.0
+     */
+    this.panSpeed = 1.0;
+
+    /**
+     * Enable or disable inertia when panning. When enabled, the camera will continue to move after the user stops dragging, gradually slowing down based on {@link ScreenSpaceMapCameraController#inertialDecay}.
+     * @type {boolean}
+     * @default true
+     */
+    this.inertiaEnabled = true;
+
+    /**
+     * The rate at which the camera's pan velocity decays over time.
+     * @type {number}
+     * @default 6.0
+     */
+    this.inertialDecay = 6.0;
+
+    /**
+     * A parameter in the range <code>[0, 1)</code> used to limit the range
+     * of inputs to a percentage of the window width/height per animation frame.
+     * This helps keep the camera under control in low-frame-rate situations.
+     * @type {number}
+     * @default 0.1
+     */
+    this.maximumMovementRatio = 0.1;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  get enabled() {
+    return this._enabled;
+  }
+  set enabled(value) {
+    this._enabled = value;
+
+    if (value) {
+      this._lastUpdateTime = getTimestamp();
+      this._panDelta.x = 0;
+      this._panDelta.y = 0;
+    } else if (defined(this._dragInputState)) {
+      this._dragInputState.isDragging = false;
+    }
+  }
+
+  /**
+   * @private
+   * @type {boolean}
+   */
+  get isDragging() {
+    return defined(this._dragInputState) && this._dragInputState.isDragging;
+  }
+
+  /**
+   * @inheritdoc
+   * @param {HTMLElement} element The DOM element containing the Cesium scene.
+   */
+  connectedCallback(element) {
+    const handler = new ScreenSpaceEventHandler(element);
+    this._handler = handler;
+
+    this._dragInputState = ScreenSpaceInputBindings.registerDragInputBindings(
+      handler,
+      this.dragInputs,
+      {
+        start: this._handleStartPan.bind(this),
+        change: this._handlePan.bind(this),
+      },
+    );
+  }
+
+  /**
+   * @inheritdoc
+   * @param {HTMLElement} element The DOM element containing the Cesium scene.
+   */
+  disconnectedCallback(element) {
+    const handler = this._handler;
+    if (defined(handler) && !handler.isDestroyed()) {
+      handler.destroy();
+    }
+  }
+
+  /**
+   * @inheritdoc
+   */
+  firstUpdate() {
+    this._lastUpdateTime = getTimestamp();
+    this._panDelta.x = 0;
+    this._panDelta.y = 0;
+  }
+
+  /**
+   * @inheritdoc
+   * @param {any} scene
+   */
+  update(scene) {
+    const dt =
+      (getTimestamp() - this._lastUpdateTime) *
+      TimeConstants.SECONDS_PER_MILLISECOND;
+
+    const { camera, ellipsoid, canvas } = scene;
+
+    let dx = -this._panDelta.x;
+    let dy = this._panDelta.y;
+
+    if (this.inertiaEnabled && !this.isDragging) {
+      const damping = Math.exp(-this.inertialDecay * dt);
+      this._panVelocity.x *= damping;
+      this._panVelocity.y *= damping;
+
+      dx = this._panVelocity.x * dt;
+      dy = this._panVelocity.y * dt;
+    }
+
+    const { clientWidth, clientHeight } = canvas;
+    if (
+      dt === 0 ||
+      clientWidth === 0 ||
+      clientHeight === 0 ||
+      (Math.abs(dx) <= CesiumMath.EPSILON3 &&
+        Math.abs(dy) <= CesiumMath.EPSILON3)
+    ) {
+      // Reset for next frame
+      this._lastUpdateTime = getTimestamp();
+      this._panDelta.x = 0;
+      this._panDelta.y = 0;
+      return;
+    }
+
+    const windowPosition = this._panPosition;
+    let surface = this.pickWorldPosition(
+      scene,
+      windowPosition,
+      this._ellipsoidSurfacePosition,
+    );
+
+    if (!defined(surface)) {
+      surface = ellipsoid.scaleToGeodeticSurface(
+        camera.positionWC,
+        this._ellipsoidSurfacePosition,
+      );
+    }
+
+    let xAxis = Cartesian3.clone(camera.rightWC, this._panDirectionX);
+    xAxis = Cartesian3.normalize(xAxis, this._panDirectionX);
+    const zAxis = Cartesian3.normalize(surface, this._panDirectionY);
+
+    const distance = Cartesian3.distance(camera.positionWC, surface);
+    const { drawingBufferWidth, drawingBufferHeight, pixelRatio } = scene;
+    const pixelSize = camera.frustum.getPixelDimensions(
+      drawingBufferWidth,
+      drawingBufferHeight,
+      distance,
+      pixelRatio,
+      this._pixelSize,
+    );
+
+    const maxPixels =
+      this.maximumMovementRatio * Math.max(clientWidth, clientHeight);
+    dx = CesiumMath.clamp(dx, -maxPixels, maxPixels);
+    this._panVelocity.x = dx / dt;
+    dx *= this.panSpeed * pixelSize.x;
+
+    dy = CesiumMath.clamp(dy, -maxPixels, maxPixels);
+    this._panVelocity.y = dy / dt;
+    dy *= this.panSpeed * pixelSize.y;
+
+    camera.move(xAxis, dx);
+    camera.move(zAxis, dy);
+
+    // Reset for next frame
+    this._lastUpdateTime = getTimestamp();
+    this._panDelta.x = 0;
+    this._panDelta.y = 0;
+  }
+
+  _handleStartPan() {
+    if (!this.enabled) {
+      return;
+    }
+
+    this._panDelta.x = 0;
+    this._panDelta.y = 0;
+  }
+
+  /**
+   * @private
+   */
+  _handlePan(event) {
+    this._panDelta.x += event.endPosition.x - event.startPosition.x;
+    this._panDelta.y += event.endPosition.y - event.startPosition.y;
+    this._panPosition.x = event.endPosition.x;
+    this._panPosition.y = event.endPosition.y;
+  }
+}
+
+export default ScreenSpaceElevatorCameraController;