简介Cesium自主漫游实战[可运行源码]是一份面向具备GIS开发基础读者的可运行代码包专门解决在Cesium三维地球场景中实现键盘控制物体自由漫游的常见需求。该资源通过CallbackProperty在每帧动态计算小车实体的位置与朝向同时监听WASD或上下左右键事件将用户按键实时转换为移动状态整个逻辑被封装为class结构清晰、便于复用。压缩包共3个文件仅6KB包括index.html三维场景运行入口、.inscode项目配置和.gitignore版本管理规则资源体积小巧便于快速阅读和集成。当前已有66人学习浏览适合希望掌握Cesium实时交互控制、事件监听与实体状态更新技巧的三维GIS开发者和学习者也可作为高校GIS课程设计或毕业设计的参考资料。通过这份源码读者能够获得完整可运行的示例并理解从键盘输入到物体位姿变化的完整链路包括事件监听、状态更新和模块化设计等关键实现其模块化方案可直接迁移至实际三维GIS项目中作为自主漫游与交互控制功能开发的基础起点。 做过 Cesium 开发的朋友应该都有这种体会让三维地球转起来很简单但让镜头“自己长眼睛”沿一条路线稳稳飞过去远比想象中麻烦。这里的Cesium 自主漫游指的是不需要用户拖鼠标、滚滚轮而是由程序控制相机位置和姿态按照预先定义好的路径执行一次连续的镜头飞行。它在智慧园区巡检、数字孪生漫游、城市预案推演里非常常见也是很多 Cesium 岗位面试题里爱考的点。这篇博文我会从原理讲起给出可直接复制的可运行源码并把我调参时踩过的坑一并写出来希望能帮你少走弯路。1. 自主漫游到底在解决什么问题1.1 为什么要用时间轴驱动而不是每帧挪相机自主漫游的本质是让相机的运动和时间绑定在一起。很多人刚开始会想直接setInterval或requestAnimationFrame每帧把相机往前挪一点不就行了吗确实能“动起来”但一旦牵扯到拐弯、变速、暂停恢复、循环播放代码很快就会变成一大坨if/else。Cesium 本身内置了完整的时钟机制坐标点只要和时间关联起来引擎就会自动做差值计算倍速、倒放、循环这些都是现成的能力。打个比方这就像剪辑软件里的关键帧动画。你只需要在时间轴上设置几个关键点中间过程由软件自动补充。Cesium 的SampledPositionProperty也是这个逻辑路径点加上时间戳引擎自动插值。用时间轴驱动还有一个额外好处——整个漫游状态可以准确还原只要记录下当前时间就能在任何时刻恢复现场。1.2 一个核心认知相机和实体是两套体系Cesium 里有两个很容易混淆的概念viewer.camera和Entity。相机是“你看世界的眼睛”实体是场景里的“被观察对象”。自主漫游有两种主流做法方式一创建一个实体把它的位置绑定到路径上然后让trackedEntity锁定它相机自动跟随。方式二不创建实体在每一帧根据时间计算出相机位置然后直接setView设置相机。这两种方式的代码组织逻辑完全不同。方式一适合快速演示几行代码就能看到效果方式二更贴近实际项目因为巡检、航拍、预案演练对视野角度有严格要求不能让引擎自行决定怎么看。这个选择在后面的源码部分会非常关键。2. 路径数据准备别让漫游变成过山车2.1 经纬度坐标序列的采集与优化自主漫游的输入一般就是一组坐标数组格式通常是[经度, 纬度, 高度]。来源可以是地图上手动采集也可以是后台接口下发。我刚开始做的时候图省事直接在地图上点了一堆点连成线结果飞起来画面剧烈抖动。原因很简单点太密且高度互不连续。路径点的数量不是越多越好。每两个点之间 Cesium 会做插值点太密反而可能因为插值算法的特性导致镜头扭动。比较合理的做法是直线段只保留起点和终点转弯处适当加密。如果原数据点过密可以先抽稀比如高德、百度路径规划返回的轨迹点通常几十米一个直接拿来做漫游完全可行但如果是手绘的复杂曲线就要先用简化算法如 Douglas-Peucker预处理一下。2.2 时间戳与坐标的绑定关系每个路径点都必须对应一个时间。这段关系直接决定了飞行速度。我在做项目时习惯用“距离 / 期望速度”来计算两点的时间间隔const dist Cesium.Cartesian3.distance(prevPos, nextPos); const dt dist / speed; // speed 单位 m/s const time Cesium.JulianDate.addSeconds(prevTime, dt, new Cesium.JulianDate());这样算出来的时间戳可以保证整条路径上速度大致均匀。直接固定时间间隔的话如果两个点之间距离忽远忽近速度就会忽快忽慢看起来特别晕。这个细节是纯靠手感调出来的没有现成文档会告诉你。还有一个容易忽略的点高度到底用绝对高度还是相对地面高度。如果给的是绝对椭球高度飞行过程中遇到地形起伏就很容易穿模。更稳妥的做法是先用viewer.scene.globe.getHeight(cartographic)把每个轨迹点的地形高度采样出来然后在地形高度上叠加一个安全高度。比如无人机巡检场景叠加 30~80 米比较合适。const carto Cesium.Cartographic.fromDegrees(lng, lat); const terrainHeight viewer.scene.globe.getHeight(carto) || 0; const safeHeight terrainHeight 50;2.3 测试阶段建议先关掉复杂地形自主漫游逻辑本身和地形数据没关系初期调试我最推荐把地形先关掉直接用默认的EllipsoidTerrainProvider。不然每次启动页面都在加载地形瓦片镜头已经飞出去了地形还没显示出来你根本分不清问题是出在“网络慢”还是“路径计算错”。跑通核心逻辑后再替换成高精度地形也不迟。3. 可运行源码两种主流实现方式3.1 准备最小可运行环境微信搜索可能直接蹭到各种封装好的组件但自己搭一个最小环境并不复杂。我习惯直接用 CDN 引入的方式做单页演示不需要 npm 工程复制粘贴就能跑。注意需要去 Cesium 官网注册一个 Ion Token否则默认底图和地形加载不出来。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleCesium 自主漫游演示/title style html, body, #cesiumContainer { width: 100%; height: 100%; margin: 0; overflow: hidden; } /style script srchttps://cesium.com/downloads/cesiumjs/releases/1.116/Build/Cesium/Cesium.js/script link hrefhttps://cesium.com/downloads/cesiumjs/releases/1.116/Build/Cesium/Widgets/widgets.css relstylesheet /head body div idcesiumContainer/div script // TODO: 替换成你自己的 Token Cesium.Ion.defaultAccessToken your_token_here; const viewer new Cesium.Viewer(cesiumContainer, { shouldAnimate: true, baseLayerPicker: false, geocoder: false, homeButton: false, sceneModePicker: false, navigationHelpButton: false, animation: true, timeline: true }); // 你的路径坐标 [经度, 纬度, 高度] const route [ [116.3913, 39.9075, 300], [116.3965, 39.9102, 320], [116.4021, 39.9077, 280], [116.4092, 39.9118, 350], [116.4159, 39.9081, 300] ]; // 下面根据不同的实现方式填充代码 /script /body /html这里的shouldAnimate: true很关键它表示让时钟自动前进。如果设成 false就算你把路径和时间都配好镜头也是静止的。3.2 方式一Entity 自动跟踪代码最少使用SampledPositionProperty是 Cesium 官方推荐的路径运动方案。我们把每个路径点和对应时间塞进去Cesium 会自动插值出中间时刻的位置// 路径点转 Cartesian3 const points route.map(item Cesium.Cartesian3.fromDegrees(item[0], item[1], item[2])); // 时间轴从当前时间开始总时长 80 秒 const startTime Cesium.JulianDate.now(); const totalDuration 80; const stopTime Cesium.JulianDate.addSeconds(startTime, totalDuration, new Cesium.JulianDate()); viewer.clock.startTime startTime; viewer.clock.stopTime stopTime; viewer.clock.currentTime startTime; viewer.clock.clockRange Cesium.ClockRange.CLAMPED; // 到点后停在终点 viewer.clock.multiplier 10; // 10 倍速播放 // 构造位置属性 const positionProperty new Cesium.SampledPositionProperty(); const segmentCount points.length - 1; points.forEach((p, index) { const time Cesium.JulianDate.addSeconds( startTime, (totalDuration / segmentCount) * index, new Cesium.JulianDate() ); positionProperty.addSample(time, p); }); // 添加一个小球体作为被跟踪对象 const entity viewer.entities.add({ position: positionProperty, ellipsoid: { radii: new Cesium.Cartesian3(5, 5, 5), material: Cesium.Color.RED }, orientation: new Cesium.VelocityOrientationProperty(positionProperty) }); // 锁定跟踪视角 viewer.trackedEntity entity;跑通这段代码后你会看到一个小红球沿着路径飞行相机始终跟随它。到这里自主漫游的最简模型已经成立。但这版有几个明显局限VelocityOrientationProperty只能保证“球体”的自身朝向顺着速度方向相机视角却不一定符合你想要的角度。如果你希望镜头像一个无人机摄像头那样固定俯仰角或者平视前方方式一就不够用了。3.3 方式二Camera 手动控制推荐用于真实项目真实项目里我更推荐直接接管相机。核心思路在clock.onTick回调里每一帧根据当前时间从positionProperty取出位置再取下一小段时间后的位置算出一个前进方向然后用viewer.camera.setView设置相机。// 先把 positionProperty 构建好代码同上 // 然后设置相机初始位置到第一个点 const firstPos points[0]; const firstTime Cesium.JulianDate.addSeconds(startTime, 0, new Cesium.JulianDate()); const firstPosition positionProperty.getValue(firstTime); viewer.camera.setView({ destination: firstPosition, orientation: { heading: Cesium.Math.toRadians(0), pitch: Cesium.Math.toRadians(-15), roll: 0 } }); // 计算两个经纬度点之间的航向角北向为 0 度顺时针 function computeHeading(fromCart, toCart) { const from Cesium.Cartographic.fromCartesian(fromCart); const to Cesium.Cartographic.fromCartesian(toCart); const lon1 from.longitude; const lat1 from.latitude; const lon2 to.longitude; const lat2 to.latitude; let heading Math.atan2( Math.sin(lon2 - lon1) * Math.cos(lat2), Math.cos(lat1) * Math.sin(lat2) - Math.sin(lat1) * Math.cos(lat2) * Math.cos(lon2 - lon1) ); heading (heading Cesium.Math.TWO_PI) % Cesium.Math.TWO_PI; return heading; } // 当前实时的朝向用于平滑过渡 let currentHeading 0; viewer.clock.onTick.addEventListener((clock) { const time clock.currentTime; const currentPosition positionProperty.getValue(time); if (!currentPosition) return; // 取 0.1 秒后的位置计算方向 const nextTime Cesium.JulianDate.addSeconds(time, 0.1, new Cesium.JulianDate()); const nextPosition positionProperty.getValue(nextTime); if (!nextPosition) return; const targetHeading computeHeading(currentPosition, nextPosition); // 角度平滑避免突然转向 let delta targetHeading - currentHeading; if (delta Math.PI) delta - Cesium.Math.TWO_PI; if (delta -Math.PI) delta Cesium.Math.TWO_PI; currentHeading delta * 0.2; viewer.camera.setView({ destination: currentPosition, orientation: { heading: currentHeading, pitch: Cesium.Math.toRadians(-15), roll: 0 } }); });这是我在实际项目里最常用的模板。pitch设置为 -15 度可以形成一种“略向下俯瞰”的视野既能看到前方路径又有情景感。如果你希望做成第一人称视角pitch设为 0同时把相机高度降到人眼高度即可。3.4 循环播放与暂停恢复循环巡检是自主漫游很常见的需求。Cesium 的ClockRange提供了三种模式ClockRange.CLAMPED时间走到stopTime就停住适合单次演示ClockRange.LOOP循环播放适合持续巡检ClockRange.LOOP_STOP循环到某个时间点后停止。如果希望在特定时间点暂停直接控制viewer.clock.shouldAnimate就行// 暂停 viewer.clock.shouldAnimate false; // 继续 viewer.clock.shouldAnimate true;4. 参数调优与常见问题排查4.1 漫游速度怎么选漫游速度没有一个固定值它取决于业务场景。整理一个我常用的参考区间场景速度建议说明步行街区漫游1 ~ 2 m/s模拟人走路视角镜头高度 1.6~2m车辆沿路巡检10 ~ 30 m/s模拟车辆行驶视野更开阔无人机/飞行演示50 ~ 200 m/s中低空飞行能看清建筑群关系城市宏观规划500 m/s 以上高空俯瞰适合大范围浏览注意还有一个clock.multiplier参数。它表示时间流速倍率如果设置为 10实际每过 1 秒时间轴前进 10 秒。这个倍率对插值效果有直接影响倍率过高会导致每一帧跨过的路径段太长镜头出现肉眼可见的“顿挫感”。我的经验是如果路径很短但想看慢动作就把 multiplier 调小如果路径很长想快速浏览优先提高速度而不是死拉 multiplier。4.2 相机穿地和穿墙的规避自主漫游最容易翻车的展示效果就是“穿地”。镜头钻进地形或者直接穿进建筑模型立刻显得很不专业。穿地的主要原因是路径高度和真实地形不匹配。解决思路在 2.2 里提过提前采样地形高度再叠加安全高度。对于建筑模型因为建筑高度是动态的最简单的办法是控制路径从空中绕过不要硬穿建筑区域。如果实在需要穿越门洞或楼宇间通道就只能手工对路径高度做微调并在调试面板里实时预览。4.3 朝向抖动问题使用VelocityOrientationProperty时如果路径上有接近 180 度的折返或者某一段速度特别慢实体朝向会自动翻转看起来像“抽搐”。即便是手动计算 heading 的方案在角度跨越 0/360 度边界时也会有问题——比如上一帧朝向是 359 度下一帧目标是 1 度如果直接相减再插值它会绕一整个大圈。我的通用处理方式是在计算差值时做角度归一化let delta targetHeading - currentHeading; if (delta Math.PI) delta - Cesium.Math.TWO_PI; if (delta -Math.PI) delta Cesium.Math.TWO_PI; currentHeading delta * 0.2;这样无论角度怎么跨边界相机始终走“最短路径”完成转向不会突然来个 360 度转圈。4.4 常见问题速查表现象常见原因处理建议镜头钻入地下路径高度与地形不匹配用getHeight采样地形再加安全高度拐弯处镜头翻转速度方向突变或 heading 跨 0 度做角度归一化和插值平滑时间轴在走镜头却不动positionProperty.getValue返回 undefined检查addSample的时间范围是否覆盖当前时间漫游结束就黑屏/空白相机停在某个不合理的坐标使用ClockRange.CLAMPED并设置结束后的固定视角镜头忽高忽低路径点间距过大插值后穿过地形起伏增加采样点或对高度做平滑滤波循环播放有跳变LOOP模式下首尾点未衔接好让首尾坐标相同或单独处理 transition4.5 性能优化几千个路径点时怎么办如果一次漫游要跑上千个路径点SampledPositionProperty会保存全部样本长时间运行内存压力不小。而且插值计算本身也有开销。我做航线漫游时数据来源于后端下发的飞行轨迹常常一次就有 5000 个点。我的做法是两句话先抽稀后分段。抽稀可以简单按间隔采样比如每 5 个点保留 1 个分段是指如果路径超长不要一次把整条路径塞进一个positionProperty而是准备一个缓冲队列当前段播放完后再加载下一段。后者代码会更复杂但对长航线漫游的提升非常明显。如果只是做普通园区演示抽稀通常就够用了。5. 在实际项目中的扩展思路自主漫游跑通后稍加改动就能接出很多实用功能。我挑几个真实项目里做过的方向简单讲一下每一个都不难但效果提升明显。第一个是动态光照。漫游时开启动态光照时间轴流动会让阴影实时变化视觉效果会瞬间提升一个档次。实现方式极简单viewer.scene.globe.enableLighting true;开启后配合clock的时间流动就能看到建筑物阴影随“时间”移动非常真实。第二个是模型姿态联动。如果你在路径上放了一架无人机模型希望它转弯时机翼跟着倾斜可以给entity.orientation设置四元数。基于HeadingPitchRoll生成四元数是最常见的方式const hpr new Cesium.HeadingPitchRoll(headingValue, pitchValue, rollValue); const quaternion Cesium.Transforms.headingPitchRollQuaternion(currentPosition, hpr); entity.orientation quaternion;第三个是多视图对比。同一个场景创建两个 Viewer左边是自主漫游视角右边是全局鹰眼视角可以同时观察飞行进度和周边环境。多个 Viewer 各自渲染注意不要让两个 canvas 互相覆盖。这个功能在项目汇报、路径方案评审时特别好用。第四个是漫游视频录制。Cesium 没有直接录制视频的 API但你可以用postRender事件在每一帧把 canvas 内容绘制到离屏 canvas再用浏览器自带的MediaRecorder编码成 WebM 视频。虽然实现细节不少但做完之后就能把漫游结果导出成视频方便直接发群里汇报。说了这么多最后分享一点个人体会我刚开始做自主漫游时总想把所有高级特性一次性全部怼上去结果调参调到吐。后来才明白先把最基础的“时间轴 位置插值 相机跟随”跑通再逐个加特效和业务逻辑才是效率最高的路径。如果你正在做类似功能建议先把上面第二、第三部分的代码跑一遍遇到哪个坑再翻对应的排查表应该能省下不少时间。本文还有配套的精品资源点击获取 Cesium自主漫游实现指南：时间轴驱动相机路径飞行
简介Cesium自主漫游实战[可运行源码]是一份面向具备GIS开发基础读者的可运行代码包专门解决在Cesium三维地球场景中实现键盘控制物体自由漫游的常见需求。该资源通过CallbackProperty在每帧动态计算小车实体的位置与朝向同时监听WASD或上下左右键事件将用户按键实时转换为移动状态整个逻辑被封装为class结构清晰、便于复用。压缩包共3个文件仅6KB包括index.html三维场景运行入口、.inscode项目配置和.gitignore版本管理规则资源体积小巧便于快速阅读和集成。当前已有66人学习浏览适合希望掌握Cesium实时交互控制、事件监听与实体状态更新技巧的三维GIS开发者和学习者也可作为高校GIS课程设计或毕业设计的参考资料。通过这份源码读者能够获得完整可运行的示例并理解从键盘输入到物体位姿变化的完整链路包括事件监听、状态更新和模块化设计等关键实现其模块化方案可直接迁移至实际三维GIS项目中作为自主漫游与交互控制功能开发的基础起点。 做过 Cesium 开发的朋友应该都有这种体会让三维地球转起来很简单但让镜头“自己长眼睛”沿一条路线稳稳飞过去远比想象中麻烦。这里的Cesium 自主漫游指的是不需要用户拖鼠标、滚滚轮而是由程序控制相机位置和姿态按照预先定义好的路径执行一次连续的镜头飞行。它在智慧园区巡检、数字孪生漫游、城市预案推演里非常常见也是很多 Cesium 岗位面试题里爱考的点。这篇博文我会从原理讲起给出可直接复制的可运行源码并把我调参时踩过的坑一并写出来希望能帮你少走弯路。1. 自主漫游到底在解决什么问题1.1 为什么要用时间轴驱动而不是每帧挪相机自主漫游的本质是让相机的运动和时间绑定在一起。很多人刚开始会想直接setInterval或requestAnimationFrame每帧把相机往前挪一点不就行了吗确实能“动起来”但一旦牵扯到拐弯、变速、暂停恢复、循环播放代码很快就会变成一大坨if/else。Cesium 本身内置了完整的时钟机制坐标点只要和时间关联起来引擎就会自动做差值计算倍速、倒放、循环这些都是现成的能力。打个比方这就像剪辑软件里的关键帧动画。你只需要在时间轴上设置几个关键点中间过程由软件自动补充。Cesium 的SampledPositionProperty也是这个逻辑路径点加上时间戳引擎自动插值。用时间轴驱动还有一个额外好处——整个漫游状态可以准确还原只要记录下当前时间就能在任何时刻恢复现场。1.2 一个核心认知相机和实体是两套体系Cesium 里有两个很容易混淆的概念viewer.camera和Entity。相机是“你看世界的眼睛”实体是场景里的“被观察对象”。自主漫游有两种主流做法方式一创建一个实体把它的位置绑定到路径上然后让trackedEntity锁定它相机自动跟随。方式二不创建实体在每一帧根据时间计算出相机位置然后直接setView设置相机。这两种方式的代码组织逻辑完全不同。方式一适合快速演示几行代码就能看到效果方式二更贴近实际项目因为巡检、航拍、预案演练对视野角度有严格要求不能让引擎自行决定怎么看。这个选择在后面的源码部分会非常关键。2. 路径数据准备别让漫游变成过山车2.1 经纬度坐标序列的采集与优化自主漫游的输入一般就是一组坐标数组格式通常是[经度, 纬度, 高度]。来源可以是地图上手动采集也可以是后台接口下发。我刚开始做的时候图省事直接在地图上点了一堆点连成线结果飞起来画面剧烈抖动。原因很简单点太密且高度互不连续。路径点的数量不是越多越好。每两个点之间 Cesium 会做插值点太密反而可能因为插值算法的特性导致镜头扭动。比较合理的做法是直线段只保留起点和终点转弯处适当加密。如果原数据点过密可以先抽稀比如高德、百度路径规划返回的轨迹点通常几十米一个直接拿来做漫游完全可行但如果是手绘的复杂曲线就要先用简化算法如 Douglas-Peucker预处理一下。2.2 时间戳与坐标的绑定关系每个路径点都必须对应一个时间。这段关系直接决定了飞行速度。我在做项目时习惯用“距离 / 期望速度”来计算两点的时间间隔const dist Cesium.Cartesian3.distance(prevPos, nextPos); const dt dist / speed; // speed 单位 m/s const time Cesium.JulianDate.addSeconds(prevTime, dt, new Cesium.JulianDate());这样算出来的时间戳可以保证整条路径上速度大致均匀。直接固定时间间隔的话如果两个点之间距离忽远忽近速度就会忽快忽慢看起来特别晕。这个细节是纯靠手感调出来的没有现成文档会告诉你。还有一个容易忽略的点高度到底用绝对高度还是相对地面高度。如果给的是绝对椭球高度飞行过程中遇到地形起伏就很容易穿模。更稳妥的做法是先用viewer.scene.globe.getHeight(cartographic)把每个轨迹点的地形高度采样出来然后在地形高度上叠加一个安全高度。比如无人机巡检场景叠加 30~80 米比较合适。const carto Cesium.Cartographic.fromDegrees(lng, lat); const terrainHeight viewer.scene.globe.getHeight(carto) || 0; const safeHeight terrainHeight 50;2.3 测试阶段建议先关掉复杂地形自主漫游逻辑本身和地形数据没关系初期调试我最推荐把地形先关掉直接用默认的EllipsoidTerrainProvider。不然每次启动页面都在加载地形瓦片镜头已经飞出去了地形还没显示出来你根本分不清问题是出在“网络慢”还是“路径计算错”。跑通核心逻辑后再替换成高精度地形也不迟。3. 可运行源码两种主流实现方式3.1 准备最小可运行环境微信搜索可能直接蹭到各种封装好的组件但自己搭一个最小环境并不复杂。我习惯直接用 CDN 引入的方式做单页演示不需要 npm 工程复制粘贴就能跑。注意需要去 Cesium 官网注册一个 Ion Token否则默认底图和地形加载不出来。!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleCesium 自主漫游演示/title style html, body, #cesiumContainer { width: 100%; height: 100%; margin: 0; overflow: hidden; } /style script srchttps://cesium.com/downloads/cesiumjs/releases/1.116/Build/Cesium/Cesium.js/script link hrefhttps://cesium.com/downloads/cesiumjs/releases/1.116/Build/Cesium/Widgets/widgets.css relstylesheet /head body div idcesiumContainer/div script // TODO: 替换成你自己的 Token Cesium.Ion.defaultAccessToken your_token_here; const viewer new Cesium.Viewer(cesiumContainer, { shouldAnimate: true, baseLayerPicker: false, geocoder: false, homeButton: false, sceneModePicker: false, navigationHelpButton: false, animation: true, timeline: true }); // 你的路径坐标 [经度, 纬度, 高度] const route [ [116.3913, 39.9075, 300], [116.3965, 39.9102, 320], [116.4021, 39.9077, 280], [116.4092, 39.9118, 350], [116.4159, 39.9081, 300] ]; // 下面根据不同的实现方式填充代码 /script /body /html这里的shouldAnimate: true很关键它表示让时钟自动前进。如果设成 false就算你把路径和时间都配好镜头也是静止的。3.2 方式一Entity 自动跟踪代码最少使用SampledPositionProperty是 Cesium 官方推荐的路径运动方案。我们把每个路径点和对应时间塞进去Cesium 会自动插值出中间时刻的位置// 路径点转 Cartesian3 const points route.map(item Cesium.Cartesian3.fromDegrees(item[0], item[1], item[2])); // 时间轴从当前时间开始总时长 80 秒 const startTime Cesium.JulianDate.now(); const totalDuration 80; const stopTime Cesium.JulianDate.addSeconds(startTime, totalDuration, new Cesium.JulianDate()); viewer.clock.startTime startTime; viewer.clock.stopTime stopTime; viewer.clock.currentTime startTime; viewer.clock.clockRange Cesium.ClockRange.CLAMPED; // 到点后停在终点 viewer.clock.multiplier 10; // 10 倍速播放 // 构造位置属性 const positionProperty new Cesium.SampledPositionProperty(); const segmentCount points.length - 1; points.forEach((p, index) { const time Cesium.JulianDate.addSeconds( startTime, (totalDuration / segmentCount) * index, new Cesium.JulianDate() ); positionProperty.addSample(time, p); }); // 添加一个小球体作为被跟踪对象 const entity viewer.entities.add({ position: positionProperty, ellipsoid: { radii: new Cesium.Cartesian3(5, 5, 5), material: Cesium.Color.RED }, orientation: new Cesium.VelocityOrientationProperty(positionProperty) }); // 锁定跟踪视角 viewer.trackedEntity entity;跑通这段代码后你会看到一个小红球沿着路径飞行相机始终跟随它。到这里自主漫游的最简模型已经成立。但这版有几个明显局限VelocityOrientationProperty只能保证“球体”的自身朝向顺着速度方向相机视角却不一定符合你想要的角度。如果你希望镜头像一个无人机摄像头那样固定俯仰角或者平视前方方式一就不够用了。3.3 方式二Camera 手动控制推荐用于真实项目真实项目里我更推荐直接接管相机。核心思路在clock.onTick回调里每一帧根据当前时间从positionProperty取出位置再取下一小段时间后的位置算出一个前进方向然后用viewer.camera.setView设置相机。// 先把 positionProperty 构建好代码同上 // 然后设置相机初始位置到第一个点 const firstPos points[0]; const firstTime Cesium.JulianDate.addSeconds(startTime, 0, new Cesium.JulianDate()); const firstPosition positionProperty.getValue(firstTime); viewer.camera.setView({ destination: firstPosition, orientation: { heading: Cesium.Math.toRadians(0), pitch: Cesium.Math.toRadians(-15), roll: 0 } }); // 计算两个经纬度点之间的航向角北向为 0 度顺时针 function computeHeading(fromCart, toCart) { const from Cesium.Cartographic.fromCartesian(fromCart); const to Cesium.Cartographic.fromCartesian(toCart); const lon1 from.longitude; const lat1 from.latitude; const lon2 to.longitude; const lat2 to.latitude; let heading Math.atan2( Math.sin(lon2 - lon1) * Math.cos(lat2), Math.cos(lat1) * Math.sin(lat2) - Math.sin(lat1) * Math.cos(lat2) * Math.cos(lon2 - lon1) ); heading (heading Cesium.Math.TWO_PI) % Cesium.Math.TWO_PI; return heading; } // 当前实时的朝向用于平滑过渡 let currentHeading 0; viewer.clock.onTick.addEventListener((clock) { const time clock.currentTime; const currentPosition positionProperty.getValue(time); if (!currentPosition) return; // 取 0.1 秒后的位置计算方向 const nextTime Cesium.JulianDate.addSeconds(time, 0.1, new Cesium.JulianDate()); const nextPosition positionProperty.getValue(nextTime); if (!nextPosition) return; const targetHeading computeHeading(currentPosition, nextPosition); // 角度平滑避免突然转向 let delta targetHeading - currentHeading; if (delta Math.PI) delta - Cesium.Math.TWO_PI; if (delta -Math.PI) delta Cesium.Math.TWO_PI; currentHeading delta * 0.2; viewer.camera.setView({ destination: currentPosition, orientation: { heading: currentHeading, pitch: Cesium.Math.toRadians(-15), roll: 0 } }); });这是我在实际项目里最常用的模板。pitch设置为 -15 度可以形成一种“略向下俯瞰”的视野既能看到前方路径又有情景感。如果你希望做成第一人称视角pitch设为 0同时把相机高度降到人眼高度即可。3.4 循环播放与暂停恢复循环巡检是自主漫游很常见的需求。Cesium 的ClockRange提供了三种模式ClockRange.CLAMPED时间走到stopTime就停住适合单次演示ClockRange.LOOP循环播放适合持续巡检ClockRange.LOOP_STOP循环到某个时间点后停止。如果希望在特定时间点暂停直接控制viewer.clock.shouldAnimate就行// 暂停 viewer.clock.shouldAnimate false; // 继续 viewer.clock.shouldAnimate true;4. 参数调优与常见问题排查4.1 漫游速度怎么选漫游速度没有一个固定值它取决于业务场景。整理一个我常用的参考区间场景速度建议说明步行街区漫游1 ~ 2 m/s模拟人走路视角镜头高度 1.6~2m车辆沿路巡检10 ~ 30 m/s模拟车辆行驶视野更开阔无人机/飞行演示50 ~ 200 m/s中低空飞行能看清建筑群关系城市宏观规划500 m/s 以上高空俯瞰适合大范围浏览注意还有一个clock.multiplier参数。它表示时间流速倍率如果设置为 10实际每过 1 秒时间轴前进 10 秒。这个倍率对插值效果有直接影响倍率过高会导致每一帧跨过的路径段太长镜头出现肉眼可见的“顿挫感”。我的经验是如果路径很短但想看慢动作就把 multiplier 调小如果路径很长想快速浏览优先提高速度而不是死拉 multiplier。4.2 相机穿地和穿墙的规避自主漫游最容易翻车的展示效果就是“穿地”。镜头钻进地形或者直接穿进建筑模型立刻显得很不专业。穿地的主要原因是路径高度和真实地形不匹配。解决思路在 2.2 里提过提前采样地形高度再叠加安全高度。对于建筑模型因为建筑高度是动态的最简单的办法是控制路径从空中绕过不要硬穿建筑区域。如果实在需要穿越门洞或楼宇间通道就只能手工对路径高度做微调并在调试面板里实时预览。4.3 朝向抖动问题使用VelocityOrientationProperty时如果路径上有接近 180 度的折返或者某一段速度特别慢实体朝向会自动翻转看起来像“抽搐”。即便是手动计算 heading 的方案在角度跨越 0/360 度边界时也会有问题——比如上一帧朝向是 359 度下一帧目标是 1 度如果直接相减再插值它会绕一整个大圈。我的通用处理方式是在计算差值时做角度归一化let delta targetHeading - currentHeading; if (delta Math.PI) delta - Cesium.Math.TWO_PI; if (delta -Math.PI) delta Cesium.Math.TWO_PI; currentHeading delta * 0.2;这样无论角度怎么跨边界相机始终走“最短路径”完成转向不会突然来个 360 度转圈。4.4 常见问题速查表现象常见原因处理建议镜头钻入地下路径高度与地形不匹配用getHeight采样地形再加安全高度拐弯处镜头翻转速度方向突变或 heading 跨 0 度做角度归一化和插值平滑时间轴在走镜头却不动positionProperty.getValue返回 undefined检查addSample的时间范围是否覆盖当前时间漫游结束就黑屏/空白相机停在某个不合理的坐标使用ClockRange.CLAMPED并设置结束后的固定视角镜头忽高忽低路径点间距过大插值后穿过地形起伏增加采样点或对高度做平滑滤波循环播放有跳变LOOP模式下首尾点未衔接好让首尾坐标相同或单独处理 transition4.5 性能优化几千个路径点时怎么办如果一次漫游要跑上千个路径点SampledPositionProperty会保存全部样本长时间运行内存压力不小。而且插值计算本身也有开销。我做航线漫游时数据来源于后端下发的飞行轨迹常常一次就有 5000 个点。我的做法是两句话先抽稀后分段。抽稀可以简单按间隔采样比如每 5 个点保留 1 个分段是指如果路径超长不要一次把整条路径塞进一个positionProperty而是准备一个缓冲队列当前段播放完后再加载下一段。后者代码会更复杂但对长航线漫游的提升非常明显。如果只是做普通园区演示抽稀通常就够用了。5. 在实际项目中的扩展思路自主漫游跑通后稍加改动就能接出很多实用功能。我挑几个真实项目里做过的方向简单讲一下每一个都不难但效果提升明显。第一个是动态光照。漫游时开启动态光照时间轴流动会让阴影实时变化视觉效果会瞬间提升一个档次。实现方式极简单viewer.scene.globe.enableLighting true;开启后配合clock的时间流动就能看到建筑物阴影随“时间”移动非常真实。第二个是模型姿态联动。如果你在路径上放了一架无人机模型希望它转弯时机翼跟着倾斜可以给entity.orientation设置四元数。基于HeadingPitchRoll生成四元数是最常见的方式const hpr new Cesium.HeadingPitchRoll(headingValue, pitchValue, rollValue); const quaternion Cesium.Transforms.headingPitchRollQuaternion(currentPosition, hpr); entity.orientation quaternion;第三个是多视图对比。同一个场景创建两个 Viewer左边是自主漫游视角右边是全局鹰眼视角可以同时观察飞行进度和周边环境。多个 Viewer 各自渲染注意不要让两个 canvas 互相覆盖。这个功能在项目汇报、路径方案评审时特别好用。第四个是漫游视频录制。Cesium 没有直接录制视频的 API但你可以用postRender事件在每一帧把 canvas 内容绘制到离屏 canvas再用浏览器自带的MediaRecorder编码成 WebM 视频。虽然实现细节不少但做完之后就能把漫游结果导出成视频方便直接发群里汇报。说了这么多最后分享一点个人体会我刚开始做自主漫游时总想把所有高级特性一次性全部怼上去结果调参调到吐。后来才明白先把最基础的“时间轴 位置插值 相机跟随”跑通再逐个加特效和业务逻辑才是效率最高的路径。如果你正在做类似功能建议先把上面第二、第三部分的代码跑一遍遇到哪个坑再翻对应的排查表应该能省下不少时间。本文还有配套的精品资源点击获取