Merge pull request #12358 from jfayot/fix_12356

fixes issue #12356 performance drop due to EnvironmentMap

Author: ggetz

.vscode/cspell.json

@@ -36,13 +36,15 @@
     "3DTILES",
     "aabb",
     "Amato",
+    "basisu",
     "bathymetric",
     "bitangent",
     "bitangents",
     "bivariate",
     "Bourke",
     "brdf",
     "cartesians",
+    "carto",
     "cartographics",
     "cesiumjs",
     "comms",
@@ -93,6 +95,7 @@
     "unregisters",
     "unrenderable",
     "voxel",
+    "VVLH",
     "WEBG",
     "xdescribe"
   ]

CHANGES.md

@@ -2,14 +2,17 @@
 
 ### 1.125 - 2025-01-02
 
+#### @cesium/engine
+
 ##### Additions :tada:
 
 - Expanded the integration with the [iTwin Platform](https://developer.bentley.com/) to load GeoJSON and KML data from the Reality Management API. Use `ITwinData.createDataSourceForRealityDataId(iTwinId, realityDataId)` to load data as the corresponding Data Source. [#12344](https://github.com/CesiumGS/cesium/pull/12344)
+- Added `environmentMapOptions` to `ModelGraphics`. For performance reasons, the environment map will not update if the entity position changes by default. If environment map updates based on entity position are desired, ensure to provide an appropriate `environmentMapOptions.maximumPositionEpsilon` value. [#12358](https://github.com/CesiumGS/cesium/pull/12358)
 
 ##### Fixes :wrench:
 
 - Reduced memory usage and peformance bottlenecks when using environment maps with models. [#12356](https://github.com/CesiumGS/cesium/issues/12356)
-- Fixed JulianDate to always generate valid ISO strings for fractional milliseconds. [#12345](https://github.com/CesiumGS/cesium/pull/12345)
+- Fixed JulianDate to always generate valid ISO strings for fractional milliseconds [#12345](https://github.com/CesiumGS/cesium/pull/12345)
 - Fixed intermittent z-fighting issue. [#12337](https://github.com/CesiumGS/cesium/issues/12337)
 
 ### 1.124 - 2024-12-02
@@ -102,9 +105,6 @@
 - Fix flickering issue caused by bounding sphere retrieval being blocked by the bounding sphere of another entity. [#12230](https://github.com/CesiumGS/cesium/pull/12230)
 - Fixed `ImageBasedLighting.imageBasedLightingFactor` not affecting lighting. [#12129](https://github.com/CesiumGS/cesium/pull/12129)
 - Fix error with normalization of corner points for lines and corridors with collinear points. [#12255](https://github.com/CesiumGS/cesium/pull/12255)
-
-##### Fixes :wrench:
-
 - Properly handle `offset` and `scale` properties when picking metadata from property textures. [#12237](https://github.com/CesiumGS/cesium/pull/12237)
 
 ### 1.122 - 2024-10-01

packages/engine/Source/DataSources/ModelGraphics.js

@@ -18,6 +18,10 @@ function createArticulationStagePropertyBag(value) {
   return new PropertyBag(value);
 }
 
+function createEnvironmentMapPropertyBag(value) {
+  return new PropertyBag(value);
+}
+
 /**
  * @typedef {object} ModelGraphics.ConstructorOptions
  *
@@ -40,6 +44,7 @@ function createArticulationStagePropertyBag(value) {
  * @property {Property | ColorBlendMode} [colorBlendMode=ColorBlendMode.HIGHLIGHT] An enum Property specifying how the color blends with the model.
  * @property {Property | number} [colorBlendAmount=0.5] A numeric Property specifying the color strength when the <code>colorBlendMode</code> is <code>MIX</code>. A value of 0.0 results in the model's rendered color while a value of 1.0 results in a solid color, with any value in-between resulting in a mix of the two.
  * @property {Property | Cartesian2} [imageBasedLightingFactor=new Cartesian2(1.0, 1.0)] A property specifying the contribution from diffuse and specular image-based lighting.
+ * @property {PropertyBag | Object<string, *>} [environmentMapOptions] The properties for managing dynamic environment maps on this entity.
  * @property {Property | Color} [lightColor] A property specifying the light color when shading the model. When <code>undefined</code> the scene's light color is used instead.
  * @property {Property | DistanceDisplayCondition} [distanceDisplayCondition] A Property specifying at what distance from the camera that this model will be displayed.
  * @property {PropertyBag | Object<string, TranslationRotationScale>} [nodeTransformations] An object, where keys are names of nodes, and values are {@link TranslationRotationScale} Properties describing the transformation to apply to that node. The transformation is applied after the node's existing transformation as specified in the glTF, and does not replace the node's existing transformation.
@@ -101,6 +106,8 @@ function ModelGraphics(options) {
   this._colorBlendAmountSubscription = undefined;
   this._imageBasedLightingFactor = undefined;
   this._imageBasedLightingFactorSubscription = undefined;
+  this._environmentMapOptions = undefined;
+  this._environmentMapOptionsSubscription = undefined;
   this._lightColor = undefined;
   this._lightColorSubscription = undefined;
   this._distanceDisplayCondition = undefined;
@@ -279,6 +286,17 @@ Object.defineProperties(ModelGraphics.prototype, {
     "imageBasedLightingFactor",
   ),
 
+  /**
+   * Gets or sets the {@link DynamicEnvironmentMapManager.ConstructorOptions} to apply to this model. This is represented as an {@link PropertyBag}.
+   * @memberof ModelGraphics.prototype
+   * @type {PropertyBag}
+   */
+  environmentMapOptions: createPropertyDescriptor(
+    "environmentMapOptions",
+    undefined,
+    createEnvironmentMapPropertyBag,
+  ),
+
   /**
    * A property specifying the {@link Cartesian3} light color when shading the model. When <code>undefined</code> the scene's light color is used instead.
    * @memberOf ModelGraphics.prototype
@@ -361,6 +379,7 @@ ModelGraphics.prototype.clone = function (result) {
   result.colorBlendMode = this.colorBlendMode;
   result.colorBlendAmount = this.colorBlendAmount;
   result.imageBasedLightingFactor = this.imageBasedLightingFactor;
+  result.environmentMapOptions = this.environmentMapOptions;
   result.lightColor = this.lightColor;
   result.distanceDisplayCondition = this.distanceDisplayCondition;
   result.nodeTransformations = this.nodeTransformations;
@@ -430,7 +449,10 @@ ModelGraphics.prototype.merge = function (source) {
     this.imageBasedLightingFactor,
     source.imageBasedLightingFactor,
   );
-
+  this.environmentMapOptions = defaultValue(
+    this.environmentMapOptions,
+    source.environmentMapOptions,
+  );
   this.lightColor = defaultValue(this.lightColor, source.lightColor);
   this.distanceDisplayCondition = defaultValue(
     this.distanceDisplayCondition,

packages/engine/Source/DataSources/ModelVisualizer.js

@@ -35,6 +35,9 @@ const defaultColor = Color.WHITE;
 const defaultColorBlendMode = ColorBlendMode.HIGHLIGHT;
 const defaultColorBlendAmount = 0.5;
 const defaultImageBasedLightingFactor = new Cartesian2(1.0, 1.0);
+const defaultEnvironmentMapOptions = {
+  maximumPositionEpsilon: Number.POSITIVE_INFINITY,
+};
 
 const modelMatrixScratch = new Matrix4();
 const nodeMatrixScratch = new Matrix4();
@@ -76,6 +79,7 @@ async function createModelPrimitive(
   entity,
   resource,
   incrementallyLoadTextures,
+  environmentMapOptions,
 ) {
   const primitives = visualizer._primitives;
   const modelHash = visualizer._modelHash;
@@ -85,6 +89,7 @@ async function createModelPrimitive(
       url: resource,
       incrementallyLoadTextures: incrementallyLoadTextures,
       scene: visualizer._scene,
+      environmentMapOptions: environmentMapOptions,
     });
 
     if (visualizer.isDestroyed() || !defined(modelHash[entity.id])) {
@@ -176,6 +181,9 @@ ModelVisualizer.prototype.update = function (time) {
         articulationsScratch: {},
         loadFailed: false,
         modelUpdated: false,
+        environmentMapOptionsScratch: {
+          ...defaultEnvironmentMapOptions,
+        },
       };
       modelHash[entity.id] = modelData;
 
@@ -185,7 +193,20 @@ ModelVisualizer.prototype.update = function (time) {
         defaultIncrementallyLoadTextures,
       );
 
-      createModelPrimitive(this, entity, resource, incrementallyLoadTextures);
+      const environmentMapOptions = Property.getValueOrDefault(
+        modelGraphics._environmentMapOptions,
+        time,
+        defaultEnvironmentMapOptions,
+        modelData.environmentMapOptionsScratch,
+      );
+
+      createModelPrimitive(
+        this,
+        entity,
+        resource,
+        incrementallyLoadTextures,
+        environmentMapOptions,
+      );
     }
 
     const model = modelData.modelPrimitive;

packages/engine/Source/Scene/Cesium3DTileset.js

@@ -105,7 +105,7 @@ import DynamicEnvironmentMapManager from "./DynamicEnvironmentMapManager.js";
  * @property {object} [pointCloudShading] Options for constructing a {@link PointCloudShading} object to control point attenuation based on geometric error and lighting.
  * @property {Cartesian3} [lightColor] The light color when shading models. When <code>undefined</code> the scene's light color is used instead.
  * @property {ImageBasedLighting} [imageBasedLighting] The properties for managing image-based lighting for this tileset.
- * @param {DynamicEnvironmentMapManager.ConstructorOptions} [options.environmentMapOptions] The properties for managing dynamic environment maps on this model.
+ * @property {DynamicEnvironmentMapManager.ConstructorOptions} [environmentMapOptions] The properties for managing dynamic environment maps on this tileset.
  * @property {boolean} [backFaceCulling=true] Whether to cull back-facing geometry. When true, back face culling is determined by the glTF material's doubleSided property; when false, back face culling is disabled.
  * @property {boolean} [enableShowOutline=true] Whether to enable outlines for models using the {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/CESIUM_primitive_outline|CESIUM_primitive_outline} extension. This can be set to false to avoid the additional processing of geometry at load time. When false, the showOutlines and outlineColor options are ignored.
  * @property {boolean} [showOutline=true] Whether to display the outline for models using the {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/CESIUM_primitive_outline|CESIUM_primitive_outline} extension. When true, outlines are displayed. When false, outlines are not displayed.

packages/engine/Source/Scene/Model/Model.js

@@ -1823,7 +1823,7 @@ Model.prototype.applyArticulations = function () {
  *
  * The given name may be the name of a glTF extension, like `"EXT_example_extension"`.
  * If the specified extension was present in the root of the underlying glTF asset,
- * and a loder for the specified extension has processed the extension data, then
+ * and a loader for the specified extension has processed the extension data, then
  * this will return the model representation of the extension.
  *
  * @param {string} extensionName The name of the extension

packages/engine/Specs/DataSources/ModelVisualizerSpec.js

@@ -196,6 +196,11 @@ describe(
 
       expect(primitive.lightColor).toEqual(new Cartesian3(1.0, 1.0, 0.0));
 
+      expect(primitive.environmentMapManager.enabled).toBeTrue();
+      expect(primitive.environmentMapManager.maximumPositionEpsilon).toEqual(
+        Number.POSITIVE_INFINITY,
+      );
+
       // wait till the model is loaded before we can check node transformations
       await pollToPromise(function () {
         scene.render();
@@ -276,6 +281,43 @@ describe(
       expect(node.matrix).toEqualEpsilon(expected, CesiumMath.EPSILON14);
     });
 
+    it("can apply model environmentMapOptions", async function () {
+      const time = JulianDate.now();
+
+      const model = new ModelGraphics();
+      model.uri = new ConstantProperty(boxArticulationsUrl);
+
+      model.environmentMapOptions = {
+        enabled: false,
+      };
+
+      const testObject = entityCollection.getOrCreateEntity("test");
+      testObject.position = new ConstantPositionProperty(
+        Cartesian3.fromDegrees(1, 2, 3),
+      );
+      testObject.model = model;
+
+      visualizer.update(time);
+
+      let primitive;
+      await pollToPromise(function () {
+        primitive = scene.primitives.get(0);
+        return defined(primitive);
+      });
+
+      // wait till the model is loaded before we can check articulations
+      await pollToPromise(function () {
+        scene.render();
+        return primitive.ready;
+      });
+      visualizer.update(time);
+
+      expect(primitive.environmentMapManager.enabled).toBeFalse();
+      expect(primitive.environmentMapManager.maximumPositionEpsilon).toEqual(
+        Number.POSITIVE_INFINITY,
+      );
+    });
+
     it("creates a primitive from ModelGraphics with a Resource", async function () {
       const time = JulianDate.now();