@baidumap/mapv-three 1.3.3 → 1.4.1

package/dist/types/threemap/animations/ObjectTracker.d.ts

@@ -1,66 +1,95 @@
+/**
+ * 对象追踪器，用于追踪指定的3D对象或坐标点
+ *
+ * `ObjectTracker`可以追踪各种Three.js `Object3D` 对象
+ *
+ * @category Camera
+ * @extends TrackerAbstract
+ * @example
+ * ```javascript
+ * // 基本用法 - 追踪3D模型
+ * const model = engine.add(new mapvthree.SimpleModel({
+ *     url: 'path/to/model.glb'
+ * }));
+ *
+ * const tracker = engine.add(new mapvthree.ObjectTracker());
+ * tracker.track(model, {
+ *     range: 100,
+ *     pitch: 60,
+ * });
+ * ```
+ */
 export class ObjectTracker extends TrackerAbstract {
     /**
+     * @private
      * 计算世界坐标系下的变换后 AABB（修正为 8 个唯一顶点）
      */
-    static computeTransformedBoundingBox(box: any, transform: any): any;
+    private static computeTransformedBoundingBox;
     /** @private */ private _trackObject;
     /** @private */ private _trackConfig;
     /** @private */ private _lastState;
     /**
-   * 开始追踪
-   * @param {Object3D|Vector3|[number,number,number]|{instance:any,instanceIndex:number}} object
-   * @param {{
-   *   radius?:number, pitch?:number, heading?:number,
-   *   lock?:boolean, height?:number, extraDir?:number,
-   *   duration?:number, easing?:string|Function
-   * }} config
-   */
-    track(object: Object3D | Vector3 | [number, number, number] | {
-        instance: any;
-        instanceIndex: number;
-    }, config?: {
-        radius?: number;
-        pitch?: number;
-        heading?: number;
-        lock?: boolean;
-        height?: number;
-        extraDir?: number;
-        duration?: number;
-        easing?: string | Function;
+     * 开始追踪指定对象
+     *
+     * @param {Object3D} object 追踪的对象
+     *   - Object3D: Three.js 3D对象
+     * @param {Object} config 追踪配置
+     * @param {number} [config.range=0] 追踪距离
+     * @param {number} [config.pitch=0] 俯仰角
+     * @param {number} [config.heading=0] 方位角
+     * @param {number} [config.height=0] 高度偏移
+     * @param {number} [config.extraDir] 额外方向修正角度
+     * @param {number} [config.duration=0] 持续时间（0表示持续追踪）
+     * @example
+     * ```javascript
+     * // 追踪3D模型，设置相机距离和角度
+     * tracker.track(model, {
+     *     range: 100,    // 距离100米
+     *     pitch: 60,     // 俯仰角60
+     *     heading: 45,   // 方位角45
+     * });
+     * ```
+     */
+    track(object: Object3D, config?: {
+        range?: number | undefined;
+        pitch?: number | undefined;
+        heading?: number | undefined;
+        height?: number | undefined;
+        extraDir?: number | undefined;
+        duration?: number | undefined;
     }): void;
     /**
-   * 基类要求：根据 ratio（0~1）返回当前帧状态
-   * 返回 { point: 地图坐标数组, hpr: {heading, pitch, roll} }
-   */
-    updatePositionByPercentage(): {
-        point: any[];
-        hpr: {
-            heading: number;
-            pitch: number;
-            roll: number;
-        };
-    } | null;
+     * @private
+     * 根据进度比例更新位置
+     * @param {number} ratio 进度比例 (0-1)
+     * @returns {Object|null} 返回 { point: 地图坐标数组, hpr: {heading, pitch, roll} }
+     */
+    private updatePositionByPercentage;
+    /**
+     * 追踪帧回调函数, 在每帧更新时调用
+     * @param {Object|null} lastState 上一帧状态
+     * @param {Object} currentState 当前帧状态
+     * @example
+     * ```javascript
+     * tracker.onTrackFrame = (lastState, currentState) => {
+     *     console.log('追踪状态更新:', currentState);
+     *     // 自定义逻辑
+     * };
+     * ```
+     */
     onTrackFrame(): void;
     /**
+     * @private
      * 计算目标点与朝向（内部统一从“世界坐标”推导 → 转为“地图坐标”返回）
      */
-    _computeTargetState(target: any, view: any): {
-        point: any[];
-        hpr: {
-            heading: number;
-            pitch: number;
-            roll: number;
-        };
-    };
+    private _computeTargetState;
     /**
+     * @private
      * 采样目标的“世界中心点 + 朝向”
      * - 支持 instanced entity
      * - 支持 Object3D（合并子层级包围盒 → 取 boundingSphere.center）
      * - 支持 Vector3 / [x,y,z]
      */
-    _sampleTargetWorldPose(target: any, view: any): {
-        worldCenter: any;
-        targetEuler: any;
-    };
+    private _sampleTargetWorldPose;
 }
 import { TrackerAbstract } from './TrackerAbstract';

package/dist/types/threemap/animations/PathTracker.d.ts

@@ -1,18 +1,53 @@
+/**
+ * 路径追踪器，用于沿指定路径进行相机或对象的动画追踪
+ *
+ * `PathTracker` 支持多种路径数据格式，包括坐标数组、GeoJSON和带帧信息的对象数组。
+ * 可以设置不同的视图模式（跟随、锁定、关键帧等）来实现各种追踪效果。
+ *
+ * @category Camera
+ * @extends TrackerAbstract
+ * @example
+ * ```javascript
+ * // 基本用法 - 沿路径追踪相机
+ * const tracker = engine.add(new mapvthree.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
+ * });
+ * ```
+ * @example
+ * ```javascript
+ * // 对象追踪 - 让3D模型沿路径移动
+ * const model = engine.add(new mapvthree.SimpleModel({
+ *     url: 'path/to/model.glb'
+ * }));
+ *
+ * const tracker = engine.add(new mapvthree.PathTracker());
+ * tracker.track = pathCoordinates;
+ * tracker.object = model; // 设置要追踪的对象
+ * tracker.start({
+ *     duration: 8000,
+ *     range: 50
+ * });
+ * ```
+ */
 export class PathTracker extends TrackerAbstract {
-    _sampledPath: any[];
-    _arcInfo: {};
+    /** @private */ private _sampledPath;
+    /** @private */ private _arcInfo;
     /** @private */ private _interpolateDirectThreshold;
     /** @private */ private _interpolateDirectThresholdPercent;
     updatePositionByPercentage(ratio: any): {
         point: any;
-        hpr: {
-            heading: number;
-            pitch: number;
-            roll: number;
-        };
-        direction: any;
-    } | {
-        point: any[];
         hpr: {
             heading: any;
             pitch: any;
@@ -21,14 +56,6 @@ export class PathTracker extends TrackerAbstract {
     } | undefined;
     _interpolatePath(ratio: any): {
         point: any;
-        hpr: {
-            heading: number;
-            pitch: number;
-            roll: number;
-        };
-        direction: any;
-    } | {
-        point: any[];
         hpr: {
             heading: any;
             pitch: any;
@@ -59,7 +86,7 @@ export class PathTracker extends TrackerAbstract {
         transPercent: number;
     };
     _updatePositionAndDirection(last: any, current: any, percent: any, isTrans: any, transPercent: any): {
-        point: any[];
+        point: any;
         hpr: {
             heading: any;
             pitch: any;
@@ -88,9 +115,10 @@ export class PathTracker extends TrackerAbstract {
         pitch: number;
     }[] | undefined;
     /**
+     * @private
      * 计算两点间的地图倾斜角度
      */
-    _getRadians(v0: any, v1: any): number;
+    private _getRadians;
     _parseCoordinateArray(target: any): {
         track: any[];
         frameInfo: never[];
@@ -111,15 +139,55 @@ export class PathTracker extends TrackerAbstract {
     } | undefined;
     /**
      * 设置路径数据
+     *
+     * 支持多种数据格式：
+     * - ***坐标数组***：[[lng, lat, alt], [lng, lat, alt], ...]
+     * - ***GeoJSON***：{geometry: {type: 'LineString', coordinates: [...]}, properties: {frameInfo: [...]}}
+     * - ***帧信息数组***：[{x, y, z, yaw, pitch, speed, time}, ...]
+     *
      * @param {Array|Object} target 路径数据
+     * @example
+     * ```javascript
+     * // 坐标数组格式
+     * tracker.track = [
+     *     [112.368264, 23.176959, 38.553634],
+     *     [112.370264, 23.178959, 40.553634]
+     * ];
+     * ```
      */
     set track(target: any[] | Object);
-    get track(): any[] | Object;
+    /**
+     * 获取当前路径数据
+     * @returns {Array|null} 路径数据
+     */
+    get track(): any[] | null;
+    /**
+     * 设置插值直接阈值
+     * 用于控制路径插值的平滑程度，值越大路径拐角过渡越平滑，但也会越偏离实际路线
+     * @param {number} value 阈值
+     */
     set interpolateDirectThreshold(value: number);
+    /**
+     * 获取插值直接阈值
+     * @returns {number} 当前阈值
+     */
     get interpolateDirectThreshold(): number;
-    set pointHandle(value: any);
-    get pointHandle(): any;
-    _pointHandle: any;
+    /**
+     * 设置轨迹点插值方式
+     * @param {string} value 插值方式，可选值：'curve'（曲线插值）
+     * @example
+     * ```javascript
+     * // 启用曲线插值，使路径更加平滑
+     * tracker.pointHandle = 'curve';
+     * ```
+     */
+    set pointHandle(value: string);
+    /**
+     * 获取轨迹点插值方式
+     * @returns {string} 当前插值方式
+     */
+    get pointHandle(): string;
+    _pointHandle: string | undefined;
     curvePath: any;
 }
 import { TrackerAbstract } from './TrackerAbstract';

package/dist/types/threemap/animations/RotateTracker.d.ts

@@ -1,29 +1,123 @@
+/**
+ * 旋转追踪器，用于围绕指定对象或坐标点进行环绕追踪
+ *
+ * RotateTracker 可以实现相机围绕目标对象的环绕动画，支持：
+ * - 围绕3D对象旋转
+ * - 围绕地理坐标点旋转
+ * - 围绕投影坐标点旋转
+ *
+ * @category Camera
+ * @extends TrackerAbstract
+ * @example
+ * ```javascript
+ * // 基本用法 - 围绕3D模型旋转
+ * const model = engine.add(new mapvthree.SimpleModel({
+ *     url: 'path/to/model.glb'
+ * }));
+ *
+ * const tracker = engine.add(new mapvthree.RotateTracker());
+ * tracker.start({
+ *     object: model,
+ *     radius: 100,
+ *     duration: 10000,
+ *     startAngle: 0,
+ *     endAngle: 360
+ * });
+ * ```
+ * @example
+ * ```javascript
+ * // 围绕地理坐标点旋转
+ * const tracker = engine.add(new mapvthree.RotateTracker());
+ * tracker.start({
+ *     center: [112.368264, 23.176959, 38.553634],
+ *     radius: 200,
+ *     duration: 15000,
+ *     pitch: 60,
+ *     heading: 45
+ * });
+ * ```
+ */
 export class RotateTracker extends TrackerAbstract {
-    center: number[];
-    radius: number;
-    _orbitNormal: any;
-    _startVector: any;
-    _pitchOffset: number;
+    /**
+     * 创建旋转追踪器
+     * @param {Object} options 配置选项
+     */
+    constructor(options?: Object);
+    _trackedObject: any;
     _runConfig: {
-        center: any;
-        radius: any;
+        center: any[] | null;
+        projectedCenter: any[] | null;
+        radius: number;
         startAngle: any;
         endAngle: any;
-        clockwise: any;
-        loopMode: any;
-        height: any;
-    } | undefined;
+        loopMode: string;
+        heading: any;
+        pitch: any;
+        useWorldAxis: boolean;
+        height: number;
+    } | null;
+    viewMode: string;
+    /**
+     * 开始旋转追踪
+     *
+     * @param {Object} options 配置选项
+     * @param {number} [options.duration=10000] 动画持续时间(毫秒)
+     * @param {number} [options.heading=0] 方位角(度)
+     * @param {number} [options.pitch=0] 俯仰角(度)
+     * @param {number} [options.range=0] 距离范围(米)
+     * @param {string|Function} [options.easing] 缓动函数，默认值'linear', 支持'linear'|'ease-in'|'ease-out'|'ease-in-out'
+     * @param {Object3D} [options.object] 要围绕的3D对象
+     * @param {Array} [options.center] 地理坐标 [lng, lat, alt]
+     * @param {Array} [options.projectedCenter] 投影坐标 [x, y, z]
+     * @param {number} [options.radius=100] 旋转半径
+     * @param {number} [options.startAngle=0] 起始角度（度）
+     * @param {number} [options.endAngle=360] 结束角度（度）
+     * @param {string} [options.loopMode='repeat'] 循环模式：'repeat'|'reverse'|'alternate',
+     * `repeat` 表示一直按同方向循环，`alternate` 表示往返循环，`reverse` 表示始终反向循环。
+     * @param {boolean} [options.keepRunning=true] 是否持续运行
+     * @param {boolean} [options.useWorldAxis=false] 是否使用世界轴
+     * @param {number} [options.repeatCount=1] 重复次数，默认值1
+     * @param {number} [options.height=0] 高度偏移(米)
+     * @example
+     * ```javascript
+     * // 围绕3D模型旋转
+     * tracker.start({
+     *     object: model,
+     *     radius: 100,
+     *     duration: 10000,
+     *     startAngle: 0,
+     *     endAngle: 360,
+     *     pitch: 60
+     * });
+     * ```
+     */
+    start(options?: {
+        duration?: number | undefined;
+        heading?: number | undefined;
+        pitch?: number | undefined;
+        range?: number | undefined;
+        easing?: string | Function | undefined;
+        object?: any;
+        center?: any[] | undefined;
+        projectedCenter?: any[] | undefined;
+        radius?: number | undefined;
+        startAngle?: number | undefined;
+        endAngle?: number | undefined;
+        loopMode?: string | undefined;
+        keepRunning?: boolean | undefined;
+        useWorldAxis?: boolean | undefined;
+        repeatCount?: number | undefined;
+        height?: number | undefined;
+    }): void;
+    /**
+     * @private
+     * 计算 ENU 基向量
+     */
+    private _computeLocalAxes;
     /**
-     * 根据 ratio 计算圆周位置
+     * @private
+     * 计算轨道法线和起始向量
      */
-    updatePositionByPercentage(ratio: any): {
-        point: any;
-        hpr: {
-            heading: any;
-            pitch: any;
-            roll: any;
-        };
-        direction: any;
-    };
+    private _computeOrbitAxes;
 }
 import { TrackerAbstract } from './TrackerAbstract';

package/dist/types/threemap/animations/TrackerAbstract.d.ts

@@ -5,12 +5,12 @@ export namespace VIEW_MODEL_MAP {
     let KEYFRAME: string;
     let ACTIVEFRAME: string;
 }
-export namespace Easing {
-    function linear(t: any): any;
-    function easeInQuad(t: any): number;
-    function easeOutQuad(t: any): number;
-    function easeInOutQuad(t: any): number;
-}
+export const Easing: {
+    linear: (t: any) => any;
+    'ease-in': (t: any) => number;
+    'ease-out': (t: any) => number;
+    'ease-in-out': (t: any) => number;
+};
 export class TrackerAbstract {
     constructor(options?: {});
     /** @private */ private _isRunning;
@@ -26,9 +26,10 @@ export class TrackerAbstract {
     /** @public */ public onStart: null;
     /** @public */ public onFinish: null;
     /** @public */ public onUpdate: null;
-    /** @private */ private _loopMode;
     /** @private */ private _runtime;
     /** @private */ private _withoutTrack;
+    /** @private */ private _repeatCount;
+    /** @private */ private _completedCount;
     _debug: boolean;
     _trackPoint: null;
     _trackLists: any[];
@@ -41,16 +42,20 @@ export class TrackerAbstract {
     _easingFn: (t: any) => any;
     _currentEasingFn: (t: any) => any;
     _resolveEasing(easing: any): any;
+    onBeforeScenePrepareRender(engine: any, scene: any, camera: any, renderState: any): void;
     afterAddToEngine(engine: any): void;
     _engine: any;
     /**
+     * @private
      * 根据百分比更新位置的核心方法
      * 子类需要重写此方法来实现具体的插值逻辑
      * @param {number} ratio 进度比例 (0-1)
      * @returns {Object} 更新后的状态
      */
-    updatePositionByPercentage(ratio: number): Object;
+    private updatePositionByPercentage;
     start(options?: {}): void;
+    _delay: number | undefined;
+    _direction: any;
     /**
      * 暂停动画
      * @returns 当前状态
@@ -62,9 +67,10 @@ export class TrackerAbstract {
     stop(): void;
     _arcInfo: {} | undefined;
     /**
+     * @protected
      * 更新动画状态
      */
-    update: () => void;
+    protected update: () => void;
     dirUpToHPR(direction: any, position: any, up: any): {
         heading: any;
         pitch: any;
@@ -98,6 +104,4 @@ export class TrackerAbstract {
     set object(value: any);
     get object(): any;
     _object: any;
-    set loopMode(v: string);
-    get loopMode(): string;
 }

package/dist/types/threemap/controls/PointerLockControls.d.ts

@@ -6,8 +6,9 @@
  * - S：向后移动
  * - D：向右移动
  * - L：旋转视野
- *
- * ```js
+ * @category Camera
+ * @example
+ * ```javascript
  * const control = new mapvthree.PointerLockControl(engine);
  * // 开启鼠标控制
  * control.enableKeyboardEvent = true;
@@ -29,7 +30,10 @@ export class PointerLockControl extends PointerLockControls {
     /** @private */ private _velocity;
     /** @private */ private _direction;
     _engine: any;
+    isGlobe: any;
     set stepSize(value: any);
+    controller: Scene3DController | ColumbusController;
+    createController(): Scene3DController | ColumbusController;
     set enableKeyboardEvent(value: any);
     /**
      * @private
@@ -54,3 +58,5 @@ export class PointerLockControl extends PointerLockControls {
     _topStepSize: any;
 }
 import { PointerLockControls } from '../../threejs/controls/PointerLockControls';
+import { Scene3DController } from './controller/Scene3DController';
+import { ColumbusController } from './controller/ColumbusController';

package/dist/types/threemap/controls/controller/ColumbusController.d.ts

@@ -0,0 +1,10 @@
+export class ColumbusController {
+    constructor(pointerSpeed?: number);
+    pointerSpeed: number;
+    minPolarAngle: number;
+    maxPolarAngle: number;
+    handleMouseMove(camera: any, event: any): void;
+    moveForward(camera: any, distance: any): void;
+    moveRight(camera: any, distance: any): void;
+    moveUp(camera: any, distance: any): void;
+}

package/dist/types/threemap/controls/controller/Scene3DController.d.ts

@@ -0,0 +1,9 @@
+export class Scene3DController {
+    constructor(ellipsoidCamera: any, pointerSpeed?: number);
+    ellipsoidCamera: any;
+    pointerSpeed: number;
+    handleMouseMove(camera: any, event: any): void;
+    moveForward(camera: any, distance: any): void;
+    moveRight(camera: any, distance: any): void;
+    moveUp(camera: any, distance: any): void;
+}

package/dist/types/threemap/controls/editors/Editor.d.ts

@@ -22,6 +22,7 @@ export class Editor {
     /** @private */ private _selectedIndex;
     /** @private */ private _mode;
     /** @private */ private _debug;
+    /** @private */ private _visible;
     _eventBindings: any[];
     _STAGES: {
         [STAGE.UNREADY]: {
@@ -250,6 +251,8 @@ export class Editor {
     get idleStage(): number;
     set data(value: any);
     get data(): any;
+    set visible(value: boolean);
+    get visible(): boolean;
     /**
      * 指定编辑元素
      * @param {number} index 元素索引