Cesium中SampledProperty的时间采样功能扩展解析

背景介绍

在Cesium这个强大的地理可视化引擎中，SampledProperty类是一个非常重要的组件，它用于处理随时间变化的属性值。开发者经常需要用它来处理动态数据，如移动物体的位置、旋转角度等。然而，当前版本的SampledProperty在时间采样功能上存在一些局限性，特别是在获取采样时间点方面。

现有问题分析

目前，SampledProperty内部维护了一个_times数组来存储所有采样时间点，但这个数组并未对外暴露。开发者只能通过间接方式获取最新时间点，这在实际应用中带来了诸多不便：

1. 无法获取完整时间序列：开发者无法直接访问所有采样时间点，难以实现复杂的时间相关逻辑
2. 最新时间点获取不便：虽然可以通过内部方法获取最新时间点，但这种方式不够直观
3. 时间索引访问缺失：无法通过索引直接访问特定位置的时间点

解决方案设计

针对上述问题，我们提出了几种API设计方案：

1. 获取最新时间点：

getLatestTime() {
  return this._times[this._times.length - 1];
}

2. 暴露时间数组： 提供一个只读的times属性，暴露_times数组内容，但确保外部无法修改

3. 索引访问时间点：

getTime(index) {
  // 支持负数索引，如-1表示最后一个元素
  return this._times[index < 0 ? this._times.length + index : index];
}

4. 明确命名的索引访问：

getTimeByIndex(index) {
  // 更明确的命名，但稍显冗长
  return this.getTime(index);
}

实际应用场景

这些API扩展在实际开发中有着广泛的应用价值：

实时位置保持

const pos = new Cesium.SampledProperty(Cesium.Cartesian3);
viewer.entities.add({
  position: new Cesium.CallbackProperty(time => {
    const val = pos.getValue(time);
    return val ?? pos.getValue(pos.getLatestTime());
  })
});

这种实现可以确保当没有新数据时，实体保持最后已知位置，而不是突然消失。

旋转姿态保持

const ori = new Cesium.SampledProperty(Cesium.Quaternion);
viewer.entities.add({
  orientation: new Cesium.CallbackProperty(time => {
    const val = ori.getValue(time);
    return val ?? ori.getValue(ori.getLatestTime());
  })
});

同样原理，这可以防止实体在没有新数据时突然回到默认姿态。

API设计考量

在最终API设计上，我们建议采用getSample方法名，这与现有的addSample方法形成良好对应，保持API的一致性。方法签名如下：

function getSample(index: number): Cesium.JulianDate

这种设计既保持了简洁性，又明确了方法用途，使开发者能够直观地理解和使用。

总结

通过对Cesium中SampledProperty类的时间采样功能扩展，我们能够为开发者提供更灵活、更强大的时间数据处理能力。这些改进将显著提升实时数据可视化场景下的用户体验，使动态实体的表现更加平滑自然。这一改进也体现了Cesium项目对开发者需求的积极响应和持续优化。