轨迹回放播放器

CesiumTrackPlayer 是一个功能强大且轻量的 Cesium 轨迹回放封装类。它能将带时间戳的坐标数组转换为 Cesium 的动态属性,并自动托管时钟、相机、时间轴以及内置 UI 面板,实现丝滑的轨迹回放效果。

1. 引入文件

  • 第一步:引入框架地图关键文件
    • https://mhc.ixiera.com/mhc/main_min.js
    • https://mhc.ixiera.com/mhc/Cesium-1.120/Build/Cesium/Cesium.js
    • https://mhc.ixiera.com/mhc/Cesium3DTile.js
  • 第二步:引入轨迹回放播放器文件
    • https://mhc.ixiera.com/mhc/mchmap/TrackPlayer/js/CesiumTrackPlayer.min.js

2. 数据格式要求

load(data) 方法的 data 参数必须是一个数组,且至少包含两组数据。类内部会自动按时间进行升序排序。

时间字段 (time) 支持以下格式:

  • ISO 8601 字符串:"2024-01-01T12:00:00Z" (推荐)
  • 13位时间戳:1704100000000
  • 相对秒数:0, 10, 20 (配合 options.startTime 使用)
  • JS Date 对象:new Date()
 

位置字段 支持以下多种写法(任选其一):

    // 写法 1:扁平经纬度 (最常见)
    { time: '...', lon: 116.39, lat: 39.90, height: 100 }

    // 写法 2:嵌套 position 对象
    { time: '...', position: { lon: 116.39, lat: 39.90, alt: 100 } }

    // 写法 3:数组格式
    { time: '...', position: [116.39, 39.90, 100] }

    // 写法 4:Cesium 原生 Cartesian3 对象
    { time: '...', position: new Cesium.Cartesian3(x, y, z) }

3. 配置项 (options)

在实例化 new CesiumTrackPlayer(viewer, options) 时传入:

配置项数据类型默认值说明
呈现形态
modelUrlStringnull3D模型地址 (.glb/.gltf),优先级最高
modelScaleNumber1模型缩放比例
iconUrlStringnull2D图标地址,若未设模型则显示图标
pointColorColorYELLOW若未设模型和图标,显示的圆点颜色
轨迹线
showPathBooleantrue是否显示轨迹线
pathWidthNumber3轨迹线宽度
pathMaterialColorCYAN轨迹线颜色
pathLeadTimeNumberundefined往后预测显示的秒数 (例如:5表示显示未来5秒的轨迹)
pathTrailTimeNumberundefined往后拖尾显示的秒数 (例如:10表示保留过去10秒的轨迹)
时钟与播放
speedNumber1初始播放倍速
loopBooleantruetrue为循环播放,false为播放完停在终点
shouldAnimateBooleantrue加载后是否自动开始播放
followBooleantrue相机是否锁定跟随模型
flyToBooleantrue若未开启跟随,加载后是否自动飞向轨迹范围
插值算法
interpolationString'Lagrange''Lagrange' 或 'Hermite'
interpolationDegreeNumber1阶数越高越平滑,但过高会在急转弯处产生“鼓包”
模型朝向
modelHeadingOffsetNumber0模型自身航向角修正(例如模型车头朝左,可填入 90 修正)
orientationStopThresholdNumber0.1速度低于此值(m/s)视为静止,保持静止朝向防抖动
orientationMaxPitchNumbernull俯仰角限幅(度),防止高度突变时模型翻跟头
外部时间
startTimeString/Datenull强制指定起点时间
stopTimeString/Datenull强制指定终点时间
回调钩子
onTickFunctionnull每帧触发 (time, entity, self)
onPlayFunctionnull播放时触发
onPauseFunctionnull暂停时触发
onStopFunctionnull停止时触发

4. API 方法

通过 player.xxx() 来动态控制:

  • player.load(data)
    加载轨迹数据,返回创建的 Cesium.Entity 实例。会自动销毁旧轨迹。

  • player.play()
    开始/继续播放。如果当前已经处于终点,会自动重置到起点并重新播放。

  • player.pause()
    暂停播放,模型停在当前位置。

  • player.stop()
    停止播放,并将时钟强制重置到起点。

  • player.seek(time)
    跳转到指定时间(支持传入与数据格式相同的 time 值)。

  • player.setSpeed(multiplier)
    动态设置倍速(例如 player.setSpeed(10))。

  • player.setFollow(follow)
    动态设置相机是否跟随实体(传入 true / false)。

  • player.destroy()
    销毁轨迹实体并解除所有事件监听。

  • player.isPlaying()
    返回当前是否处于播放状态 (Boolean)。

  • player.enableUI(uiOptions)
    开启悬浮 UI 控制面板。

    • uiOptions.container: 挂载的 DOM 节点,默认是 viewer.container。

    • uiOptions.onReload: 点击 UI 上的“重新加载”或拖拽参数变更后触发的回调,需要在该回调中重新调用 player.load(data)。

5. 完整代码实例

    // 1. 初始化地图Viewer
    const viewer = new Cesium.Viewer('cesiumContainer');

    // 2. 准备轨迹数据(支持多种格式,下面是最基础的一种)
    const trackData = [
      { time: '2024-01-01T00:00:00Z', lon: 116.391, lat: 39.907, height: 100 },
      { time: '2024-01-01T00:00:10Z', lon: 116.401, lat: 39.917, height: 200 },
      { time: '2024-01-01T00:00:20Z', lon: 116.411, lat: 39.927, height: 300 },
    ];

    // 3. 实例化播放器
    const player = new CesiumTrackPlayer(viewer, {
      modelUrl: 'path/to/your/model.glb', // 传入模型地址
      showPath: true, // 显示轨迹线
      speed: 5, // 5倍速
      loop: false, // 不循环,播完停在终点
    });

    // 4. 加载数据并开启内置 UI 面板
    player.load(trackData);
    player.enableUI({
      // 如果用户在 UI 上修改了朝向或插值阶数,点击重新加载时触发此回调
      onReload: (playerInstance) => {
        playerInstance.load(trackData); // 重新灌入数据即可自动重载
      }
    });

6. 效果展示

Demo地址:https://mhc.ixiera.com/mhc/mchmap/TrackPlayer/index.html

 

本文档来自—MCHMAP 丨 地图引擎平台