@cesium/engine 25.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/Pass.js

@@ -26,8 +26,9 @@ const Pass = {
   TRANSLUCENT: 9,
   VOXELS: 10,
   GAUSSIAN_SPLATS: 11,
-  OVERLAY: 12,
-  NUMBER_OF_PASSES: 13,
+  CESIUM_3D_TILE_EDGES_DIRECT: 12,
+  OVERLAY: 13,
+  NUMBER_OF_PASSES: 14,
 };
 
 Object.freeze(Pass);

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);