@cesium/engine 26.0.0 → 26.1.0

package/Source/DataSources/PathGraphics.js

@@ -14,10 +14,11 @@ import createPropertyDescriptor from "./createPropertyDescriptor.js";
  * @property {Property | number} [leadTime] A Property specifying the number of seconds in front the object to show.
  * @property {Property | number} [trailTime] A Property specifying the number of seconds behind of the object to show.
  * @property {Property | number} [width=1.0] A numeric Property specifying the width in pixels.
- * @property {Property | number} [resolution=60] A numeric Property specifying the maximum number of seconds to step when sampling the position.
+ * @property {Property | number} [resolution=60] A numeric Property specifying the maximum number of seconds to step when sampling the position. Fractional positive values are allowed; in PORTIONS materialMode, non-positive values fall back to the default resolution of 60 seconds.
  * @property {MaterialProperty | Color} [material=Color.WHITE] A Property specifying the material used to draw the path.
  * @property {Property | DistanceDisplayCondition} [distanceDisplayCondition] A Property specifying at what distance from the camera that this path will be displayed.
  * @property {Property | string} [relativeTo] A Property specifying the frame in which to visualize the path. Use another entity's id to visualize the path relative to that entity, or use the string values "FIXED" or "INERTIAL" to visualize the path in those reference frames.
+ * @property {Property | PathMode} [materialMode] A Property specifying how material properties are applied along the path.
  */
 
 /**
@@ -46,6 +47,8 @@ function PathGraphics(options) {
   this._distanceDisplayConditionSubscription = undefined;
   this._relativeTo = undefined;
   this._relativeToSubscription = undefined;
+  this._materialMode = undefined;
+  this._materialModeSubscription = undefined;
 
   this.merge(options ?? Frozen.EMPTY_OBJECT);
 }
@@ -95,6 +98,7 @@ Object.defineProperties(PathGraphics.prototype, {
 
   /**
    * Gets or sets the Property specifying the maximum number of seconds to step when sampling the position.
+   * Fractional positive values are allowed; in PORTIONS materialMode, non-positive values fall back to the default resolution of 60 seconds.
    * @memberof PathGraphics.prototype
    * @type {Property|undefined}
    * @default 60
@@ -125,6 +129,7 @@ Object.defineProperties(PathGraphics.prototype, {
    * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
    */
   relativeTo: createPropertyDescriptor("relativeTo"),
+  materialMode: createPropertyDescriptor("materialMode"),
 });
 
 /**
@@ -145,6 +150,7 @@ PathGraphics.prototype.clone = function (result) {
   result.material = this.material;
   result.distanceDisplayCondition = this.distanceDisplayCondition;
   result.relativeTo = this.relativeTo;
+  result.materialMode = this.materialMode;
   return result;
 };
 
@@ -170,5 +176,6 @@ PathGraphics.prototype.merge = function (source) {
   this.distanceDisplayCondition =
     this.distanceDisplayCondition ?? source.distanceDisplayCondition;
   this.relativeTo = this.relativeTo ?? source.relativeTo;
+  this.materialMode = this.materialMode ?? source.materialMode;
 };
 export default PathGraphics;

package/Source/DataSources/PathMode.js

@@ -0,0 +1,27 @@
+// @ts-check
+
+/**
+ * Defines how material properties are applied along a path.
+ *
+ * @enum {number}
+ */
+const PathMode = {
+  /**
+   * The material is applied to the entire path as a whole.
+   * @type {number}
+   * @constant
+   */
+  WHOLE: 0,
+
+  /**
+   * The material is applied in portions based on temporal position information,
+   * using interval-based material properties.
+   * @type {number}
+   * @constant
+   */
+  PORTIONS: 1,
+};
+
+Object.freeze(PathMode);
+
+export default PathMode;

package/Source/DataSources/PathVisualizer.js

@@ -17,12 +17,14 @@ import CallbackPositionProperty from "./CallbackPositionProperty.js";
 import CompositePositionProperty from "./CompositePositionProperty.js";
 import ConstantPositionProperty from "./ConstantPositionProperty.js";
 import MaterialProperty from "./MaterialProperty.js";
+import PathMode from "./PathMode.js";
 import Property from "./Property.js";
 import ReferenceProperty from "./ReferenceProperty.js";
 import SampledPositionProperty from "./SampledPositionProperty.js";
 import ScaledPositionProperty from "./ScaledPositionProperty.js";
 import TimeIntervalCollectionPositionProperty from "./TimeIntervalCollectionPositionProperty.js";
 import Quaternion from "../Core/Quaternion.js";
+import arrayRemoveDuplicates from "../Core/arrayRemoveDuplicates.js";
 
 const update3DMatrix3Scratch1 = new Matrix3();
 const update3DMatrix3Scratch2 = new Matrix3();
@@ -210,6 +212,7 @@ const subSampleIntervalPropertyScratch = new TimeInterval();
 function EntityData(entity) {
   this.entity = entity;
   this.polyline = undefined;
+  this.segmentPolylines = [];
   this.index = undefined;
   this.updater = undefined;
 }
@@ -734,6 +737,111 @@ function subSample(
 const toFixedScratch = new Matrix3();
 const updateOrientationScratch = new Quaternion();
 const updateRotationScratch = new Matrix3();
+const portionsVisibleIntervalScratch = new TimeInterval();
+const portionsSegmentIntervalScratch = new TimeInterval();
+const portionsDynamicIntervalScratch = new TimeInterval();
+
+function getDynamicMaterialProperties(materialData) {
+  const dynamic = [];
+  if (!defined(materialData)) {
+    return dynamic;
+  }
+
+  for (const key in materialData) {
+    // Material properties store uniforms as underscored backing fields.
+    // Ignore event and subscription bookkeeping fields.
+    if (
+      key[0] !== "_" ||
+      key === "_definitionChanged" ||
+      key.endsWith("Subscription")
+    ) {
+      continue;
+    }
+
+    const prop = materialData[key];
+    if (
+      defined(prop) &&
+      typeof prop.getValue === "function" &&
+      !Property.isConstant(prop)
+    ) {
+      dynamic.push(prop);
+    }
+  }
+
+  return dynamic;
+}
+
+function emitSegmentsForSplitTimes(
+  splitTimes,
+  positionProperty,
+  time,
+  pathGraphics,
+  entity,
+  item,
+  polylineCollection,
+  resolution,
+  referenceFrame,
+  materialProp,
+  startingSegIndex,
+) {
+  // Sort and dedupe
+  splitTimes.sort(JulianDate.compare);
+  splitTimes = arrayRemoveDuplicates(splitTimes, JulianDate.equalsEpsilon);
+
+  let segIndex = startingSegIndex;
+  for (let j = 0; j < splitTimes.length - 1; j++) {
+    const splitStart = splitTimes[j];
+    const splitStop = splitTimes[j + 1];
+    if (!JulianDate.lessThan(splitStart, splitStop)) {
+      continue;
+    }
+
+    // Get segment midpoint
+    const splitMidTime = JulianDate.addSeconds(
+      splitStart,
+      JulianDate.secondsDifference(splitStop, splitStart) / 2,
+      new JulianDate(),
+    );
+
+    // Subsample positions
+    const subPositions = subSample(
+      positionProperty,
+      splitStart,
+      splitStop,
+      time,
+      referenceFrame,
+      resolution,
+      [],
+    );
+    if (subPositions.length < 2) {
+      continue;
+    }
+
+    // Get or create a polyline for this segment
+    let segPolyline = item.segmentPolylines[segIndex];
+    if (!defined(segPolyline)) {
+      segPolyline = polylineCollection.add();
+      segPolyline.id = entity;
+      item.segmentPolylines[segIndex] = segPolyline;
+    }
+    segPolyline.show = true;
+    segPolyline.positions = subPositions;
+    segPolyline.material = MaterialProperty.getValue(
+      splitMidTime,
+      materialProp,
+      segPolyline.material,
+    );
+    segPolyline.width = Property.getValueOrDefault(
+      pathGraphics._width,
+      time,
+      defaultWidth,
+    );
+
+    segIndex++;
+  }
+  return segIndex;
+}
+
 function PolylineUpdater(scene, referenceFrame) {
   this._unusedIndexes = [];
   this._polylineCollection = new PolylineCollection();
@@ -845,6 +953,9 @@ PolylineUpdater.prototype.updateObject = function (time, item) {
       polyline.show = false;
       item.index = undefined;
     }
+    for (let j = 0; j < item.segmentPolylines.length; j++) {
+      item.segmentPolylines[j].show = false;
+    }
     return;
   }
 
@@ -883,16 +994,198 @@ PolylineUpdater.prototype.updateObject = function (time, item) {
   // This can happen if the position is sampled at a time when it is only defined at a single point
   if (positions.length < 2) {
     polyline.show = false;
+    for (let j = 0; j < item.segmentPolylines.length; j++) {
+      item.segmentPolylines[j].show = false;
+    }
     return;
   }
 
   polyline.show = true;
   polyline.positions = positions;
+
   polyline.material = MaterialProperty.getValue(
     time,
-    pathGraphics._material,
+    pathGraphics.material,
     polyline.material,
   );
+
+  const materialMode = Property.getValueOrUndefined(
+    pathGraphics.materialMode,
+    time,
+  );
+  const materialProp = pathGraphics.material;
+  if (materialMode === PathMode.PORTIONS && !materialProp.isConstant) {
+    // Hide the single polyline if it exists
+    if (defined(polyline)) {
+      polyline.show = false;
+    }
+
+    // Prevent non-positive split steps from creating non-terminating loops.
+    // Positive fractional resolutions are valid; only values <= 0 fall back to the default.
+    const splitResolution = resolution > 0 ? resolution : defaultResolution;
+
+    const intervals = materialProp.intervals;
+    let nextSegIndex = 0;
+
+    if (!defined(intervals)) {
+      // Sampled/interpolated root material - generate synthetic times at resolution intervals
+      const splitTimes = [
+        JulianDate.clone(sampleStart),
+        JulianDate.clone(sampleStop),
+      ];
+      let splitTime = JulianDate.addSeconds(
+        sampleStart,
+        splitResolution,
+        new JulianDate(),
+      );
+      while (JulianDate.lessThan(splitTime, sampleStop)) {
+        splitTimes.push(JulianDate.clone(splitTime));
+        splitTime = JulianDate.addSeconds(
+          splitTime,
+          splitResolution,
+          new JulianDate(),
+        );
+      }
+      nextSegIndex = emitSegmentsForSplitTimes(
+        splitTimes,
+        positionProperty,
+        time,
+        pathGraphics,
+        entity,
+        item,
+        this._polylineCollection,
+        splitResolution,
+        this._referenceFrame,
+        pathGraphics.material,
+        nextSegIndex,
+      );
+    } else {
+      portionsVisibleIntervalScratch.start = sampleStart;
+      portionsVisibleIntervalScratch.stop = sampleStop;
+      portionsVisibleIntervalScratch.isStartIncluded = true;
+      portionsVisibleIntervalScratch.isStopIncluded = true;
+
+      // Interval-based material - process each interval separately
+      for (let i = 0; i < intervals.length; i++) {
+        const interval = intervals.get(i);
+
+        if (
+          !TimeInterval.intersect(
+            interval,
+            portionsVisibleIntervalScratch,
+            portionsSegmentIntervalScratch,
+          )
+        ) {
+          continue;
+        }
+
+        const segStart = portionsSegmentIntervalScratch.start;
+        const segStop = portionsSegmentIntervalScratch.stop;
+
+        if (JulianDate.greaterThanOrEquals(segStart, segStop)) {
+          continue;
+        }
+
+        // Detect dynamic properties and collect their split times
+        const dynamic = getDynamicMaterialProperties(interval.data);
+        const splitTimes = [
+          JulianDate.clone(segStart),
+          JulianDate.clone(segStop),
+        ];
+
+        for (let j = 0; j < dynamic.length; j++) {
+          const prop = dynamic[j];
+          const timeDynamicIntervals = prop.intervals;
+
+          if (defined(timeDynamicIntervals)) {
+            // Interval-based property: collect interval boundaries
+            for (let k = 0; k < timeDynamicIntervals.length; k++) {
+              const timeDynamicInterval = timeDynamicIntervals.get(k);
+
+              if (
+                !TimeInterval.intersect(
+                  timeDynamicInterval,
+                  portionsSegmentIntervalScratch,
+                  portionsDynamicIntervalScratch,
+                )
+              ) {
+                continue;
+              }
+
+              if (
+                JulianDate.greaterThan(
+                  portionsDynamicIntervalScratch.start,
+                  segStart,
+                ) &&
+                JulianDate.lessThan(
+                  portionsDynamicIntervalScratch.start,
+                  segStop,
+                )
+              ) {
+                splitTimes.push(
+                  JulianDate.clone(portionsDynamicIntervalScratch.start),
+                );
+              }
+
+              if (
+                JulianDate.greaterThan(
+                  portionsDynamicIntervalScratch.stop,
+                  segStart,
+                ) &&
+                JulianDate.lessThan(
+                  portionsDynamicIntervalScratch.stop,
+                  segStop,
+                )
+              ) {
+                splitTimes.push(
+                  JulianDate.clone(portionsDynamicIntervalScratch.stop),
+                );
+              }
+            }
+          } else if (!Property.isConstant(prop)) {
+            // Sampled/interpolated property: add resolution-based split times
+            let sampledTime = JulianDate.clone(segStart);
+            while (JulianDate.lessThan(sampledTime, segStop)) {
+              splitTimes.push(JulianDate.clone(sampledTime));
+              sampledTime = JulianDate.addSeconds(
+                sampledTime,
+                splitResolution,
+                new JulianDate(),
+              );
+            }
+          }
+        }
+
+        // Emit segments for this interval's split times
+        nextSegIndex = emitSegmentsForSplitTimes(
+          splitTimes,
+          positionProperty,
+          time,
+          pathGraphics,
+          entity,
+          item,
+          this._polylineCollection,
+          splitResolution,
+          this._referenceFrame,
+          interval.data,
+          nextSegIndex,
+        );
+      }
+    }
+
+    // Hide any excess segment polylines from previous frames.
+    for (let j = nextSegIndex; j < item.segmentPolylines.length; j++) {
+      if (defined(item.segmentPolylines[j])) {
+        item.segmentPolylines[j].show = false;
+      }
+    }
+  } else {
+    // Not in PORTIONS mode, hide all segment polylines from previous frames
+    for (let j = 0; j < item.segmentPolylines.length; j++) {
+      item.segmentPolylines[j].show = false;
+    }
+  }
+
   polyline.width = Property.getValueOrDefault(
     pathGraphics._width,
     time,
@@ -914,6 +1207,10 @@ PolylineUpdater.prototype.removeObject = function (item) {
     polyline.id = undefined;
     item.index = undefined;
   }
+  for (let i = 0; i < item.segmentPolylines.length; i++) {
+    item.segmentPolylines[i].show = false;
+  }
+  item.segmentPolylines.length = 0;
 };
 
 PolylineUpdater.prototype.destroy = function () {

package/Source/Renderer/Texture.js

@@ -576,7 +576,7 @@ function loadNull(texture) {
 /**
  * This function is identical to using the Texture constructor except that it can be
  * replaced with a mock/spy in tests.
- * @private
+ * @ignore
  */
 Texture.create = function (options) {
   return new Texture(options);

package/Source/Renderer/VertexArray.js

@@ -16,6 +16,7 @@ import assert from "../Core/assert.js";
 
 /** @import {TypedArray, TypedArrayConstructor} from "../Core/globalTypes.js"; */
 
+/** @ignore */
 function addAttribute(attributes, attribute, index, context) {
   const hasVertexBuffer = defined(attribute.vertexBuffer);
   const hasValue = defined(attribute.value);

package/Source/Scene/ArcGisMapService.js

@@ -4,7 +4,7 @@ import Resource from "../Core/Resource.js";
 
 let defaultTokenCredit;
 const defaultAccessToken =
-  "AAPTauP-rqeCeHTtrSMga9XbPxQ..ZMIZzf1tcwicoJi5E5T2mG0EO3qlIRkQNe5S-uA95RJKU0YkrwOT0AF-lSIyXXBFakDJIPaxsZ5vpnzlaW3kCYG2Tk53bY6OntMqn1EBYtDPyqz38iM4NU_bbDN3DuxUdkxYDWnxJXxxWe3bEeUANbvhKK76PU7N0wjZgtEYHYocspYXSHxbCEYo_eXrHDkrWpgkzcmQ3WpQqf2XprJ39pbqVSZbxskDh3zBm92XxUaiSmdf7rC1w3VoAT1_UarLJfAQ";
+  "AAPTaNEKX8S_W5tHpwdW7Txp1uA..bCHyKIo32UDZUn0ep6bzo_JLzQdslNSJ9HpSru5K9nkNyUqvkKFceNFYUFPbtEEZPfCqpF_qVG3zdTZOzocx6Dnzy0e2LctUukYPVrG2GPAdcPN-M9nklag0M8cYMkSCHQOort_AeIxl8C7ORIX0KjE5Mrvbe0Rm3eC-YpZDiHp6PUyarwFpsRdcq1TvpcQqsqJQ3aoWdEIxnEjEZ6e6iZhte1i2oJgrZ8SxsSPaIbrjA4USgsQGeBjUAT1_V7gBCY6D";
 /**
  * Default options for accessing the ArcGIS image tile service.
  *

package/Source/Scene/BillboardTexture.js

@@ -199,9 +199,11 @@ BillboardTexture.prototype.loadImage = async function (
   let index;
   const atlas = this._billboardCollection.textureAtlas;
   try {
-    index = atlas.addImage(id, image, width, height);
-    if (index instanceof Promise) {
-      index = await index;
+    const indexOrPromise = atlas.addImage(id, image, width, height);
+    if (typeof indexOrPromise === "number") {
+      index = indexOrPromise;
+    } else {
+      index = await indexOrPromise;
     }
   } catch (error) {
     // There was an error loading the image

package/Source/Scene/Cesium3DTileOptimizations.js

@@ -49,12 +49,10 @@ Cesium3DTileOptimizations.checkChildrenWithinParent = function (tile) {
 
       // Check if the child has an oriented bounding box.
       const childBoundingVolume = child.boundingVolume;
-      if (
-        !(
-          childBoundingVolume instanceof TileOrientedBoundingBox ||
-          childBoundingVolume instanceof TileBoundingRegion
-        )
-      ) {
+      if (!(
+        childBoundingVolume instanceof TileOrientedBoundingBox ||
+        childBoundingVolume instanceof TileBoundingRegion
+      )) {
         // Do not support if the parent and child both do not have oriented bounding boxes.
         tile._optimChildrenWithinParent =
           Cesium3DTileOptimizationHint.SKIP_OPTIMIZATION;

package/Source/Scene/ClippingPlaneCollection.js

@@ -605,7 +605,7 @@ const scratchMatrix = new Matrix4();
 const scratchPlane = new Plane(Cartesian3.UNIT_X, 0.0);
 /**
  * Determines the type intersection with the planes of this ClippingPlaneCollection instance and the specified {@link TileBoundingVolume}.
- * @private
+ * @ignore
  *
  * @param {object} tileBoundingVolume The volume to determine the intersection with the planes.
  * @param {Matrix4} [transform] An optional, additional matrix to transform the plane to world coordinates.
@@ -656,7 +656,7 @@ ClippingPlaneCollection.prototype.computeIntersectionWithBoundingVolume =
  * @param {ClippingPlaneCollection} [clippingPlaneCollection] A ClippingPlaneCollection (or undefined) being attached to an object
  * @param {object} owner An Object that should receive the new ClippingPlaneCollection
  * @param {string} key The Key for the Object to reference the ClippingPlaneCollection
- * @private
+ * @ignore
  */
 ClippingPlaneCollection.setOwner = function (
   clippingPlaneCollection,

package/Source/Scene/ClippingPolygon.js

@@ -84,6 +84,7 @@ function ClippingPolygon(options) {
  *
  * @param {Cartesian3[]|undefined} input The input array
  * @returns {Cartesian3[]|undefined} The copy
+ * @ignore
  */
 function copyArrayCartesian3(input) {
   if (!defined(input)) {
@@ -110,6 +111,7 @@ function copyArrayCartesian3(input) {
  * @param {Cartesian3[]|undefined} a The first array
  * @param {Cartesian3[]|undefined} b The second array
  * @returns {boolean} Whether the arrays are equal
+ * @ignore
  */
 function equalsArrayCartesian3(a, b) {
   if (!defined(a) && !defined(b)) {

package/Source/Scene/ClippingPolygonCollection.js

@@ -897,7 +897,7 @@ const scratchRectangleIntersection = new Rectangle();
 const scratchRectanglePolygon = new Rectangle();
 /**
  * Determines the type intersection with the polygons of this ClippingPolygonCollection instance and the specified {@link TileBoundingVolume}.
- * @private
+ * @ignore
  *
  * @param {object} tileBoundingVolume The volume to determine the intersection with the polygons.
  * @param {Ellipsoid} [ellipsoid=Ellipsoid.default] The ellipsoid on which the bounding volumes are defined.
@@ -963,7 +963,7 @@ ClippingPolygonCollection.prototype.computeIntersectionWithBoundingVolume =
  * @param {ClippingPolygonCollection} [clippingPolygonsCollection] A ClippingPolygonCollection (or undefined) being attached to an object
  * @param {object} owner An Object that should receive the new ClippingPolygonCollection
  * @param {string} key The Key for the Object to reference the ClippingPolygonCollection
- * @private
+ * @ignore
  */
 ClippingPolygonCollection.setOwner = function (
   clippingPolygonsCollection,

package/Source/Scene/DerivedCommand.js

@@ -403,6 +403,7 @@ function getComponentCount(classProperty) {
  * @param {string} offset The offset
  * @param {string} scale The scale
  * @returns {string} The statement
+ * @ignore
  */
 function unapplyValueTransform(input, offset, scale) {
   return `((${input} - float(${offset})) / float(${scale}))`;
@@ -415,6 +416,7 @@ function unapplyValueTransform(input, offset, scale) {
  * @param {string} input The input value
  * @param {string} componentType The component type
  * @returns {string} The statement
+ * @ignore
  */
 function unnormalize(input, componentType) {
   const max = MetadataComponentType.getMaximum(componentType);
@@ -429,6 +431,7 @@ function unnormalize(input, componentType) {
  * @param {object} metadataProperty The metadata property, either
  * a `PropertyTextureProperty` or a `PropertyAttributeProperty`
  * @returns {string} The string
+ * @ignore
  */
 function getSourceValueStringScalar(classProperty, metadataProperty) {
   let result = `float(value)`;
@@ -457,6 +460,7 @@ function getSourceValueStringScalar(classProperty, metadataProperty) {
  * a `PropertyTextureProperty` or a `PropertyAttributeProperty`
  * @param {string} componentName The name, in ["x", "y", "z", "w"]
  * @returns {string} The string
+ * @ignore
  */
 function getSourceValueStringComponent(
   classProperty,

package/Source/Scene/Expression.js

@@ -1341,14 +1341,12 @@ Node.prototype._evaluateNegative = function (feature) {
 Node.prototype._evaluatePositive = function (feature) {
   const left = this._left.evaluate(feature);
 
-  if (
-    !(
-      left instanceof Cartesian2 ||
-      left instanceof Cartesian3 ||
-      left instanceof Cartesian4 ||
-      typeof left === "number"
-    )
-  ) {
+  if (!(
+    left instanceof Cartesian2 ||
+    left instanceof Cartesian3 ||
+    left instanceof Cartesian4 ||
+    typeof left === "number"
+  )) {
     throw new RuntimeError(
       `Operator "+" requires a vector or number argument. Argument is ${left}.`,
     );