@baidumap/mapv-three 1.0.1 → 1.2.0

package/dist/types/threemap/mapView/tileProvider/vector/MapboxVectorTileProvider.d.ts

@@ -1,28 +1,129 @@
+/**
+ * Mapbox矢量瓦片提供者，用于加载和渲染Mapbox矢量瓦片数据。
+ * 支持Mapbox样式规范，提供完整的矢量瓦片渲染功能。
+ *
+ * 主要功能：
+ * - 支持Mapbox矢量瓦片加载和解析
+ * - 支持Mapbox样式规范（version 8）
+ * - 支持多种图层类型（填充、线条、符号、挤压等）
+ * - 支持自定义样式和访问令牌
+ * - 支持POI标签渲染
+ *
+ * @category MapView
+ * @example
+ * ```javascript
+ * // 创建Mapbox矢量瓦片提供者
+ * const provider = new mapvthree.MapboxVectorTileProvider({
+ *     style: 'mapbox://styles/mapbox/streets-v11',
+ *     accessToken: 'your_mapbox_access_token'
+ * });
+ *
+ * // 使用自定义样式
+ * const customProvider = new mapvthree.MapboxVectorTileProvider({
+ *     style: 'path/to/custom-style.json',
+ * });
+ * ```
+ */
 export class MapboxVectorTileProvider extends VectorTileProvider {
-    constructor(options?: {});
-    /** @private */
+    /**
+     * @param {object} options 配置选项
+     * @param {string} [options.style] Mapbox样式URL或本地样式文件路径，默认为 'mapbox://styles/mapbox/streets-v11'
+     * @param {string} [options.accessToken] Mapbox访问令牌，如果不提供则使用全局配置
+     * @param {object} [options.defaultStyle] 默认样式配置
+     * @param {object} [options.displayOptions] 显示选项
+     * @param {boolean} [options.displayOptions.background=true] 是否显示背景
+     * @param {boolean} [options.displayOptions.base=true] 是否显示基础面
+     * @param {boolean} [options.displayOptions.link=true] 是否显示道路
+     * @param {boolean} [options.displayOptions.building=true] 是否显示3D建筑物
+     * @param {boolean} [options.displayOptions.poi=true] 是否显示POI
+     */
+    constructor(options?: {
+        style?: string | undefined;
+        accessToken?: string | undefined;
+        defaultStyle?: object | undefined;
+        displayOptions?: {
+            background?: boolean | undefined;
+            base?: boolean | undefined;
+            link?: boolean | undefined;
+            building?: boolean | undefined;
+            poi?: boolean | undefined;
+        } | undefined;
+    });
+    /**
+     * 瓦片提供者名称
+     * @readonly
+     */
+    readonly name: "MapboxVectorTileProvider";
+    /**
+     * 是否渲染占位符
+     * @private
+     */
     private _shouldRenderPlaceholder;
-    /** @private */
+    /**
+     * 默认起始缩放级别
+     * @private
+     */
     private _defaultStartLevel;
-    /** @private */
+    /**
+     * 默认最大缩放级别
+     * @private
+     */
     private _defaultMaxLevel;
-    /** @private */
+    /**
+     * LOD缩放因子
+     * @private
+     */
+    private _lodScaleFactor;
+    /**
+     * 默认材质集合
+     * @private
+     */
     private _defaultMaterials;
-    /** @private */
+    /**
+     * 符号集合
+     * @private
+     */
     private _symbols;
-    /** @private */
+    /**
+     * 材质管理器
+     * @private
+     */
     private _materialManager;
-    _style: any;
-    _accessToken: any;
-    _defaultStyle: any;
-    _dispalyOptions: any;
-    _options: {};
+    _style: string;
+    _accessToken: string | null;
+    _defaultStyle: object | undefined;
+    _dispalyOptions: {
+        background?: boolean | undefined;
+        base?: boolean | undefined;
+        link?: boolean | undefined;
+        building?: boolean | undefined;
+        poi?: boolean | undefined;
+    };
+    _options: {
+        style?: string | undefined;
+        accessToken?: string | undefined;
+        defaultStyle?: object | undefined;
+        displayOptions?: {
+            background?: boolean | undefined;
+            base?: boolean | undefined;
+            link?: boolean | undefined;
+            building?: boolean | undefined;
+            poi?: boolean | undefined;
+        } | undefined;
+    };
     /**
-     * 异步初始化方法。
+     * 异步初始化方法
+     * 初始化数据加载器和样式
+     * @private
      */
-    _asyncInit(): Promise<void>;
+    private _asyncInit;
     _dataLoader: AsyncDataTileLoader | undefined;
-    _loadStyle(): Promise<void>;
+    /**
+     * 加载样式文件
+     * 解析Mapbox样式规范并设置相关配置
+     * @private
+     */
+    private _loadStyle;
     _stylePath: string | undefined;
     _sourceUrl: any;
     _styleJSON: any;
@@ -34,44 +135,167 @@ export class MapboxVectorTileProvider extends VectorTileProvider {
     spriteTexture: any;
     _ready: boolean | undefined;
     /**
+     * 获取瓦片JSON配置
+     * @param {object} source 数据源配置
+     * @returns {Promise<object>} 瓦片JSON配置
      * @private
-     * @returns {Promise}
      */
     private _getTileJson;
     /**
-     * @returns {Promise}
+     * 获取样式JSON配置
+     * @returns {Promise<Array>} 样式JSON配置数组
+     * @private
      */
-    _getStyleJSON(): Promise<any>;
-    getTileURL(z: any, x: any, y: any, tile: any): any;
-    getWorkerOptions(): {
-        displayOptions: any;
-    };
+    private _getStyleJSON;
+    /**
+     * 获取瓦片URL
+     * @param {number} z 缩放级别
+     * @param {number} x 瓦片X坐标
+     * @param {number} y 瓦片Y坐标
+     * @param {object} tile 瓦片对象
+     * @returns {string} 瓦片URL
+     */
+    getTileURL(z: number, x: number, y: number, tile: object): string;
+    /**
+     * 获取Worker选项
+     * @returns {object} Worker选项配置
+     */
+    getWorkerOptions(): object;
     /**
      * 获取瓦片数据并返回对应的Group对象
-     * @param {*} tile
-     * @returns {Group} 返回一个包含瓦片数据的Group对象
-     */
-    doRequestTileData(tile: any): Group;
-    _hasBufferData(bufferData: any): any;
-    _getBackgroundMesh(data: any, meshType: any, maxLayerIndex: any): any;
-    _getFillOpaqueMesh(data: any, meshType: any, maxLayerIndex: any): any;
-    _getFillPatternMesh(data: any, meshType: any, maxLayerIndex: any): any;
-    _getFillTranslucentMesh(data: any, meshType: any, maxLayerIndex: any): any;
+     * @param {object} tile 瓦片对象
+     * @returns {Promise<Object3D>} 返回一个包含瓦片数据的Group对象
+     */
+    doRequestVectorTileData(tile: object): Promise<Object3D>;
+    /**
+     * 取消瓦片请求
+     * @param {Array} tiles 要取消的瓦片数组
+     */
+    cancelTiles(tiles: any[]): void;
+    /**
+     * 检查是否有缓冲区数据
+     * @param {object} bufferData 缓冲区数据
+     * @returns {boolean} 是否有有效数据
+     * @private
+     */
+    private _hasBufferData;
+    /**
+     * 创建背景网格
+     * @param {object} data 网格数据
+     * @param {string} meshType 网格类型
+     * @param {number} maxLayerIndex 最大图层索引
+     * @returns {Mesh} 背景网格对象
+     * @private
+     */
+    private _getBackgroundMesh;
+    /**
+     * 创建不透明填充网格
+     * @param {object} data 网格数据
+     * @param {string} meshType 网格类型
+     * @param {number} maxLayerIndex 最大图层索引
+     * @returns {Mesh} 不透明填充网格对象
+     * @private
+     */
+    private _getFillOpaqueMesh;
+    /**
+     * 创建图案填充网格
+     * @param {object} data 网格数据
+     * @param {string} meshType 网格类型
+     * @param {number} maxLayerIndex 最大图层索引
+     * @returns {Mesh} 图案填充网格对象
+     * @private
+     */
+    private _getFillPatternMesh;
+    /**
+     * 创建半透明填充网格
+     * @param {object} data 网格数据
+     * @param {string} meshType 网格类型
+     * @param {number} maxLayerIndex 最大图层索引
+     * @returns {Mesh} 半透明填充网格对象
+     * @private
+     */
+    private _getFillTranslucentMesh;
     _getLineOpaqueMesh(data: any, meshType: any, maxLayerIndex: any): any;
     _getLineTranslucentMesh(data: any, meshType: any, maxLayerIndex: any): any;
-    _getLineDashedMesh(data: any, meshType: any, maxLayerIndex: any, scale: any): any;
+    _getLineDashedMesh(data: any, meshType: any, maxLayerIndex: any, scale: any, tile: any): any;
     _getExtrusionOpaqueMesh(data: any, meshType: any, maxLayerIndex: any): any;
     _getExtrusionTranslucentMesh(data: any, meshType: any, maxLayerIndex: any): any;
-    _getMaterial(type: any): any;
-    _setupSymbolData(symbolData: any, group: any): void;
-    _addTilePOI(surfaceTile: any, engine: any): void;
-    _removeTilePOI(surfaceTile: any, engine: any): void;
-    onSurfaceTileAdded(surfaceTile: any, engine: any): void;
-    onSurfaceTileRemoved(surfaceTile: any, engine: any): void;
+    /**
+     * 获取材质
+     * 根据类型创建或获取对应的MVT材质
+     * @param {string} type 材质类型
+     * @returns {Material} 材质对象
+     * @private
+     */
+    private _getMaterial;
+    /**
+     * 计算标签容差
+     * 针对审图进行的label碰撞特殊处理
+     * @param {object} surfaceTile 表面瓦片对象
+     * @param {object} engine 引擎对象
+     * @param {object} label 标签对象
+     * @returns {number} 容差值
+     * @private
+     */
+    private _calculateTolerance;
+    /**
+     * 设置符号数据
+     * @param {object} symbolData 符号数据
+     * @param {Object3D} group 组对象
+     * @private
+     */
+    private _setupSymbolData;
+    /**
+     * 添加瓦片POI标签
+     * @param {object} surfaceTile 表面瓦片对象
+     * @param {object} engine 引擎对象
+     * @private
+     */
+    private _addTilePOI;
+    /**
+     * 移除瓦片POI标签
+     * @param {object} surfaceTile 表面瓦片对象
+     * @param {object} engine 引擎对象
+     * @private
+     */
+    private _removeTilePOI;
+    /**
+     * 表面瓦片添加时的回调
+     * @param {object} surfaceTile 表面瓦片对象
+     * @param {object} engine 引擎对象
+     */
+    onSurfaceTileAdded(surfaceTile: object, engine: object): void;
+    /**
+     * 表面瓦片移除时的回调
+     * @param {object} surfaceTile 表面瓦片对象
+     * @param {object} engine 引擎对象
+     */
+    onSurfaceTileRemoved(surfaceTile: object, engine: object): void;
+    /**
+     * 添加所有符号
+     * 显示所有隐藏的符号标签
+     */
     addAllSymbols(): void;
+    /**
+     * 移除所有符号
+     * 隐藏所有显示的符号标签
+     */
     removeAllSymbols(): void;
-    set materialManager(materialManager: null);
-    get materialManager(): null;
+    /**
+     * 瓦片销毁时的回调
+     * @param {object} tile 瓦片对象
+     */
+    onTileDispose(tile: object): void;
+    /**
+     * 设置材质管理器
+     * @param {object} materialManager 材质管理器对象
+     */
+    set materialManager(materialManager: object);
+    /**
+     * 材质管理器
+     * @type {object}
+     */
+    get materialManager(): object;
 }
 import { VectorTileProvider } from './VectorTileProvider';
 import { AsyncDataTileLoader } from '../AsyncDataTileLoader';

package/dist/types/threemap/mapView/tileProvider/vector/PlaneVectorTileProvider.d.ts

@@ -5,7 +5,7 @@ export class PlaneVectorTileProvider extends VectorTileProvider {
      * 请求瓦片数据
      * @param tile 需要请求的瓦片对象
      */
-    doRequestTileData(tile: any): Promise<any>;
+    doRequestVectorTileData(tile: any): Promise<any>;
     /**
      * 从瓦片中请求Web墨卡托数据。
      *

package/dist/types/threemap/mapView/tileProvider/vector/VectorTileProvider.d.ts

@@ -4,9 +4,11 @@
  *
  * @category Internal
  */
-export class VectorTileProvider extends TileProvider {
+export class VectorTileProvider extends BaseImageryTileProvider {
     isVectorTileProvider: boolean;
-    errorFeedback(): any[];
+    name: string;
+    _imageryTileSize: number;
+    errorFallback(): any[];
     /**
      * @param {*} tile
      * @returns
@@ -15,8 +17,8 @@ export class VectorTileProvider extends TileProvider {
      * groundObject: 在地面上渲染的对象
      * @desc 请求瓦片数据
      */
-    doRequestTileData(tile: any): Promise<void>;
+    doRequestImageTileData(tile: any, surfaceTile: any): Promise<any>;
     getGroundTileData(tile: any): any[];
     _groundTileMaterial: any;
 }
-import { TileProvider } from '../TileProvider';
+import { BaseImageryTileProvider } from '../BaseImageryTileProvider';

package/dist/types/threemap/mapView/utils/projectVertices.d.ts

@@ -1,4 +1,4 @@
-export function reprojectCoordinate(sourceProjection: any, targetProjection: any, input: any, output: any): any;
+export function reprojectCoordinate(sourceCoordType: any, targetCoordType: any, sourceProjection: any, targetProjection: any, input: any, output: any): any;
 export function projectVertices(vertices: any, tileConfig: any, isMerge?: boolean, isSubCenter?: boolean): void;
 export function subdivideVertices(vertices: any, indices: any, uvs: any, tileConfig: any): {
     vertices: any;

package/dist/types/threemap/model/AnimationModel.d.ts

@@ -1,14 +1,94 @@
+/**
+ * 动画模型，支持GLTF/GLB等格式的骨骼动画播放与控制。
+ * 继承自 {@link SimpleModel}，可用于加载带有动画的3D模型，并提供动画的播放、停止、速度、循环等控制接口。
+ *
+ * @category Model
+ * @example
+ * ```javascript
+ * // 加载带动画的模型
+ * let model = engine.add(new mapvthree.AnimationModel({
+ *   url: 'assets/models/animated.glb',
+ *   autoPlay: true
+ * }));
+ * // 播放第1个动画
+ * model.play(0);
+ * // 停止所有动画
+ * model.stopAll();
+ * // 设置动画速度为2倍
+ * model.setSpeed(2);
+ * ```
+ */
 export class AnimationModel extends SimpleModel {
-    constructor(params: any);
-    _updateData(gltf: any, model: any): void;
+    /**
+     * 构造函数
+     * @param {Object} params 配置参数，参考SimpleModel
+     */
+    constructor(params: Object);
+    /**
+     * 初始化动画数据，内部方法
+     * @param {Object} gltf GLTF加载结果
+     * @param {Object3D} model 模型对象
+     * @internal
+     */
+    _updateData(gltf: Object, model: Object3D): void;
     animations: any;
     mixer: any;
     animationActions: any;
-    play(actionIndex: any): void;
-    stop(actionIndex: any): void;
+    /**
+     * 播放指定索引的动画
+     * @param {number} [actionIndex=0] 动画索引，默认播放第一个
+     * @example
+     * ```javascript
+     * model.play(1); // 播放第2个动画
+     * ```
+     */
+    play(actionIndex?: number): void;
+    /**
+     * 停止指定索引的动画
+     * @param {number} [actionIndex=0] 动画索引，默认停止第一个
+     * @example
+     * ```javascript
+     * model.stop(0); // 停止第1个动画
+     * ```
+     */
+    stop(actionIndex?: number): void;
+    /**
+     * 播放所有动画
+     * @example
+     * ```javascript
+     * model.playAll();
+     * ```
+     */
     playAll(): void;
+    /**
+     * 停止所有动画
+     * @example
+     * ```javascript
+     * model.stopAll();
+     * ```
+     */
     stopAll(): void;
-    setSpeed(speed: any, actionIndex: any): void;
-    setLoop(loop: any, actionIndex: any): void;
+    /**
+     * 设置动画播放速度
+     * @param {number} speed 播放速度，1为正常速度
+     * @param {number} [actionIndex] 动画索引，若不传则设置所有动画
+     * @example
+     * ```javascript
+     * model.setSpeed(2); // 所有动画2倍速
+     * model.setSpeed(0.5, 0); // 第1个动画0.5倍速
+     * ```
+     */
+    setSpeed(speed: number, actionIndex?: number): void;
+    /**
+     * 设置动画循环模式
+     * @param {boolean} loop 是否循环，true为循环，false为只播放一次
+     * @param {number} [actionIndex] 动画索引，若不传则设置所有动画
+     * @example
+     * ```javascript
+     * model.setLoop(true); // 所有动画循环
+     * model.setLoop(false, 0); // 第1个动画只播放一次
+     * ```
+     */
+    setLoop(loop: boolean, actionIndex?: number): void;
 }
 import { SimpleModel } from './SimpleModel';

package/dist/types/threemap/natural/DynamicWeather.d.ts

@@ -65,6 +65,98 @@ export class DynamicWeather {
     private _inTransition;
     /** @private */
     private _modifyCount;
+    _lightConfig: {
+        DefaultSky: {
+            clear: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            partlyCloudy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            cloudy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            overcast: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            foggy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            rainy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            snowy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+        };
+        DynamicSky: {
+            clear: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            partlyCloudy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            cloudy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            overcast: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            foggy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            rainy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            snowy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+        };
+        EmptySky: {
+            clear: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            partlyCloudy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            cloudy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            overcast: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            foggy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            rainy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+            snowy: {
+                sunLightIntensity: number;
+                skyLightIntensity: number;
+            };
+        };
+    };
     /**
      * 设置天气类型
      * @type {string}

package/dist/types/threemap/natural/EmptySky.d.ts

@@ -30,6 +30,7 @@ export class EmptySky {
      * @readonly
      */
     readonly isEmptySky: boolean;
+    name: string;
     /** @private */ private _addDefaultEnvMap;
     /** @private */ private _time;
     /** @private */ private _timeRatio;

package/dist/types/threemap/natural/StaticSky.d.ts

@@ -1,9 +1,31 @@
 /**
  * 静态天空，预置了常见的天气状态和时段状态
- * ![](media://static_sky.png)
+ * 根据时间和天气自动切换不同的天空纹理贴图，提供基础的天空渲染效果。
+ * 相比 {@link DynamicSky}，静态天空性能更好但效果相对简单。
+ *
+ * @category Natural
+ * @example
+ * ```javascript
+ * // 创建静态天空
+ * const sky = engine.add(new mapvthree.StaticSky());
+ *
+ * // 设置时间为下午5:30
+ * sky.time = 3600 * 17.5;
+ * ```
  */
 export class StaticSky extends CustomStaticSky {
-    isStaticSky: boolean;
+    /**
+     * 标识为StaticSky对象
+     * @type {boolean}
+     * @readonly
+     */
+    readonly isStaticSky: boolean;
+    /**
+     * 天空名称
+     * @type {string}
+     * @readonly
+     */
+    readonly name: string;
     /** @internal */ _phase: string;
     /** @internal */ _lastPhase: null;
     /** @internal */ _lastWeather: null;
@@ -12,12 +34,17 @@ export class StaticSky extends CustomStaticSky {
     /** @internal */ _afternoonTime: number;
     /** @internal */ _duskTime: number;
     /**
-     * 天气变化时加载不同的纹理贴图用于天空
+     * 本地变换处理，旋转天空纹理
+     * @param {Object3D} mesh 天空网格对象
+     * @internal
      */
-    onWeatherChanged(weather: any): void;
+    _onLocalTransform(mesh: Object3D): void;
     /**
      * 加载纹理用于天空，加载的纹理由天气和时间决定
+     * 根据当前的时间段和天气状态，从预置的纹理资源中加载对应的天空贴图
+     *
+     * @private
      */
-    loadSkyTexture(): void;
+    private loadSkyTexture;
 }
 import { CustomStaticSky } from './CustomStaticSky';

package/dist/types/threemap/projections/BaiduMercatorProjection.d.ts

@@ -22,5 +22,19 @@ export class BaiduMercatorProjection extends Projection {
      * @readonly
      */
     readonly name: string;
+    /**
+     * 将地理坐标(经纬度)转换为百度墨卡托投影坐标
+     * @param {Vector3} input 输入的地理坐标，x,y分别为经度和纬度
+     * @param {Vector3} [output] 可选的输出向量，如不提供则创建新的Vector3
+     * @returns {Vector3} 转换后的百度墨卡托投影坐标(单位:米)
+     */
+    projectCoordinate(input: Vector3, output?: Vector3, extend?: boolean): Vector3;
+    /**
+     * 将百度墨卡托投影坐标转换为地理坐标(经纬度)
+     * @param {Vector3} input 输入的百度墨卡托投影坐标(单位:米)
+     * @param {Vector3} [output] 可选的输出向量，如不提供则创建新的Vector3
+     * @returns {Vector3} 转换后的地理坐标，x,y分别为经度和纬度
+     */
+    unprojectCoordinate: (input: Vector3, output?: Vector3, extend: any) => Vector3;
 }
 import { Projection } from './Projection';

package/dist/types/threemap/projections/CoordTransformer.d.ts

@@ -0,0 +1,13 @@
+export class CoordTransformer {
+    static _registeredTransformers: {};
+    static _pathCache: Map<any, any>;
+    static _cacheKey(srcCoord: any, targetCoord: any): string;
+    static _clearPathCache(): void;
+    static _findTransformPath(srcCoord: any, targetCoord: any, visited?: Set<any>): any;
+    static transform(srcCoord: any, targetCoord: any, input: any, output: any): any;
+    static register(srcCoord: any, targetCoord: any, transformer: any): void;
+    static unregister(srcCoord: any, targetCoord: any): void;
+    static canTransform(srcCoord: any, targetCoord: any): boolean;
+    static serialize(): string;
+    static deserialize(json: any): void;
+}

package/dist/types/threemap/projections/GenericDefinedProjection.d.ts

@@ -0,0 +1,10 @@
+export class GenericDefinedProjection extends Projection {
+    constructor(name: any, parameters: any, geoBoundingBox: any);
+    _name: any;
+    _parameters: any;
+    _geoBoundingBox: any;
+    projectCoordinate(input: any, output: any, extend: any): any;
+    unprojectCoordinate(input: any, output: any, extend: any): any;
+    get name(): any;
+}
+import { Projection } from './Projection';