@cesium/engine 17.0.0 → 18.0.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.
@@ -347,6 +349,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 +1153,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>
@@ -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);
 };
 

package/Source/Scene/GlobeSurfaceShaderSet.js

@@ -409,17 +409,16 @@ GlobeSurfaceShaderSet.prototype.getShaderProgram = function (options) {
             u_dayTextureTexCoordsRectangle[${i}],\n\
             u_dayTextureTranslationAndScale[${i}],\n\
             ${applyAlpha ? `u_dayTextureAlpha[${i}]` : "1.0"},\n\
-            ${applyDayNightAlpha ? `u_dayTextureNightAlpha[${i}]` : "1.0"},\n${
-              applyDayNightAlpha ? `u_dayTextureDayAlpha[${i}]` : "1.0"
-            },\n${applyBrightness ? `u_dayTextureBrightness[${i}]` : "0.0"},\n\
+            ${applyDayNightAlpha ? `u_dayTextureNightAlpha[${i}]` : "1.0"},\n\
+            ${applyDayNightAlpha ? `u_dayTextureDayAlpha[${i}]` : "1.0"},\n\
+            ${applyBrightness ? `u_dayTextureBrightness[${i}]` : "0.0"},\n\
             ${applyContrast ? `u_dayTextureContrast[${i}]` : "0.0"},\n\
             ${applyHue ? `u_dayTextureHue[${i}]` : "0.0"},\n\
             ${applySaturation ? `u_dayTextureSaturation[${i}]` : "0.0"},\n\
             ${applyGamma ? `u_dayTextureOneOverGamma[${i}]` : "0.0"},\n\
             ${applySplit ? `u_dayTextureSplit[${i}]` : "0.0"},\n\
             ${colorToAlpha ? `u_colorsToAlpha[${i}]` : "vec4(0.0)"},\n\
-        nightBlend\
-        );\n`;
+            nightBlend\);\n`;
       if (hasImageryLayerCutout) {
         computeDayColor +=
           "\

package/Source/Scene/ImageryLayer.js

@@ -127,7 +127,7 @@ import TileImagery from "./TileImagery.js";
 
 /**
  * An imagery layer that displays tiled image data from a single imagery provider
- * on a {@link Globe}.
+ * on a {@link Globe} or {@link Cesium3DTileset}.
  *
  * @alias ImageryLayer
  * @constructor
@@ -135,8 +135,10 @@ import TileImagery from "./TileImagery.js";
  * @param {ImageryProvider} [imageryProvider] The imagery provider to use.
  * @param {ImageryLayer.ConstructorOptions} [options] An object describing initialization options
  *
- * @see ImageryLayer.fromProviderAsync
- * @see ImageryLayer.fromWorldImagery
+ * @see {@link ImageryLayer.fromProviderAsync} for creating an imagery layer from an asynchronous imagery provider.
+ * @see {@link ImageryLayer.fromWorldImagery} for creating an imagery layer for Cesium ion's default global base imagery layer.
+ * @see {@link Scene#imageryLayers} for adding an imagery layer to the globe.
+ * @see {@link Cesium3DTileset#imageryLayers} for adding an imagery layer to a 3D tileset.
  *
  * @example
  * // Add an OpenStreetMaps layer
@@ -155,6 +157,19 @@ import TileImagery from "./TileImagery.js";
  * const imageryLayer = Cesium.ImageryLayer.fromProviderAsync(Cesium.IonImageryProvider.fromAssetId(3812));
  * imageryLayer.alpha = 0.5;
  * scene.imageryLayers.add(imageryLayer);
+ *
+ * @example
+ * // Drape Bing Maps Aerial imagery over a 3D tileset
+ * const tileset = await Cesium.Cesium3DTileset.fromUrl(
+ *   "http://localhost:8002/tilesets/Seattle/tileset.json"
+ * );
+ * scene.primitives.add(tileset);
+ *
+ * const imageryProvider = await Cesium.createWorldImageryAsync({
+ *   style: Cesium.IonWorldImageryStyle.AERIAL,
+ * });
+ * const imageryLayer = new ImageryLayer(imageryProvider);
+ * tileset.imageryLayers.add(imageryLayer);
  */
 function ImageryLayer(imageryProvider, options) {
   this._imageryProvider = imageryProvider;
@@ -663,7 +678,7 @@ ImageryLayer.prototype.getImageryRectangle = function () {
  *
  * @private
  *
- * @param {Tile} tile The terrain tile.
+ * @param {QuadtreeTile} tile The terrain tile.
  * @param {TerrainProvider|undefined} terrainProvider The terrain provider associated with the terrain tile.
  * @param {number} insertionPoint The position to insert new skeletons before in the tile's imagery list.
  * @returns {boolean} true if this layer overlaps any portion of the terrain tile; otherwise, false.

package/Source/Scene/ImageryLayerCollection.js

@@ -7,11 +7,12 @@ import Rectangle from "../Core/Rectangle.js";
 import ImageryLayer from "./ImageryLayer.js";
 
 /**
- * An ordered collection of imagery layers.
+ * An ordered collection of imagery layers for rendering raster imagery on a {@link Globe} or {@link Cesium3DTileset}.
  *
  * @alias ImageryLayerCollection
  * @constructor
- *
+ * @see {@link Scene#imageryLayers} for manipulating imagery layers on the globe.
+ * @see {@link Cesium3DTileset#imageryLayers} for manipulating imagery layers on a 3D tileset.
  * @demo {@link https://sandcastle.cesium.com/index.html?src=Imagery%20Adjustment.html|Cesium Sandcastle Imagery Adjustment Demo}
  * @demo {@link https://sandcastle.cesium.com/index.html?src=Imagery%20Layers%20Manipulation.html|Cesium Sandcastle Imagery Manipulation Demo}
  */

package/Source/Scene/Model/CartesianRectangle.js

@@ -0,0 +1,108 @@
+/**
+ * Internal class for texture coordinate and index range computations.
+ *
+ * @private
+ */
+class CartesianRectangle {
+  /**
+   * Creates a new instance
+   *
+   * @param {number} [minX=0] The minimum x-coordinate
+   * @param {number} [minY=0] The minimum y-coordinate
+   * @param {number} [maxX=0] The maximum x-coordinate
+   * @param {number} [maxY=0] The maximum y-coordinate
+   */
+  constructor(minX, minY, maxX, maxY) {
+    this._minX = minX ?? 0.0;
+    this._minY = minY ?? 0.0;
+    this._maxX = maxX ?? 0.0;
+    this._maxY = maxY ?? 0.0;
+  }
+
+  /**
+   * Returns the minimum x-coordinate
+   *
+   * @returns {number} The coordinate
+   */
+  get minX() {
+    return this._minX;
+  }
+  set minX(value) {
+    this._minX = value;
+  }
+
+  /**
+   * Returns the minimum y-coordinate
+   *
+   * @returns {number} The coordinate
+   */
+  get minY() {
+    return this._minY;
+  }
+  set minY(value) {
+    this._minY = value;
+  }
+
+  /**
+   * Returns the maximum x-coordinate
+   *
+   * @returns {number} The coordinate
+   */
+  get maxX() {
+    return this._maxX;
+  }
+  set maxX(value) {
+    this._maxX = value;
+  }
+
+  /**
+   * Returns the maximum y-coordinate
+   *
+   * @returns {number} The coordinate
+   */
+  get maxY() {
+    return this._maxY;
+  }
+  set maxY(value) {
+    this._maxY = value;
+  }
+
+  /**
+   * Returns whether this rectangle contains the given coordinates,
+   * using the default containment check, which includes the
+   * minimum point, but excludes the maximum point
+   *
+   * @param {number} x The x-coordinate
+   * @param {number} y The y-coordinate
+   * @returns {boolean} The result
+   */
+  contains(x, y) {
+    return x >= this.minX && x < this.maxX && y >= this.minY && y < this.maxY;
+  }
+
+  /**
+   * Returns whether this rectangle contains the given coordinates,
+   * excluding the border
+   *
+   * @param {number} x The x-coordinate
+   * @param {number} y The y-coordinate
+   * @returns {boolean} The result
+   */
+  containsExclusive(x, y) {
+    return x > this.minX && x < this.maxX && y > this.minY && y < this.maxY;
+  }
+
+  /**
+   * Returns whether this rectangle contains the given coordinates,
+   * including the border
+   *
+   * @param {number} x The x-coordinate
+   * @param {number} y The y-coordinate
+   * @returns {boolean} The result
+   */
+  containsInclusive(x, y) {
+    return x >= this.minX && x <= this.maxX && y >= this.minY && y <= this.maxY;
+  }
+}
+
+export default CartesianRectangle;

package/Source/Scene/Model/ImageryConfiguration.js

@@ -0,0 +1,25 @@
+/**
+ * A class containing a the values that affect the appearance of
+ * an <code>ImageryLayer</code>.
+ *
+ * This is used in the <code>ModelImagery</code> to detect changes in
+ * the imagery settings: The <code>ModelImagery</code> stores one
+ * instance per imagery layer. During the <code>update</code>
+ * call, it checks whether any of the settings was changed.
+ * If this is the case, the draw commands of the model are reset.
+ *
+ * @private
+ */
+class ImageryConfiguration {
+  constructor(imageryLayer) {
+    this.alpha = imageryLayer.alpha;
+    this.brightness = imageryLayer.brightness;
+    this.contrast = imageryLayer.contrast;
+    this.hue = imageryLayer.hue;
+    this.saturation = imageryLayer.saturation;
+    this.gamma = imageryLayer.gamma;
+    this.colorToAlpha = imageryLayer.colorToAlpha;
+  }
+}
+
+export default ImageryConfiguration;