@cesium/engine 17.0.0 → 18.0.1-splats.0

package/Source/Scene/Cesium3DTileset.js

@@ -62,6 +62,7 @@ import Cesium3DTilesetBaseTraversal from "./Cesium3DTilesetBaseTraversal.js";
 import Cesium3DTilesetSkipTraversal from "./Cesium3DTilesetSkipTraversal.js";
 import Ray from "../Core/Ray.js";
 import DynamicEnvironmentMapManager from "./DynamicEnvironmentMapManager.js";
+import ImageryLayerCollection from "./ImageryLayerCollection.js";
 
 /**
  * @typedef {Object} Cesium3DTileset.ConstructorOptions
@@ -119,6 +120,7 @@ import DynamicEnvironmentMapManager from "./DynamicEnvironmentMapManager.js";
  * @property {boolean} [enableCollision=false] When <code>true</code>, enables collisions for camera or CPU picking. While this is <code>true</code> the camera will be prevented from going below the tileset surface if {@link ScreenSpaceCameraController#enableCollisionDetection} is true.
  * @property {boolean} [projectTo2D=false] Whether to accurately project the tileset to 2D. If this is true, the tileset will be projected accurately to 2D, but it will use more memory to do so. If this is false, the tileset will use less memory and will still render in 2D / CV mode, but its projected positions may be inaccurate. This cannot be set after the tileset has been created.
  * @property {boolean} [enablePick=false] Whether to allow collision and CPU picking with <code>pick</code> when using WebGL 1. If using WebGL 2 or above, this option will be ignored. If using WebGL 1 and this is true, the <code>pick</code> operation will work correctly, but it will use more memory to do so. If running with WebGL 1 and this is false, the model will use less memory, but <code>pick</code> will always return <code>undefined</code>. This cannot be set after the tileset has loaded.
+ * @property {boolean} [asynchronouslyLoadImagery=false] Whether loading imagery that is draped over the tileset should be done asynchronously. If this is <code>true</code>, then tile content will be displayed with its original texture until the imagery texture is loaded. If this is <code>false</code>, then the tile content will not be displayed until the imagery is ready.
  * @property {string} [debugHeatmapTilePropertyName] The tile variable to colorize as a heatmap. All rendered tiles will be colorized relative to each other's specified variable value.
  * @property {boolean} [debugFreezeFrame=false] For debugging only. Determines if only the tiles from last frame should be used for rendering.
  * @property {boolean} [debugColorizeTiles=false] For debugging only. When true, assigns a random color to each tile.
@@ -143,7 +145,7 @@ import DynamicEnvironmentMapManager from "./DynamicEnvironmentMapManager.js";
  *
  * @alias Cesium3DTileset
  * @constructor
- *
+ * @experimental Support for loading Gaussian splats content encoded with SPZ compression using the draft glTF extension {@link https://github.com/KhronosGroup/glTF/pull/2490 | KHR_spz_gaussian_splats_compression} is experimental and is subject change without Cesium's standard deprecation policy.
  * @param {Cesium3DTileset.ConstructorOptions} options An object describing initialization options
  *
  * @exception {DeveloperError} The tileset must be 3D Tiles version 0.0 or 1.0.
@@ -194,7 +196,6 @@ import DynamicEnvironmentMapManager from "./DynamicEnvironmentMapManager.js";
  *      dynamicScreenSpaceErrorHeightFalloff: 0.25
  * });
  * scene.primitives.add(tileset);
- *
  * @see {@link https://github.com/CesiumGS/3d-tiles/tree/main/specification|3D Tiles specification}
  */
 function Cesium3DTileset(options) {
@@ -347,6 +348,60 @@ function Cesium3DTileset(options) {
   this._vectorKeepDecodedPositions =
     options.vectorKeepDecodedPositions ?? false;
 
+  /**
+   * The collection of <code>ImageryLayer</code> objects providing 2D georeferenced
+   * image data that will be rendered over the tileset.
+   *
+   * @private
+   * @type {ImageryLayerCollection}
+   * @readonly
+   */
+  this._imageryLayers = new ImageryLayerCollection(this);
+
+  /**
+   * A counter that will be increased for each modification of the
+   * imagery layers (i.e. for each layerAdded, layerRemoved,
+   * layerMoved, or layerShownOrHidden event). This can be used
+   * by the <code>ModelImagery</code> class to detect changes in
+   * the imagery, and trigger the appropriate updates.
+   *
+   * @private
+   */
+  this._imageryLayersModificationCounter = 0;
+
+  /**
+   * A listener that will be attached to the layerAdded, layerRemoved,
+   * layerMoved, and layerShownOrHidden events of the imagery layers,
+   * and increment the imagery layers modification counter for each
+   * event.
+   *
+   * @private
+   * @readonly
+   */
+  this._imageryLayersListener = () => {
+    this._imageryLayersModificationCounter++;
+  };
+
+  // Attach the imagery layers listener to all events of
+  // the imagery layers collection
+  this.imageryLayers.layerAdded.addEventListener(this._imageryLayersListener);
+  this.imageryLayers.layerRemoved.addEventListener(this._imageryLayersListener);
+  this.imageryLayers.layerMoved.addEventListener(this._imageryLayersListener);
+  this.imageryLayers.layerShownOrHidden.addEventListener(
+    this._imageryLayersListener,
+  );
+
+  /**
+   * Whether loading imagery that is draped over the tileset should be
+   * done asynchronously. If this is <code>true</code>, then tile content
+   * will be displayed with its original texture until the imagery texture
+   * is loaded. If this is <code>false</code>, then the tile content will
+   * not be displayed until the imagery is ready.
+   *
+   * @private
+   */
+  this._asynchronouslyLoadImagery = options.asynchronouslyLoadImagery ?? false;
+
   /**
    * Preload tiles when <code>tileset.show</code> is <code>false</code>. Loads tiles as if the tileset is visible but does not render them.
    *
@@ -1097,6 +1152,69 @@ Object.defineProperties(Cesium3DTileset.prototype, {
     },
   },
 
+  /**
+   * The collection of <code>ImageryLayer</code> objects providing 2D georeferenced
+   * image data that will be rendered over the tileset.
+   *
+   * The imagery will be draped over glTF, B3DM, PNTS, or GeoJSON tile content.
+   *
+   * @see ImageryLayer
+   *
+   * @memberof Cesium3DTileset.prototype
+   * @readonly
+   * @type {ImageryLayerCollection}
+   *
+   * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+   *
+   * @example
+   * // Drape Bing Maps Aerial imagery over the tileset
+   * const imageryProvider = await Cesium.createWorldImageryAsync({
+   *   style: Cesium.IonWorldImageryStyle.AERIAL,
+   * });
+   * const imageryLayer = new ImageryLayer(imageryProvider);
+   * tileset.imageryLayers.add(imageryLayer);
+   */
+  imageryLayers: {
+    get: function () {
+      return this._imageryLayers;
+    },
+  },
+
+  /**
+   * The modification counter of the imagery layers.
+   *
+   * This is incremented for each modification (layerAdded, layerMoved,
+   * layerRemoved, layerShownOrHidden) of the imagery layers, and can
+   * be used <b>internally</b> (by <code>ModelPrimitiveImagery</code>)
+   * to trigger updates whenever the collection of imagery layers
+   * changes.
+   *
+   * @memberof Cesium3DTileset.prototype
+   * @readonly
+   * @type {number}
+   * @private
+   */
+  imageryLayersModificationCounter: {
+    get: function () {
+      return this._imageryLayersModificationCounter;
+    },
+  },
+
+  /**
+   * Whether loading imagery that is draped over the tileset should be
+   * done asynchronously.
+   *
+   * @memberof Cesium3DTileset.prototype
+   * @readonly
+   * @type {boolean}
+   * @private
+   */
+  asynchronouslyLoadImagery: {
+    get: function () {
+      return this._asynchronouslyLoadImagery;
+    },
+  },
+
   /**
    * Gets the tileset's properties dictionary object, which contains metadata about per-feature properties.
    * <p>
@@ -2638,6 +2756,7 @@ function filterProcessingQueue(tileset) {
 const scratchUpdateHeightCartographic = new Cartographic();
 const scratchUpdateHeightCartographic2 = new Cartographic();
 const scratchUpdateHeightCartesian = new Cartesian3();
+
 function processUpdateHeight(tileset, tile, frameState) {
   if (!tileset.enableCollision || !tileset.show) {
     return;
@@ -3338,6 +3457,8 @@ Cesium3DTileset.prototype.updateForPass = function (
   Check.typeOf.object("tilesetPassState", tilesetPassState);
   //>>includeEnd('debug');
 
+  this.imageryLayers._update();
+
   const pass = tilesetPassState.pass;
   if (
     (pass === Cesium3DTilePass.PRELOAD &&
@@ -3484,6 +3605,23 @@ Cesium3DTileset.prototype.destroy = function () {
   }
   this._environmentMapManager = undefined;
 
+  if (!this._imageryLayers.isDestroyed()) {
+    this.imageryLayers.layerAdded.removeEventListener(
+      this._imageryLayersListener,
+    );
+    this.imageryLayers.layerRemoved.removeEventListener(
+      this._imageryLayersListener,
+    );
+    this.imageryLayers.layerMoved.removeEventListener(
+      this._imageryLayersListener,
+    );
+    this.imageryLayers.layerShownOrHidden.removeEventListener(
+      this._imageryLayersListener,
+    );
+    this._imageryLayers.destroy();
+  }
+  this._imageryLayers = undefined;
+
   return destroyObject(this);
 };
 
@@ -3681,6 +3819,63 @@ Cesium3DTileset.prototype.pick = function (ray, frameState, result) {
   }
 };
 
+/**
+ * Returns true if the given glTF extension is used by this tileset.
+ * <br/><br/>
+ * Relies on the <code>3DTILES_content_gltf</code> extension and will return
+ * false if that extension is not used.
+ *
+ * @param {string} gltfExtensionName The name of the glTF extension to check.
+ * @returns {boolean} <code>true</code> if the glTF extension is used by this tileset; otherwise, <code>false</code>.
+ *
+ * @private
+ */
+Cesium3DTileset.prototype.isGltfExtensionUsed = function (gltfExtensionName) {
+  if (this.hasExtension("3DTILES_content_gltf")) {
+    if (!defined(this.extensions)) {
+      return false;
+    }
+    const extensionsUsed =
+      this.extensions["3DTILES_content_gltf"]?.extensionsUsed;
+
+    if (!defined(extensionsUsed)) {
+      return false;
+    }
+
+    return extensionsUsed.indexOf(gltfExtensionName) > -1;
+  }
+
+  return false;
+};
+
+/**
+ * Returns true if the given glTF extension is used and required by this tileset.
+ * <br/><br/>
+ * Relies on the <code>3DTILES_content_gltf</code> extension and will return
+ * <code>false</code> if that extension is not used.
+ *
+ * @param {string} gltfExtensionName The name of the glTF extension to check.
+ * @returns {boolean} <code>true</code> if the glTF extension is required by this tileset; otherwise, <code>false</code>.
+ *
+ * @private
+ */
+Cesium3DTileset.prototype.isGltfExtensionRequired = function (
+  gltfExtensionName,
+) {
+  if (this.isGltfExtensionUsed(gltfExtensionName)) {
+    const extensionsRequired =
+      this.extensions["3DTILES_content_gltf"].extensionsRequired;
+
+    if (!defined(extensionsRequired)) {
+      return false;
+    }
+
+    return extensionsRequired.indexOf(gltfExtensionName) > -1;
+  }
+
+  return false;
+};
+
 /**
  * Optimization option. Used as a callback when {@link Cesium3DTileset#foveatedScreenSpaceError} is true to control how much to raise the screen space error for tiles outside the foveated cone,
  * interpolating between {@link Cesium3DTileset#foveatedMinimumScreenSpaceErrorRelaxation} and {@link Cesium3DTileset#maximumScreenSpaceError}.