PathTracker与ObjectTracker完整使用指南
在3D地图可视化场景中，相机控制和对象追踪是核心功能。mapv-three提供了两个强大的追踪器：PathTracker（路径追踪器）和ObjectTracker（对象追踪器）。本文将深入解析这两个组件的使用方法，帮助开发者快速掌握相机追踪和对象追踪技术。
一、PathTracker：路径追踪器
PathTracker用于沿指定路径进行相机或对象的动画追踪。它支持多种路径数据格式，可以设置不同的视图模式来实现各种追踪效果。
1.1 基本用法
沿路径追踪相机
最基本的用法是让相机沿着路径移动：
// 创建路径追踪器
const tracker = engine.add(new mapv-three.PathTracker());
// 设置路径数据（坐标数组格式）
tracker.track = [
[112.368264, 23.176959, 38.553634],
[112.370264, 23.178959, 40.553634],
[112.372264, 23.180959, 42.553634]
];
// 开始追踪
tracker.start({
duration: 10000, // 持续时间（毫秒）
pitch: 60, // 俯仰角
range: 100 // 距离
});
让3D模型沿路径移动
除了追踪相机，PathTracker还可以让3D对象沿着路径移动：
// 创建3D模型
const model = engine.add(new mapv-three.SimpleModel({
url: 'path/to/model.glb'
}));
// 创建路径追踪器
const tracker = engine.add(new mapv-three.PathTracker());
tracker.track = pathCoordinates;
tracker.object = model; // 设置要追踪的对象
// 开始追踪
tracker.start({
duration: 8000,
range: 50
});
1.2 支持的路径数据格式
PathTracker支持三种路径数据格式，开发者可以根据数据源选择最合适的格式。
坐标数组格式
最简单的格式，直接使用坐标点数组：
tracker.track = [
[lng1, lat1, alt1],
[lng2, lat2, alt2],
[lng3, lat3, alt3]
];
GeoJSON格式
支持标准的GeoJSON格式，可以包含额外的属性信息：
tracker.track = {
type: 'Feature',
geometry: {
type: 'LineString',
coordinates: [
[lng1, lat1, alt1],
[lng2, lat2, alt2]
]
},
properties: {
frameInfo: [] // 可选的帧信息
}
};
帧信息数组格式
包含更丰富信息的格式，支持速度、时间、朝向等参数：
tracker.track = [
{
x: lng1, y: lat1, z: alt1,
yaw: 1.57, // 偏航角
pitch: 0.7, // 俯仰角
speed: 10, // 速度（米/秒）
time: 1000 // 时间（毫秒）
},
// ... 更多点
];
1.3 视图模式
PathTracker提供了多种视图模式，满足不同场景的需求。
跟随模式（follow）
相机跟随路径方向，自动调整朝向：
tracker.track = pathData;
tracker.viewMode = 'follow';
tracker.start({
duration: 7000,
heading: 10,
pitch: 70,
range: 10
});
锁定模式（lock）
相机保持固定角度，不随路径改变朝向：
tracker.track = pathData;
tracker.viewMode = 'lock';
tracker.start({
duration: 50000,
pitch: 70,
range: 100
});
解锁模式（unlock）
相机不锁定，可以自由调整：
tracker.viewMode = 'unlock';
tracker.object = model;
tracker.start({
duration: 50000,
pitch: 70,
range: 100
});
关键帧模式（keyFrame）
使用预定义的关键帧信息控制相机角度：
// 在GeoJSON的properties中添加frameInfo
pathData.properties.frameInfo = [
{ pitch: 0.7, yaw: 1.57, time: 1000 },
{ pitch: 0.9, yaw: 0, time: 2000 },
{ pitch: 1.2, yaw: 2, time: 3000 }
];
tracker.track = pathData;
tracker.viewMode = 'keyFrame';
tracker.start({
range: 0
});
关键帧模式还支持瞄准点（aim）功能：
pathData.properties.frameInfo = [
{
aim: [lng, lat, alt], // 瞄准点坐标
time: 1000
}
];
活动帧模式（activeFrame）
类似于关键帧，但支持更灵活的插值：
tracker.track = pathData;
tracker.viewMode = 'activeFrame';
tracker.start({
range: 0
});
1.4 高级配置
插值阈值控制
interpolateDirectThreshold参数控制路径插值的平滑程度：
// 值越大，路径拐角过渡越平滑，但也会越偏离实际路线
tracker.interpolateDirectThreshold = 100;
曲线插值
启用曲线插值可以使路径更加平滑：
tracker.pointHandle = 'curve';
暂停和恢复
支持暂停和恢复追踪：
// 暂停追踪
const stateInfo = tracker.pause();
console.log(stateInfo);
// 恢复追踪
tracker.start();
// 重新播放
tracker.replay();
回调函数
提供多个生命周期回调：
tracker.onStart = () => {
console.log('追踪开始');
};
tracker.onUpdate = (state) => {
console.log('状态更新:', state);
};
tracker.onFinish = () => {
console.log('追踪完成');
};
二、ObjectTracker：对象追踪器
ObjectTracker用于追踪指定的3D对象或坐标点，让相机始终跟随目标对象。
2.1 基本用法
追踪3D模型
最常用的场景是追踪一个3D模型：
// 创建3D模型
const model = engine.add(new mapv-three.SimpleModel({
url: 'path/to/model.glb'
}));
// 创建对象追踪器
const tracker = engine.add(new mapv-three.ObjectTracker());
// 开始追踪
tracker.track(model, {
range: 100, // 距离100米
pitch: 60, // 俯仰角60度
heading: 45 // 方位角45度
});
2.2 配置参数
ObjectTracker提供了丰富的配置选项：
tracker.track(object, {
range: 100, // 追踪距离（米）
pitch: 60, // 俯仰角（度）
heading: 45, // 方位角（度）
height: 50, // 高度偏移（米）
extraDir: 30, // 额外方向修正角度（度）
duration: 0, // 持续时间（0表示持续追踪）
easing: 'linear', // 缓动函数
lock: true // 是否锁定视图
});
参数说明
- range/radius：相机与对象的距离，单位米
- pitch：俯仰角，控制相机上下角度
- heading：方位角，控制相机左右角度
- height：高度偏移，在非地球模式下可以调整相机高度
- extraDir：额外方向修正，用于微调相机朝向
- duration：持续时间，0表示持续追踪直到手动停止
- easing：缓动函数，可选值：'linear'、'easeIn'、'easeOut'、'easeInOut'
- lock：是否锁定视图，锁定后相机角度固定
2.3 追踪帧回调
ObjectTracker提供了追踪帧回调，可以在每帧更新时执行自定义逻辑：
tracker.onTrackFrame = (lastState, currentState) => {
console.log('追踪状态更新:', currentState);
// 可以在这里添加自定义逻辑
// 例如：根据对象位置更新UI
// 或者：触发其他动画效果
};
2.4 停止追踪
停止追踪并重置状态：
tracker.stop();
三、联合使用场景
在实际项目中，PathTracker和ObjectTracker经常需要联合使用，实现更复杂的追踪效果。
3.1 路径追踪 + 对象追踪
让对象沿路径移动，同时相机追踪对象：
// 创建模型
const model = engine.add(new mapv-three.SimpleModel({
url: 'path/to/model.glb'
}));
// 创建路径追踪器（让模型沿路径移动）
const pathTracker = engine.add(new mapv-three.PathTracker());
pathTracker.track = pathData;
pathTracker.object = model;
pathTracker.viewMode = 'unlock'; // 解锁视图模式
pathTracker.start({
duration: 50000,
pitch: 70,
range: 100
});
// 创建对象追踪器（让相机追踪模型）
const objectTracker = engine.add(new mapv-three.ObjectTracker());
objectTracker.track(model, {
pitch: 80,
radius: 100,
height: 100
});
重要提示：为了避免抖动，需要先初始化PathTracker，然后再初始化ObjectTracker。这是因为PathTracker会更新对象位置，如果先根据对象计算旋转再更新对象，使用的就是上一帧的对象信息。
四、最佳实践
4.1 性能优化
- 合理设置插值阈值：根据路径复杂度调整
interpolateDirectThreshold，避免过度平滑导致性能问题 - 使用合适的视图模式：如果不需要动态调整角度，使用
lock模式可以减少计算 - 及时停止追踪：不需要追踪时及时调用
stop()方法
4.2 数据准备
- 路径数据预处理：如果路径点过多，可以预先进行抽稀处理
- 坐标格式统一：确保所有坐标使用相同的坐标系和单位
- 帧信息优化：使用关键帧模式时，合理设置关键帧数量，避免过多导致卡顿
五、常见问题
5.1 追踪抖动问题
问题：使用PathTracker和ObjectTracker联合时出现抖动
解决方案：
- 确保先初始化
PathTracker，再初始化ObjectTracker - 调整
interpolateDirectThreshold参数 - 检查对象位置更新频率
5.2 路径格式不支持
问题：设置的路径数据格式不被识别
解决方案：
- 检查数据格式是否符合三种支持格式之一
- 确保坐标数组格式正确：
[[lng, lat, alt], ...] - GeoJSON格式需要包含
geometry.type === 'LineString'
5.3 相机角度不正确
问题：相机角度不符合预期
解决方案：
- 检查
pitch和heading参数设置 - 使用
viewMode控制视图行为 - 在关键帧模式下检查
frameInfo数据
六、总结
PathTracker和ObjectTracker是mapv-three中强大的追踪工具，它们可以单独使用，也可以联合使用，实现各种复杂的相机控制和对象追踪效果。
关键要点：
PathTracker适合沿路径移动的场景，支持多种数据格式和视图模式ObjectTracker适合追踪固定对象的场景，配置简单灵活- 联合使用时需要注意初始化顺序，避免抖动问题
- 合理使用配置参数和回调函数，可以优化性能和用户体验
参考：
