Merge pull request #12778 from CesiumGS/imodel-changeset-support

Add support for optional changesets when loading iModels

Author: ggetz

Apps/Sandcastle/gallery/Drape Imagery on 3D Tiles.html

@@ -40,12 +40,10 @@
         });
         viewer.scene.skyAtmosphere.show = true;
 
-        const iTwinId = "535a24a3-9b29-4e23-bb5d-9cedb524c743";
-        const realityMeshId = "85897090-3bcc-470b-bec7-20bb639cc1b9";
-        const tileset = await Cesium.ITwinData.createTilesetForRealityDataId(
-          iTwinId,
-          realityMeshId,
-        );
+        const tileset = await Cesium.ITwinData.createTilesetForRealityDataId({
+          iTwinId: "535a24a3-9b29-4e23-bb5d-9cedb524c743",
+          realityDataId: "85897090-3bcc-470b-bec7-20bb639cc1b9",
+        });
         viewer.scene.primitives.add(tileset);
         tileset.maximumScreenSpaceError = 2;
 

Apps/Sandcastle/gallery/iModel Mesh Export Service.html

@@ -110,12 +110,12 @@
         }
 
         // Create tilesets using the iModel ids
-        const surroundingArea = await Cesium.ITwinData.createTilesetFromIModelId(
-          "f856f57d-3d28-4265-9c4f-5e60c0662c15",
-        );
-        const station = await Cesium.ITwinData.createTilesetFromIModelId(
-          "669dde67-eb69-4e0b-bcf2-f722eee94746",
-        );
+        const surroundingArea = await Cesium.ITwinData.createTilesetFromIModelId({
+          iModelId: "f856f57d-3d28-4265-9c4f-5e60c0662c15",
+        });
+        const station = await Cesium.ITwinData.createTilesetFromIModelId({
+          iModelId: "669dde67-eb69-4e0b-bcf2-f722eee94746",
+        });
         // Change how highlighting with the feature selection changes the color
         surroundingArea.colorBlendMode = Cesium.Cesium3DTileColorBlendMode.REPLACE;
         station.colorBlendMode = Cesium.Cesium3DTileColorBlendMode.REPLACE;
@@ -124,12 +124,10 @@
         scene.primitives.add(station);
 
         // Create tileset of the reality data mesh
-        const iTwinId = "535a24a3-9b29-4e23-bb5d-9cedb524c743";
-        const realityMeshId = "85897090-3bcc-470b-bec7-20bb639cc1b9";
-        const realityMesh = await Cesium.ITwinData.createTilesetForRealityDataId(
-          iTwinId,
-          realityMeshId,
-        );
+        const realityMesh = await Cesium.ITwinData.createTilesetForRealityDataId({
+          iTwinId: "535a24a3-9b29-4e23-bb5d-9cedb524c743",
+          realityDataId: "85897090-3bcc-470b-bec7-20bb639cc1b9",
+        });
         scene.primitives.add(realityMesh);
 
         Sandcastle.addToolbarButton(

Apps/Sandcastle/gallery/iTwin Feature Service.html

@@ -66,18 +66,18 @@
         viewer.scene.camera.flyTo(birdsEyeView);
 
         // Load feature service geojson files
-        const points = await Cesium.ITwinData.loadGeospatialFeatures(
-          iTwinId,
-          "2380dc1b-1dac-4709-aa5c-f6cb38c4e9f5",
-        );
-        const lines = await Cesium.ITwinData.loadGeospatialFeatures(
-          iTwinId,
-          "613d2310-4d01-43b7-bc92-873a2ca4a4a0",
-        );
-        const areas = await Cesium.ITwinData.loadGeospatialFeatures(
-          iTwinId,
-          "93e7ef51-5210-49f2-92a3-c7f6685e102f",
-        );
+        const points = await Cesium.ITwinData.loadGeospatialFeatures({
+          iTwinId: iTwinId,
+          collectionId: "2380dc1b-1dac-4709-aa5c-f6cb38c4e9f5",
+        });
+        const lines = await Cesium.ITwinData.loadGeospatialFeatures({
+          iTwinId: iTwinId,
+          collectionId: "613d2310-4d01-43b7-bc92-873a2ca4a4a0",
+        });
+        const areas = await Cesium.ITwinData.loadGeospatialFeatures({
+          iTwinId: iTwinId,
+          collectionId: "93e7ef51-5210-49f2-92a3-c7f6685e102f",
+        });
 
         // Add some styling to the lines and points to differentiate types
         const pinBuilder = new Cesium.PinBuilder();
@@ -118,17 +118,15 @@
         viewer.dataSources.add(areas);
 
         // Create tileset of the reality data mesh and pointcloud
-        const realityMeshId = "62e4432d-621d-489a-87ff-1fc56a2b5369";
-        const realityMesh = await Cesium.ITwinData.createTilesetForRealityDataId(
-          iTwinId,
-          realityMeshId,
-        );
+        const realityMesh = await Cesium.ITwinData.createTilesetForRealityDataId({
+          iTwinId: iTwinId,
+          realityDataId: "62e4432d-621d-489a-87ff-1fc56a2b5369",
+        });
         viewer.scene.primitives.add(realityMesh);
-        const pointcloudId = "ebf2ee74-f0de-4cd6-a311-19a169c55fdc";
-        const pointcloud = await Cesium.ITwinData.createTilesetForRealityDataId(
-          iTwinId,
-          pointcloudId,
-        );
+        const pointcloud = await Cesium.ITwinData.createTilesetForRealityDataId({
+          iTwinId: iTwinId,
+          realityDataId: "ebf2ee74-f0de-4cd6-a311-19a169c55fdc",
+        });
         // increase the size of the pointcloud points and turn on attenuation to
         // make them more visible in the viewer
         pointcloud.maximumScreenSpaceError = 1;

CHANGES.md

@@ -22,6 +22,11 @@
 
 - Expand the CustomShader Sample to support real-time modification of CustomShader. [#12702](https://github.com/CesiumGS/cesium/pull/12702)
 - Add wrapR property to Sampler and Texture3D, to support the newly added third dimension wrap.[#12701](https://github.com/CesiumGS/cesium/pull/12701)
+- Added the ability to load a specific changeset for iTwin Mesh Exports using `ITwinData.createTilesetFromIModelId` [#12778](https://github.com/CesiumGS/cesium/issues/12778)
+
+#### Deprecated :hourglass_flowing_sand:
+
+- Updated all of the `ITwinData.*` functions to accept an `options` parameter instead of individual arguments to avoid confusion with multiple optional arguments. There is a fallback to the old signature that will be removed in 1.133 [#12778](https://github.com/CesiumGS/cesium/issues/12778)
 
 ## 1.131 - 2025-07-01
 

packages/engine/Source/Core/ITwinPlatform.js

@@ -153,13 +153,17 @@ ITwinPlatform.apiEndpoint = new Resource({
  * @private
  *
  * @param {string} iModelId iModel id
+ * @param {string} [changesetId] The id of the changeset to filter results by. If not provided, exports from the latest available changesets will be returned.
  * @returns {Promise<GetExportsResponse>}
  *
  * @throws {RuntimeError} If the iTwin API request is not successful
  */
-ITwinPlatform.getExports = async function (iModelId) {
+ITwinPlatform.getExports = async function (iModelId, changesetId) {
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.string("iModelId", iModelId);
+  if (defined(changesetId)) {
+    Check.typeOf.string("changesetId", changesetId);
+  }
   if (
     !defined(ITwinPlatform.defaultAccessToken) &&
     !defined(ITwinPlatform.defaultShareKey)
@@ -191,6 +195,9 @@ ITwinPlatform.getExports = async function (iModelId) {
   if (typeof CESIUM_VERSION !== "undefined") {
     resource.appendQueryParameters({ clientVersion: CESIUM_VERSION });
   }
+  if (defined(changesetId) && changesetId !== "") {
+    resource.appendQueryParameters({ changesetId: changesetId });
+  }
 
   try {
     const response = await resource.fetchJson();

packages/engine/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);

packages/engine/Specs/Core/ITwinPlatformSpec.js

@@ -156,6 +156,17 @@ describe("ITwinPlatform", () => {
       expect(resource).toBeDefined();
       expect(resource.url).toContain("imodel-id-1");
     });
+
+    it("uses the changeset in the API request", async () => {
+      let resource;
+      requestSpy.and.callFake(function () {
+        resource = this;
+        return JSON.stringify({ exports: [] });
+      });
+      await ITwinPlatform.getExports("imodel-id-1", "changeset-id-1");
+      expect(resource).toBeDefined();
+      expect(resource.url).toContain("changeset-id-1");
+    });
   });
 
   describe("getRealityDataMetadata", () => {