@cesium/engine 26.1.0 → 26.3.0

package/Source/Scene/Cesium3DTile.js

@@ -438,6 +438,16 @@ function Cesium3DTile(tileset, baseResource, header, parent) {
    */
   this.clippingPolygonsDirty = false;
 
+  /**
+   * Tracks if the tileset's ClippingPolygonCollection's geometry changed (a polygon was added or removed),
+   * which requires the tile's content to rebake its clipping textures.
+   *
+   * @type {boolean}
+   *
+   * @private
+   */
+  this.clippingPolygonsNeedRebake = false;
+
   /**
    * Tracks if the tile's request should be deferred until all non-deferred
    * tiles load.
@@ -1483,6 +1493,7 @@ Cesium3DTile.prototype.unloadContent = function () {
   this._clippingPlanesState = 0;
   this.clippingPolygonsDirty = this._clippingPolygonsState === 0;
   this._clippingPolygonsState = 0;
+  this.clippingPolygonsNeedRebake = false;
 
   this._debugColorizeTiles = false;
 
@@ -2315,6 +2326,7 @@ Cesium3DTile.prototype.update = function (tileset, frameState, passOptions) {
 
   this.clippingPlanesDirty = false; // reset after content update
   this.clippingPolygonsDirty = false;
+  this.clippingPolygonsNeedRebake = false;
 };
 
 const scratchCommandList = [];

package/Source/Scene/Cesium3DTileset.js

@@ -11,6 +11,7 @@ import Frozen from "../Core/Frozen.js";
 import defined from "../Core/defined.js";
 import deprecationWarning from "../Core/deprecationWarning.js";
 import destroyObject from "../Core/destroyObject.js";
+import DeveloperError from "../Core/DeveloperError.js";
 import Ellipsoid from "../Core/Ellipsoid.js";
 import Event from "../Core/Event.js";
 import ImageBasedLighting from "./ImageBasedLighting.js";
@@ -44,6 +45,7 @@ import ClippingPlaneCollection from "./ClippingPlaneCollection.js";
 import ClippingPolygonCollection from "./ClippingPolygonCollection.js";
 import EdgeDisplayMode from "./EdgeDisplayMode.js";
 import hasExtension from "./hasExtension.js";
+import { isHeightReferenceClamp } from "./HeightReference.js";
 import ImplicitTileset from "./ImplicitTileset.js";
 import ImplicitTileCoordinates from "./ImplicitTileCoordinates.js";
 import LabelCollection from "./LabelCollection.js";
@@ -103,7 +105,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.
@@ -153,6 +155,7 @@ import ImageryLayerCollection from "./ImageryLayerCollection.js";
  * @param {Cesium3DTileset.ConstructorOptions} options An object describing initialization options
  *
  * @exception {DeveloperError} The tileset must be 3D Tiles version 0.0 or 1.0.
+ * @exception {DeveloperError} Height reference is not supported without a scene.
  *
  * @example
  * try {
@@ -343,6 +346,14 @@ function Cesium3DTileset(options) {
   this._heightReference = options.heightReference;
   this._scene = options.scene;
 
+  //>>includeStart('debug', pragmas.debug);
+  if (isHeightReferenceClamp(this._heightReference) && !defined(this._scene)) {
+    throw new DeveloperError(
+      "Height reference is not supported without a scene.",
+    );
+  }
+  //>>includeEnd('debug');
+
   this._ellipsoid = options.ellipsoid ?? Ellipsoid.WGS84;
 
   this._initialClippingPlanesOriginMatrix = Matrix4.IDENTITY; // Computed from the tileset JSON.
@@ -856,12 +867,16 @@ function Cesium3DTileset(options) {
   }
 
   this._clippingPolygons = undefined;
+  this._clippingPolygonsNeedRebake = false;
+  this._removeClippingPolygonAdded = undefined;
+  this._removeClippingPolygonRemoved = undefined;
   if (defined(options.clippingPolygons)) {
     ClippingPolygonCollection.setOwner(
       options.clippingPolygons,
       this,
       "_clippingPolygons",
     );
+    updateTilesetClippingPolygonListeners(this);
   }
 
   if (defined(options.imageBasedLighting)) {
@@ -1193,6 +1208,8 @@ Object.defineProperties(Cesium3DTileset.prototype, {
     },
     set: function (value) {
       ClippingPolygonCollection.setOwner(value, this, "_clippingPolygons");
+      updateTilesetClippingPolygonListeners(this);
+      this._clippingPolygonsNeedRebake = true;
     },
   },
 
@@ -2693,6 +2710,34 @@ Cesium3DTileset.prototype.postPassesUpdate = function (frameState) {
   this._styleApplied = false;
 };
 
+/**
+ * Subscribes the owning tileset to its clipping polygon add/remove events so
+ * tile content can rebake clipping textures when the geometry changes.
+ * @private
+ * @param {Cesium3DTileset} tileset
+ */
+function updateTilesetClippingPolygonListeners(tileset) {
+  tileset._removeClippingPolygonAdded =
+    tileset._removeClippingPolygonAdded &&
+    tileset._removeClippingPolygonAdded();
+  tileset._removeClippingPolygonRemoved =
+    tileset._removeClippingPolygonRemoved &&
+    tileset._removeClippingPolygonRemoved();
+
+  const clippingPolygons = tileset._clippingPolygons;
+  if (!defined(clippingPolygons)) {
+    return;
+  }
+
+  const markDirty = () => {
+    tileset._clippingPolygonsNeedRebake = true;
+  };
+  tileset._removeClippingPolygonAdded =
+    clippingPolygons.polygonAdded.addEventListener(markDirty);
+  tileset._removeClippingPolygonRemoved =
+    clippingPolygons.polygonRemoved.addEventListener(markDirty);
+}
+
 /**
  * Perform any pass invariant tasks here. Called before any passes are executed.
  * @ignore
@@ -2718,6 +2763,15 @@ Cesium3DTileset.prototype.prePassesUpdate = function (frameState) {
     clippingPolygons.update(frameState);
   }
 
+  // After a polygon add/remove, mark loaded tiles so their content rebakes
+  // clipping textures. Done once per frame to dedupe multiple changes.
+  if (this._clippingPolygonsNeedRebake) {
+    this._clippingPolygonsNeedRebake = false;
+    this._cache.forEachLoadedTile((tile) => {
+      tile.clippingPolygonsNeedRebake = true;
+    });
+  }
+
   if (!defined(this._loadTimestamp)) {
     this._loadTimestamp = JulianDate.clone(frameState.time);
   }
@@ -3579,12 +3633,6 @@ Cesium3DTileset.prototype.updateForPass = function (
     environmentMapManager.update(frameState);
   }
 
-  // Update clipping polygons
-  const clippingPolygons = this._clippingPolygons;
-  if (defined(clippingPolygons) && clippingPolygons.enabled) {
-    clippingPolygons.queueCommands(frameState);
-  }
-
   const passStatistics = this._statisticsPerPass[pass];
 
   if (this.show || ignoreCommands) {
@@ -3652,9 +3700,14 @@ Cesium3DTileset.prototype.isDestroyed = function () {
 Cesium3DTileset.prototype.destroy = function () {
   this._tileDebugLabels =
     this._tileDebugLabels && this._tileDebugLabels.destroy();
+
+  this._removeClippingPolygonAdded =
+    this._removeClippingPolygonAdded && this._removeClippingPolygonAdded();
+  this._removeClippingPolygonRemoved =
+    this._removeClippingPolygonRemoved && this._removeClippingPolygonRemoved();
+
   this._clippingPlanes = this._clippingPlanes && this._clippingPlanes.destroy();
-  this._clippingPolygons =
-    this._clippingPolygons && this._clippingPolygons.destroy();
+  this._clippingPolygons = undefined;
 
   // Traverse the tree and destroy all tiles
   if (defined(this._root)) {

package/Source/Scene/Cesium3DTilesetBaseTraversal.js

@@ -247,6 +247,13 @@ function executeTraversal(root, frameState) {
 function executeEmptyTraversal(root, frameState) {
   const { canTraverse, updateTile, loadTile, touchTile } =
     Cesium3DTilesetTraversal;
+  // Vector tilesets opt into relaxed empty-tile refinement so empty regions reached
+  // through implicit or external placeholders do not block their content siblings.
+  // Note: it's likely we don't need to limit this behavior to vector tilesets. However,
+  // we are being cautious of breaking changes to existing tilesets.
+  const isVectorTileset = root.tileset.hasExtension(
+    "3DTILES_content_gltf_vector",
+  );
   let allDescendantsLoaded = true;
   const stack = emptyTraversal.stack;
   stack.push(root);
@@ -264,9 +271,14 @@ function executeEmptyTraversal(root, frameState) {
     // Only traverse if the tile is empty - traversal stops at descendants with content
     const traverse = !tile.hasRenderableContent && canTraverse(tile);
 
-    // Traversal stops but the tile does not have content yet
-    // There will be holes if the parent tries to refine to its children, so don't refine
-    if (!traverse && !tile.contentAvailable) {
+    // For vector tilesets only unloaded renderable content blocks refinement, so an empty
+    // tile at its resolved level of detail does not hold back its content siblings,
+    // including across implicit or external placeholders. All other tilesets keep the
+    // original behavior of blocking whenever traversal stops without content available.
+    const blocksRefinement = isVectorTileset
+      ? tile.hasRenderableContent
+      : !traverse;
+    if (blocksRefinement && !tile.contentAvailable) {
       allDescendantsLoaded = false;
     }
 

package/Source/Scene/Cesium3DTilesetCache.js

@@ -34,6 +34,21 @@ Cesium3DTilesetCache.prototype.add = function (tile) {
   }
 };
 
+/**
+ * Invokes the callback for each tile with loaded content in the cache.
+ *
+ * @param {Function} callback A function that takes a {@link Cesium3DTile}.
+ * @private
+ */
+Cesium3DTilesetCache.prototype.forEachLoadedTile = function (callback) {
+  for (let node = this._list.head; defined(node); node = node.next) {
+    // The sentinel node has no item.
+    if (defined(node.item)) {
+      callback(node.item);
+    }
+  }
+};
+
 Cesium3DTilesetCache.prototype.unloadTile = function (
   tileset,
   tile,

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);

package/Source/Scene/ClippingPolygon.js

@@ -1,9 +1,8 @@
 import Check from "../Core/Check.js";
 import Cartesian3 from "../Core/Cartesian3.js";
-import Cartographic from "../Core/Cartographic.js";
 import defined from "../Core/defined.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 import Ellipsoid from "../Core/Ellipsoid.js";
-import CesiumMath from "../Core/Math.js";
 import PolygonGeometry from "../Core/PolygonGeometry.js";
 import Rectangle from "../Core/Rectangle.js";
 
@@ -14,6 +13,7 @@ import Rectangle from "../Core/Rectangle.js";
  *
  * @param {object} options Object with the following properties:
  * @param {Cartesian3[]} options.positions A list of three or more Cartesian coordinates defining the outer ring of the clipping polygon.
+ * @param {Cartesian3[][]} [options.holes] An array of interior rings (holes), each a list of three or more Cartesian coordinates. Regions inside a hole are excluded from the polygon.
  * @param {Ellipsoid} [options.ellipsoid=Ellipsoid.default]
  *
  * @example
@@ -33,6 +33,34 @@ import Rectangle from "../Core/Rectangle.js";
  * const polygon = new Cesium.ClippingPolygon({
  *     positions: positions
  * });
+ *
+ * @example
+ * // A clipping polygon with two holes. Regions inside the holes are not clipped.
+ * const outerRing = Cesium.Cartesian3.fromDegreesArray([
+ *     -100.0, 40.0,
+ *     -90.0, 40.0,
+ *     -90.0, 50.0,
+ *     -100.0, 50.0,
+ * ]);
+ *
+ * const firstHole = Cesium.Cartesian3.fromDegreesArray([
+ *     -98.0, 42.0,
+ *     -96.0, 42.0,
+ *     -96.0, 44.0,
+ *     -98.0, 44.0,
+ * ]);
+ *
+ * const secondHole = Cesium.Cartesian3.fromDegreesArray([
+ *     -94.0, 46.0,
+ *     -92.0, 46.0,
+ *     -92.0, 48.0,
+ *     -94.0, 48.0,
+ * ]);
+ *
+ * const polygonWithHoles = new Cesium.ClippingPolygon({
+ *     positions: outerRing,
+ *     holes: [firstHole, secondHole],
+ * });
  */
 function ClippingPolygon(options) {
   //>>includeStart('debug', pragmas.debug);
@@ -43,35 +71,38 @@ function ClippingPolygon(options) {
     options.positions.length,
     3,
   );
+  if (defined(options.holes)) {
+    for (let i = 0; i < options.holes.length; i++) {
+      Check.typeOf.number.greaterThanOrEquals(
+        `options.holes[${i}].length`,
+        options.holes[i].length,
+        3,
+      );
+    }
+  }
   //>>includeEnd('debug');
 
   this._ellipsoid = options.ellipsoid ?? Ellipsoid.default;
   this._positions = copyArrayCartesian3(options.positions);
+  this._holes = defined(options.holes)
+    ? options.holes.map(copyArrayCartesian3)
+    : [];
 
   /**
-   * A copy of the input positions.
-   *
-   * This is used to detect modifications of the positions in
-   * <code>coputeRectangle</code>: The rectangle only has
-   * to be re-computed when these positions have changed.
+   * The cartographic rectangle enclosing the outer ring
    *
-   * @type {Cartesian3[]|undefined}
+   * @type {Rectangle}
    * @private
    */
-  this._cachedPositions = undefined;
+  this._rectangle = PolygonGeometry.computeRectangleFromPositions(
+    this._positions,
+    this._ellipsoid,
+  );
 
-  /**
-   * A cached version of the rectangle that is computed in
-   * <code>computeRectangle</code>.
-   *
-   * This is only re-computed when the positions have changed, as
-   * determined  by comparing the <code>_positions</code> to the
-   * <code>_cachedPositions</code>
-   *
-   * @type {Rectangle|undefined}
-   * @private
-   */
-  this._cachedRectangle = undefined;
+  // Freeze the geometry so it cannot change after construction. To change a
+  // polygon, remove it from the collection and add a new one.
+  deepFreeze(this._positions);
+  deepFreezeHoles(this._holes);
 }
 
 /**
@@ -98,6 +129,35 @@ function copyArrayCartesian3(input) {
   return output;
 }
 
+/**
+ * Freezes an array of positions and each Cartesian3 it contains, so that the
+ * polygon's geometry cannot be mutated in place. Returns the same array.
+ *
+ * @param {Cartesian3[]} positions The array to freeze
+ * @returns {Cartesian3[]} The frozen array
+ * @ignore
+ */
+function deepFreeze(positions) {
+  for (let i = 0; i < positions.length; i++) {
+    Object.freeze(positions[i]);
+  }
+  return Object.freeze(positions);
+}
+
+/**
+ * Freezes an array of rings (holes) and their contents. Returns the same array.
+ *
+ * @param {Cartesian3[][]} holes The rings to freeze
+ * @returns {Cartesian3[][]} The frozen array
+ * @ignore
+ */
+function deepFreezeHoles(holes) {
+  for (let i = 0; i < holes.length; i++) {
+    deepFreeze(holes[i]);
+  }
+  return Object.freeze(holes);
+}
+
 /**
  * Returns whether the given arrays are component-wise equal.
  *
@@ -134,9 +194,29 @@ function equalsArrayCartesian3(a, b) {
   return true;
 }
 
+/**
+ * Returns whether two arrays of rings are component-wise equal.
+ *
+ * @param {Cartesian3[][]} a The first array of rings
+ * @param {Cartesian3[][]} b The second array of rings
+ * @returns {boolean} Whether the ring arrays are equal
+ * @ignore
+ */
+function equalsHoles(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (!equalsArrayCartesian3(a[i], b[i])) {
+      return false;
+    }
+  }
+  return true;
+}
+
 Object.defineProperties(ClippingPolygon.prototype, {
   /**
-   * Returns the total number of positions in the polygon, include any holes.
+   * Returns the total number of positions in the polygon, including any holes.
    *
    * @memberof ClippingPolygon.prototype
    * @type {number}
@@ -144,11 +224,17 @@ Object.defineProperties(ClippingPolygon.prototype, {
    */
   length: {
     get: function () {
-      return this._positions.length;
+      let count = this._positions.length;
+      const holes = this._holes;
+      for (let i = 0; i < holes.length; i++) {
+        count += holes[i].length;
+      }
+      return count;
     },
   },
   /**
-   * Returns the outer ring of positions.
+   * Returns the outer ring of positions. A ClippingPolygon's geometry is
+   * immutable; the returned array and its coordinates are frozen.
    *
    * @memberof ClippingPolygon.prototype
    * @type {Cartesian3[]}
@@ -159,6 +245,18 @@ Object.defineProperties(ClippingPolygon.prototype, {
       return this._positions;
     },
   },
+  /**
+   * Returns the interior rings (holes) of the polygon, each a list of positions.
+   *
+   * @memberof ClippingPolygon.prototype
+   * @type {Cartesian3[][]}
+   * @readonly
+   */
+  holes: {
+    get: function () {
+      return this._holes;
+    },
+  },
   /**
    * Returns the ellipsoid used to project the polygon onto surfaces when clipping.
    *
@@ -171,6 +269,20 @@ Object.defineProperties(ClippingPolygon.prototype, {
       return this._ellipsoid;
     },
   },
+  /**
+   * Returns the cartographic rectangle enclosing the polygon, computed once on
+   * construction. Since a ClippingPolygon's geometry is immutable, this rectangle
+   * never changes.
+   *
+   * @memberof ClippingPolygon.prototype
+   * @type {Rectangle}
+   * @readonly
+   */
+  rectangle: {
+    get: function () {
+      return this._rectangle;
+    },
+  },
 });
 
 /**
@@ -187,13 +299,20 @@ ClippingPolygon.clone = function (polygon, result) {
   if (!defined(result)) {
     return new ClippingPolygon({
       positions: polygon.positions,
+      holes: polygon.holes,
       ellipsoid: polygon.ellipsoid,
     });
   }
 
   result._ellipsoid = polygon.ellipsoid;
-  result._positions.length = 0;
-  result._positions.push(...polygon.positions);
+  result._positions = copyArrayCartesian3(polygon.positions);
+  result._holes = polygon.holes.map(copyArrayCartesian3);
+  result._rectangle = PolygonGeometry.computeRectangleFromPositions(
+    result._positions,
+    result._ellipsoid,
+  );
+  deepFreeze(result._positions);
+  deepFreezeHoles(result._holes);
   return result;
 };
 
@@ -212,7 +331,9 @@ ClippingPolygon.equals = function (left, right) {
   //>>includeEnd('debug');
 
   return (
-    left.ellipsoid.equals(right.ellipsoid) && left.positions === right.positions
+    left.ellipsoid.equals(right.ellipsoid) &&
+    left.positions === right.positions &&
+    equalsHoles(left.holes, right.holes)
   );
 };
 
@@ -221,82 +342,15 @@ ClippingPolygon.equals = function (left, right) {
  *
  * @param {Rectangle} [result] An object in which to store the result.
  * @returns {Rectangle} The result rectangle
- */
-ClippingPolygon.prototype.computeRectangle = function (result) {
-  if (equalsArrayCartesian3(this._positions, this._cachedPositions)) {
-    return Rectangle.clone(this._cachedRectangle, result);
-  }
-  const rectangle = PolygonGeometry.computeRectangleFromPositions(
-    this.positions,
-    this.ellipsoid,
-    undefined,
-    result,
-  );
-  this._cachedPositions = copyArrayCartesian3(this._positions);
-  this._cachedRectangle = Rectangle.clone(rectangle);
-  return rectangle;
-};
-
-const scratchRectangle = new Rectangle();
-const spherePointScratch = new Cartesian3();
-/**
- * Computes a rectangle with the spherical extents that encloses the polygon defined by the list of positions, including cases over the international date line and the poles.
- *
- * @private
  *
- * @param {Rectangle} [result] An object in which to store the result.
- * @returns {Rectangle} The result rectangle with spherical extents.
+ * @deprecated This function is deprecated and will be removed in CesiumJS 1.147. Use {@link ClippingPolygon#rectangle} instead.
  */
-ClippingPolygon.prototype.computeSphericalExtents = function (result) {
-  if (!defined(result)) {
-    result = new Rectangle();
-  }
-
-  const rectangle = this.computeRectangle(scratchRectangle);
-
-  let spherePoint = Cartographic.toCartesian(
-    Rectangle.southwest(rectangle),
-    this.ellipsoid,
-    spherePointScratch,
-  );
-
-  // Project into plane with vertical for latitude
-  let magXY = Math.sqrt(
-    spherePoint.x * spherePoint.x + spherePoint.y * spherePoint.y,
-  );
-
-  // Use fastApproximateAtan2 for alignment with shader
-  let sphereLatitude = CesiumMath.fastApproximateAtan2(magXY, spherePoint.z);
-  let sphereLongitude = CesiumMath.fastApproximateAtan2(
-    spherePoint.x,
-    spherePoint.y,
-  );
-
-  result.south = sphereLatitude;
-  result.west = sphereLongitude;
-
-  spherePoint = Cartographic.toCartesian(
-    Rectangle.northeast(rectangle),
-    this.ellipsoid,
-    spherePointScratch,
-  );
-
-  // Project into plane with vertical for latitude
-  magXY = Math.sqrt(
-    spherePoint.x * spherePoint.x + spherePoint.y * spherePoint.y,
-  );
-
-  // Use fastApproximateAtan2 for alignment with shader
-  sphereLatitude = CesiumMath.fastApproximateAtan2(magXY, spherePoint.z);
-  sphereLongitude = CesiumMath.fastApproximateAtan2(
-    spherePoint.x,
-    spherePoint.y,
+ClippingPolygon.prototype.computeRectangle = function (result) {
+  deprecationWarning(
+    "ClippingPolygon.computeRectangle",
+    "ClippingPolygon.computeRectangle is deprecated as of CesiumJS 1.145 and will be removed in 1.147. Use the ClippingPolygon.rectangle property instead.",
   );
-
-  result.north = sphereLatitude;
-  result.east = sphereLongitude;
-
-  return result;
+  return Rectangle.clone(this._rectangle, result);
 };
 
 export default ClippingPolygon;