@cesium/engine 18.3.1-ion.0 → 19.0.0

package/Source/Scene/ITwinData.js

@@ -7,6 +7,7 @@ import Check from "../Core/Check.js";
 import KmlDataSource from "../DataSources/KmlDataSource.js";
 import GeoJsonDataSource from "../DataSources/GeoJsonDataSource.js";
 import DeveloperError from "../Core/DeveloperError.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 
 /**
  * Methods for loading iTwin platform data into CesiumJS
@@ -25,23 +26,40 @@ const ITwinData = {};
  * We recommend waiting 10-20 seconds and trying to load the tileset again.
  * If all exports are Invalid this will throw an error.
  *
+ * See the {@link https://developer.bentley.com/apis/mesh-export/overview/|iTwin Platform Mesh Export API documentation} for more information on request parameters
+ *
  * @example
- * const tileset = await Cesium.ITwinData.createTilesetFromIModelId(iModelId);
+ * const tileset = await Cesium.ITwinData.createTilesetFromIModelId({ iModelId });
  * if (Cesium.defined(tileset)) {
  *   viewer.scene.primitives.add(tileset);
  * }
  *
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  *
- * @param {string} iModelId The id of the iModel to load
- * @param {Cesium3DTileset.ConstructorOptions} [options] Object containing options to pass to the internally created {@link Cesium3DTileset}.
+ * @param {Object} options
+ * @param {string} options.iModelId The id of the iModel to load
+ * @param {Cesium3DTileset.ConstructorOptions} [options.tilesetOptions] Object containing options to pass to the internally created {@link Cesium3DTileset}.
+ * @param {string} [options.changesetId] The id of the changeset to load, if not provided the latest changesets will be used
  * @returns {Promise<Cesium3DTileset | undefined>} A promise that will resolve to the created 3D tileset or <code>undefined</code> if there is no completed export for the given iModel id
  *
  * @throws {RuntimeError} If all exports for the given iModel are Invalid
  * @throws {RuntimeError} If the iTwin API request is not successful
  */
-ITwinData.createTilesetFromIModelId = async function (iModelId, options) {
-  const { exports } = await ITwinPlatform.getExports(iModelId);
+ITwinData.createTilesetFromIModelId = async function (options) {
+  let internalOptions = options;
+
+  if (typeof options === "string") {
+    // the old signature was (iModelId: string, options?: Cesium3DTileset.ConstructorOptions)
+    // grab the later arguments directly instead of in the params only for this special case
+    internalOptions = { iModelId: options, tilesetOptions: arguments[1] };
+    deprecationWarning(
+      "ITwinData.createTilesetFromIModelId",
+      "The arguments signature for ITwinData functions has changed in 1.132 in favor of a single options object. Please update your code. This fallback will be removed in 1.133",
+    );
+  }
+
+  const { iModelId, changesetId, tilesetOptions } = internalOptions;
+  const { exports } = await ITwinPlatform.getExports(iModelId, changesetId);
 
   if (
     exports.length > 0 &&
@@ -72,7 +90,7 @@ ITwinData.createTilesetFromIModelId = async function (iModelId, options) {
     url: tilesetUrl,
   });
 
-  return Cesium3DTileset.fromUrl(resource, options);
+  return Cesium3DTileset.fromUrl(resource, tilesetOptions);
 };
 
 /**
@@ -84,20 +102,35 @@ ITwinData.createTilesetFromIModelId = async function (iModelId, options) {
  *
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  *
- * @param {string} iTwinId The id of the iTwin to load data from
- * @param {string} realityDataId The id of the reality data to load
- * @param {ITwinPlatform.RealityDataType} [type] The type of this reality data
- * @param {string} [rootDocument] The path of the root document for this reality data
+ * @param {Object} options
+ * @param {string} options.iTwinId The id of the iTwin to load data from
+ * @param {string} options.realityDataId The id of the reality data to load
+ * @param {ITwinPlatform.RealityDataType} [options.type] The type of this reality data
+ * @param {string} [options.rootDocument] The path of the root document for this reality data
  * @returns {Promise<Cesium3DTileset>}
  *
  * @throws {RuntimeError} if the type of reality data is not supported by this function
  */
-ITwinData.createTilesetForRealityDataId = async function (
-  iTwinId,
-  realityDataId,
-  type,
-  rootDocument,
-) {
+ITwinData.createTilesetForRealityDataId = async function (options) {
+  let internalOptions = options;
+
+  if (typeof options === "string") {
+    // the old signature was (iTwinId: string, realityDataId: string, type: RealityDataType, rootDocument: string)
+    // grab the later arguments directly instead of in the params only for this special case
+    internalOptions = {
+      iTwinId: options,
+      realityDataId: arguments[1],
+      type: arguments[2],
+      rootDocument: arguments[3],
+    };
+    deprecationWarning(
+      "ITwinData.createTilesetFromIModelId",
+      "The arguments signature for ITwinData functions has changed in 1.132 in favor of a single options object. Please update your code. This fallback will be removed in 1.133",
+    );
+  }
+  const { iTwinId, realityDataId } = internalOptions;
+  let { type, rootDocument } = internalOptions;
+
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.string("iTwinId", iTwinId);
   Check.typeOf.string("realityDataId", realityDataId);
@@ -147,20 +180,35 @@ ITwinData.createTilesetForRealityDataId = async function (
  * If the <code>type</code> or <code>rootDocument</code> are not provided this function
  * will first request the full metadata for the specified reality data to fill these values.
  *
- * @param {string} iTwinId The id of the iTwin to load data from
- * @param {string} realityDataId The id of the reality data to load
- * @param {ITwinPlatform.RealityDataType} [type] The type of this reality data
- * @param {string} [rootDocument] The path of the root document for this reality data
+ * @param {Object} options
+ * @param {string} options.iTwinId The id of the iTwin to load data from
+ * @param {string} options.realityDataId The id of the reality data to load
+ * @param {ITwinPlatform.RealityDataType} [options.type] The type of this reality data
+ * @param {string} [options.rootDocument] The path of the root document for this reality data
  * @returns {Promise<GeoJsonDataSource | KmlDataSource>}
  *
  * @throws {RuntimeError} if the type of reality data is not supported by this function
  */
-ITwinData.createDataSourceForRealityDataId = async function (
-  iTwinId,
-  realityDataId,
-  type,
-  rootDocument,
-) {
+ITwinData.createDataSourceForRealityDataId = async function (options) {
+  let internalOptions = options;
+
+  if (typeof options === "string") {
+    // the old signature was (iTwinId: string, realityDataId: string, type: RealityDataType, rootDocument: string)
+    // grab the later arguments directly instead of in the params only for this special case
+    internalOptions = {
+      iTwinId: options,
+      realityDataId: arguments[1],
+      type: arguments[2],
+      rootDocument: arguments[3],
+    };
+    deprecationWarning(
+      "ITwinData.createTilesetFromIModelId",
+      "The arguments signature for ITwinData functions has changed in 1.132 in favor of a single options object. Please update your code. This fallback will be removed in 1.133",
+    );
+  }
+  const { iTwinId, realityDataId } = internalOptions;
+  let { type, rootDocument } = internalOptions;
+
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.string("iTwinId", iTwinId);
   Check.typeOf.string("realityDataId", realityDataId);
@@ -209,16 +257,31 @@ ITwinData.createDataSourceForRealityDataId = async function (
 /**
  * Load data from the Geospatial Features API as GeoJSON.
  *
- * @param {string} iTwinId The id of the iTwin to load data from
- * @param {string} collectionId The id of the data collection to load
- * @param {number} [limit=10000] number of items per page, must be between 1 and 10,000 inclusive
+ * @param {Object} options
+ * @param {string} options.iTwinId The id of the iTwin to load data from
+ * @param {string} options.collectionId The id of the data collection to load
+ * @param {number} [options.limit=10000] number of items per page, must be between 1 and 10,000 inclusive
  * @returns {Promise<GeoJsonDataSource>}
  */
-ITwinData.loadGeospatialFeatures = async function (
-  iTwinId,
-  collectionId,
-  limit,
-) {
+ITwinData.loadGeospatialFeatures = async function (options) {
+  let internalOptions = options;
+
+  if (typeof options === "string") {
+    // the old signature was (iTwinId: string, collectionId: string, limit: number)
+    // grab the later arguments directly instead of in the params only for this special case
+    internalOptions = {
+      iTwinId: options,
+      collectionId: arguments[1],
+      limit: arguments[2],
+    };
+    deprecationWarning(
+      "ITwinData.createTilesetFromIModelId",
+      "The arguments signature for ITwinData functions has changed in 1.132 in favor of a single options object. Please update your code. This fallback will be removed in 1.133",
+    );
+  }
+
+  const { iTwinId, collectionId, limit } = internalOptions;
+
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.string("iTwinId", iTwinId);
   Check.typeOf.string("collectionId", collectionId);

package/Source/Scene/ImageBasedLighting.js

@@ -86,6 +86,7 @@ function ImageBasedLighting(options) {
 
   // Store the previous frame number to prevent redundant update calls
   this._previousFrameNumber = undefined;
+  this._previousFrameContext = undefined;
 
   // Keeps track of the last values for use during update logic
   this._previousImageBasedLightingFactor = Cartesian2.clone(
@@ -325,12 +326,15 @@ function createSpecularEnvironmentCubeMap(imageBasedLighting, context) {
 }
 
 ImageBasedLighting.prototype.update = function (frameState) {
-  if (frameState.frameNumber === this._previousFrameNumber) {
+  if (
+    frameState.frameNumber === this._previousFrameNumber &&
+    frameState.context === this._previousFrameContext
+  ) {
     return;
   }
 
   this._previousFrameNumber = frameState.frameNumber;
-  const context = frameState.context;
+  const context = (this._previousFrameContext = frameState.context);
 
   frameState.brdfLutGenerator.update(frameState);
   this._shouldRegenerateShaders = false;

package/Source/Scene/ImageryLayer.js

@@ -388,8 +388,8 @@ Object.defineProperties(ImageryLayer.prototype, {
    * Gets an event that is raised when the imagery provider encounters an asynchronous error.  By subscribing
    * to the event, you will be notified of the error and can potentially recover from it.  Event listeners
    * are passed an instance of the thrown error.
-   * @memberof Imagery.prototype
-   * @type {Event<Imagery.ErrorEventCallback>}
+   * @memberof ImageryLayer.prototype
+   * @type {Event<ImageryLayer.ErrorEventCallback>}
    * @readonly
    */
   errorEvent: {
@@ -518,7 +518,7 @@ ImageryLayer.DEFAULT_APPLY_COLOR_TO_ALPHA_THRESHOLD = 0.004;
  * viewer.imageryLayers.add(imageryLayer);
  *
  * imageryLayer.readyEvent.addEventListener(provider => {
- *   imageryLayer.provider.errorEvent.addEventListener(error => {
+ *   imageryLayer.imageryProvider.errorEvent.addEventListener(error => {
  *     alert(`Encountered an error while loading imagery tiles! ${error}`);
  *   });
  * });
@@ -527,9 +527,9 @@ ImageryLayer.DEFAULT_APPLY_COLOR_TO_ALPHA_THRESHOLD = 0.004;
  *   alert(`Encountered an error while creating an imagery layer! ${error}`);
  * });
  *
- * @see ImageryLayer.errorEvent
- * @see ImageryLayer.readyEvent
- * @see ImageryLayer.provider
+ * @see ImageryLayer#errorEvent
+ * @see ImageryLayer#readyEvent
+ * @see ImageryLayer#imageryProvider
  * @see ImageryLayer.fromWorldImagery
  */
 ImageryLayer.fromProviderAsync = function (imageryProviderPromise, options) {
@@ -576,7 +576,7 @@ ImageryLayer.fromProviderAsync = function (imageryProviderPromise, options) {
  * viewer.imageryLayers.add(imageryLayer);
  *
  * imageryLayer.readyEvent.addEventListener(provider => {
- *   imageryLayer.provider.errorEvent.addEventListener(error => {
+ *   imageryLayer.imageryProvider.errorEvent.addEventListener(error => {
  *     alert(`Encountered an error while loading imagery tiles! ${error}`);
  *   });
  * });
@@ -585,9 +585,9 @@ ImageryLayer.fromProviderAsync = function (imageryProviderPromise, options) {
  *   alert(`Encountered an error while creating an imagery layer! ${error}`);
  * });
  *
- * @see ImageryLayer.errorEvent
- * @see ImageryLayer.readyEvent
- * @see ImageryLayer.provider
+ * @see ImageryLayer#errorEvent
+ * @see ImageryLayer#readyEvent
+ * @see ImageryLayer#imageryProvider
  */
 ImageryLayer.fromWorldImagery = function (options) {
   options = options ?? Frozen.EMPTY_OBJECT;

package/Source/Scene/MetadataTableProperty.js

@@ -10,6 +10,7 @@ import oneTimeWarning from "../Core/oneTimeWarning.js";
 import MetadataComponentType from "./MetadataComponentType.js";
 import MetadataClassProperty from "./MetadataClassProperty.js";
 import MetadataType from "./MetadataType.js";
+import addAllToArray from "../Core/addAllToArray.js";
 
 /**
  * A binary property in a {@MetadataTable}
@@ -374,7 +375,7 @@ function flatten(values) {
   for (let i = 0; i < values.length; i++) {
     const value = values[i];
     if (Array.isArray(value)) {
-      result.push.apply(result, value);
+      addAllToArray(result, value);
     } else {
       result.push(value);
     }

package/Source/Scene/Model/ClassificationModelDrawCommand.js

@@ -1,3 +1,4 @@
+import addAllToArray from "../../Core/addAllToArray.js";
 import BoundingSphere from "../../Core/BoundingSphere.js";
 import Check from "../../Core/Check.js";
 import Frozen from "../../Core/Frozen.js";
@@ -482,16 +483,16 @@ ClassificationModelDrawCommand.prototype.pushCommands = function (
   const passes = frameState.passes;
   if (passes.render) {
     if (this._useDebugWireframe) {
-      result.push.apply(result, this._commandListDebugWireframe);
+      addAllToArray(result, this._commandListDebugWireframe);
       return;
     }
 
     if (this._classifiesTerrain) {
-      result.push.apply(result, this._commandListTerrain);
+      addAllToArray(result, this._commandListTerrain);
     }
 
     if (this._classifies3DTiles) {
-      result.push.apply(result, this._commandList3DTiles);
+      addAllToArray(result, this._commandList3DTiles);
     }
 
     const useIgnoreShowCommands =
@@ -513,17 +514,17 @@ ClassificationModelDrawCommand.prototype.pushCommands = function (
         );
       }
 
-      result.push.apply(result, this._commandListIgnoreShow);
+      addAllToArray(result, this._commandListIgnoreShow);
     }
   }
 
   if (passes.pick) {
     if (this._classifiesTerrain) {
-      result.push.apply(result, this._commandListTerrainPicking);
+      addAllToArray(result, this._commandListTerrainPicking);
     }
 
     if (this._classifies3DTiles) {
-      result.push.apply(result, this._commandList3DTilesPicking);
+      addAllToArray(result, this._commandList3DTilesPicking);
     }
   }
 

package/Source/Scene/Model/GeoJsonLoader.js

@@ -19,6 +19,7 @@ import StructuralMetadata from "../StructuralMetadata.js";
 import VertexAttributeSemantic from "../VertexAttributeSemantic.js";
 import Buffer from "../../Renderer/Buffer.js";
 import BufferUsage from "../../Renderer/BufferUsage.js";
+import addAllToArray from "../../Core/addAllToArray.js";
 
 /**
  * Loads a GeoJson model as part of the <code>MAXAR_content_geojson</code> extension with the following constraints:
@@ -166,7 +167,8 @@ function parseMultiPolygon(coordinates) {
   const polygonsLength = coordinates.length;
   const lines = [];
   for (let i = 0; i < polygonsLength; i++) {
-    Array.prototype.push.apply(lines, parsePolygon(coordinates[i]));
+    const polygon = parsePolygon(coordinates[i]);
+    addAllToArray(lines, polygon);
   }
   return lines;
 }

package/Source/Scene/Model/ImageryConfiguration.js

@@ -12,6 +12,7 @@
  */
 class ImageryConfiguration {
   constructor(imageryLayer) {
+    this.show = imageryLayer.show;
     this.alpha = imageryLayer.alpha;
     this.brightness = imageryLayer.brightness;
     this.contrast = imageryLayer.contrast;

package/Source/Scene/Model/ImageryPipelineStage.js

@@ -109,7 +109,9 @@ class ImageryPipelineStage {
     );
 
     // This can happen when none of the imagery textures could
-    // be obtained, because they had all been INVALID/FAILED.
+    // be obtained, because they had all been INVALID/FAILED,
+    // or when none of the imagery layers is actually visible
+    // according to `show==true`
     // Bail out in this case
     if (imageryInputs.length === 0) {
       return;
@@ -758,7 +760,8 @@ class ImageryPipelineStage {
    * pipeline stage for draping the given imagery layers over the primitive
    * that is described by the given model primitive imagery.
    *
-   * This will obtain the <code>ImageryCoverage</code> objects that are provided by
+   * For each imagery layer that is currently visible (as of `show==true`), this
+   * will obtain the <code>ImageryCoverage</code> objects that are provided by
    * the given model primitive imagery (and that describe the imagery tiles
    * that are covered by the primitive), and create one <code>ImageryInput</code> for
    * each of them.
@@ -791,6 +794,9 @@ class ImageryPipelineStage {
 
     for (let i = 0; i < imageryLayers.length; i++) {
       const imageryLayer = imageryLayers.get(i);
+      if (!imageryLayer.show) {
+        continue;
+      }
       const imageryTexCoordAttributeSetIndex =
         imageryTexCoordAttributeSetIndices[i];
       const mappedPositions =

package/Source/Scene/Model/InstancingPipelineStage.js

@@ -1,3 +1,4 @@
+import addAllToArray from "../../Core/addAllToArray.js";
 import AttributeCompression from "../../Core/AttributeCompression.js";
 import Cartesian3 from "../../Core/Cartesian3.js";
 import clone from "../../Core/clone.js";
@@ -210,10 +211,7 @@ InstancingPipelineStage.process = function (renderResources, node, frameState) {
   renderResources.uniformMap = combine(uniformMap, renderResources.uniformMap);
 
   renderResources.instanceCount = count;
-  renderResources.attributes.push.apply(
-    renderResources.attributes,
-    instancingVertexAttributes,
-  );
+  addAllToArray(renderResources.attributes, instancingVertexAttributes);
 };
 
 const projectedTransformScratch = new Matrix4();
@@ -988,10 +986,7 @@ function processMatrixAttributes(
   shaderBuilder.addAttribute("vec4", `a_instancing${attributeString}Row1`);
   shaderBuilder.addAttribute("vec4", `a_instancing${attributeString}Row2`);
 
-  instancingVertexAttributes.push.apply(
-    instancingVertexAttributes,
-    matrixAttributes,
-  );
+  addAllToArray(instancingVertexAttributes, matrixAttributes);
 }
 
 function processVec3Attribute(

package/Source/Scene/Model/MaterialPipelineStage.js

@@ -139,9 +139,18 @@ MaterialPipelineStage.process = function (
     VertexAttributeSemantic.NORMAL,
   );
 
+  // Disable PointCloud normals if the user explicitly turned them off.
+  const disablePointCloudNormals =
+    defined(model.pointCloudShading) && !model.pointCloudShading.normalShading;
+
   // Classification models will be rendered as unlit.
   const lightingOptions = renderResources.lightingOptions;
-  if (material.unlit || !hasNormals || hasClassification) {
+  if (
+    material.unlit ||
+    !hasNormals ||
+    hasClassification ||
+    disablePointCloudNormals
+  ) {
     lightingOptions.lightingModel = LightingModel.UNLIT;
   } else {
     lightingOptions.lightingModel = LightingModel.PBR;

package/Source/Scene/Model/ModelImagery.js

@@ -335,6 +335,9 @@ class ModelImagery {
       const imageryLayer = imageryLayers.get(i);
       const imageryConfiguration = imageryConfigurations[i];
 
+      if (imageryLayer.show !== imageryConfiguration.show) {
+        return true;
+      }
       if (imageryLayer.alpha !== imageryConfiguration.alpha) {
         return true;
       }

package/Source/Scene/Model/ModelSceneGraph.js

@@ -26,6 +26,7 @@ import ModelType from "./ModelType.js";
 import NodeRenderResources from "./NodeRenderResources.js";
 import PrimitiveRenderResources from "./PrimitiveRenderResources.js";
 import ModelDrawCommands from "./ModelDrawCommands.js";
+import addAllToArray from "../../Core/addAllToArray.js";
 
 /**
  * An in memory representation of the scene graph for a {@link Model}
@@ -1018,7 +1019,7 @@ ModelSceneGraph.prototype.pushDrawCommands = function (frameState) {
     pushDrawCommandOptions,
   );
 
-  frameState.commandList.push.apply(frameState.commandList, silhouetteCommands);
+  addAllToArray(frameState.commandList, silhouetteCommands);
 };
 
 // Callback is defined here to avoid allocating a closure in the render loop

package/Source/Scene/Picking.js

@@ -272,7 +272,7 @@ function computePickingDrawingBufferRectangle(
  * @param {Cartesian2} windowPosition Window coordinates to perform picking on.
  * @param {number} [width=3] Width of the pick rectangle.
  * @param {number} [height=3] Height of the pick rectangle.
- * @returns {object} Object containing the picked primitive.
+ * @returns {object | undefined} Object containing the picked primitive.
  */
 Picking.prototype.pick = function (scene, windowPosition, width, height) {
   //>>includeStart('debug', pragmas.debug);
@@ -923,6 +923,16 @@ function getTilesets(primitives, objectsToExclude, tilesets) {
   }
 }
 
+/**
+ * @private
+ * @param {Picking} picking
+ * @param {Scene} scene
+ * @param {Ray} ray
+ * @param {Object[] | undefined} objectsToExclude
+ * @param {number | undefined} width
+ * @param {Function} callback
+ * @returns {Promise<Cartesian3 | undefined>}
+ */
 function launchMostDetailedRayPick(
   picking,
   scene,
@@ -1266,6 +1276,12 @@ const scratchSurfaceNormal = new Cartesian3();
 const scratchSurfaceRay = new Ray();
 const scratchCartographic = new Cartographic();
 
+/**
+ * @private
+ * @param {Scene} scene
+ * @param {Cartographic} cartographic
+ * @returns {Ray}
+ */
 function getRayForSampleHeight(scene, cartographic) {
   const ellipsoid = scene.ellipsoid;
   const height = ApproximateTerrainHeights._defaultMaxTerrainHeight;
@@ -1287,6 +1303,12 @@ function getRayForSampleHeight(scene, cartographic) {
   return ray;
 }
 
+/**
+ * @private
+ * @param {Scene} scene
+ * @param {Cartesian3} cartesian
+ * @returns {Ray}
+ */
 function getRayForClampToHeight(scene, cartesian) {
   const ellipsoid = scene.ellipsoid;
   const cartographic = Cartographic.fromCartesian(
@@ -1338,6 +1360,16 @@ function sampleHeightMostDetailed(
   );
 }
 
+/**
+ * @private
+ * @param {Picking} picking
+ * @param {Scene} scene
+ * @param {Cartesian3} cartesian
+ * @param {Object[]} [objectsToExclude]
+ * @param {number} [width]
+ * @param {Cartesian3} [result]
+ * @returns {Promise<Cartesian3 | undefined>}
+ */
 function clampToHeightMostDetailed(
   picking,
   scene,
@@ -1483,6 +1515,14 @@ Picking.prototype.sampleHeightMostDetailed = function (
   );
 };
 
+/**
+ * @private
+ * @param {Scene} scene
+ * @param {Cartesian3[]} cartesians
+ * @param {Object[]} [objectsToExclude]
+ * @param {number} [width]
+ * @returns {Promise<Array<Cartesian3 | undefined>>}
+ */
 Picking.prototype.clampToHeightMostDetailed = function (
   scene,
   cartesians,

package/Source/Scene/Primitive.js

@@ -1966,7 +1966,6 @@ Primitive._updateBoundingVolumes = function (
             primitive._boundingSphereCV[i],
             primitive._boundingSphere2D[i],
           );
-          primitive._boundingSphere2D[i].center.x = 0.0;
           primitive._boundingSphereMorph[i] = BoundingSphere.union(
             primitive._boundingSphereWC[i],
             primitive._boundingSphereCV[i],

package/Source/Scene/PrimitiveCollection.js

@@ -16,6 +16,9 @@ import Event from "../Core/Event.js";
  * @param {object} [options] Object with the following properties:
  * @param {boolean} [options.show=true] Determines if the primitives in the collection will be shown.
  * @param {boolean} [options.destroyPrimitives=true] Determines if primitives in the collection are destroyed when they are removed.
+ * @privateParam {boolean} [options.countReferences=false] Specifies whether adding and removing primitives from this collection alters their reference counts. If so, adding a
+ * primitive to this collection increments its reference count. Removing the primitive decrements its reference count and - if the count reaches zero **and** destroyPrimitives is true - destroys the primitive.
+ * This permits primitives to be shared between multiple collections.
  *
  * @example
  * const billboards = new Cesium.BillboardCollection();
@@ -71,6 +74,8 @@ function PrimitiveCollection(options) {
    * labels = labels.destroy();    // explicitly destroy
    */
   this.destroyPrimitives = options.destroyPrimitives ?? true;
+
+  this._countReferences = options.countReferences ?? false;
 }
 
 Object.defineProperties(PrimitiveCollection.prototype, {
@@ -160,6 +165,14 @@ PrimitiveCollection.prototype.add = function (primitive, index) {
     this._primitives.splice(index, 0, primitive);
   }
 
+  if (this._countReferences) {
+    if (!defined(external._referenceCount)) {
+      external._referenceCount = 1;
+    } else {
+      ++external._referenceCount;
+    }
+  }
+
   this._primitiveAdded.raiseEvent(primitive);
 
   return primitive;
@@ -188,8 +201,14 @@ PrimitiveCollection.prototype.remove = function (primitive) {
       this._primitives.splice(index, 1);
 
       delete primitive._external._composites[this._guid];
+      if (this._countReferences) {
+        primitive._external._referenceCount--;
+      }
 
-      if (this.destroyPrimitives) {
+      if (
+        this.destroyPrimitives &&
+        (!this._countReferences || primitive._external._referenceCount <= 0)
+      ) {
         primitive.destroy();
       }
 
@@ -204,7 +223,7 @@ PrimitiveCollection.prototype.remove = function (primitive) {
 };
 
 /**
- * Removes and destroys a primitive, regardless of destroyPrimitives setting.
+ * Removes and destroys a primitive, regardless of destroyPrimitives or countReferences setting.
  * @private
  */
 PrimitiveCollection.prototype.removeAndDestroy = function (primitive) {
@@ -226,13 +245,20 @@ PrimitiveCollection.prototype.removeAll = function () {
   const primitives = this._primitives;
   const length = primitives.length;
   for (let i = 0; i < length; ++i) {
-    delete primitives[i]._external._composites[this._guid];
+    const primitive = primitives[i];
+    delete primitive._external._composites[this._guid];
+    if (this._countReferences) {
+      primitive._external._referenceCount--;
+    }
 
-    if (this.destroyPrimitives) {
-      primitives[i].destroy();
+    if (
+      this.destroyPrimitives &&
+      (!this._countReferences || primitive._external._referenceCount <= 0)
+    ) {
+      primitive.destroy();
     }
 
-    this._primitiveRemoved.raiseEvent(primitives[i]);
+    this._primitiveRemoved.raiseEvent(primitive);
   }
   this._primitives = [];
 };