@cesium/engine 6.2.0 → 8.0.0

package/Source/Scene/ScreenSpaceCameraController.js

@@ -255,6 +255,8 @@ function ScreenSpaceCameraController(scene) {
   this._globe = undefined;
   this._ellipsoid = undefined;
 
+  this._lastGlobeHeight = 0.0;
+
   this._aggregator = new CameraEventAggregator(scene.canvas);
 
   this._lastInertiaSpinMovement = undefined;
@@ -1645,7 +1647,7 @@ function rotateCVOnTerrain(controller, startPosition, movement) {
   );
 
   if (controller.enableCollisionDetection) {
-    adjustHeightForTerrain(controller);
+    adjustHeightForTerrain(controller, true);
   }
 
   if (!Cartesian3.equals(camera.positionWC, originalPosition)) {
@@ -2651,7 +2653,7 @@ function tilt3DOnTerrain(controller, startPosition, movement) {
   );
 
   if (controller.enableCollisionDetection) {
-    adjustHeightForTerrain(controller);
+    adjustHeightForTerrain(controller, true);
   }
 
   if (!Cartesian3.equals(camera.positionWC, originalPosition)) {
@@ -2854,23 +2856,19 @@ function update3D(controller) {
 const scratchAdjustHeightTransform = new Matrix4();
 const scratchAdjustHeightCartographic = new Cartographic();
 
-function adjustHeightForTerrain(controller) {
+function adjustHeightForTerrain(controller, cameraChanged) {
   controller._adjustedHeightForTerrain = true;
 
   const scene = controller._scene;
   const mode = scene.mode;
   const globe = scene.globe;
 
-  if (
-    !defined(globe) ||
-    mode === SceneMode.SCENE2D ||
-    mode === SceneMode.MORPHING
-  ) {
+  if (mode === SceneMode.SCENE2D || mode === SceneMode.MORPHING) {
     return;
   }
 
   const camera = scene.camera;
-  const ellipsoid = globe.ellipsoid;
+  const ellipsoid = defaultValue(globe?.ellipsoid, Ellipsoid.WGS84);
   const projection = scene.mapProjection;
 
   let transform;
@@ -2893,7 +2891,15 @@ function adjustHeightForTerrain(controller) {
     const globeHeight = controller._scene.globeHeight;
     if (defined(globeHeight)) {
       const height = globeHeight + controller.minimumZoomDistance;
-      if (cartographic.height < height) {
+      const difference = globeHeight - controller._lastGlobeHeight;
+      const percentDifference = difference / controller._lastGlobeHeight;
+
+      // Unless the camera has been moved by user input, to avoid big jumps during tile loads
+      // only make height updates when the globe height has been fairly stable across several frames
+      if (
+        cartographic.height < height &&
+        (cameraChanged || Math.abs(percentDifference) <= 0.1)
+      ) {
         cartographic.height = height;
         if (mode === SceneMode.SCENE3D) {
           ellipsoid.cartographicToCartesian(cartographic, camera.position);
@@ -2902,6 +2908,12 @@ function adjustHeightForTerrain(controller) {
         }
         heightUpdated = true;
       }
+
+      if (cameraChanged || Math.abs(percentDifference) <= 0.1) {
+        controller._lastGlobeHeight = globeHeight;
+      } else {
+        controller._lastGlobeHeight += difference * 0.1;
+      }
     }
   }
 
@@ -3008,9 +3020,7 @@ ScreenSpaceCameraController.prototype.update = function () {
     const cameraChanged =
       !Cartesian3.equals(previousPosition, camera.positionWC) ||
       !Cartesian3.equals(previousDirection, camera.directionWC);
-    if (cameraChanged) {
-      adjustHeightForTerrain(this);
-    }
+    adjustHeightForTerrain(this, cameraChanged);
   }
 
   this._aggregator.reset();

package/Source/Scene/SensorVolumePortionToDisplay.js

@@ -0,0 +1,69 @@
+import { DeveloperError } from "@cesium/engine";
+
+/**
+ * Constants used to indicated what part of the sensor volume to display.
+ *
+ * @enum {Number}
+ */
+const SensorVolumePortionToDisplay = {
+  /**
+   * 0x0000.  Display the complete sensor volume.
+   *
+   * @type {Number}
+   * @constant
+   */
+  COMPLETE: 0x0000,
+  /**
+   * 0x0001.  Display the portion of the sensor volume that lies below the true horizon of the ellipsoid.
+   *
+   * @type {Number}
+   * @constant
+   */
+  BELOW_ELLIPSOID_HORIZON: 0x0001,
+  /**
+   * 0x0002.  Display the portion of the sensor volume that lies above the true horizon of the ellipsoid.
+   *
+   * @type {Number}
+   * @constant
+   */
+  ABOVE_ELLIPSOID_HORIZON: 0x0002,
+};
+
+/**
+ * Validates that the provided value is a valid {@link SensorVolumePortionToDisplay} enumeration value.
+ *
+ * @param {SensorVolumePortionToDisplay} portionToDisplay The value to validate.
+ *
+ * @returns {Boolean} <code>true</code> if the provided value is a valid enumeration value; otherwise, <code>false</code>.
+ */
+SensorVolumePortionToDisplay.validate = function (portionToDisplay) {
+  return (
+    portionToDisplay === SensorVolumePortionToDisplay.COMPLETE ||
+    portionToDisplay === SensorVolumePortionToDisplay.BELOW_ELLIPSOID_HORIZON ||
+    portionToDisplay === SensorVolumePortionToDisplay.ABOVE_ELLIPSOID_HORIZON
+  );
+};
+
+/**
+ * Converts the provided value to its corresponding enumeration string.
+ *
+ * @param {SensorVolumePortionToDisplay} portionToDisplay The value to be converted to its corresponding enumeration string.
+ *
+ * @returns {String} The enumeration string corresponding to the value.
+ */
+SensorVolumePortionToDisplay.toString = function (portionToDisplay) {
+  switch (portionToDisplay) {
+    case SensorVolumePortionToDisplay.COMPLETE:
+      return "COMPLETE";
+    case SensorVolumePortionToDisplay.BELOW_ELLIPSOID_HORIZON:
+      return "BELOW_ELLIPSOID_HORIZON";
+    case SensorVolumePortionToDisplay.ABOVE_ELLIPSOID_HORIZON:
+      return "ABOVE_ELLIPSOID_HORIZON";
+    default:
+      throw new DeveloperError(
+        "SensorVolumePortionToDisplay value is not valid and cannot be converted to a String."
+      );
+  }
+};
+
+export default SensorVolumePortionToDisplay;

package/Source/Scene/SkyAtmosphere.js

@@ -217,14 +217,13 @@ Object.defineProperties(SkyAtmosphere.prototype, {
 });
 
 /**
+ * Set the dynamic lighting enum value for the shader
+ * @param {DynamicAtmosphereLightingType} lightingEnum The enum that determines the dynamic atmosphere light source
+ *
  * @private
  */
-SkyAtmosphere.prototype.setDynamicAtmosphereColor = function (
-  enableLighting,
-  useSunDirection
-) {
-  const lightEnum = enableLighting ? (useSunDirection ? 2.0 : 1.0) : 0.0;
-  this._radiiAndDynamicAtmosphereColor.z = lightEnum;
+SkyAtmosphere.prototype.setDynamicLighting = function (lightingEnum) {
+  this._radiiAndDynamicAtmosphereColor.z = lightingEnum;
 };
 
 const scratchModelMatrix = new Matrix4();

package/Source/Scene/SpatialNode.js

@@ -23,7 +23,6 @@ import OrientedBoundingBox from "../Core/OrientedBoundingBox.js";
  */
 function SpatialNode(level, x, y, z, parent, shape, voxelDimensions) {
   /**
-   * @ignore
    * @type {SpatialNode[]}
    */
   this.children = undefined;
@@ -35,24 +34,24 @@ function SpatialNode(level, x, y, z, parent, shape, voxelDimensions) {
   this.z = z;
 
   /**
-   * @ignore
+   * @type {Cartesian3}
+   */
+  this.dimensions = Cartesian3.clone(voxelDimensions);
+  /**
    * @type {KeyframeNode[]}
    */
   this.keyframeNodes = [];
   /**
-   * @ignore
    * @type {KeyframeNode[]}
    */
   this.renderableKeyframeNodes = [];
 
   this.renderableKeyframeNodeLerp = 0.0;
   /**
-   * @ignore
    * @type {KeyframeNode}
    */
   this.renderableKeyframeNodePrevious = undefined;
   /**
-   * @ignore
    * @type {KeyframeNode}
    */
   this.renderableKeyframeNodeNext = undefined;
@@ -62,19 +61,15 @@ function SpatialNode(level, x, y, z, parent, shape, voxelDimensions) {
   this.screenSpaceError = 0.0;
   this.visitedFrameNumber = -1;
 
-  this.computeBoundingVolumes(shape, voxelDimensions);
+  this.computeBoundingVolumes(shape);
 }
 
 const scratchObbHalfScale = new Cartesian3();
 
 /**
  * @param {VoxelShape} shape
- * @param {Cartesian3} voxelDimensions
  */
-SpatialNode.prototype.computeBoundingVolumes = function (
-  shape,
-  voxelDimensions
-) {
+SpatialNode.prototype.computeBoundingVolumes = function (shape) {
   this.orientedBoundingBox = shape.computeOrientedBoundingBoxForTile(
     this.level,
     this.x,
@@ -89,15 +84,14 @@ SpatialNode.prototype.computeBoundingVolumes = function (
   );
   const maximumScale = 2.0 * Cartesian3.maximumComponent(halfScale);
   this.approximateVoxelSize =
-    maximumScale / Cartesian3.minimumComponent(voxelDimensions);
+    maximumScale / Cartesian3.minimumComponent(this.dimensions);
 };
 
 /**
  * @param {VoxelShape} shape The shape of the parent VoxelPrimitive
- * @param {Cartesian3} voxelDimensions
  * @private
  */
-SpatialNode.prototype.constructChildNodes = function (shape, voxelDimensions) {
+SpatialNode.prototype.constructChildNodes = function (shape) {
   const { level, x, y, z } = this;
   const xMin = x * 2;
   const yMin = y * 2;
@@ -119,7 +113,7 @@ SpatialNode.prototype.constructChildNodes = function (shape, voxelDimensions) {
   ];
 
   this.children = childCoords.map(([level, x, y, z]) => {
-    return new SpatialNode(level, x, y, z, this, shape, voxelDimensions);
+    return new SpatialNode(level, x, y, z, this, shape, this.dimensions);
   });
 };
 
@@ -328,7 +322,7 @@ SpatialNode.prototype.destroyKeyframeNode = function (
 
   keyframeNode.spatialNode = undefined;
   keyframeNode.state = KeyframeNode.LoadState.UNLOADED;
-  keyframeNode.metadatas = {};
+  keyframeNode.metadata = {};
   keyframeNode.megatextureIndex = -1;
   keyframeNode.priority = -Number.MAX_VALUE;
   keyframeNode.highPriorityFrameNumber = -1;
@@ -345,15 +339,14 @@ SpatialNode.prototype.addKeyframeNodeToMegatextures = function (
   if (
     keyframeNode.state !== KeyframeNode.LoadState.RECEIVED ||
     keyframeNode.megatextureIndex !== -1 ||
-    keyframeNode.metadatas.length !== megatextures.length
+    keyframeNode.metadata.length !== megatextures.length
   ) {
     throw new DeveloperError("Keyframe node cannot be added to megatexture");
   }
 
   for (let i = 0; i < megatextures.length; i++) {
     const megatexture = megatextures[i];
-    keyframeNode.megatextureIndex = megatexture.add(keyframeNode.metadatas[i]);
-    keyframeNode.metadatas[i] = undefined; // data is in megatexture so no need to hold onto it
+    keyframeNode.megatextureIndex = megatexture.add(keyframeNode.metadata[i]);
   }
 
   keyframeNode.state = KeyframeNode.LoadState.LOADED;

package/Source/Scene/StructuralMetadata.js

@@ -5,7 +5,7 @@ import defined from "../Core/defined.js";
 /**
  * An object containing structural metadata.
  * <p>
- * See the {@link https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadatas|EXT_structural_metadata Extension} as well as the
+ * See the {@link https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_structural_metadata|EXT_structural_metadata Extension} as well as the
  * previous {@link https://github.com/CesiumGS/glTF/tree/3d-tiles-next/extensions/2.0/Vendor/EXT_feature_metadata|EXT_feature_metadata Extension} for glTF.
  * </p>
  *

package/Source/Scene/Terrain.js

@@ -1,5 +1,6 @@
 import Check from "../Core/Check.js";
 import Event from "../Core/Event.js";
+import createWorldBathymetryAsync from "../Core/createWorldBathymetryAsync.js";
 import createWorldTerrainAsync from "../Core/createWorldTerrainAsync.js";
 
 /**
@@ -156,6 +157,54 @@ Terrain.fromWorldTerrain = function (options) {
   return new Terrain(createWorldTerrainAsync(options));
 };
 
+/**
+ * Creates a {@link Terrain} instance for {@link https://cesium.com/content/#cesium-world-bathymetry|Cesium World Bathymetry}.
+ *
+ * @function
+ *
+ * @param {Object} [options] Object with the following properties:
+ * @param {Boolean} [options.requestVertexNormals=false] Flag that indicates if the client should request additional lighting information from the server if available.
+ * @returns {Terrain} An asynchronous helper object for a CesiumTerrainProvider
+ *
+ * @see Ion
+ * @see createWorldBathymetryAsync
+ *
+ * @example
+ * // Create Cesium World Bathymetry with default settings
+ * const viewer = new Cesium.Viewer("cesiumContainer", {
+ *   terrain: Cesium.Terrain.fromWorldBathymetry)
+ * });
+ *
+ * @example
+ * // Create Cesium World Terrain with normals.
+ * const viewer1 = new Cesium.Viewer("cesiumContainer", {
+ *   terrain: Cesium.Terrain.fromWorldBathymetry({
+ *      requestVertexNormals: true
+ *    });
+ * });
+ *
+ * @example
+ * // Handle loading events
+ * const bathymetry = Cesium.Terrain.fromWorldBathymetry();
+ *
+ * scene.setTerrain(bathymetry);
+ *
+ * bathymetry.readyEvent.addEventListener(provider => {
+ *   scene.globe.enableLighting = true;
+ *
+ *   bathymetry.provider.errorEvent.addEventListener(error => {
+ *     alert(`Encountered an error while loading bathymetric terrain tiles! ${error}`);
+ *   });
+ * });
+ *
+ * bathymetry.errorEvent.addEventListener(error => {
+ *   alert(`Encountered an error while creating bathymetric terrain! ${error}`);
+ * });
+ */
+Terrain.fromWorldBathymetry = function (options) {
+  return new Terrain(createWorldBathymetryAsync(options));
+};
+
 function handleError(errorEvent, error) {
   if (errorEvent.numberOfListeners > 0) {
     errorEvent.raiseEvent(error);

package/Source/Scene/TileBoundingS2Cell.js

@@ -330,7 +330,7 @@ Object.defineProperties(TileBoundingS2Cell.prototype, {
   /**
    * The underlying bounding volume.
    *
-   * @memberof TileOrientedBoundingBox.prototype
+   * @memberof TileBoundingS2Cell.prototype
    *
    * @type {object}
    * @readonly
@@ -343,7 +343,7 @@ Object.defineProperties(TileBoundingS2Cell.prototype, {
   /**
    * The underlying bounding sphere.
    *
-   * @memberof TileOrientedBoundingBox.prototype
+   * @memberof TileBoundingS2Cell.prototype
    *
    * @type {BoundingSphere}
    * @readonly

package/Source/Scene/Tileset3DTileContent.js

@@ -168,6 +168,10 @@ Tileset3DTileContent.prototype.applyStyle = function (style) {};
 
 Tileset3DTileContent.prototype.update = function (tileset, frameState) {};
 
+Tileset3DTileContent.prototype.pick = function (ray, frameState, result) {
+  return undefined;
+};
+
 Tileset3DTileContent.prototype.isDestroyed = function () {
   return false;
 };

package/Source/Scene/Vector3DTileContent.js

@@ -727,6 +727,10 @@ Vector3DTileContent.prototype.update = function (tileset, frameState) {
   }
 };
 
+Vector3DTileContent.prototype.pick = function (ray, frameState, result) {
+  return undefined;
+};
+
 Vector3DTileContent.prototype.getPolylinePositions = function (batchId) {
   const polylines = this._polylines;
   if (!defined(polylines)) {

package/Source/Scene/VoxelBoxShape.js

@@ -351,6 +351,82 @@ VoxelBoxShape.prototype.computeOrientedBoundingBoxForTile = function (
   );
 };
 
+const sampleSizeScratch = new Cartesian3();
+
+/**
+ * Computes an oriented bounding box for a specified sample within a specified tile.
+ * The update function must be called before calling this function.
+ *
+ * @param {SpatialNode} spatialNode The spatial node containing the sample
+ * @param {Cartesian3} tileDimensions The size of the tile in number of samples, before padding
+ * @param {Cartesian3} tileUv The sample coordinate within the tile
+ * @param {OrientedBoundingBox} result The oriented bounding box that will be set to enclose the specified sample
+ * @returns {OrientedBoundingBox} The oriented bounding box.
+ */
+VoxelBoxShape.prototype.computeOrientedBoundingBoxForSample = function (
+  spatialNode,
+  tileDimensions,
+  tileUv,
+  result
+) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("spatialNode", spatialNode);
+  Check.typeOf.object("tileDimensions", tileDimensions);
+  Check.typeOf.object("tileUv", tileUv);
+  Check.typeOf.object("result", result);
+  //>>includeEnd('debug');
+
+  const tileSizeAtLevel = 1.0 / Math.pow(2, spatialNode.level);
+  const sampleSize = Cartesian3.divideComponents(
+    Cartesian3.ONE,
+    tileDimensions,
+    sampleSizeScratch
+  );
+  const sampleSizeAtLevel = Cartesian3.multiplyByScalar(
+    sampleSize,
+    tileSizeAtLevel,
+    sampleSizeScratch
+  );
+
+  const minLerp = Cartesian3.multiplyByScalar(
+    Cartesian3.fromElements(
+      spatialNode.x + tileUv.x,
+      spatialNode.y + tileUv.y,
+      spatialNode.z + tileUv.z,
+      scratchTileMinBounds
+    ),
+    tileSizeAtLevel,
+    scratchTileMinBounds
+  );
+  const maxLerp = Cartesian3.add(
+    minLerp,
+    sampleSizeAtLevel,
+    scratchTileMaxBounds
+  );
+
+  const minBounds = this._minBounds;
+  const maxBounds = this._maxBounds;
+  const sampleMinBounds = Cartesian3.fromElements(
+    CesiumMath.lerp(minBounds.x, maxBounds.x, minLerp.x),
+    CesiumMath.lerp(minBounds.y, maxBounds.y, minLerp.y),
+    CesiumMath.lerp(minBounds.z, maxBounds.z, minLerp.z),
+    scratchTileMinBounds
+  );
+  const sampleMaxBounds = Cartesian3.fromElements(
+    CesiumMath.lerp(minBounds.x, maxBounds.x, maxLerp.x),
+    CesiumMath.lerp(minBounds.y, maxBounds.y, maxLerp.y),
+    CesiumMath.lerp(minBounds.z, maxBounds.z, maxLerp.z),
+    scratchTileMaxBounds
+  );
+
+  return getBoxChunkObb(
+    sampleMinBounds,
+    sampleMaxBounds,
+    this.shapeTransform,
+    result
+  );
+};
+
 /**
  * Computes an approximate step size for raymarching the root tile of a voxel grid.
  * The update function must be called before calling this function.