Allow passing tileset options to reality data

CHANGES.md

@@ -7,6 +7,7 @@
 #### Breaking Changes :mega:
 
 - Removed the argument fallback in `ITwinData.*` functions. Please switch to the new options argument signature [#12778](https://github.com/CesiumGS/cesium/issues/12778)
+- Allow passing tileset constructor options to the tileset that is created with `ITwinData.createTilesetForRealityDataId` [#12709](https://github.com/CesiumGS/cesium/issues/12709)
 
 ## 1.132 - 2025-08-01
 

packages/engine/Source/Scene/ITwinData.js

@@ -90,13 +90,18 @@ ITwinData.createTilesetFromIModelId = 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.
  *
+ * The <code>maximumScreenSpaceError</code> of the resulting tileset will default to 4,
+ * unless it is explicitly overridden with the given tileset options.
+ *
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  *
  * @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
+ * @param {Cesium3DTileset.ConstructorOptions} [options.tilesetOptions] Object containing
+ * options to pass to the internally created {@link Cesium3DTileset}.
  * @returns {Promise<Cesium3DTileset>}
  *
  * @throws {RuntimeError} if the type of reality data is not supported by this function
@@ -106,6 +111,7 @@ ITwinData.createTilesetForRealityDataId = async function ({
   realityDataId,
   type,
   rootDocument,
+  tilesetOptions,
 }) {
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.string("iTwinId", iTwinId);
@@ -144,9 +150,16 @@ ITwinData.createTilesetForRealityDataId = async function ({
     rootDocument,
   );
 
-  return Cesium3DTileset.fromUrl(tilesetAccessUrl, {
+  // The maximum screen space error was defined to default to 4 for
+  // reality data tilesets, because they did not show the expected
+  // amount of detail with the default value of 16. Values that are
+  // given in the tilesetOptions should still override that default.
+  const internalTilesetOptions = {
     maximumScreenSpaceError: 4,
-  });
+    ...tilesetOptions,
+  };
+
+  return Cesium3DTileset.fromUrl(tilesetAccessUrl, internalTilesetOptions);
 };
 
 /**

packages/engine/Specs/Scene/ITwinDataSpec.js

@@ -231,6 +231,54 @@ describe("ITwinData", () => {
         maximumScreenSpaceError: 4,
       });
     });
+
+    it("creates a tileset with the given tilesetOptions", async () => {
+      const tilesetUrl =
+        "https://example.com/root/document/path.json?auth=token";
+      getUrlSpy.and.resolveTo(tilesetUrl);
+
+      await ITwinData.createTilesetForRealityDataId({
+        iTwinId: "itwin-id-1",
+        realityDataId: "reality-data-id-1",
+        type: ITwinPlatform.RealityDataType.Cesium3DTiles,
+        rootDocument: "root/document/path.json",
+        tilesetOptions: {
+          cacheBytes: 500000000,
+        },
+      });
+
+      // The createTilesetForRealityDataId was defined to use a
+      // maximum screen space error of 4 by default
+      expect(tilesetSpy).toHaveBeenCalledOnceWith(tilesetUrl, {
+        maximumScreenSpaceError: 4,
+        cacheBytes: 500000000,
+      });
+    });
+
+    it("creates a tileset with tilesetOptions overriding the defaults", async () => {
+      const tilesetUrl =
+        "https://example.com/root/document/path.json?auth=token";
+      getUrlSpy.and.resolveTo(tilesetUrl);
+
+      await ITwinData.createTilesetForRealityDataId({
+        iTwinId: "itwin-id-1",
+        realityDataId: "reality-data-id-1",
+        type: ITwinPlatform.RealityDataType.Cesium3DTiles,
+        rootDocument: "root/document/path.json",
+        tilesetOptions: {
+          maximumScreenSpaceError: 32,
+          cacheBytes: 500000000,
+        },
+      });
+
+      // The createTilesetForRealityDataId was defined to use a
+      // maximum screen space error of 4 by default, which should
+      // be overridden with the value from the given options
+      expect(tilesetSpy).toHaveBeenCalledOnceWith(tilesetUrl, {
+        maximumScreenSpaceError: 32,
+        cacheBytes: 500000000,
+      });
+    });
   });
 
   describe("createDataSourceForRealityDataId", () => {