@cesium/engine 7.0.0 → 9.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,7 +2856,7 @@ 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;
@@ -2889,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);
@@ -2898,6 +2908,12 @@ function adjustHeightForTerrain(controller) {
         }
         heightUpdated = true;
       }
+
+      if (cameraChanged || Math.abs(percentDifference) <= 0.1) {
+        controller._lastGlobeHeight = globeHeight;
+      } else {
+        controller._lastGlobeHeight += difference * 0.1;
+      }
     }
   }
 
@@ -3004,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 "../Core/DeveloperError.js";
+
+/**
+ * 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/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/VoxelBoxShape.js

@@ -351,19 +351,80 @@ VoxelBoxShape.prototype.computeOrientedBoundingBoxForTile = function (
   );
 };
 
+const sampleSizeScratch = new Cartesian3();
+
 /**
- * Computes an approximate step size for raymarching the root tile of a voxel grid.
+ * Computes an oriented bounding box for a specified sample within a specified tile.
  * The update function must be called before calling this function.
  *
- * @param {Cartesian3} dimensions The voxel grid dimensions for a tile.
- * @returns {number} The step size.
+ * @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.computeApproximateStepSize = function (dimensions) {
+VoxelBoxShape.prototype.computeOrientedBoundingBoxForSample = function (
+  spatialNode,
+  tileDimensions,
+  tileUv,
+  result
+) {
   //>>includeStart('debug', pragmas.debug);
-  Check.typeOf.object("dimensions", dimensions);
+  Check.typeOf.object("spatialNode", spatialNode);
+  Check.typeOf.object("tileDimensions", tileDimensions);
+  Check.typeOf.object("tileUv", tileUv);
+  Check.typeOf.object("result", result);
   //>>includeEnd('debug');
 
-  return 1.0 / Cartesian3.maximumComponent(dimensions);
+  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
+  );
 };
 
 /**

package/Source/Scene/VoxelCell.js

@@ -0,0 +1,273 @@
+import Cartesian3 from "../Core/Cartesian3.js";
+import Check from "../Core/Check.js";
+import defined from "../Core/defined.js";
+import MetadataType from "./MetadataType.js";
+import OrientedBoundingBox from "../Core/OrientedBoundingBox.js";
+
+/**
+ * A cell from a {@link VoxelPrimitive}.
+ * <p>
+ * Provides access to properties associated with one cell of a voxel primitive.
+ * </p>
+ * <p>
+ * Do not construct this directly.  Access it through picking using {@link Scene#pickVoxel}.
+ * </p>
+ *
+ * @alias VoxelCell
+ * @constructor
+ *
+ * @param {VoxelPrimitive} primitive The voxel primitive containing the cell
+ * @param {number} tileIndex The index of the tile
+ * @param {number} sampleIndex The index of the sample within the tile, containing metadata for this cell
+ *
+ * @example
+ * // On left click, display all the properties for a voxel cell in the console log.
+ * handler.setInputAction(function(movement) {
+ *   const voxelCell = scene.pickVoxel(movement.position);
+ *   if (voxelCell instanceof Cesium.VoxelCell) {
+ *     const propertyIds = voxelCell.getPropertyIds();
+ *     const length = propertyIds.length;
+ *     for (let i = 0; i < length; ++i) {
+ *       const propertyId = propertyIds[i];
+ *       console.log(`{propertyId}: ${voxelCell.getProperty(propertyId)}`);
+ *     }
+ *   }
+ * }, Cesium.ScreenSpaceEventType.LEFT_CLICK);
+ *
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+function VoxelCell(primitive, tileIndex, sampleIndex) {
+  this._primitive = primitive;
+  this._tileIndex = tileIndex;
+  this._sampleIndex = sampleIndex;
+  this._metadata = {};
+  this._orientedBoundingBox = new OrientedBoundingBox();
+}
+
+/**
+ * Construct a VoxelCell, and update the metadata and bounding box using the properties
+ * of a supplied keyframe node.
+ *
+ * @private
+ * @param {VoxelPrimitive} primitive The voxel primitive containing the cell.
+ * @param {number} tileIndex The index of the tile.
+ * @param {number} sampleIndex The index of the sample within the tile, containing metadata for this cell.
+ * @param {KeyframeNode} keyframeNode The keyframe node containing information about the tile.
+ * @returns {VoxelCell}
+ *
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+VoxelCell.fromKeyframeNode = function (
+  primitive,
+  tileIndex,
+  sampleIndex,
+  keyframeNode
+) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("primitive", primitive);
+  Check.typeOf.number("tileIndex", tileIndex);
+  Check.typeOf.number("sampleIndex", sampleIndex);
+  Check.typeOf.object("keyframeNode", keyframeNode);
+  //>>includeEnd('debug');
+
+  const voxelCell = new VoxelCell(primitive, tileIndex, sampleIndex);
+  const { spatialNode, metadata } = keyframeNode;
+  voxelCell._metadata = getMetadataForSample(primitive, metadata, sampleIndex);
+  voxelCell._orientedBoundingBox = getOrientedBoundingBox(
+    primitive,
+    spatialNode,
+    sampleIndex,
+    voxelCell._orientedBoundingBox
+  );
+  return voxelCell;
+};
+
+/**
+ * @private
+ * @param {VoxelPrimitive} primitive
+ * @param {object} metadata
+ * @param {number} sampleIndex
+ * @returns {object}
+ */
+function getMetadataForSample(primitive, metadata, sampleIndex) {
+  if (!defined(metadata)) {
+    return undefined;
+  }
+  const { names, types } = primitive.provider;
+  const metadataMap = {};
+  for (let i = 0; i < names.length; i++) {
+    const name = names[i];
+    const componentCount = MetadataType.getComponentCount(types[i]);
+    const samples = metadata[i].slice(
+      sampleIndex * componentCount,
+      (sampleIndex + 1) * componentCount
+    );
+    metadataMap[name] = samples;
+  }
+  return metadataMap;
+}
+
+const tileCoordinateScratch = new Cartesian3();
+const tileUvScratch = new Cartesian3();
+
+/**
+ * @private
+ * @param {VoxelPrimitive} primitive
+ * @param {SpatialNode} spatialNode
+ * @param {OrientedBoundingBox} result
+ * @returns {OrientedBoundingBox}
+ */
+function getOrientedBoundingBox(primitive, spatialNode, sampleIndex, result) {
+  // Convert the sample index into a 3D tile coordinate
+  // Note: dimensions from the spatialNode include padding
+  const paddedDimensions = spatialNode.dimensions;
+  const sliceSize = paddedDimensions.x * paddedDimensions.y;
+  const zIndex = Math.floor(sampleIndex / sliceSize);
+  const indexInSlice = sampleIndex - zIndex * sliceSize;
+  const yIndex = Math.floor(indexInSlice / paddedDimensions.x);
+  const xIndex = indexInSlice - yIndex * paddedDimensions.x;
+  const tileCoordinate = Cartesian3.fromElements(
+    xIndex,
+    yIndex,
+    zIndex,
+    tileCoordinateScratch
+  );
+
+  // Remove padding, and convert to a fraction in [0, 1], where the limits are
+  // the unpadded bounds of the tile
+  const tileUv = Cartesian3.divideComponents(
+    Cartesian3.subtract(
+      tileCoordinate,
+      primitive._paddingBefore,
+      tileCoordinateScratch
+    ),
+    primitive.dimensions,
+    tileUvScratch
+  );
+
+  const shape = primitive._shape;
+  return shape.computeOrientedBoundingBoxForSample(
+    spatialNode,
+    primitive.dimensions,
+    tileUv,
+    result
+  );
+}
+
+Object.defineProperties(VoxelCell.prototype, {
+  /**
+   * Gets an object of the metadata values for this cell. The object's keys are the metadata names.
+   *
+   * @memberof VoxelCell.prototype
+   *
+   * @type {object}
+   *
+   * @readonly
+   * @private
+   */
+  metadata: {
+    get: function () {
+      return this._metadata;
+    },
+  },
+
+  /**
+   * All objects returned by {@link Scene#pick} have a <code>primitive</code> property. This returns
+   * the VoxelPrimitive containing the cell.
+   *
+   * @memberof VoxelCell.prototype
+   *
+   * @type {VoxelPrimitive}
+   *
+   * @readonly
+   */
+  primitive: {
+    get: function () {
+      return this._primitive;
+    },
+  },
+
+  /**
+   * Get the sample index of the cell.
+   *
+   * @memberof VoxelCell.prototype
+   *
+   * @type {number}
+   *
+   * @readonly
+   */
+  sampleIndex: {
+    get: function () {
+      return this._sampleIndex;
+    },
+  },
+
+  /**
+   * Get the index of the tile containing the cell.
+   *
+   * @memberof VoxelCell.prototype
+   *
+   * @type {number}
+   *
+   * @readonly
+   */
+  tileIndex: {
+    get: function () {
+      return this._tileIndex;
+    },
+  },
+
+  /**
+   * Get a copy of the oriented bounding box containing the cell.
+   *
+   * @memberof VoxelCell.prototype
+   *
+   * @type {OrientedBoundingBox}
+   *
+   * @readonly
+   */
+  orientedBoundingBox: {
+    get: function () {
+      return this._orientedBoundingBox.clone();
+    },
+  },
+});
+
+/**
+ * Returns <code>true</code> if the feature contains this property.
+ *
+ * @param {string} name The case-sensitive name of the property.
+ * @returns {boolean} Whether the feature contains this property.
+ */
+VoxelCell.prototype.hasProperty = function (name) {
+  return defined(this._metadata[name]);
+};
+
+/**
+ * Returns an array of metadata property names for the feature.
+ *
+ * @returns {string[]} The IDs of the feature's properties.
+ */
+VoxelCell.prototype.getNames = function () {
+  return Object.keys(this._metadata);
+};
+
+/**
+ * Returns a copy of the value of the metadata in the cell with the given name.
+ *
+ * @param {string} name The case-sensitive name of the property.
+ * @returns {*} The value of the property or <code>undefined</code> if the feature does not have this property.
+ *
+ * @example
+ * // Display all the properties for a voxel cell in the console log.
+ * const names = voxelCell.getNames();
+ * for (let i = 0; i < names.length; ++i) {
+ *   const name = names[i];
+ *   console.log(`{name}: ${voxelCell.getProperty(name)}`);
+ * }
+ */
+VoxelCell.prototype.getProperty = function (name) {
+  return this._metadata[name];
+};
+
+export default VoxelCell;