@cesium/engine 26.1.0 → 26.3.0

package/Source/Scene/Controllers/ScreenSpaceZoomCameraController.js

@@ -0,0 +1,431 @@
+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 ScreenSpaceEventType from "../../Core/ScreenSpaceEventType.js";
+import defaultPickWorldPosition from "./defaultPickWorldPosition.js";
+import ScreenSpaceInputBindings from "./ScreenSpaceInputBindings.js";
+import TimeConstants from "../../Core/TimeConstants.js";
+import MouseButton from "./MouseButton.js";
+
+/**
+ * @typedef {object} ControllerOptions
+ * @memberof ScreenSpaceZoomCameraController
+ * @property {ScreenSpaceInputBindings.InputBinding[]} [dragInputs] The drag input bindings that control zooming.
+ * @property {ScreenSpaceEventType[]} [scrollInputs] The scroll input bindings that control zooming.
+ */
+
+/**
+ * A camera controller that allows zooming the camera in and out based on the pointer location in screen space.
+ * @class
+ * @implements Controller
+ * @example
+ * viewer.scene.screenSpaceCameraController.enableInputs = false;
+ * viewer.scene.screenSpaceCameraController.enableCollisionDetection = false;
+ *
+ * const zoomCameraController = new Cesium.ScreenSpaceZoomCameraController();
+ * viewer.addController(zoomCameraController);
+ */
+class ScreenSpaceZoomCameraController {
+  /**
+   * @private
+   * @returns {ScreenSpaceInputBindings.InputBinding[]} The default drag input bindings.
+   */
+  static _getDefaultDragInputs() {
+    return [
+      Object.freeze({
+        button: MouseButton.MIDDLE,
+      }),
+    ];
+  }
+
+  /**
+   * @private
+   * @returns {ScreenSpaceEventType[]} The default scroll input bindings.
+   */
+  static _getDefaultScrollInputs() {
+    return [ScreenSpaceEventType.WHEEL];
+  }
+
+  /**
+   * Creates a new instance of <code>ScreenSpaceZoomCameraController</code>.
+   * @param {ScreenSpaceZoomCameraController.ControllerOptions} [options] The options for configuring the controller.
+   */
+  constructor(options = Frozen.EMPTY_OBJECT) {
+    this._enabled = true;
+    this._handler = undefined;
+    this._lastUpdateTime = undefined;
+
+    /**
+     * If false, the camera will zoom to the position at the center of the screen. If true, the camera will zoom to the position under the cursor or tap when dragging starts or when scrolling with the scroll wheel.
+     * @type {boolean}
+     * @default false
+     */
+    this.usePointerPosition = false;
+
+    /**
+     * The drag input bindings that control zooming. Each binding is a combination of the mouse button
+     * and an optional keyboard modifier.
+     * @type {ScreenSpaceInputBindings.InputBinding[]}
+     * @see ScreenSpaceEventHandler
+     */
+    this.dragInputs =
+      options.dragInputs ??
+      ScreenSpaceZoomCameraController._getDefaultDragInputs();
+
+    /**
+     * The scroll input bindings that control zooming.
+     * @type {ScreenSpaceEventType[]}
+     * @see ScreenSpaceEventHandler
+     * @default [ScreenSpaceEventType.WHEEL]
+     */
+    this.scrollInputs =
+      options.scrollInputs ??
+      ScreenSpaceZoomCameraController._getDefaultScrollInputs();
+
+    this._dragInputState = undefined;
+    this._dragDelta = new Cartesian2();
+    this._scrollDelta = 0.0;
+    this._zoomInputVelocity = 0.0;
+    this._screenSpaceScrollPosition = new Cartesian2();
+    this._screenSpaceDragPosition = new Cartesian2();
+    this._screenSpaceOrigin = new Cartesian2();
+
+    /**
+     * The rate at which the camera zooms in and out based on the mouse wheel delta.
+     * @type {number}
+     * @default 0.2
+     */
+    this.zoomSensitivity = 0.2;
+
+    /**
+     * A callback function used to pick the world position from which to zoom. 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 zoom, or <code>undefined</code> if no position could be picked.
+     * @type {Function(Scene, Cartesian2, Cartesian3): Cartesian3|undefined}
+     * @default defaultPickWorldPosition
+     * @example
+     * const zoomCameraController = new Cesium.ScreenSpaceZoomCameraController();
+     * zoomCameraController.pickWorldPosition = function (scene, windowPosition, result) {
+     *   // Pick the world position from the depth buffer
+     *   return scene.pickPosition(windowPosition, result);
+     * };
+     * viewer.addController(zoomCameraController);
+     */
+    this.pickWorldPosition = defaultPickWorldPosition;
+
+    /**
+     * The ratio of the camera's distance to the zoom target that defines how much the camera zooms in and out per second.
+     * @type {number}
+     * @default 0.4
+     */
+    this.zoomDistanceRatio = 0.4;
+
+    /**
+     * Enable or disable inertia when zooming. When enabled, the camera will continue to move after the user input stops, gradually slowing down based on {@link ScreenSpaceZoomCameraController#inertialDecay}.
+     * @type {boolean}
+     * @default true
+     */
+    this.inertiaEnabled = false;
+
+    /**
+     * The rate at which the camera's zoom velocity decays over time.
+     * @type {number}
+     * @default 6.0
+     */
+    this.inertialDecay = 6.0;
+
+    /**
+     * @private
+     * @type number
+     * @default 0.0
+     */
+    this.minimumZoomDistance = 0.0;
+
+    /**
+     * Maximum distance from the zoom target that the camera can move away.
+     * @type {number}
+     * @default 100000.0
+     */
+    this.maximumZoomDistance = 100000.0;
+
+    /**
+     * @private
+     * @type {number}
+     * @default CesiumMath.EPSILON20
+     */
+    this.minimumZoomVelocity = CesiumMath.EPSILON20;
+
+    /**
+     * The maximum zoom velocity in meters per second. This limits the speed at which the camera can zoom in and out.
+     * @type {number}
+     * @default 1.0
+     */
+    this.maximumZoomVelocity = 1.0;
+
+    /**
+     * Enables or disables damping for zooming. Damping smooths out the camera movement and makes it feel more natural or weighty, but it can also introduce a slight delay in the camera response. If damping is disabled, the camera will respond immediately to user input.
+     * @type {boolean}
+     * @default true
+     */
+    this.dampingEnabled = true;
+
+    /**
+     * Specifies the length of time in seconds in which a single zoom animation is targeted to complete.
+     * @type {number}
+     * @default 0.45
+     */
+    this.zoomAnimationDuration = 0.45;
+
+    this._target = new Cartesian3();
+    this._zoomDirection = new Cartesian3();
+    this._zoomDampenedResults = {
+      velocity: 0.0,
+      value: 0.0,
+    };
+  }
+
+  /**
+   * @inheritdoc
+   */
+  get enabled() {
+    return this._enabled;
+  }
+  set enabled(value) {
+    this._enabled = value;
+
+    if (value) {
+      this._lastUpdateTime = getTimestamp();
+      this._scrollDelta = 0.0;
+      this._dragDelta.x = 0.0;
+      this._dragDelta.y = 0.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;
+
+    for (const input of this.scrollInputs) {
+      handler.setInputAction(this._handleZoom.bind(this), input);
+    }
+
+    handler.setInputAction(
+      this._handleZoomPosition.bind(this),
+      ScreenSpaceEventType.MOUSE_MOVE,
+    );
+
+    this._dragInputState = ScreenSpaceInputBindings.registerDragInputBindings(
+      handler,
+      this.dragInputs,
+      {
+        start: this._handleStartDrag.bind(this),
+        change: this._handleDrag.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._scrollDelta = 0.0;
+    this._dragDelta.x = 0.0;
+    this._dragDelta.y = 0.0;
+  }
+
+  /**
+   * The current zoom distance of the camera in meters. This is the distance from the camera to the zoom target.
+   * @type {number}
+   * @private
+   */
+  get zoomDistance() {
+    return this._zoomDampenedResults.value;
+  }
+
+  /**
+   * The current zoom velocity of the camera in radians per second.
+   * @type {number}
+   * @private
+   */
+  get zoomVelocity() {
+    return this._zoomDampenedResults.velocity;
+  }
+
+  /**
+   * The current zoom velocity of the camera in radians per second.
+   * @type {number}
+   * @private
+   */
+  set zoomVelocity(value) {
+    this._zoomDampenedResults.velocity = value;
+  }
+
+  /**
+   * @inheritdoc
+   * @param {Scene} scene
+   */
+  update(scene) {
+    const now = getTimestamp();
+    const dt =
+      (now - this._lastUpdateTime) * TimeConstants.SECONDS_PER_MILLISECOND;
+
+    const { canvas } = scene;
+    const { clientWidth, clientHeight } = canvas;
+    if (dt === 0 || clientWidth === 0 || clientHeight === 0) {
+      this._lastUpdateTime = getTimestamp();
+      this._scrollDelta = 0.0;
+      this._dragDelta.x = 0;
+      this._dragDelta.y = 0;
+      return;
+    }
+
+    let dz = this._scrollDelta + this._dragDelta.y;
+    if (dz === 0.0 && this.inertiaEnabled) {
+      const damping = Math.exp(-this.inertialDecay * dt);
+      this._zoomInputVelocity *= damping;
+      dz = this._zoomInputVelocity * dt;
+    }
+
+    if (
+      Math.abs(this.zoomVelocity) < this.minimumZoomVelocity &&
+      dz <= CesiumMath.EPSILON3 &&
+      dz >= -CesiumMath.EPSILON3 &&
+      this.zoomVelocity <= CesiumMath.EPSILON3
+    ) {
+      this._lastUpdateTime = getTimestamp();
+      this._scrollDelta = 0.0;
+      this._dragDelta.x = 0;
+      this._dragDelta.y = 0;
+      this.zoomVelocity = 0.0;
+      return;
+    }
+
+    this._zoomInputVelocity = CesiumMath.clamp(
+      dz / dt,
+      -this.maximumZoomVelocity,
+      this.maximumZoomVelocity,
+    );
+
+    const { camera, ellipsoid } = scene;
+
+    let direction = camera.direction;
+    let distance =
+      Cartesian3.magnitude(camera.positionWC) - ellipsoid.maximumRadius;
+
+    let windowPosition = this.isDragging
+      ? this._screenSpaceDragPosition
+      : this._screenSpaceScrollPosition;
+    if (!this.useDragPosition) {
+      windowPosition = this._screenSpaceOrigin;
+      windowPosition.x = clientWidth / 2.0;
+      windowPosition.y = clientHeight / 2.0;
+    }
+    const target = this.pickWorldPosition(scene, windowPosition, this._target);
+    if (defined(target)) {
+      direction = Cartesian3.subtract(
+        target,
+        camera.positionWC,
+        this._zoomDirection,
+      );
+      direction = Cartesian3.normalize(direction, this._zoomDirection);
+      distance = Cartesian3.distance(target, camera.positionWC);
+    }
+
+    distance = CesiumMath.clamp(
+      distance,
+      distance > 0.0 ? this.minimumZoomDistance : -this.maximumZoomDistance,
+      distance > 0.0 ? this.maximumZoomDistance : -this.minimumZoomDistance,
+    );
+
+    const zoom = dz * distance * this.zoomDistanceRatio;
+
+    const smoothTime = this.dampingEnabled
+      ? this.zoomAnimationDuration
+      : undefined;
+    this._zoomDampenedResults = CesiumMath.smoothDamp(
+      0.0,
+      zoom,
+      this.zoomVelocity,
+      dt,
+      undefined,
+      smoothTime,
+      this._zoomDampenedResults,
+    );
+
+    camera.move(direction, this.zoomDistance);
+
+    // Reset for next frame
+    this._lastUpdateTime = getTimestamp();
+    this._scrollDelta = 0.0;
+    this._dragDelta.x = 0;
+    this._dragDelta.y = 0;
+  }
+
+  /**
+   * @private
+   * @param {number} amount
+   */
+  _handleZoom(amount) {
+    this._scrollDelta += amount * this.zoomSensitivity;
+  }
+
+  /**
+   * @private
+   */
+  _handleZoomPosition(event) {
+    this._screenSpaceScrollPosition.x = event.endPosition.x;
+    this._screenSpaceScrollPosition.y = event.endPosition.y;
+  }
+
+  /**
+   * @private
+   */
+  _handleStartDrag(event) {
+    if (!this.enabled) {
+      return;
+    }
+
+    this._screenSpaceDragPosition.x = event.position.x;
+    this._screenSpaceDragPosition.y = event.position.y;
+    this._dragDelta.x = 0.0;
+    this._dragDelta.y = 0.0;
+  }
+
+  /**
+   * @private
+   */
+  _handleDrag(event) {
+    this._dragDelta.x += event.endPosition.x - event.startPosition.x;
+    this._dragDelta.y += event.endPosition.y - event.startPosition.y;
+  }
+}
+
+export default ScreenSpaceZoomCameraController;

package/Source/Scene/Controllers/defaultPickWorldPosition.js

@@ -0,0 +1,84 @@
+import Cartesian3 from "../../Core/Cartesian3.js";
+import Cartesian2 from "../../Core/Cartesian2.js";
+import Check from "../../Core/Check.js";
+import defined from "../../Core/defined.js";
+import IntersectionTests from "../../Core/IntersectionTests.js";
+import Plane from "../../Core/Plane.js";
+import Ray from "../../Core/Ray.js";
+
+const scratchSurfaceCartesian = new Cartesian3();
+const scratchPlane = new Plane(Cartesian3.UNIT_X, 0.0);
+const scratchRay = new Ray();
+const defaultTargetPixelSize = new Cartesian2(1.0, 1.0, 1.0);
+
+/**
+ * Picks a cartesian worldspace position based on the specified window coordinates and the camera's current position and orientation.
+ * <ol>
+ * <li>If the camera is above the scene's defined ellipsoid, the position is picked on the ellipsoid.</li>
+ * <li> If the camera is below the ellipsoid, a temporary plane is created relative to the camera's position and orientation, and the position is picked on that plane.</li>
+ * </ol>
+ * @param {Scene} scene The scene to pick the world position from.
+ * @param {Cartesian2} windowPosition The x and y coordinates of a pixel.
+ * @param {Cartesian3} result The object onto which to store the result.
+ * @param {Cartesian2} targetPixelSize The pixel size at the target position, used to preserve relative camera distance from the target position when navigating.
+ * @returns {Cartesian3|undefined} The picked cartesian worldspace position, or <code>undefined</code> if no position could be picked.
+ * @see {@link ScreenSpaceMapCameraController#pickWorldPosition}
+ * @see {@link ScreenSpaceElevatorCameraController#pickWorldPosition}
+ * @see {@link ScreenSpaceTiltOrbitCameraController#pickWorldPosition}
+ * @see {@link ScreenSpaceZoomCameraController#pickWorldPosition}
+ */
+export default function (
+  scene,
+  windowPosition,
+  result,
+  targetPixelSize = defaultTargetPixelSize,
+) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("scene", scene);
+  Check.typeOf.object("windowPosition", windowPosition);
+  Check.typeOf.object("result", result);
+  //>>includeEnd('debug');
+
+  const { camera, ellipsoid } = scene;
+  const surface = ellipsoid.scaleToGeodeticSurface(
+    camera.positionWC,
+    scratchSurfaceCartesian,
+  );
+
+  // Camera is at the origin
+  if (!defined(surface)) {
+    return undefined;
+  }
+
+  const cameraMagnitude = Cartesian3.magnitude(camera.positionWC);
+  const surfaceMagnitude = Cartesian3.magnitude(surface);
+  const belowEllipsoid = cameraMagnitude <= surfaceMagnitude;
+
+  const normal = ellipsoid.geodeticSurfaceNormal(
+    camera.positionWC,
+    scratchSurfaceCartesian,
+  );
+  const dot = Cartesian3.dot(normal, camera.directionWC);
+  const lookingUp = dot > 0.0;
+
+  if (belowEllipsoid || lookingUp) {
+    // Camera is inside the ellipsoid. When underground, create a temporary plane beneath the ellipsoid surface to avoid picking a position on the inside and opposite side of the ellipsoid.
+
+    const plane = Plane.fromPointNormal(
+      camera.positionWC,
+      normal,
+      scratchPlane,
+    );
+
+    const { clientHeight } = scene.canvas;
+    const focusDistance =
+      (targetPixelSize.y * clientHeight) /
+      (2.0 * Math.tan(camera.frustum.fovy * 0.5));
+
+    plane.distance -= dot * focusDistance;
+    const ray = camera.getPickRay(windowPosition, scratchRay);
+    return IntersectionTests.rayPlane(ray, plane, result);
+  }
+
+  return camera.pickEllipsoid(windowPosition, ellipsoid, result);
+}

package/Source/Scene/CreditDisplay.js

@@ -162,6 +162,29 @@ function styleLightboxContainer(that) {
   }
 }
 
+/**
+ * Wraps a callback so that it also runs when a keyboard user activates an element
+ * with <code>Enter</code> or <code>Space</code>. Elements exposed as <code>role="button"</code>
+ * are expected to respond to both keys, which anchors without an <code>href</code> do not do natively.
+ *
+ * @param {Function} callback The function to invoke when the element is activated.
+ * @returns {Function} A <code>keydown</code> handler.
+ *
+ * @private
+ */
+function activateOnKeydown(callback) {
+  return function (event) {
+    if (event.key !== "Enter" && event.key !== " ") {
+      return;
+    }
+    // Prevent Space from scrolling the page and stop the event from also
+    // reaching the overlay, which would immediately close the lightbox again.
+    event.preventDefault();
+    event.stopPropagation();
+    callback();
+  };
+}
+
 function appendCss(container) {
   const style = /*css*/ `
 .cesium-credit-lightbox-overlay {
@@ -237,6 +260,12 @@ function appendCss(container) {
   color: ${highlightColor};
 }
 
+.cesium-credit-expand-link:focus-visible,
+.cesium-credit-lightbox-close:focus-visible {
+  outline: 2px solid ${highlightColor};
+  outline-offset: 2px;
+}
+
 .cesium-credit-text {
   color: ${textColor};
 }
@@ -312,6 +341,9 @@ function CreditDisplay(container, delimiter, viewport) {
 
   const lightboxCredits = document.createElement("div");
   lightboxCredits.className = "cesium-credit-lightbox";
+  lightboxCredits.setAttribute("role", "dialog");
+  lightboxCredits.setAttribute("aria-modal", "true");
+  lightboxCredits.setAttribute("aria-label", "Data attribution");
   lightbox.appendChild(lightboxCredits);
 
   function hideLightbox(event) {
@@ -322,6 +354,14 @@ function CreditDisplay(container, delimiter, viewport) {
   }
   lightbox.addEventListener("click", hideLightbox, false);
 
+  function hideLightboxOnEscape(event) {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      that.hideLightbox();
+    }
+  }
+  lightbox.addEventListener("keydown", hideLightboxOnEscape, false);
+
   const title = document.createElement("div");
   title.className = "cesium-credit-lightbox-title";
   title.textContent = "Data provided by:";
@@ -329,8 +369,12 @@ function CreditDisplay(container, delimiter, viewport) {
 
   const closeButton = document.createElement("a");
   closeButton.onclick = this.hideLightbox.bind(this);
+  closeButton.onkeydown = activateOnKeydown(this.hideLightbox.bind(this));
   closeButton.innerHTML = "&times;";
   closeButton.className = "cesium-credit-lightbox-close";
+  closeButton.setAttribute("role", "button");
+  closeButton.setAttribute("tabindex", "0");
+  closeButton.setAttribute("aria-label", "Close data attribution");
   lightboxCredits.appendChild(closeButton);
 
   const creditList = document.createElement("ul");
@@ -349,7 +393,12 @@ function CreditDisplay(container, delimiter, viewport) {
   const expandLink = document.createElement("a");
   expandLink.className = "cesium-credit-expand-link";
   expandLink.onclick = this.showLightbox.bind(this);
+  expandLink.onkeydown = activateOnKeydown(this.showLightbox.bind(this));
   expandLink.textContent = "Data attribution";
+  expandLink.setAttribute("role", "button");
+  expandLink.setAttribute("tabindex", "0");
+  expandLink.setAttribute("aria-haspopup", "dialog");
+  expandLink.setAttribute("aria-expanded", "false");
   container.appendChild(expandLink);
 
   appendCss(container);
@@ -364,7 +413,9 @@ function CreditDisplay(container, delimiter, viewport) {
   this._creditList = creditList;
   this._lightbox = lightbox;
   this._hideLightbox = hideLightbox;
+  this._hideLightboxOnEscape = hideLightboxOnEscape;
   this._expandLink = expandLink;
+  this._closeButton = closeButton;
   this._expanded = false;
   this._staticCredits = [];
   this._cesiumCredit = cesiumCredit;
@@ -492,6 +543,9 @@ CreditDisplay.prototype.removeStaticCredit = function (credit) {
 CreditDisplay.prototype.showLightbox = function () {
   this._lightbox.style.display = "block";
   this._expanded = true;
+  this._expandLink.setAttribute("aria-expanded", "true");
+  // Move focus into the dialog so keyboard users can reach its contents.
+  this._closeButton.focus();
 };
 
 /**
@@ -500,6 +554,9 @@ CreditDisplay.prototype.showLightbox = function () {
 CreditDisplay.prototype.hideLightbox = function () {
   this._lightbox.style.display = "none";
   this._expanded = false;
+  this._expandLink.setAttribute("aria-expanded", "false");
+  // Restore focus to the element that opened the dialog.
+  this._expandLink.focus();
 };
 
 /**
@@ -581,6 +638,11 @@ CreditDisplay.prototype.endFrame = function () {
  */
 CreditDisplay.prototype.destroy = function () {
   this._lightbox.removeEventListener("click", this._hideLightbox, false);
+  this._lightbox.removeEventListener(
+    "keydown",
+    this._hideLightboxOnEscape,
+    false,
+  );
 
   this.container.removeChild(this._cesiumCreditContainer);
   this.container.removeChild(this._screenContainer);