feat: Introduce SampledProperty new function getSample

CHANGES.md

@@ -6,6 +6,7 @@
 
 ##### Additions :tada:
 
+- Added `getSample` to `SampledProperty` to get the time of samples. [#12253](https://github.com/CesiumGS/cesium/pull/12253)
 - Added `ScreenSpaceCameraController.maximumTiltAngle` to limit how much the camera can tilt. [#12169](https://github.com/CesiumGS/cesium/pull/12169)
 
 ### 1.122 - 2024-10-01

packages/engine/Source/DataSources/SampledProperty.js

@@ -674,6 +674,30 @@ SampledProperty.prototype.addSamples = function (
   this._definitionChanged.raiseEvent(this);
 };
 
+/**
+ * Gets the time of the sample. Negative for backward.
+ *
+ * @param {number} index The index of samples list.
+ * @returns {JulianDate | undefined} The JulianDate time of the sample, or undefined if failed.
+ */
+SampledProperty.prototype.getSample = function (index) {
+  //>>includeStart('debug', pragmas.debug);
+  Check.defined("index", index);
+  //>>includeEnd('debug');
+
+  const times = this._times;
+  const len = times.length;
+  if (!len) {
+    return undefined;
+  }
+
+  if (index < 0) {
+    index += len;
+  }
+
+  return times[index];
+};
+
 /**
  * Adds samples as a single packed array where each new sample is represented as a date,
  * followed by the packed representation of the corresponding value and derivatives.

packages/engine/Specs/DataSources/SampledPropertySpec.js

@@ -110,6 +110,28 @@ describe("DataSources/SampledProperty", function () {
     expect(property.getValue(new JulianDate(0.5, 0))).toEqual(7.5);
   });
 
+  it("getSample works", function () {
+    const times = [
+      new JulianDate(0, 0),
+      new JulianDate(1, 0),
+      new JulianDate(2, 0),
+    ];
+    const values = [7, 8, 9];
+
+    const property = new SampledProperty(Number);
+    property.addSamples(times, values);
+
+    expect(property.getSample(0)).toEqual(times[0]);
+    expect(property.getSample(1)).toEqual(times[1]);
+    expect(property.getSample(2)).toEqual(times[2]);
+    expect(property.getSample(3)).toBe(undefined);
+
+    expect(property.getSample(-1)).toBe(times[2]);
+    expect(property.getSample(-2)).toBe(times[1]);
+    expect(property.getSample(-3)).toBe(times[0]);
+    expect(property.getSample(-4)).toBe(undefined);
+  });
+
   it("can remove a sample at a date", function () {
     const times = [
       new JulianDate(0, 0),