PathTracker与ObjectTracker完整使用指南

原创

用户11921230

发布于 2025-11-20 15:30:20

290

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适合追踪固定对象的场景，配置简单灵活
联合使用时需要注意初始化顺序，避免抖动问题
合理使用配置参数和回调函数，可以优化性能和用户体验

参考：

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

前端

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

登录后参与评论

0 条评论

热度

PathTracker与ObjectTracker完整使用指南

PathTracker与ObjectTracker完整使用指南

PathTracker与ObjectTracker完整使用指南

一、PathTracker：路径追踪器

1.1 基本用法

沿路径追踪相机

让3D模型沿路径移动

1.2 支持的路径数据格式

坐标数组格式

GeoJSON格式

帧信息数组格式

1.3 视图模式

跟随模式（follow）

锁定模式（lock）

解锁模式（unlock）

关键帧模式（keyFrame）

活动帧模式（activeFrame）

1.4 高级配置

插值阈值控制

曲线插值

暂停和恢复

回调函数

二、ObjectTracker：对象追踪器

2.1 基本用法

追踪3D模型

2.2 配置参数

参数说明

2.3 追踪帧回调

2.4 停止追踪

三、联合使用场景

3.1 路径追踪 + 对象追踪

四、最佳实践

4.1 性能优化

4.2 数据准备

五、常见问题

5.1 追踪抖动问题

5.2 路径格式不支持

5.3 相机角度不正确

六、总结

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐