Cesium2s文档

Appearance

cesium2s

cesium2s / CameraPathRoaming

类: CameraPathRoaming ​

Description ​

基于Cesium实现的相机路径漫游工具类 支持检查点管理、路径插值生成、自动漫游、进度控制等功能，可可视化展示路径和检查点

示例 ​

ts
// 1. 初始化相机路径漫游实例
const cameraRoaming = new CameraPathRoaming(viewer, {
  modelUrl: "/models/camera-marker.glb" // 可选：检查点模型地址
});

// 2. 添加检查点（从当前相机姿态添加）
cameraRoaming.addCheckPoint(viewer.camera);

// 3. 生成路径并开始漫游
cameraRoaming.start();

// 4. 监听漫游进度
cameraRoaming.onPlay = (percent) => {
  console.log(`漫游进度：${(percent * 100).toFixed(1)}%`);
};

构造函数 ​

构造函数 ​

new CameraPathRoaming(viewer, options?): CameraPathRoaming

构造函数 - 初始化相机路径漫游实例

参数 ​

viewer ​

Viewer

Cesium Viewer实例

options? ​

Option

初始化配置（可选）

返回 ​

CameraPathRoaming

属性 ​

cameraPath ​

cameraPath: CameraOption[] = []

插值生成的相机路径数组（包含连续的相机姿态节点）

默认值 ​

ts
[]

checkPointEntities ​

checkPointEntities: Entity[] = []

检查点可视化实体数组（用于在场景中显示每个检查点）

默认值 ​

ts
[]

checkPoints ​

checkPoints: ObservableArray<CameraOption>

检查点列表（可观察数组，变化时自动触发路径更新）

默认值 ​

ts
[]

cursor ​

cursor: number = 0

漫游进度游标（当前漫游到的路径节点索引）

默认值 ​

ts
0

isPaused ​

isPaused: boolean = false

isRoaming ​

isRoaming: boolean = false

是否正在漫游的状态标记

默认值 ​

ts
false

options? ​

optional options: Option

初始化配置选项

pathEntity ​

pathEntity: Entity | undefined

路径可视化实体（用于在场景中显示漫游路径）

默认值 ​

ts
undefined

speed ​

speed: number = 1.0

viewer ​

viewer: Viewer

Cesium Viewer实例，用于操作三维场景和相机

方法 ​

addCheckPoint() ​

addCheckPoint(camera): void

参数 ​

camera ​

Camera

Cesium相机实例（通常使用viewer.camera）

返回 ​

void

Description ​

从当前相机姿态添加检查点

示例 ​

ts
// 从当前视图添加检查点
cameraRoaming.addCheckPoint(viewer.camera);

end() ​

end(): void

返回 ​

void

Description ​

结束相机路径漫游 恢复路径和检查点可视化，重置进度游标和漫游状态

示例 ​

ts
// 手动结束漫游
cameraRoaming.end();

getPath() ​

getPath(): CameraOption[]

返回 ​

CameraOption[]

检查点数组

Description ​

获取当前检查点列表（原始控制点，非插值路径）

示例 ​

ts
const checkPoints = cameraRoaming.getPath();
console.log("当前检查点数量：", checkPoints.length);

jumpTo() ​

jumpTo(percentage): void

参数 ​

percentage ​

number

目标进度（0~1之间的小数，0为起点，1为终点）

返回 ​

void

Description ​

按百分比跳转漫游进度

示例 ​

ts
// 跳转到50%进度
cameraRoaming.jumpTo(0.5);

onPlay() ​

onPlay(percent): void

参数 ​

percent ​

number

漫游进度（0~1之间的小数）

返回 ​

void

Description ​

漫游进度监听回调（可重写） 每次相机姿态更新时触发，返回当前漫游进度百分比

示例 ​

ts
// 重写进度监听，更新UI进度条
cameraRoaming.onPlay = (percent) => {
  document.getElementById("progress-bar").value = percent * 100;
};

pause() ​

pause(): void

暂停漫游

返回 ​

void

readPath() ​

readPath(data): void

参数 ​

data ​

CameraOption[]

外部相机路径数据（检查点数组）

返回 ​

void

Description ​

导入外部相机路径（覆盖当前检查点列表）

示例 ​

ts
// 导入预设的路径数据
const presetPath = [
  { position: new Cesium.Cartesian3(...), orientation: new Cesium.Quaternion(...) },
  { position: new Cesium.Cartesian3(...), orientation: new Cesium.Quaternion(...) }
];
cameraRoaming.readPath(presetPath);

removeCheckPoints() ​

removeCheckPoints(): void

返回 ​

void

Description ​

清空所有检查点，同时移除路径和检查点的可视化实体

示例 ​

ts
cameraRoaming.removeCheckPoints();

resume() ​

resume(): void

继续漫游

返回 ​

void

setSpeed() ​

setSpeed(speed): void

[NEW] 设置播放速率

参数 ​

speed ​

number

速率倍数 (建议范围 0.1 - 5.0)

返回 ​

void

start() ​

start(): void

返回 ​

void

Description ​

开始相机路径漫游

Warning ​

若当前已在漫游中或插值路径为空，会打印错误日志且不执行操作

示例 ​

ts
// 生成路径后开始漫游
if (cameraRoaming.cameraPath.length > 0) {
  cameraRoaming.start();
}