@cesium/engine 26.2.0 → 26.3.0

package/Source/Renderer/UniformState.js

@@ -162,8 +162,10 @@ function UniformState() {
   this._frustum2DWidth = 0.0;
   this._eyeHeight = 0.0;
   this._eyeHeight2D = new Cartesian2();
+  this._eyeCartographic = new Cartesian3();
   this._eyeEllipsoidNormalEC = new Cartesian3();
   this._eyeEllipsoidCurvature = new Cartesian2();
+  this._eyeToEnu = new Matrix3();
   this._modelToEnu = new Matrix4();
   this._enuToModel = new Matrix4();
   this._pixelRatio = 1.0;
@@ -715,6 +717,19 @@ Object.defineProperties(UniformState.prototype, {
     },
   },
 
+  /**
+   * The geodetic longitude (<code>x</code>), latitude (<code>y</code>) in radians and
+   * height (<code>z</code>) in meters of the eye (camera).
+   * This is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
+   * @memberof UniformState.prototype
+   * @type {Cartesian3}
+   */
+  eyeCartographic: {
+    get: function () {
+      return this._eyeCartographic;
+    },
+  },
+
   /**
    * The height (<code>x</code>) and the height squared (<code>y</code>)
    * in meters of the eye (camera) above the 2D world plane. This uniform is only valid
@@ -751,9 +766,22 @@ Object.defineProperties(UniformState.prototype, {
     },
   },
 
+  /**
+   * A 3x3 rotation from eye coordinates to an east-north-up coordinate system
+   * centered at the position on the ellipsoid below the camera.
+   * This uniform is only valid when the {@link SceneMode} is <code>SCENE3D</code>.
+   * @memberof UniformState.prototype
+   * @type {Matrix3}
+   */
+  eyeToEnu: {
+    get: function () {
+      return this._eyeToEnu;
+    },
+  },
+
   /**
    * A transform from model coordinates to an east-north-up coordinate system
-   * centered at the position on the ellipsoid below the camera
+   * centered at the position on the ellipsoid nearest to the camera.
    * @memberof UniformState.prototype
    * @type {Matrix4}
    */
@@ -1241,6 +1269,7 @@ function setInfiniteProjection(uniformState, matrix) {
 
 const surfacePositionScratch = new Cartesian3();
 const enuTransformScratch = new Matrix4();
+const enuRotationScratch = new Matrix3();
 
 function setCamera(uniformState, camera) {
   Cartesian3.clone(camera.positionWC, uniformState._cameraPosition);
@@ -1266,6 +1295,12 @@ function setCamera(uniformState, camera) {
     );
   } else {
     uniformState._eyeHeight = positionCartographic.height;
+    uniformState._eyeCartographic = Cartesian3.fromElements(
+      positionCartographic.longitude,
+      positionCartographic.latitude,
+      positionCartographic.height,
+      uniformState._eyeCartographic,
+    );
     uniformState._eyeEllipsoidNormalEC =
       ellipsoid.geodeticSurfaceNormalCartographic(
         positionCartographic,
@@ -1307,6 +1342,17 @@ function setCamera(uniformState, camera) {
     uniformState._modelToEnu,
   );
 
+  const enuToWorldRotation = Matrix4.getRotation(
+    enuToWorld,
+    enuRotationScratch,
+  );
+  const enuToView = Matrix3.multiply(
+    uniformState._viewRotation,
+    enuToWorldRotation,
+    enuRotationScratch,
+  );
+  uniformState._eyeToEnu = Matrix3.transpose(enuToView, uniformState._eyeToEnu);
+
   if (
     !CesiumMath.equalsEpsilon(
       ellipsoid._radii.x,

package/Source/Scene/ArcGisMapService.js

@@ -4,7 +4,7 @@ import Resource from "../Core/Resource.js";
 
 let defaultTokenCredit;
 const defaultAccessToken =
-  "AAPTa7BPWL4PoZRFPJ2CM2YRclg..ub1vMOBXctC7ozMMKNnmx3ZwVTsDJAXo2GLomQ2CZjuOc2HLr1-CryeuRo9ZsV65cuZ9xN1yFKeLTu7Cxld7B97aI28os_NnuC9nvWde_l4G1DTApSHmhrVoZfKgO0bqOrsDfvvSgO-cdkUEvBASNX_4Lb9tB5fEY7lbYaWdOOWBXyZylR9il0-biB248V6HdDT1kgkSwz9esfKialRTLgxJx8AFM9is--UXK0CLvZn6JUU44PZSFuMyAT1_rgxsirsZ";
+  "AAPTaeRGM19PsTpo1ePVkJZk4Tg..zqn3rpU4kUaF-8QMW-oWZntlxvKhdUFXLBoo5dQwRNEKd1EoKJh-Ha2zxbrz2Nhz2tV_gLVZTQwFHLzJHKwsGDz4GTKV8jeUgb12Ci9CeU_9sOrauJYnGK2vHhtSSAQ-73rmKzNG_2lZ0zuCCEKslxCmXUw2mT1Cpk0RoCCtDheWByX1e7Lnb3LKCBDt9VhGFSGCOiaFfizFRLld8LWukKgxCgluTpKgUuUi4OytX84roEpm6mP7PE91AT1_5Uash6To";
 /**
  * Default options for accessing the ArcGIS image tile service.
  *

package/Source/Scene/BufferPointCollection.js

@@ -12,6 +12,7 @@ import BufferPointMaterial from "./BufferPointMaterial.js";
 /** @import ComponentDatatype from "../Core/ComponentDatatype.js"; */
 /** @import Matrix4 from "../Core/Matrix4.js"; */
 /** @import FrameState from "./FrameState.js"; */
+/** @import { BufferPrimitiveCollectionOptions } from "./BufferPrimitiveCollection.js"; */
 
 /**
  * @typedef {object} BufferPointOptions
@@ -91,17 +92,13 @@ class BufferPointCollection extends BufferPrimitiveCollection {
   // COLLECTION LIFECYCLE
 
   /**
-   * @param {BufferPointCollection} collection
+   * @param {BufferPrimitiveCollectionOptions} [options]
    * @returns {BufferPointCollection}
    * @override
    * @ignore
    */
-  static _cloneEmpty(collection) {
-    return new BufferPointCollection({
-      primitiveCountMax: collection.primitiveCountMax,
-      positionDatatype: collection.positionDatatype,
-      positionNormalized: collection.positionNormalized,
-    });
+  _cloneEmpty(options = Frozen.EMPTY_OBJECT) {
+    return new BufferPointCollection(this._cloneEmptyBaseArgs(options));
   }
 
   /////////////////////////////////////////////////////////////////////////////

package/Source/Scene/BufferPolygonCollection.js

@@ -14,6 +14,7 @@ import BufferPolygonMaterial from "./BufferPolygonMaterial.js";
 /** @import { TypedArray } from "../Core/globalTypes.js"; */
 /** @import Matrix4 from "../Core/Matrix4.js"; */
 /** @import FrameState from "./FrameState.js" */
+/** @import HeightReference from "./HeightReference.js"; */
 /** @import ComponentDatatype from "../Core/ComponentDatatype.js"; */
 
 const { ERR_CAPACITY } = BufferPrimitiveCollection.Error;
@@ -31,6 +32,29 @@ const { ERR_CAPACITY } = BufferPrimitiveCollection.Error;
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  */
 
+/**
+ * @typedef {object} BufferPolygonCollectionOptions
+ * @property {number} [primitiveCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY] Maximum number of polygons.
+ * @property {number} [vertexCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY] Maximum number of vertices.
+ * @property {number} [holeCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY] Maximum number of holes.
+ * @property {number} [triangleCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY] Maximum number of triangles.
+ * @property {ComponentDatatype} [positionDatatype=ComponentDatatype.DOUBLE] The component datatype used to store position values.
+ * @property {boolean} [positionNormalized=false] When <code>true</code>, integer position values are treated as normalized,
+ *   where the full integer range maps to [-1, 1] (signed) or [0, 1] (unsigned). Only relevant for integer position datatypes
+ *   (BYTE, UNSIGNED_BYTE, SHORT, UNSIGNED_SHORT).
+ * @property {boolean} [show=true]
+ * @property {boolean} [allowPicking=true] When <code>true</code>, primitives are pickable with {@link Scene#pick}. When <code>false</code>, memory and initialization cost are lower.
+ * @property {BoundingSphere} [boundingVolume] Bounding volume, in world space, for the collection. When
+ *    unspecified, a bounding volume is computed automatically and updated when primitive positions change. When
+ *    specified, users are responsible for updating bounding volume as needed. Pre-computing the bounding volume
+ *    manually, and updating it only as needed, will improve performance for larger dynamic collections.
+ * @property {boolean} [debugShowBoundingVolume=false]
+ * @property {BlendOption} [blendOption=BlendOption.TRANSLUCENT]
+ * @property {HeightReference} [heightReference=HeightReference.NONE] When set to a clamping value, the
+ *   collection is draped onto terrain and/or 3D Tiles, rather than drawn as geometry of its own.
+ * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
+ */
+
 /**
  * Collection of polygons held in ArrayBuffer storage for performance and memory optimization.
  *
@@ -76,21 +100,7 @@ const { ERR_CAPACITY } = BufferPrimitiveCollection.Error;
  */
 class BufferPolygonCollection extends BufferPrimitiveCollection {
   /**
-   * @param {object} options
-   * @param {number} [options.primitiveCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
-   * @param {number} [options.vertexCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
-   * @param {number} [options.holeCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
-   * @param {number} [options.triangleCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
-   * @param {ComponentDatatype} [options.positionDatatype=ComponentDatatype.DOUBLE]
-   * @param {boolean} [options.positionNormalized=false]
-   * @param {boolean} [options.show=true]
-   * @param {boolean} [options.allowPicking=true] When <code>true</code>, primitives are pickable with {@link Scene#pick}. When <code>false</code>, memory and initialization cost are lower.
-   * @param {BoundingSphere} [options.boundingVolume] Bounding volume, in world space, for the collection. When
-   *    unspecified, a bounding volume is computed automatically and updated when primitive positions change. When
-   *    specified, users are responsible for updating bounding volume as needed. Pre-computing the bounding volume
-   *    manually, and updating it only as needed, will improve performance for larger dynamic collections.
-   * @param {boolean} [options.debugShowBoundingVolume=false]
-   * @param {BlendOption} [options.blendOption=BlendOption.TRANSLUCENT]
+   * @param {BufferPolygonCollectionOptions} [options]
    */
   constructor(options = Frozen.EMPTY_OBJECT) {
     super(options);
@@ -193,10 +203,16 @@ class BufferPolygonCollection extends BufferPrimitiveCollection {
    *
    * @param {BufferPolygonCollection} collection
    * @param {BufferPolygonCollection} result
+   * @param {function(BufferPolygon, number): boolean} [predicate] When provided, only polygons for which this returns <code>true</code> are copied. Surviving polygons are compacted into contiguous indices.
    * @returns {BufferPolygonCollection}
    */
-  static clone(collection, result) {
-    super.clone(collection, result);
+  static clone(collection, result, predicate) {
+    super.clone(collection, result, predicate);
+
+    // Base class's filtered clone uses PrimitiveClass.clone, which handles holes and triangles, so just return the result.
+    if (defined(predicate)) {
+      return result;
+    }
 
     //>>includeStart('debug', pragmas.debug);
     assert(collection.holeCount <= result.holeCountMax, ERR_CAPACITY);
@@ -222,19 +238,33 @@ class BufferPolygonCollection extends BufferPrimitiveCollection {
   }
 
   /**
-   * @param {BufferPolygonCollection} collection
+   * Returns a copy of the given collection, overriding any constructor options
+   * provided. Omitted options are inherited from the source collection. Any
+   * resized buffers must be large enough to hold every polygon.
+   *
+   * @param {BufferPolygonCollection} collection Source collection to copy.
+   * @param {BufferPolygonCollectionOptions} [options] Constructor options to override. Omitted options are inherited from the source collection.
+   * @param {function(BufferPolygon, number): boolean} [predicate] When provided, only polygons for which this returns <code>true</code> are copied. Surviving polygons are compacted into contiguous indices.
+   * @returns {BufferPolygonCollection}
+   * @override
+   */
+  static fromCollection(collection, options, predicate) {
+    return /** @type {BufferPolygonCollection} */ (
+      super.fromCollection(collection, options, predicate)
+    );
+  }
+
+  /**
+   * @param {BufferPolygonCollectionOptions} [options]
    * @returns {BufferPolygonCollection}
    * @override
    * @ignore
    */
-  static _cloneEmpty(collection) {
+  _cloneEmpty(options = Frozen.EMPTY_OBJECT) {
     return new BufferPolygonCollection({
-      primitiveCountMax: collection.primitiveCountMax,
-      vertexCountMax: collection.vertexCountMax,
-      holeCountMax: collection.holeCountMax,
-      triangleCountMax: collection.triangleCountMax,
-      positionDatatype: collection.positionDatatype,
-      positionNormalized: collection.positionNormalized,
+      holeCountMax: this.holeCountMax,
+      triangleCountMax: this.triangleCountMax,
+      ...this._cloneEmptyBaseArgs(options),
     });
   }
 
@@ -305,8 +335,7 @@ class BufferPolygonCollection extends BufferPrimitiveCollection {
   update(frameState) {
     super.update(frameState);
 
-    const passes = frameState.passes;
-    if (this.show && (passes.render || passes.pick)) {
+    if (this._isRendered(frameState)) {
       this._renderContext = renderPolygons(
         this,
         frameState,

package/Source/Scene/BufferPolylineCollection.js

@@ -1,6 +1,8 @@
 // @ts-check
 
 import defined from "../Core/defined.js";
+import DeveloperError from "../Core/DeveloperError.js";
+import Frozen from "../Core/Frozen.js";
 import BufferPrimitiveCollection from "./BufferPrimitiveCollection.js";
 import BufferPolyline from "./BufferPolyline.js";
 import renderPolylines from "./renderBufferPolylineCollection.js";
@@ -8,7 +10,12 @@ import BufferPolylineMaterial from "./BufferPolylineMaterial.js";
 
 /** @import { TypedArray } from "../Core/globalTypes.js"; */
 /** @import Matrix4 from "../Core/Matrix4.js"; */
+/** @import BoundingSphere from "../Core/BoundingSphere.js"; */
+/** @import ComponentDatatype from "../Core/ComponentDatatype.js"; */
+/** @import BlendOption from "./BlendOption.js"; */
+/** @import HeightReference from "./HeightReference.js"; */
 /** @import FrameState from "./FrameState.js" */
+/** @import { BufferPrimitiveCollectionOptions } from "./BufferPrimitiveCollection.js"; */
 
 /**
  * @typedef {object} BufferPolylineOptions
@@ -57,6 +64,55 @@ import BufferPolylineMaterial from "./BufferPolylineMaterial.js";
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  */
 class BufferPolylineCollection extends BufferPrimitiveCollection {
+  /**
+   * @param {object} [options]
+   * @param {Matrix4} [options.modelMatrix=Matrix4.IDENTITY] Transforms geometry from model to world coordinates.
+   * @param {number} [options.primitiveCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
+   * @param {number} [options.vertexCountMax=BufferPrimitiveCollection.DEFAULT_CAPACITY]
+   * @param {boolean} [options.show=true]
+   * @param {ComponentDatatype} [options.positionDatatype=ComponentDatatype.DOUBLE]
+   * @param {boolean} [options.positionNormalized=false]
+   * @param {boolean} [options.allowPicking=false] When <code>true</code>, primitives are pickable with {@link Scene#pick}. When <code>false</code>, memory and initialization cost are lower.
+   * @param {BoundingSphere} [options.boundingVolume] Bounding volume, in world space, for the collection.
+   * @param {boolean} [options.debugShowBoundingVolume=false]
+   * @param {BlendOption} [options.blendOption=BlendOption.TRANSLUCENT]
+   * @param {HeightReference} [options.heightReference=HeightReference.NONE]
+   * @param {"pixels"|"meters"} [options.widthUnits="pixels"] Unit of polyline widths in this collection:
+   *   <code>"pixels"</code> on the screen, or <code>"meters"</code> in world space. A clamped
+   *   {@link HeightReference} measures those meters on the ellipsoid surface, so elevation and terrain
+   *   slope stretch the drawn width.
+   */
+  constructor(options = Frozen.EMPTY_OBJECT) {
+    super(options);
+
+    const widthUnits = options.widthUnits ?? "pixels";
+
+    //>>includeStart('debug', pragmas.debug);
+    if (widthUnits !== "pixels" && widthUnits !== "meters") {
+      throw new DeveloperError(
+        'options.widthUnits must be "pixels" or "meters".',
+      );
+    }
+    //>>includeEnd('debug');
+
+    /**
+     * @type {"pixels"|"meters"}
+     * @private
+     */
+    this._widthUnits = widthUnits;
+  }
+
+  /**
+   * Unit of polyline widths in this collection: <code>"pixels"</code> on the screen, or
+   * <code>"meters"</code> in world space, measured on the ellipsoid surface when clamped.
+   *
+   * @type {"pixels"|"meters"}
+   * @readonly
+   */
+  get widthUnits() {
+    return this._widthUnits;
+  }
+
   _getCollectionClass() {
     return BufferPolylineCollection;
   }
@@ -73,17 +129,15 @@ class BufferPolylineCollection extends BufferPrimitiveCollection {
   // COLLECTION LIFECYCLE
 
   /**
-   * @param {BufferPolylineCollection} collection
+   * @param {BufferPrimitiveCollectionOptions} [options]
    * @returns {BufferPolylineCollection}
    * @override
    * @ignore
    */
-  static _cloneEmpty(collection) {
+  _cloneEmpty(options = Frozen.EMPTY_OBJECT) {
     return new BufferPolylineCollection({
-      primitiveCountMax: collection.primitiveCountMax,
-      vertexCountMax: collection.vertexCountMax,
-      positionDatatype: collection.positionDatatype,
-      positionNormalized: collection.positionNormalized,
+      widthUnits: this._widthUnits,
+      ...this._cloneEmptyBaseArgs(options),
     });
   }
 
@@ -126,8 +180,7 @@ class BufferPolylineCollection extends BufferPrimitiveCollection {
   update(frameState) {
     super.update(frameState);
 
-    const passes = frameState.passes;
-    if (this.show && (passes.render || passes.pick)) {
+    if (this._isRendered(frameState)) {
       this._renderContext = renderPolylines(
         this,
         frameState,

package/Source/Scene/BufferPolylineMaterial.js

@@ -11,7 +11,8 @@ import BufferPrimitiveMaterial from "./BufferPrimitiveMaterial.js";
  * @property {Color} [color=Color.WHITE] Color of fill.
  * @property {Color} [outlineColor=Color.WHITE] Color of outline.
  * @property {number} [outlineWidth=0.0] Width of outline, 0-255px.
- * @property {number} [width=1.0] Width of line, 0-255px.
+ * @property {number} [width=1.0] Width of line, in the unit selected by
+ *   {@link BufferPolylineCollection#widthUnits}.
  */
 
 /**
@@ -28,7 +29,7 @@ class BufferPolylineMaterial extends BufferPrimitiveMaterial {
   /** @ignore */
   static Layout = {
     ...BufferPrimitiveMaterial.Layout,
-    WIDTH_U8: BufferPrimitiveMaterial.Layout.__BYTE_LENGTH,
+    WIDTH_F32: BufferPrimitiveMaterial.Layout.__BYTE_LENGTH,
     __BYTE_LENGTH: BufferPrimitiveMaterial.Layout.__BYTE_LENGTH + 4,
   };
 
@@ -45,7 +46,7 @@ class BufferPolylineMaterial extends BufferPrimitiveMaterial {
     super(options);
 
     /**
-     * Width of polyline, 0–255px.
+     * Width of polyline, in the unit selected by {@link BufferPolylineCollection#widthUnits}.
      * @type {number}
      */
     this.width = options.width ?? 1;
@@ -59,7 +60,7 @@ class BufferPolylineMaterial extends BufferPrimitiveMaterial {
    */
   static pack(material, view, byteOffset) {
     super.pack(material, view, byteOffset);
-    view.setUint8(this.Layout.WIDTH_U8 + byteOffset, material.width);
+    view.setFloat32(this.Layout.WIDTH_F32 + byteOffset, material.width, true);
   }
 
   /**
@@ -71,7 +72,7 @@ class BufferPolylineMaterial extends BufferPrimitiveMaterial {
    */
   static unpack(view, byteOffset, result) {
     super.unpack(view, byteOffset, result);
-    result.width = view.getUint8(this.Layout.WIDTH_U8 + byteOffset);
+    result.width = view.getFloat32(this.Layout.WIDTH_F32 + byteOffset, true);
     return result;
   }