Cesium中SampledProperty类的采样时间访问优化

在Cesium三维地理可视化库中，SampledProperty类是一个用于处理随时间变化属性的重要组件。它允许开发者通过添加时间-值样本来定义属性如何随时间变化。然而，当前版本中，开发者无法直接访问这些样本的时间信息，这限制了某些高级应用场景的实现。

核心问题分析

SampledProperty类内部维护了一个时间数组_times，用于存储所有采样点的时间戳。目前这个数组是私有属性，外部无法直接访问。这导致开发者无法获取采样时间信息，从而难以实现一些常见的功能需求：

1. 当实时数据流中断时，无法让实体保持在最后一个有效位置
2. 无法基于时间索引进行精确查询
3. 难以实现自定义的插值或回退逻辑

解决方案设计

为了解决这个问题，我们建议为SampledProperty类增加以下API：

1. getSample(index) - 根据索引获取特定时间点

   • 支持负数索引，表示从末尾开始计数
   • 与现有的addSample方法命名风格一致

2. getSamples() - 获取所有时间样本的只读副本

   • 返回数组的浅拷贝，防止外部修改内部状态
   • 与addSamples方法对应

3. getLatestTime() - 便捷获取最后一个样本时间

   • 内部实现为this._times[this._times.length - 1]

应用场景示例

这些API的加入将显著增强SampledProperty的实用性：

// 实时位置保持示例
const position = new Cesium.SampledProperty(Cesium.Cartesian3);
viewer.entities.add({
  position: new Cesium.CallbackProperty(time => {
    const val = position.getValue(time);
    return val ?? position.getValue(position.getLatestTime());
  })
});

// 旋转姿态保持示例
const orientation = new Cesium.SampledProperty(Cesium.Quaternion);
viewer.entities.add({
  orientation: new Cesium.CallbackProperty(time => {
    const val = orientation.getValue(time);
    return val ?? orientation.getValue(orientation.getLatestTime());
  })
});

在这些示例中，当实时数据流中断时，实体不会突然消失或重置，而是保持在最后一个有效位置，直到新数据到达。这大大提升了用户体验和应用的稳定性。

实现考量

在实现这些API时，需要注意以下几点：

1. 数据安全性：必须确保外部代码无法直接修改内部时间数组
2. 性能优化：频繁调用时应避免不必要的数组拷贝
3. API一致性：新API应与现有方法命名风格保持一致
4. 边界处理：对无效索引应有明确的处理逻辑

总结

通过为SampledProperty类增加时间样本访问API，Cesium将能够更好地支持实时数据可视化场景，特别是那些需要处理数据中断或延迟的情况。这一改进既保持了API的简洁性，又显著扩展了功能灵活性，是框架演进的重要一步。