Merge branch 'main' into replace-push-apply

.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

@@ -1,10 +1,29 @@
 # Change Log
 
+### 1.126 - 2025-02-03
+
+#### @cesium/engine
+
+##### Fixes :wrench:
+
+- Fixed error when resetting `Cesium3DTileset.modelMatrix` to its initial value. [#12409](https://github.com/CesiumGS/cesium/pull/12409)
+- Fixed the parameter types of the `ClippingPolygon.equals` function, and fixed cases where parameters to `equals` functions had erroneously not been marked as 'optional'. [#12394](https://github.com/CesiumGS/cesium/pull/12394)
+- Fixed type of `ImageryLayer.fromProviderAsync`, to correctly show that the param `options` is optional. [#12400](https://github.com/CesiumGS/cesium/pull/12400)
+
 ### 1.125 - 2025-01-02
 
+#### @cesium/engine
+
+##### Additions :tada:
+
+- Expanded integration with the [iTwin Platform](https://developer.bentley.com/) to load GeoJSON and KML data from the Reality Management API. Use `ITwinData.createDataSourceForRealityDataId` to load data as either GeoJSON or KML`. [#12344](https://github.com/CesiumGS/cesium/pull/12344)
+- Added `environmentMapOptions` to `ModelGraphics`. For performance reasons by default, the environment map will not update if the entity position change. If environment map updates based on entity position are desired, provide an appropriate `environmentMapOptions.maximumPositionEpsilon` value. [#12358](https://github.com/CesiumGS/cesium/pull/12358)
+
 ##### Fixes :wrench:
 
-- Fixed JulianDate to always generate valid ISO strings for fractional milliseconds [#12345](https://github.com/CesiumGS/cesium/pull/12345)
+- Reduced memory usage and performance 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 intermittent z-fighting issue. [#12337](https://github.com/CesiumGS/cesium/issues/12337)
 
 ### 1.124 - 2024-12-02
 
@@ -13,7 +32,7 @@
 ##### Additions :tada:
 
 - Added an integration with the [iTwin Platform](https://developer.bentley.com/) to load iModels as 3D Tiles. Use `ITwinPlatform.defaultAccessToken` to set the access token. Use `ITwinData.createTilesetFromIModelId(iModelId)` to load the iModel as a `Cesium3DTileset`. [#12289](https://github.com/CesiumGS/cesium/pull/12289)
-- Added an integration with the [iTwin Platform](https://developer.bentley.com/) to load Reality Data terrain meshes and GeoJSON. Use `ITwinPlatform.defaultAccessToken` to set the access token. Then use `ITwinData.createTilesetForRealityDataId(iTwinId, dataId)` to load terrain meshes as a `Cesium3DTileset` or `ITwinData.createDataSourceForRealityDataId(iTwinId, dataId)` to load GeoJSON or KML files as data sources. [#12344](https://github.com/CesiumGS/cesium/pull/12344)
+- Added an integration with the [iTwin Platform](https://developer.bentley.com/) to load Reality Data terrain meshes. Use `ITwinPlatform.defaultAccessToken` to set the access token. Then use `ITwinData.createTilesetForRealityDataId(iTwinId, dataId)` to load terrain meshes as a `Cesium3DTileset` [#12334](https://github.com/CesiumGS/cesium/pull/12334)
 - Added `getSample` to `SampledProperty` to get the time of samples. [#12253](https://github.com/CesiumGS/cesium/pull/12253)
 - Added `Entity.trackingReferenceFrame` property to allow tracking entities in various reference frames. [#12194](https://github.com/CesiumGS/cesium/pull/12194), [#12314](https://github.com/CesiumGS/cesium/pull/12314)
   - `TrackingReferenceFrame.AUTODETECT` (default): uses either VVLH or ENU depending on entity's dynamic. Use `TrackingReferenceFrame.ENU` if your camera orientation flips abruptly from time to time.
@@ -96,9 +115,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

CONTRIBUTORS.md

@@ -419,3 +419,6 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to Cesiu
 - [Kirn Kim](https://github.com/squrki)
 - [Emanuele Mastaglia](https://github.com/Masty88)
 - [Connor Manning](https://github.com/connormanning)
+- [Isaac Young](https://github.com/ibreathebsb)
+- [Nick Crews](https://github.com/NickCrews)
+- [胡文康](https://github.com/XiaoHu1994)

Documentation/Contributors/ReleaseGuide/README.md

@@ -1,6 +1,6 @@
 # Release Guide
 
-We release Cesium on the first work day of every month. [This file](../../../.slackbot.yml) outlines the release schedule and the developer responsible for each month's release.
+We release Cesium on the first work day of every month. The [Release Schedule](./ReleaseSchedule.md) outlines the release schedule and the developer responsible for each month's release.
 
 There is no release manager; instead, our community shares the responsibility. Any committer can create the release for a given month, and at any point, they can pass the responsibility to someone else, or someone else can ask for it. This spreads knowledge, avoids stratification, avoids a single point of failure, and is beautifully unstructured ([more info](https://community.cesium.com/t/cesium-releases/45)).
 

Documentation/Contributors/ReleaseGuide/ReleaseSchedule.md

@@ -0,0 +1,16 @@
+# Release Schedule
+
+| Date      | User             |
+| --------- | ---------------- |
+| 1/2/2025  | `@ggetz`         |
+| 2/3/2025  | `@jjhembd`       |
+| 3/3/2025  | `@lukemckinstry` |
+| 4/1/2025  | `@jjspace`       |
+| 5/1/2025  | `@ggetz`         |
+| 6/2/2025  | `@jjhembd`       |
+| 7/1/2025  | `@lukemckinstry` |
+| 8/1/2025  | `@jjspace`       |
+| 9/1/2025  | `@ggetz`         |
+| 10/1/2025 | `@jjhembd`       |
+| 11/3/2025 | `@lukemckinstry` |
+| 12/1/2025 | `@jjspace`       |

ThirdParty.json

@@ -12,15 +12,15 @@
     "license": [
       "BSD-3-Clause"
     ],
-    "version": "2.7.53",
+    "version": "2.7.54",
     "url": "https://www.npmjs.com/package/@zip.js/zip.js"
   },
   {
     "name": "autolinker",
     "license": [
       "MIT"
     ],
-    "version": "4.0.0",
+    "version": "4.1.0",
     "url": "https://www.npmjs.com/package/autolinker"
   },
   {
@@ -44,7 +44,7 @@
     "license": [
       "Apache-2.0"
     ],
-    "version": "3.2.2",
+    "version": "3.2.3",
     "url": "https://www.npmjs.com/package/dompurify",
     "notes": "dompurify is available as both MPL-2.0 OR Apache-2.0"
   },
@@ -61,7 +61,7 @@
     "license": [
       "ISC"
     ],
-    "version": "3.0.0",
+    "version": "3.0.1",
     "url": "https://www.npmjs.com/package/earcut"
   },
   {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cesium",
-  "version": "1.124.0",
+  "version": "1.125.0",
   "description": "CesiumJS is a JavaScript library for creating 3D globes and 2D maps in a web browser without a plugin.",
   "homepage": "http://cesium.com/cesiumjs/",
   "license": "Apache-2.0",
@@ -51,8 +51,8 @@
     "./Specs/**/*"
   ],
   "dependencies": {
-    "@cesium/engine": "^13.0.0",
-    "@cesium/widgets": "^10.0.0"
+    "@cesium/engine": "^13.1.0",
+    "@cesium/widgets": "^10.1.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.41.1",
@@ -159,4 +159,4 @@
     "packages/engine",
     "packages/widgets"
   ]
-}
+}

packages/engine/Source/Core/Color.js

@@ -536,8 +536,8 @@ Color.clone = function (color, result) {
 /**
  * Returns true if the first Color equals the second color.
  *
- * @param {Color} left The first Color to compare for equality.
- * @param {Color} right The second Color to compare for equality.
+ * @param {Color} [left] The first Color to compare for equality.
+ * @param {Color} [right] The second Color to compare for equality.
  * @returns {boolean} <code>true</code> if the Colors are equal; otherwise, <code>false</code>.
  */
 Color.equals = function (left, right) {
@@ -577,7 +577,7 @@ Color.prototype.clone = function (result) {
 /**
  * Returns true if this Color equals other.
  *
- * @param {Color} other The Color to compare for equality.
+ * @param {Color} [other] The Color to compare for equality.
  * @returns {boolean} <code>true</code> if the Colors are equal; otherwise, <code>false</code>.
  */
 Color.prototype.equals = function (other) {

packages/engine/Source/Core/Credit.js

@@ -115,8 +115,8 @@ Object.defineProperties(Credit.prototype, {
 /**
  * Returns true if the credits are equal
  *
- * @param {Credit} left The first credit
- * @param {Credit} right The second credit
+ * @param {Credit} [left] The first credit
+ * @param {Credit} [right] The second credit
  * @returns {boolean} <code>true</code> if left and right are equal, <code>false</code> otherwise.
  */
 Credit.equals = function (left, right) {
@@ -132,7 +132,7 @@ Credit.equals = function (left, right) {
 /**
  * Returns true if the credits are equal
  *
- * @param {Credit} credit The credit to compare to.
+ * @param {Credit} [credit] The credit to compare to.
  * @returns {boolean} <code>true</code> if left and right are equal, <code>false</code> otherwise.
  */
 Credit.prototype.equals = function (credit) {

packages/engine/Source/Core/DistanceDisplayCondition.js

@@ -115,8 +115,8 @@ DistanceDisplayCondition.unpack = function (array, startingIndex, result) {
 /**
  * Determines if two distance display conditions are equal.
  *
- * @param {DistanceDisplayCondition} left A distance display condition.
- * @param {DistanceDisplayCondition} right Another distance display condition.
+ * @param {DistanceDisplayCondition} [left] A distance display condition.
+ * @param {DistanceDisplayCondition} [right] Another distance display condition.
  * @return {boolean} Whether the two distance display conditions are equal.
  */
 DistanceDisplayCondition.equals = function (left, right) {
@@ -163,7 +163,7 @@ DistanceDisplayCondition.prototype.clone = function (result) {
 /**
  * Determines if this distance display condition is equal to another.
  *
- * @param {DistanceDisplayCondition} other Another distance display condition.
+ * @param {DistanceDisplayCondition} [other] Another distance display condition.
  * @return {boolean} Whether this distance display condition is equal to the other.
  */
 DistanceDisplayCondition.prototype.equals = function (other) {

packages/engine/Source/Core/Ion.js

@@ -4,7 +4,7 @@ import Resource from "./Resource.js";
 
 let defaultTokenCredit;
 const defaultAccessToken =
-  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI0ZDdmNWJiNy0wMmNlLTQ1MWUtODM2YS02NGM1MTBlOGMwMWQiLCJpZCI6MjU5LCJpYXQiOjE3MzMxNTc4OTV9.B3URHf0VdHDtGckb-hv7uqATdn8KfvkiuoAFZUq8tAo";
+  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIzYTBjYzY2NC0yMGEyLTQxZDYtYmI2MC1hMWE4ZTBlMGNlNjciLCJpZCI6MjU5LCJpYXQiOjE3MzU4NTEwMzF9.nshpaoC5qpRD4F5diwcjwJ3tddp1OjCSXoMrv37Ales";
 /**
  * Default settings for accessing the Cesium ion API.
  *

packages/engine/Source/Core/OrientedBoundingBox.js

@@ -1236,8 +1236,8 @@ OrientedBoundingBox.prototype.isOccluded = function (occluder) {
  * Compares the provided OrientedBoundingBox componentwise and returns
  * <code>true</code> if they are equal, <code>false</code> otherwise.
  *
- * @param {OrientedBoundingBox} left The first OrientedBoundingBox.
- * @param {OrientedBoundingBox} right The second OrientedBoundingBox.
+ * @param {OrientedBoundingBox} [left] The first OrientedBoundingBox.
+ * @param {OrientedBoundingBox} [right] The second OrientedBoundingBox.
  * @returns {boolean} <code>true</code> if left and right are equal, <code>false</code> otherwise.
  */
 OrientedBoundingBox.equals = function (left, right) {

packages/engine/Source/Core/Spherical.js

@@ -107,8 +107,8 @@ Spherical.normalize = function (spherical, result) {
 /**
  * Returns true if the first spherical is equal to the second spherical, false otherwise.
  *
- * @param {Spherical} left The first Spherical to be compared.
- * @param {Spherical} right The second Spherical to be compared.
+ * @param {Spherical} [left] The first Spherical to be compared.
+ * @param {Spherical} [right] The second Spherical to be compared.
  * @returns {boolean} true if the first spherical is equal to the second spherical, false otherwise.
  */
 Spherical.equals = function (left, right) {
@@ -145,7 +145,7 @@ Spherical.equalsEpsilon = function (left, right, epsilon) {
 /**
  * Returns true if this spherical is equal to the provided spherical, false otherwise.
  *
- * @param {Spherical} other The Spherical to be compared.
+ * @param {Spherical} [other] The Spherical to be compared.
  * @returns {boolean} true if this spherical is equal to the provided spherical, false otherwise.
  */
 Spherical.prototype.equals = function (other) {

packages/engine/Source/Core/writeTextToCanvas.js

@@ -104,7 +104,6 @@ let imageSmoothingEnabledName;
  * @param {string} text The text to write.
  * @param {object} [options] Object with the following properties:
  * @param {string} [options.font='10px sans-serif'] The CSS font to use.
- * @param {string} [options.textBaseline='bottom'] The baseline of the text.
  * @param {boolean} [options.fill=true] Whether to fill the text.
  * @param {boolean} [options.stroke=false] Whether to stroke the text.
  * @param {Color} [options.fillColor=Color.WHITE] The fill color.

packages/engine/Source/DataSources/DataSourceClock.js

@@ -108,7 +108,7 @@ DataSourceClock.prototype.clone = function (result) {
 /**
  * Returns true if this DataSourceClock is equivalent to the other
  *
- * @param {DataSourceClock} other The other DataSourceClock to compare to.
+ * @param {DataSourceClock} [other] The other DataSourceClock to compare to.
  * @returns {boolean} <code>true</code> if the DataSourceClocks are equal; otherwise, <code>false</code>.
  */
 DataSourceClock.prototype.equals = function (other) {

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,