@cesium/engine 9.0.0 → 9.1.0

package/Source/Scene/Cesium3DTile.js

@@ -411,6 +411,16 @@ function Cesium3DTile(tileset, baseResource, header, parent) {
    */
   this.clippingPlanesDirty = false;
 
+  /**
+   * Tracks if the tile's relationship with a ClippingPolygonCollection has changed with regards
+   * to the ClippingPolygonCollection's state.
+   *
+   * @type {boolean}
+   *
+   * @private
+   */
+  this.clippingPolygonsDirty = false;
+
   /**
    * Tracks if the tile's request should be deferred until all non-deferred
    * tiles load.
@@ -481,7 +491,9 @@ function Cesium3DTile(tileset, baseResource, header, parent) {
   this._refines = false;
   this._shouldSelect = false;
   this._isClipped = true;
+  this._isClippedByPolygon = false;
   this._clippingPlanesState = 0; // encapsulates (_isClipped, clippingPlanes.enabled) and number/function
+  this._clippingPolygonsState = 0; // encapsulates (_isClipped, clippingPolygons.enabled) and number/function
   this._debugBoundingVolume = undefined;
   this._debugContentBoundingVolume = undefined;
   this._debugViewerRequestVolume = undefined;
@@ -1418,6 +1430,8 @@ Cesium3DTile.prototype.unloadContent = function () {
   this.lastStyleTime = 0.0;
   this.clippingPlanesDirty = this._clippingPlanesState === 0;
   this._clippingPlanesState = 0;
+  this.clippingPolygonsDirty = this._clippingPolygonsState === 0;
+  this._clippingPolygonsState = 0;
 
   this._debugColorizeTiles = false;
 
@@ -1516,6 +1530,17 @@ Cesium3DTile.prototype.visibility = function (
     }
   }
 
+  const clippingPolygons = tileset.clippingPolygons;
+  if (defined(clippingPolygons) && clippingPolygons.enabled) {
+    const intersection = clippingPolygons.computeIntersectionWithBoundingVolume(
+      boundingVolume
+    );
+
+    this._isClippedByPolygon = intersection !== Intersect.OUTSIDE;
+    // Polygon clipping intersections are determined by outer rectangles, therefore we cannot
+    // preemptively determine if a tile is completely clipped or not here.
+  }
+
   return cullingVolume.computeVisibilityWithPlaneMask(
     boundingVolume,
     parentVisibilityPlaneMask
@@ -1562,6 +1587,17 @@ Cesium3DTile.prototype.contentVisibility = function (frameState) {
     }
   }
 
+  const clippingPolygons = tileset.clippingPolygons;
+  if (defined(clippingPolygons) && clippingPolygons.enabled) {
+    const intersection = clippingPolygons.computeIntersectionWithBoundingVolume(
+      boundingVolume
+    );
+    this._isClippedByPolygon = intersection !== Intersect.OUTSIDE;
+    if (intersection === Intersect.INSIDE) {
+      return Intersect.OUTSIDE;
+    }
+  }
+
   return cullingVolume.computeVisibility(boundingVolume);
 };
 
@@ -2150,6 +2186,33 @@ function updateClippingPlanes(tile, tileset) {
   }
 }
 
+/**
+ * Compute and compare ClippingPolygons state:
+ *  - enabled-ness - are clipping polygons enabled? is this tile clipped?
+ *  - clipping polygon count & position count
+ *  - clipping function (inverse)
+
+ * @private
+ * @param {Cesium3DTile} tile
+ * @param {Cesium3DTileset} tileset
+ */
+function updateClippingPolygons(tile, tileset) {
+  const clippingPolygons = tileset.clippingPolygons;
+  let currentClippingPolygonsState = 0;
+  if (
+    defined(clippingPolygons) &&
+    tile._isClippedByPolygon &&
+    clippingPolygons.enabled
+  ) {
+    currentClippingPolygonsState = clippingPolygons.clippingPolygonsState;
+  }
+  // If clippingPolygonState for tile changed, mark clippingPolygonsDirty so content can update
+  if (currentClippingPolygonsState !== tile._clippingPolygonsState) {
+    tile._clippingPolygonsState = currentClippingPolygonsState;
+    tile.clippingPolygonsDirty = true;
+  }
+}
+
 /**
  * Get the draw commands needed to render this tile.
  *
@@ -2163,6 +2226,7 @@ Cesium3DTile.prototype.update = function (tileset, frameState, passOptions) {
   const commandStart = commandList.length;
 
   updateClippingPlanes(this, tileset);
+  updateClippingPolygons(this, tileset);
   applyDebugSettings(this, tileset, frameState, passOptions);
   updateContent(this, tileset, frameState);
 
@@ -2176,6 +2240,7 @@ Cesium3DTile.prototype.update = function (tileset, frameState, passOptions) {
   }
 
   this.clippingPlanesDirty = false; // reset after content update
+  this.clippingPolygonsDirty = false;
 };
 
 const scratchCommandList = [];

package/Source/Scene/Cesium3DTileset.js

@@ -41,6 +41,7 @@ import Cesium3DTilesetHeatmap from "./Cesium3DTilesetHeatmap.js";
 import Cesium3DTilesetStatistics from "./Cesium3DTilesetStatistics.js";
 import Cesium3DTileStyleEngine from "./Cesium3DTileStyleEngine.js";
 import ClippingPlaneCollection from "./ClippingPlaneCollection.js";
+import ClippingPolygonCollection from "./ClippingPolygonCollection.js";
 import hasExtension from "./hasExtension.js";
 import ImplicitTileset from "./ImplicitTileset.js";
 import ImplicitTileCoordinates from "./ImplicitTileCoordinates.js";
@@ -97,6 +98,7 @@ import Ray from "../Core/Ray.js";
  * @property {boolean} [immediatelyLoadDesiredLevelOfDetail=false] When <code>skipLevelOfDetail</code> is <code>true</code>, only tiles that meet the maximum screen space error will ever be downloaded. Skipping factors are ignored and just the desired tiles are loaded.
  * @property {boolean} [loadSiblings=false] When <code>skipLevelOfDetail</code> is <code>true</code>, determines whether siblings of visible tiles are always downloaded during traversal.
  * @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 {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.
@@ -800,7 +802,22 @@ function Cesium3DTileset(options) {
   this.loadSiblings = defaultValue(options.loadSiblings, false);
 
   this._clippingPlanes = undefined;
-  this.clippingPlanes = options.clippingPlanes;
+  if (defined(options.clippingPlanes)) {
+    ClippingPlaneCollection.setOwner(
+      options.clippingPlanes,
+      this,
+      "_clippingPlanes"
+    );
+  }
+
+  this._clippingPolygons = undefined;
+  if (defined(options.clippingPolygons)) {
+    ClippingPolygonCollection.setOwner(
+      options.clippingPolygons,
+      this,
+      "_clippingPolygons"
+    );
+  }
 
   if (defined(options.imageBasedLighting)) {
     this._imageBasedLighting = options.imageBasedLighting;
@@ -1120,6 +1137,22 @@ Object.defineProperties(Cesium3DTileset.prototype, {
     },
   },
 
+  /**
+   * The {@link ClippingPolygonCollection} used to selectively disable rendering the tileset.
+   *
+   * @memberof Cesium3DTileset.prototype
+   *
+   * @type {ClippingPolygonCollection}
+   */
+  clippingPolygons: {
+    get: function () {
+      return this._clippingPolygons;
+    },
+    set: function (value) {
+      ClippingPolygonCollection.setOwner(value, this, "_clippingPolygons");
+    },
+  },
+
   /**
    * Gets the tileset's properties dictionary object, which contains metadata about per-feature properties.
    * <p>
@@ -2519,6 +2552,12 @@ Cesium3DTileset.prototype.prePassesUpdate = function (frameState) {
     clippingPlanes.update(frameState);
   }
 
+  // Update clipping polygons
+  const clippingPolygons = this._clippingPolygons;
+  if (defined(clippingPolygons) && clippingPolygons.enabled) {
+    clippingPolygons.update(frameState);
+  }
+
   if (!defined(this._loadTimestamp)) {
     this._loadTimestamp = JulianDate.clone(frameState.time);
   }
@@ -3372,6 +3411,12 @@ Cesium3DTileset.prototype.updateForPass = function (
     originalCullingVolume
   );
 
+  // Update clipping polygons
+  const clippingPolygons = this._clippingPolygons;
+  if (defined(clippingPolygons) && clippingPolygons.enabled) {
+    clippingPolygons.queueCommands(frameState);
+  }
+
   const passStatistics = this._statisticsPerPass[pass];
 
   if (this.show || ignoreCommands) {
@@ -3440,6 +3485,8 @@ Cesium3DTileset.prototype.destroy = function () {
   this._tileDebugLabels =
     this._tileDebugLabels && this._tileDebugLabels.destroy();
   this._clippingPlanes = this._clippingPlanes && this._clippingPlanes.destroy();
+  this._clippingPolygons =
+    this._clippingPolygons && this._clippingPolygons.destroy();
 
   // Traverse the tree and destroy all tiles
   if (defined(this._root)) {

package/Source/Scene/ClippingPolygon.js

@@ -0,0 +1,212 @@
+import Check from "../Core/Check.js";
+import Cartesian3 from "../Core/Cartesian3.js";
+import Cartographic from "../Core/Cartographic.js";
+import defaultValue from "../Core/defaultValue.js";
+import defined from "../Core/defined.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";
+
+/**
+ * A geodesic polygon to be used with {@link ClippingPlaneCollection} for selectively hiding regions in a model, a 3D tileset, or the globe.
+ * @alias ClippingPolygon
+ * @constructor
+ *
+ * @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 {Ellipsoid} [options.ellipsoid=Ellipsoid.WGS84]
+ *
+ * @example
+ * const positions = Cesium.Cartesian3.fromRadiansArray([
+ *     -1.3194369277314022,
+ *     0.6988062530900625,
+ *     -1.31941,
+ *     0.69879,
+ *     -1.3193955980204217,
+ *     0.6988091578771254,
+ *     -1.3193931220959367,
+ *     0.698743632490865,
+ *     -1.3194358224045408,
+ *     0.6987471965556998,
+ * ]);
+ *
+ * const polygon = new Cesium.ClippingPolygon({
+ *     positions: positions
+ * });
+ */
+function ClippingPolygon(options) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("options", options);
+  Check.typeOf.object("options.positions", options.positions);
+  Check.typeOf.number.greaterThanOrEquals(
+    "options.positions.length",
+    options.positions.length,
+    3
+  );
+  //>>includeEnd('debug');
+
+  this._ellipsoid = defaultValue(options.ellipsoid, Ellipsoid.WGS84);
+  this._positions = [...options.positions];
+}
+
+Object.defineProperties(ClippingPolygon.prototype, {
+  /**
+   * Returns the total number of positions in the polygon, include any holes.
+   *
+   * @memberof ClippingPolygon.prototype
+   * @type {number}
+   * @readonly
+   */
+  length: {
+    get: function () {
+      return this._positions.length;
+    },
+  },
+  /**
+   * Returns the outer ring of positions.
+   *
+   * @memberof ClippingPolygon.prototype
+   * @type {Cartesian3[]}
+   * @readonly
+   */
+  positions: {
+    get: function () {
+      return this._positions;
+    },
+  },
+  /**
+   * Returns the ellipsoid used to project the polygon onto surfaces when clipping.
+   *
+   * @memberof ClippingPolygon.prototype
+   * @type {Ellipsoid}
+   * @readonly
+   */
+  ellipsoid: {
+    get: function () {
+      return this._ellipsoid;
+    },
+  },
+});
+
+/**
+ * Clones the ClippingPolygon without setting its ownership.
+ * @param {ClippingPolygon} polygon The ClippingPolygon to be cloned
+ * @param {ClippingPolygon} [result] The object on which to store the cloned parameters.
+ * @returns {ClippingPolygon} a clone of the input ClippingPolygon
+ */
+ClippingPolygon.clone = function (polygon, result) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("polygon", polygon);
+  //>>includeEnd('debug');
+
+  if (!defined(result)) {
+    return new ClippingPolygon({
+      positions: polygon.positions,
+      ellipsoid: polygon.ellipsoid,
+    });
+  }
+
+  result._ellipsoid = polygon.ellipsoid;
+  result._positions.length = 0;
+  result._positions.push(...polygon.positions);
+  return result;
+};
+
+/**
+ * Compares the provided ClippingPolygons and returns
+ * <code>true</code> if they are equal, <code>false</code> otherwise.
+ *
+ * @param {Plane} left The first polygon.
+ * @param {Plane} right The second polygon.
+ * @returns {boolean} <code>true</code> if left and right are equal, <code>false</code> otherwise.
+ */
+ClippingPolygon.equals = function (left, right) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.typeOf.object("left", left);
+  Check.typeOf.object("right", right);
+  //>>includeEnd('debug');
+
+  return (
+    left.ellipsoid.equals(right.ellipsoid) && left.positions === right.positions
+  );
+};
+
+/**
+ * Computes a cartographic rectangle which encloses the polygon defined by the list of positions, including cases over the international date line and the poles.
+ *
+ * @param {Rectangle} [result] An object in which to store the result.
+ * @returns {Rectangle} The result rectangle
+ */
+ClippingPolygon.prototype.computeRectangle = function (result) {
+  return PolygonGeometry.computeRectangleFromPositions(
+    this.positions,
+    this.ellipsoid,
+    undefined,
+    result
+  );
+};
+
+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.
+ */
+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
+  );
+
+  result.north = sphereLatitude;
+  result.east = sphereLongitude;
+
+  return result;
+};
+
+export default ClippingPolygon;