@baidumap/mapv-three 1.4.0 → 1.4.1

package/dist/types/threejs/objects/text/ScreenText.d.ts

@@ -0,0 +1,273 @@
+/**
+ * 屏幕文字对象, 支持沿线绘制文字
+ *
+ *
+ * @category Objects
+ */
+export class ScreenText extends GeoMesh {
+    /**
+     * 构造函数
+     * @param {Object} parameters 配置参数
+     * @param {number} [parameters.fontSize=26] 字体大小
+     * @param {string} [parameters.fontFamily='Arial'] 字体族
+     * @param {string} [parameters.color='#ffffff'] 文字颜色
+     * @param {number} [parameters.opacity=1] 不透明度
+     * @param {number} [parameters.strokeWidth=0] 描边宽度
+     * @param {string} [parameters.strokeColor='#000000'] 描边颜色
+     */
+    constructor(parameters?: {
+        fontSize?: number | undefined;
+        fontFamily?: string | undefined;
+        color?: string | undefined;
+        opacity?: number | undefined;
+        strokeWidth?: number | undefined;
+        strokeColor?: string | undefined;
+    });
+    /** @protected */ protected parameters: {
+        fontSize: number;
+        fontFamily: string;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        strokeColor: string;
+        fontWeight: string;
+        keepUpright: boolean;
+        textMaxAngle: number;
+        clippingBuffer: number;
+        debug: boolean;
+    };
+    /** @protected */ protected fontAtlasManager: any;
+    /** @protected */ protected atlasTexture: any;
+    frustumCulled: boolean;
+    matrixAutoUpdate: boolean;
+    renderOrder: number;
+    FlipState: {
+        unknown: number;
+        flipRequired: number;
+        flipNotRequired: number;
+    };
+    _flipStates: Map<any, any>;
+    _textsAlongLinesData: any[];
+    _tempMatrix4: any;
+    _tempVector2: any;
+    _tempVector4: any;
+    _tempVector4_2: any;
+    _measureCanvas: HTMLCanvasElement;
+    _measureCtx: CanvasRenderingContext2D | null;
+    _emptyFrameCount: number;
+    _emptyFrameThreshold: number;
+    _placeTextCache: Map<any, any>;
+    _shapeCache: LRUCache;
+    _debugPolyline: Polyline | null;
+    _debugNormalPoints: SimplePoint | null;
+    _debugAnchorPoints: SimplePoint | null;
+    geometry: ScreenTextGeometry | undefined;
+    material: ScreenTextMaterial | undefined;
+    /**
+     * 初始化调试对象
+     * @private
+     */
+    private _initDebugObjects;
+    /**
+     * 碰撞检测（返回屏幕坐标的字符包围盒）
+     * @param {Object} data 数据项（来自 dataSource.userData）
+     * @returns {Object|null} 包围盒信息 {chars, isProjected, tolerance}
+     */
+    collisionTest(data: Object): Object | null;
+    /**
+     * 更新分辨率
+     * @private
+     */
+    private _updateResolution;
+    /**
+     * 初始化字体图集管理器
+     * @private
+     */
+    private _initFontAtlas;
+    /**
+     * 定义代理属性
+     * @private
+     */
+    private _defineProxyProperties;
+    /**
+     * 设置文字数据（核心API）
+     * @param {Array<Object>} chars 字符数据数组（注意：每个是单个字符！）
+     * @param {number} chars[].x 屏幕X坐标（像素）
+     * @param {number} chars[].y 屏幕Y坐标（像素）
+     * @param {string} chars[].char 单个字符
+     * @param {number} [chars[].rotation=0] 旋转角度（弧度）
+     * @param {number} [chars[].size] 字符大小（可选，默认使用fontSize）
+     * @example
+     * ```javascript
+     * screenText.setTexts([
+     *     { x: 100, y: 100, char: '建', rotation: 0, size: 26 },
+     *     { x: 126, y: 100, char: '国', rotation: 0, size: 26 },
+     *     { x: 152, y: 100, char: '门', rotation: 0, size: 26 }
+     * ]);
+     * ```
+     */
+    setTexts(chars: Array<Object>): void;
+    _lastCharCount: number | undefined;
+    /**
+     * 更新字体图集
+     * @private
+     */
+    private _updateFontAtlas;
+    /**
+     * 沿线绘制单组文字（向后兼容）
+     * @param {string} text 要显示的文字
+     * @param {Array<Array<number>>} line 世界坐标线段数组 [[x,y,z], [x,y,z], ...]
+     * @param {Array<number>} anchor 锚点世界坐标 [x,y,z]
+     * @example
+     * ```javascript
+     * screenText.setTextAlongLine('建国门南大街', line, [x, y, z]);
+     * ```
+     */
+    setTextAlongLine(text: string, line: Array<Array<number>>, anchor: Array<number>): void;
+    /**
+     * 沿线绘制多组文字
+     * @param {Array<Object>} textsData 多组文字数据
+     * @param {string} textsData[].text 要显示的文字
+     * @param {Array<Array<number>>} textsData[].line 世界坐标线段数组
+     * @param {Array<number>} textsData[].anchor 锚点世界坐标
+     * @example
+     * ```javascript
+     * screenText.setTextsAlongLines([
+     *     { text: '建国门南大街', line: line1, anchor: anchor1 },
+     *     { text: '西便门大街', line: line2, anchor: anchor2 }
+     * ]);
+     * ```
+     */
+    setTextsAlongLines(textsData: Array<Object>): void;
+    /**
+     * 渲染前更新
+     * @internal
+     */
+    onBeforeScenePrepareRenderHook(renderer: any, scene: any, camera: any): void;
+    /**
+     * 更新多组沿线文字（新方法）
+     * @private
+     */
+    private _updateTextsAlongLines;
+    /**
+     * 放置单组沿线文字（重构后的核心方法）
+     * @private
+     * @returns {Array} 字符数组，如果过滤则返回空数组
+     */
+    private _placeTextAlongLine;
+    _initializedGroups: Set<any> | undefined;
+    /**
+     * 解析颜色为RGBA数组（归一化到0-1）
+     * @private
+     * @param {string|Array} color - 颜色值（支持多种格式）
+     * @param {string} defaultColor - 默认颜色（十六进制）
+     * @returns {Array} RGBA数组 [r, g, b, a]（0-1范围）
+     */
+    private _parseColorToRgba;
+    /**
+     * 文字形状化（计算每个字符的位置和宽度）
+     * @private
+     */
+    private _shapeText;
+    /**
+     * 计算两点距离
+     * @private
+     */
+    private _distance;
+    /**
+     * 将世界坐标线段转换为屏幕坐标
+     * 包含近平面裁剪处理（处理 w < 0 的情况）
+     * @private
+     */
+    private _lineToScreenCoords;
+    /**
+     * 世界坐标转屏幕坐标
+     * @private
+     */
+    private _worldToScreen;
+    /**
+     * 查找锚点所在的线段
+     * @private
+     */
+    private _findSegmentForAnchor;
+    /**
+     * 计算点到线段的最短距离
+     * @private
+     */
+    private _pointToSegmentDistance;
+    /**
+     * 判断锚点是否在屏幕可见区域内
+     * @private
+     */
+    private _isAnchorVisible;
+    /**
+     * 判断点是否在相机后面（w <= 0）
+     * @private
+     */
+    private _isPointBehindCamera;
+    /**
+     * 判断是否在翻转保持范围内
+     * @private
+     */
+    private _isInFlipRetainRange;
+    /**
+     * 判断是否需要改变朝向（Mapbox 完整算法）
+     * @private
+     */
+    private _requiresOrientationChange;
+    /**
+     * 沿线放置字符
+     * @private
+     */
+    private _placeGlyphAlongLine;
+    _placeGlyphDebugDone: boolean | undefined;
+    /**
+     * 更新调试对象的数据
+     * @private
+     */
+    private _updateDebugObjects;
+    /**
+     * 显示 Atlas 纹理调试面板
+     * @param {Object} options 配置选项
+     * @param {number} [options.size=300] 显示尺寸（像素）
+     * @param {string} [options.position='top-right'] 位置：'top-left', 'top-right', 'bottom-left', 'bottom-right'
+     * @param {boolean} [options.autoUpdate=true] 是否自动更新
+     * @example
+     * ```javascript
+     * screenText.showAtlasDebug({ size: 400, position: 'bottom-right' });
+     * ```
+     */
+    showAtlasDebug(options?: {
+        size?: number | undefined;
+        position?: string | undefined;
+        autoUpdate?: boolean | undefined;
+    }): this;
+    _debugPanel: HTMLDivElement | null | undefined;
+    _debugUpdateInterval: number | null | undefined;
+    /**
+     * 隐藏 Atlas 纹理调试面板
+     */
+    hideAtlasDebug(): this;
+    /**
+     * 获取 Atlas 纹理（用于自定义调试）
+     * @returns {DataTexture} Atlas texture
+     */
+    getAtlasTexture(): DataTexture;
+    /**
+     * 获取字体图集管理器
+     * @returns {FontAtlasManager} Font atlas manager
+     */
+    getFontAtlasManager(): FontAtlasManager;
+    /**
+     * 获取字符集合（从实际的atlas mapping中提取）
+     * @returns {Set} 字符集合
+     */
+    getCharacterSet(): Set<any>;
+}
+import { GeoMesh } from '../GeoMesh';
+import { LRUCache } from '../../../util/LRUCache';
+import { Polyline } from '../line/Polyline';
+import { SimplePoint } from '../point/SimplePoint';
+import { ScreenTextGeometry } from '../../geometries/text/ScreenTextGeometry';
+import { ScreenTextMaterial } from '../../materials/text/ScreenTextMaterial';
+import { FontAtlasManager } from './font-atlas-manager';

package/dist/types/threejs/objects/text/font-atlas-manager.d.ts

@@ -2,20 +2,28 @@ export class FontAtlasManager {
     props: {};
     _entry: {};
     _textureData: Uint8Array<ArrayBuffer>;
+    _currentWidth: number;
+    _currentHeight: number;
     _xOffset: number;
     _yOffset: number;
     _mapping: {};
     _canvasHeight: number;
-    _oldMapping: {};
     /** @private */ private _atlas;
     _ctx: any;
+    _version: number;
     get atlas(): any;
     get mapping(): any;
     setProps(props?: {}): void;
     setPropsAsync(scheduler: any, props?: {}, batchSize?: number): Promise<any>;
     _prepareFontAtlas(): void;
     _generateFontAtlas(characterSet: any): void;
-    _processCharBatch(batch: any): true | undefined;
+    _processCharBatch(batch: any): void;
     _finalizeTextureData(): void;
+    /**
+     * 渲染 textureData
+     * @private
+     */
+    private _debugRenderTexture;
     _createTextureData(characterSet: any): any;
+    _reset(): void;
 }

package/dist/types/threemap/Engine.d.ts

@@ -1,11 +1,13 @@
 /**
  * 引擎核心入口，用来初始化渲染引擎。
  * 内部核心系统包括：
- * - {@link EngineMap} 地图系统
+ * - {@link EngineMap} 地图视野系统
  * - {@link EngineRendering} 渲染系统
  * - {@link EngineEvent} 事件系统
  * - {@link EngineWidgets} UI控件系统
  * - {@link EngineSelection} 选择器系统
+ * - {@link EngineController} 键鼠交互控制器系统
+ * - {@link EngineClock} 时钟系统
  *
  * @category Core
  * @example
@@ -31,14 +33,16 @@ export class Engine {
         selection: object;
         widgets: object;
     });
-    /** @internal */ _container: HTMLElement;
+    /** @internal */ _container: HTMLElement | null;
     /** @internal */ _event: EngineEvent;
     /** @internal */ _map: EngineMap;
     /** @internal */ _rendering: EngineRendering;
     /** @internal */ _selection: EngineSelection;
     /** @internal */ _widgets: EngineWidgets;
     /** @internal */ _clock: EngineClock;
+    /** @internal */ _controller: EngineController;
     isEngine: boolean;
+    _id: number;
     /**
      * 将object放到渲染场景中
      * @param {Object3D} object threejs或者mapvthree的object对象
@@ -134,9 +138,9 @@ export class Engine {
     private unlockCamera;
     /**
      * 渲染电影
-     * @param {Movie} movie 电影对象
+     * @param {VideoConfig} videoConfig 影片配置对象
      */
-    renderVideo(videoConfig: any): Promise<void>;
+    renderVideo(videoConfig: VideoConfig): Promise<void>;
     /**
      * 容器对象
      * @type {HTMLElement}
@@ -181,6 +185,14 @@ export class Engine {
      * 时钟对象，用于模拟时间
      */
     get clock(): EngineClock;
+    /**
+     * 键鼠交互控制器对象
+     */
+    get controller(): EngineController;
+    /**
+     * 引擎实例唯一ID
+     */
+    get id(): number;
     /**
      * 释放全部资源，之后引擎实例不再可用
     */
@@ -197,3 +209,4 @@ import { EngineRendering } from './engine/Rendering';
 import { EngineSelection } from './engine/Selection';
 import { EngineWidgets } from './engine/Widgets';
 import { EngineClock } from './engine/Clock';
+import { EngineController } from './engine/Controller';

package/dist/types/threemap/engine/Controller.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 键鼠交互控制器API
+* @category Internal
+ * @example
+ * ```javascript
+ * // 访问控制器
+ * const controller = engine.controller;
+ *
+ *  // 设置是否启用
+ * controller.enabled = true;
+ *
+ * // 设置是否启用旋转
+ * controller.enableRotate = true;
+ *
+ * // 设置是否启用缩放
+ * controller.enableZoom = true;
+ *
+ * // 设置是否启用平移
+ * controller.enablePan = true;
+ *
+ * // 设置惯性拖拽
+ * controller.inertiaDragging = 0.9;
+ *
+ * // 设置惯性缩放
+ * controller.inertiaZoom = 0.8;
+ * ```
+ *
+ */
+export class EngineController {
+    constructor(engine: any, options?: {});
+    /** @internal */ _engine: any;
+    _enabled: boolean;
+    _enableRotate: boolean;
+    _enableZoom: boolean;
+    _enablePan: boolean;
+    _enableTilt: boolean;
+    _enableFixCenter: boolean;
+    _enableTerrainCollision: boolean;
+    _inertiaDragging: number;
+    _inertiaZoom: number;
+    _maximumMovementRatio: number;
+    _bounceAnimationTime: number;
+    _minimumZoomDistance: number;
+    _maximumZoomDistance: number;
+    /**
+     * 设置是否启用控制器，设置为false时，地图将无法响应任何交互事件
+     * @type {Boolean}
+     * @default true
+     */
+    set enabled(value: boolean);
+    /**
+     * 是否启用控制器
+     * @type {Boolean}
+     * @default true
+     */
+    get enabled(): boolean;
+    /**
+     * 设置是否启用旋转
+     * @type {Boolean}
+     * @default true
+     */
+    set enableRotate(value: boolean);
+    /**
+     * 是否启用旋转
+     * @type {Boolean}
+     * @default true
+     */
+    get enableRotate(): boolean;
+    /**
+     * 设置是否启用缩放
+     * @type {Boolean}
+     * @default true
+     */
+    set enableZoom(value: boolean);
+    /**
+     * 是否启用缩放
+     * @type {Boolean}
+     * @default true
+     */
+    get enableZoom(): boolean;
+    /**
+     * 设置是否启用平移
+     * @type {Boolean}
+     * @default true
+     */
+    set enablePan(value: boolean);
+    /**
+     * 是否启用平移
+     * @type {Boolean}
+     * @default true
+     */
+    get enablePan(): boolean;
+    /**
+     * 设置是否启用倾斜
+     * @type {Boolean}
+     * @default true
+     */
+    set enableTilt(value: boolean);
+    /**
+     * 是否启用倾斜
+     * @type {Boolean}
+     * @default true
+     */
+    get enableTilt(): boolean;
+    set enableFixCenter(value: boolean);
+    get enableFixCenter(): boolean;
+    set enableTerrainCollision(value: boolean);
+    get enableTerrainCollision(): boolean;
+    inertiaTranslate: any;
+    /**
+     * 设置惯性缩放，0-1，0表示完全禁用惯性缩放，1表示惯性达到最大
+     * @type {Number}
+     * @default 0.8
+     */
+    set inertiaZoom(value: number);
+    /**
+     * 惯性缩放值
+     * @type {Number}
+     * @default 0.8
+     */
+    get inertiaZoom(): number;
+    set maximumMovementRatio(value: number);
+    get maximumMovementRatio(): number;
+    set bounceAnimationTime(value: number);
+    get bounceAnimationTime(): number;
+    set minimumZoomDistance(value: number);
+    get minimumZoomDistance(): number;
+    set maximumZoomDistance(value: number);
+    get maximumZoomDistance(): number;
+    /**
+     * 设置惯性拖拽，0-1，0表示完全禁用惯性拖拽，1表示惯性达到最大
+     * @default 0.9
+     */
+    set inertiaDragging(value: number);
+    /**
+     * 惯性拖拽值
+     * @type {Number}
+     * @default 0.9
+     */
+    get inertiaDragging(): number;
+}

package/dist/types/threemap/engine/Map.d.ts

@@ -1,5 +1,5 @@
 /**
- * 地图管理器<br/>
+ * 地图管理器，主要负责地图视野控制相关功能<br/>
  * 该类会随{@link Engine}的初始化自动实例化，不需要开发者手动执行初始化调用，通过`engine.map`访问
  *
  * @category Internal
@@ -99,6 +99,11 @@ export class EngineMap {
      * @param {number} range 距离
      */
     setMaxRange(range: number): void;
+    /**
+     * 设置3d地图最近视距
+     * @param {number} range 距离
+     */
+    setMinRange(range: number): void;
     /**
      * 设置地图视野
      * @param {Array | Vector3} target 目标视野中心点, 经纬度和海拔高度
@@ -259,11 +264,15 @@ export class EngineMap {
      */
     projectArrayCoordinates(coordinates: any): number[];
     /**
+     * @internal
+     * @deprecated
      * 开启地图控制，允许用户拖动、平移、旋转等操作
      */
     enableControl(): void;
     /**
      * 禁用地图控制
+     * @internal
+     * @deprecated
      */
     disableControl(): void;
     /**
@@ -333,6 +342,7 @@ export class EngineMap {
      */
     pickSeaLevelWorldPosition(pixel: Array<number>): Vector3;
     /**
+     * @internal 引擎销毁时内部自动调用
      * 销毁地图实例，移除其绑定事件
      */
     dispose(): void;
@@ -357,9 +367,11 @@ export class EngineMap {
      */
     get mapType(): string | undefined;
     /**
+     * @internal
+     * @deprecated
      * 获取map的dom容器
      */
-    get container(): any;
+    get container(): HTMLElement | undefined;
     set fov(fov: any);
     /**
      * 获取地图视野开角

package/dist/types/threemap/engine/event/EntityProxy.d.ts

@@ -9,6 +9,7 @@ export class EntityProxy {
     _object: any;
     _intersection: any;
     _computeEntity(): any;
+    _addPointProperty(entity: any): void;
     get entity(): any;
     _entity: any;
     get intersection(): any;

package/dist/types/threemap/engine/map/BlankMap.d.ts

@@ -108,4 +108,4 @@ export class BlankMap extends BaseMap {
     get far(): number;
 }
 import { BaseMap } from './BaseMap';
-import { MapControl } from '../../../threejs/controls/MapControl';
+import { MapControl } from './controls/MapControl';

package/dist/types/threemap/engine/map/BlankMap3DControl.d.ts

@@ -2,7 +2,8 @@ export class BlankMap3DControl extends BlankMap {
     isBlankMap3D: boolean;
     /** @private */
     private _viewStateDirty;
-    maxRange: any;
+    maxRange: number;
+    minRange: number;
     range: any;
     bounds: any[];
     /**
@@ -23,6 +24,7 @@ export class BlankMap3DControl extends BlankMap {
      */
     getCameraDistance(forceUpdate: any): any;
     setRange(range: any): void;
+    setMinRange(range: any): void;
     /**
      * 相机指向某个具体目标，
      * @param {*} target 目标点
@@ -41,5 +43,6 @@ export class BlankMap3DControl extends BlankMap {
     };
     lockDrag(status: any): void;
     handleEventCameraChange: () => boolean;
+    get controller(): import("./controls/MapControl").MapControl | undefined;
 }
 import { BlankMap } from './BlankMap';

package/dist/types/{threejs → threemap/engine/map}/controls/DraggingMovementAggregator.d.ts

@@ -16,8 +16,11 @@ export class DraggingMovementAggregator {
     _amplitudeY: number;
     _targetX: number;
     _targetY: number;
+    _scale: number;
     start(x: any, y: any, time: any): void;
     update(x: any, y: any, time: any): void;
     startInertia(isOperateRotation?: boolean): void;
     getInertiaPosition(time: any): any[];
+    set scale(scale: number);
+    get scale(): number;
 }

package/dist/types/{threejs → threemap/engine/map}/controls/MapControl3D.d.ts

@@ -25,7 +25,16 @@ export class MapControl3D {
     startProjectionCenter: any;
     /** @private */
     private _enabled;
-    enableInertia: boolean;
+    /** @private */
+    private _enableRotate;
+    /** @private */
+    private _enableZoom;
+    /** @private */
+    private _enablePan;
+    /** @private */
+    private _enableTilt;
+    /** @private 历史遗留问题，不对外暴露 */
+    private enableInertia;
     minPitch: number;
     maxPitch: number;
     zoomSpeed: number;
@@ -154,7 +163,15 @@ export class MapControl3D {
     _tiltBounceBack: () => void;
     _pickPosition(mouse: any): Promise<any>;
     dispose: () => void;
+    set enableRotate(enabled: any);
+    set enableZoom(enabled: any);
+    set enablePan(enabled: any);
+    set enableTilt(enabled: any);
+    set inertiaDragging(scale: number);
+    get inertiaDragging(): number;
+    set inertiaZoom(scale: number);
+    get inertiaZoom(): number;
 }
-import { EventThrottle } from '../../threemap/engine/event/EventThrottle';
+import { EventThrottle } from '../../event/EventThrottle';
 import { DraggingMovementAggregator } from './DraggingMovementAggregator';
 import { PointerMovementAggregator } from './PointerMovementAggregator';

package/dist/types/{threejs → threemap/engine/map}/controls/PointerMovementAggregator.d.ts

@@ -14,10 +14,13 @@ export class PointerMovementAggregator {
     private _inertiaSpeed;
     /** @private */
     private _inertiaDirection;
+    _scale: number;
     start(x: any, y: any, time: any): void;
     update(x: any, y: any, time: any): void;
     setInertiaState(speed: any, direction: any, time: any): void;
     startInertia(): void;
     getInertiaPosition(time: any): any[];
     get inertiaDirection(): any;
+    set scale(scale: number);
+    get scale(): number;
 }

package/dist/types/threemap/engine/map/earth/Earth.d.ts

@@ -105,6 +105,7 @@ export class Earth extends BaseMap {
     _canvas: any;
     set farScale(value: number);
     get farScale(): number;
+    get controller(): ScreenSpaceCameraController | undefined;
 }
 import { BaseMap } from '../BaseMap';
 import { Ellipsoid } from './Ellipsoid';

package/dist/types/threemap/engine/rendering/Collision.d.ts

@@ -121,6 +121,11 @@ export class RenderingCollision {
      */
     _collisionTest(): false | undefined;
     _getScreenPosition(position: any, matrix: any, width: any, height: any): any[];
+    /**
+     * 计算已投影的字符包围盒（屏幕坐标）
+     * @private
+     */
+    private _computeProjectedCharBoundingBoxes;
     _computeCharBoundingBoxes(chars: any, pixelSize: any, rotationMatrix: any, basePosition: any, camera: any, cameraOffset: any, matrix4: any, margin: any, tolerance: any, containerWidth: any, containerHeight: any): {
         minX: number;
         minY: number;