@cesium/engine 26.0.0 → 26.2.0

package/Source/Scene/Billboard.js

@@ -706,8 +706,9 @@ Object.defineProperties(Billboard.prototype, {
   },
 
   /**
-   * Gets or sets the aligned axis in world space. The aligned axis is the unit vector that the billboard up vector points towards.
+   * The aligned axis is the direction vector that the billboard up vector points towards.
    * The default is the zero vector, which means the billboard is aligned to the screen up vector.
+   * Note that only the zero vector (0,0,0) resets the alignment to screen up.
    * @memberof Billboard.prototype
    * @type {Cartesian3}
    * @example

package/Source/Scene/BillboardCollection.js

@@ -1033,8 +1033,9 @@ function writeCompressedAttrib1(
   billboard,
 ) {
   const writer = vafWriters[attributeLocations.compressedAttribute1];
-  const alignedAxis = billboard.alignedAxis;
+  let alignedAxis = billboard.alignedAxis;
   if (!Cartesian3.equals(alignedAxis, Cartesian3.ZERO)) {
+    alignedAxis = Cartesian3.normalize(alignedAxis, new Cartesian3());
     billboardCollection._shaderAlignedAxis = true;
   }
 
@@ -1096,12 +1097,15 @@ function writeCompressedAttrib2(
     ? billboard.getPickId(frameState.context).color
     : Color.WHITE;
   const sizeInMeters = billboard.sizeInMeters ? 1.0 : 0.0;
+  const rawAxis = billboard.alignedAxis;
+  const normalizedAxis = !Cartesian3.equals(rawAxis, Cartesian3.ZERO)
+    ? Cartesian3.normalize(rawAxis, new Cartesian3())
+    : rawAxis;
   const validAlignedAxis =
-    Math.abs(Cartesian3.magnitudeSquared(billboard.alignedAxis) - 1.0) <
+    Math.abs(Cartesian3.magnitudeSquared(normalizedAxis) - 1.0) <
     CesiumMath.EPSILON6
       ? 1.0
       : 0.0;
-
   billboardCollection._allSizedInMeters =
     billboardCollection._allSizedInMeters && sizeInMeters === 1.0;
 

package/Source/Scene/BillboardTexture.js

@@ -199,9 +199,11 @@ BillboardTexture.prototype.loadImage = async function (
   let index;
   const atlas = this._billboardCollection.textureAtlas;
   try {
-    index = atlas.addImage(id, image, width, height);
-    if (index instanceof Promise) {
-      index = await index;
+    const indexOrPromise = atlas.addImage(id, image, width, height);
+    if (typeof indexOrPromise === "number") {
+      index = indexOrPromise;
+    } else {
+      index = await indexOrPromise;
     }
   } catch (error) {
     // There was an error loading the image

package/Source/Scene/BufferPrimitiveCollection.js

@@ -194,7 +194,6 @@ class BufferPrimitiveCollection {
 
     /**
      * @type {number}
-     * @protected
      * @ignore
      */
     this._positionCountMax =
@@ -249,6 +248,13 @@ class BufferPrimitiveCollection {
      */
     this._dirtyBoundingVolume = false;
 
+    /**
+     * Monotonically increasing counter, bumped each time collection is marked "clean".
+     * @type {number}
+     * @ignore
+     */
+    this._version = 0;
+
     this._allocatePrimitiveBuffer();
     this._allocatePositionBuffer();
     this._allocateMaterialBuffer();
@@ -524,13 +530,14 @@ class BufferPrimitiveCollection {
       vertices,
       Cartesian3.ZERO,
       3,
-      this.boundingVolume,
+      this._boundingVolume,
     );
     BoundingSphere.transform(
-      this.boundingVolume,
-      this.modelMatrix,
-      this.boundingVolume,
+      this._boundingVolume,
+      this._modelMatrix,
+      this._boundingVolume,
     );
+
     this._dirtyBoundingVolume = false;
   }
 
@@ -660,6 +667,18 @@ class BufferPrimitiveCollection {
     }
   }
 
+  /**
+   * Marks all primitives 'clean', and updates version counter.
+   * @ignore
+   */
+  _makeClean() {
+    if (this._dirtyCount > 0) {
+      this._dirtyCount = 0;
+      this._dirtyOffset = 0;
+      this._version++;
+    }
+  }
+
   /**
    * Marks collection bounding volume as 'dirty', to be updated on next render,
    * if automatic bounding volume updates are enabled.
@@ -771,6 +790,9 @@ class BufferPrimitiveCollection {
    * @readonly
    */
   get boundingVolume() {
+    if (this._dirtyBoundingVolume) {
+      this._updateBoundingVolume();
+    }
     return this._boundingVolume;
   }
 

package/Source/Scene/Camera.js

@@ -3,6 +3,7 @@ import Cartesian2 from "../Core/Cartesian2.js";
 import Cartesian3 from "../Core/Cartesian3.js";
 import Cartesian4 from "../Core/Cartesian4.js";
 import Cartographic from "../Core/Cartographic.js";
+import Check from "../Core/Check.js";
 import Frozen from "../Core/Frozen.js";
 import defined from "../Core/defined.js";
 import DeveloperError from "../Core/DeveloperError.js";
@@ -2356,7 +2357,7 @@ const scratchLookAtHeadingPitchRangeQuaternion1 = new Quaternion();
 const scratchLookAtHeadingPitchRangeQuaternion2 = new Quaternion();
 const scratchHeadingPitchRangeMatrix3 = new Matrix3();
 
-function offsetFromHeadingPitchRange(heading, pitch, range) {
+function offsetFromHeadingPitchRange(heading, pitch, range, result) {
   pitch = CesiumMath.clamp(
     pitch,
     -CesiumMath.PI_OVER_TWO,
@@ -2380,10 +2381,7 @@ function offsetFromHeadingPitchRange(heading, pitch, range) {
     scratchHeadingPitchRangeMatrix3,
   );
 
-  const offset = Cartesian3.clone(
-    Cartesian3.UNIT_X,
-    scratchLookAtHeadingPitchRangeOffset,
-  );
+  const offset = Cartesian3.clone(Cartesian3.UNIT_X, result);
   Matrix3.multiplyByVector(rotMatrix, offset, offset);
   Cartesian3.negate(offset, offset);
   Cartesian3.multiplyByScalar(offset, range, offset);
@@ -2441,6 +2439,7 @@ Camera.prototype.lookAtTransform = function (transform, offset) {
       offset.heading,
       offset.pitch,
       offset.range,
+      scratchLookAtHeadingPitchRangeOffset,
     );
   } else {
     cartesianOffset = offset;
@@ -2492,6 +2491,72 @@ Camera.prototype.lookAtTransform = function (transform, offset) {
   this._adjustOrthographicFrustum(true);
 };
 
+const scratchLookAtWorldPositionTransform = new Matrix4();
+const scratchLookAtWorldPositionDirection = new Cartesian3();
+const scratchLookAtWorldPositionWorldUp = new Cartesian3();
+const scratchLookAtWorldPositionRight = new Cartesian3();
+
+/**
+ * Sets the camera orientation to look at a target position in world coordinates. The camera's up vector will be oriented to the world up vector at the target position.
+ * If the camera is at the target position, the camera will be oriented to the world up vector at the target position.
+ * @param {Cartesian3} target The target position in world coordinates.
+ * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid to use for determining the world up.
+ */
+Camera.prototype.lookAtWorldPosition = function (
+  target,
+  ellipsoid = Ellipsoid.default,
+) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("target", target);
+  Check.typeOf.object("ellipsoid", ellipsoid);
+  //>>includeEnd('debug');
+
+  const transform = Matrix4.clone(
+    this._transform,
+    scratchLookAtWorldPositionTransform,
+  );
+
+  this._setTransform(Matrix4.IDENTITY);
+
+  // Get direction to look at target
+  let direction = Cartesian3.subtract(
+    target,
+    this.positionWC,
+    scratchLookAtWorldPositionDirection,
+  );
+
+  // If the camera is at the target position, we can't look at it, but we should still continue to re-orient the camera to the world up vector at the target position.
+  if (Cartesian3.magnitudeSquared(direction) < CesiumMath.EPSILON8) {
+    direction = Cartesian3.clone(
+      this.directionWC,
+      scratchLookAtWorldPositionDirection,
+    );
+  }
+
+  direction = Cartesian3.normalize(direction, this.direction);
+
+  // Orient the camera to the world up vector at the target position
+  const worldUp = ellipsoid.geodeticSurfaceNormal(
+    target,
+    scratchLookAtWorldPositionWorldUp,
+  );
+
+  let right = Cartesian3.cross(
+    direction,
+    worldUp,
+    scratchLookAtWorldPositionRight,
+  );
+  if (Cartesian3.magnitudeSquared(right) < CesiumMath.EPSILON8) {
+    right = Cartesian3.clone(this.rightWC, scratchLookAtWorldPositionRight);
+  }
+  Cartesian3.normalize(right, this.right);
+
+  const up = Cartesian3.cross(right, direction, this.up);
+  Cartesian3.normalize(up, this.up);
+
+  this._setTransform(transform);
+};
+
 const viewRectangle3DCartographic1 = new Cartographic();
 const viewRectangle3DCartographic2 = new Cartographic();
 const viewRectangle3DNorthEast = new Cartesian3();
@@ -3621,6 +3686,7 @@ Camera.prototype.flyToBoundingSphere = function (boundingSphere, options) {
       offset.heading,
       offset.pitch,
       offset.range,
+      scratchflyToBoundingSphereDestination,
     );
   }
 

package/Source/Scene/Cesium3DTileOptimizations.js

@@ -49,12 +49,10 @@ Cesium3DTileOptimizations.checkChildrenWithinParent = function (tile) {
 
       // Check if the child has an oriented bounding box.
       const childBoundingVolume = child.boundingVolume;
-      if (
-        !(
-          childBoundingVolume instanceof TileOrientedBoundingBox ||
-          childBoundingVolume instanceof TileBoundingRegion
-        )
-      ) {
+      if (!(
+        childBoundingVolume instanceof TileOrientedBoundingBox ||
+        childBoundingVolume instanceof TileBoundingRegion
+      )) {
         // Do not support if the parent and child both do not have oriented bounding boxes.
         tile._optimChildrenWithinParent =
           Cesium3DTileOptimizationHint.SKIP_OPTIMIZATION;

package/Source/Scene/Cesium3DTileset.js

@@ -103,7 +103,7 @@ import ImageryLayerCollection from "./ImageryLayerCollection.js";
  * @property {ClippingPlaneCollection} [clippingPlanes] The {@link ClippingPlaneCollection} used to selectively disable rendering the tileset.
  * @property {ClippingPolygonCollection} [clippingPolygons] The {@link ClippingPolygonCollection} used to selectively disable rendering the tileset.
  * @property {ClassificationType} [classificationType] Determines whether terrain, 3D Tiles or both will be classified by this tileset. See {@link Cesium3DTileset#classificationType} for details about restrictions and limitations.
- * @property {HeightReference} [heightReference] Sets the {@link HeightReference} for point features in vector tilesets.
+ * @property {HeightReference} [heightReference] Sets the {@link HeightReference} for features in vector tilesets.
  * @property {Scene} [scene] The {@link CesiumWidget#scene} that the tileset will be rendered in, required for tilesets that specify a {@link heightReference} value for clamping 3D Tiles vector data content- like points, lines, and labels- to terrain or 3D tiles.
  * @property {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid determining the size and shape of the globe.
  * @property {object} [pointCloudShading] Options for constructing a {@link PointCloudShading} object to control point attenuation based on geometric error and lighting.

package/Source/Scene/ClippingPlaneCollection.js

@@ -545,8 +545,8 @@ ClippingPlaneCollection.prototype.update = function (frameState) {
   }
   if (!this._multipleDirtyPlanes) {
     // partial updates possible
-    let offsetX = 0;
-    let offsetY = 0;
+    let offsetX;
+    let offsetY;
     if (useFloatTexture) {
       offsetY = Math.floor(dirtyIndex / clippingPlanesTexture.width);
       offsetX = Math.floor(dirtyIndex - offsetY * clippingPlanesTexture.width);
@@ -605,7 +605,7 @@ const scratchMatrix = new Matrix4();
 const scratchPlane = new Plane(Cartesian3.UNIT_X, 0.0);
 /**
  * Determines the type intersection with the planes of this ClippingPlaneCollection instance and the specified {@link TileBoundingVolume}.
- * @private
+ * @ignore
  *
  * @param {object} tileBoundingVolume The volume to determine the intersection with the planes.
  * @param {Matrix4} [transform] An optional, additional matrix to transform the plane to world coordinates.
@@ -656,7 +656,7 @@ ClippingPlaneCollection.prototype.computeIntersectionWithBoundingVolume =
  * @param {ClippingPlaneCollection} [clippingPlaneCollection] A ClippingPlaneCollection (or undefined) being attached to an object
  * @param {object} owner An Object that should receive the new ClippingPlaneCollection
  * @param {string} key The Key for the Object to reference the ClippingPlaneCollection
- * @private
+ * @ignore
  */
 ClippingPlaneCollection.setOwner = function (
   clippingPlaneCollection,

package/Source/Scene/ClippingPolygon.js

@@ -84,6 +84,7 @@ function ClippingPolygon(options) {
  *
  * @param {Cartesian3[]|undefined} input The input array
  * @returns {Cartesian3[]|undefined} The copy
+ * @ignore
  */
 function copyArrayCartesian3(input) {
   if (!defined(input)) {
@@ -110,6 +111,7 @@ function copyArrayCartesian3(input) {
  * @param {Cartesian3[]|undefined} a The first array
  * @param {Cartesian3[]|undefined} b The second array
  * @returns {boolean} Whether the arrays are equal
+ * @ignore
  */
 function equalsArrayCartesian3(a, b) {
   if (!defined(a) && !defined(b)) {

package/Source/Scene/ClippingPolygonCollection.js

@@ -897,7 +897,7 @@ const scratchRectangleIntersection = new Rectangle();
 const scratchRectanglePolygon = new Rectangle();
 /**
  * Determines the type intersection with the polygons of this ClippingPolygonCollection instance and the specified {@link TileBoundingVolume}.
- * @private
+ * @ignore
  *
  * @param {object} tileBoundingVolume The volume to determine the intersection with the polygons.
  * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid on which the bounding volumes are defined.
@@ -963,7 +963,7 @@ ClippingPolygonCollection.prototype.computeIntersectionWithBoundingVolume =
  * @param {ClippingPolygonCollection} [clippingPolygonsCollection] A ClippingPolygonCollection (or undefined) being attached to an object
  * @param {object} owner An Object that should receive the new ClippingPolygonCollection
  * @param {string} key The Key for the Object to reference the ClippingPolygonCollection
- * @private
+ * @ignore
  */
 ClippingPolygonCollection.setOwner = function (
   clippingPolygonsCollection,

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;