@baidumap/mapv-three 1.0.0 → 1.1.3

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

@@ -6,6 +6,8 @@ export class HDTrafficTileProvider extends VectorTileProvider {
     private _defaultMinLevel;
     /** @private */
     private _defaultMaxLevel;
+    /** @private */
+    private _trafficLinks;
     _url: any;
     _apiHost: any;
     _options: {};
@@ -18,8 +20,10 @@ export class HDTrafficTileProvider extends VectorTileProvider {
     _asyncInit(): Promise<void>;
     _dataLoader: AsyncDataTileLoader | undefined;
     getTileURL(z: any, x: any, y: any, tile: any): any;
-    getWorkerOptions(): {};
-    doRequestTileData(tile: any): Promise<any[]>;
+    getWorkerOptions(tile: any): {};
+    doRequestTileData(tile: any): Promise<any>;
+    onSurfaceTileRefresh(surfaceTile: any): void;
+    refreshTile(surfaceTile: any): Promise<void>;
     _request(data: any): Promise<any>;
     /**
      * @protected
@@ -29,6 +33,7 @@ export class HDTrafficTileProvider extends VectorTileProvider {
      * @protected
      */
     protected onSurfaceTileRemoved(surfaceTile: any, engine: any): void;
+    toggleTrafficLinkVisible(visible: any): void;
     set apiHost(apiHost: any);
     get apiHost(): 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/EqualEarthProjection.d.ts

@@ -1,11 +1,31 @@
 /**
- * @class EqualEarthProjection
- * @extends {Projection}
+ * 等面积地球投影(EPSG:8857)，用于保持面积比例的世界地图投影
+ *
+ * 等面积地球投影是一种伪圆柱投影，专门设计用于保持面积比例：
+ * - 等面积性：所有区域的面积比例保持正确
+ * - 视觉平衡：在保持面积的同时，尽量减少形状变形
+ * - 全球覆盖：适用于完整的世界地图表示
+ * - 坐标单位为米
+ *
+ * 特点：
+ * - 等面积性：所有区域的面积比例准确
+ * - 中等程度的形状变形：在面积和形状之间取得平衡
+ * - 适合统计地图：用于人口密度、资源分布等统计可视化
+ * - 现代设计：2018年发布的新投影方法
+ *
+ * 该投影主要用于：
+ * - 世界地图的统计可视化
+ * - 人口密度、资源分布等专题地图
+ * - 需要准确面积比例的地理分析
+ *
+ * @category Internal
  */
 export class EqualEarthProjection extends Projection {
-    name: string;
-    projectCoordinate(input: any, output: any): any;
-    unprojectCoordinate(input: any, output: any): any;
-    geoBoxToProjectedBox(geoBox: any, projectedBox: any): any;
+    /**
+     * 投影名称
+     * @type {string}
+     * @readonly
+     */
+    readonly name: string;
 }
 import { Projection } from './Projection';

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

@@ -1,12 +1,31 @@
 /**
- * 屏幕像素投影，Y轴反的
- * @class ScreenPixelProjection
- * @extends {Projection}
+ * 屏幕像素投影，用于屏幕坐标系与WebGL坐标系的转换
+ *
+ * 屏幕像素投影是一种简单的坐标变换投影，主要用于处理屏幕坐标系与WebGL坐标系之间的差异：
+ * - Y轴翻转：将屏幕坐标系(原点在左上角，Y轴向下)转换为WebGL坐标系(原点在中心，Y轴向上)
+ * - 保持X轴和Z轴不变
+ * - 适用于2D屏幕空间的可视化
+ *
+ * 特点：
+ * - 简单的线性变换：仅对Y轴进行翻转
+ * - 无地理意义：不涉及地理坐标转换
+ * - 适用于屏幕空间：专门用于屏幕像素坐标处理
+ * - 高效计算：变换计算非常简单
+ *
+ * 该投影主要用于：
+ * - 屏幕坐标与WebGL坐标的转换
+ * - 2D界面元素的定位
+ * - 屏幕空间的可视化效果
+ *
+ * @category Internal
+ * ```
  */
 export class ScreenPixelProjection extends Projection {
-    name: string;
-    isAxisAligned: boolean;
-    projectCoordinate(input: any, output: any): any;
-    unprojectCoordinate(input: any, output: any): any;
+    /**
+     * 投影名称
+     * @type {string}
+     * @readonly
+     */
+    readonly name: string;
 }
 import { Projection } from './Projection';

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

@@ -1,21 +1,72 @@
 /**
- * @class UTMProjection
- * @extends {Projection}
+ * 通用横轴墨卡托(UTM)投影，用于区域性的高精度地图投影，EPSG:32601-32660为北半球，EPSG:32701-32760为南半球
+ *
+ * UTM投影是一种分带投影系统，将地球表面划分为60个经度带，每个带6度宽：
+ * - 每个UTM带使用独立的墨卡托投影
+ * - 提供高精度的距离和角度测量
+ * - 适用于中纬度地区的工程测量和制图
+ * - 坐标单位为米
+ *
+ * 特点：
+ * - 等角性：保持局部形状和角度
+ * - 高精度：在投影带内变形很小
+ * - 分带设计：避免高纬度地区变形过大
+ * - 标准化的坐标系统
+ *
+ * 该投影主要用于：
+ * - 工程测量和制图
+ * - 区域性的高精度地图
+ * - 军事和导航应用
+ *
+ * @category Internal
  */
 export class UTMProjection extends Projection {
+    /**
+     * 构造函数
+     * @param {number} zone UTM带号，范围1-60
+     * @param {boolean} isSouth 是否为南半球，true表示南半球，false表示北半球
+     * @throws {Error} 当带号不在有效范围内时抛出错误
+     */
     constructor(zone?: number, isSouth?: boolean);
-    categoryName: string;
-    _zone: number;
-    _isSouth: boolean;
-    projectCoordinate(input: any, output: any): any;
-    unprojectCoordinate(input: any, output: any): any;
-    geoBoxToProjectedBox(geoBox: any, projectedBox: any): any;
-    equals(projection: any): boolean;
-    get name(): string;
-    _name: string | undefined;
-    get zone(): number;
-    get isSouth(): boolean;
-    get geoBoundingBox(): any;
-    _geoBoundingBox: any;
+    /** @private */ private _zone;
+    /** @private */ private _isSouth;
+    /** @private */ private _name;
+    /** @private */ private _geoBoundingBox;
+    /**
+     * 投影名称
+     * @type {string}
+     * @readonly
+     */
+    readonly categoryName: string;
+    /**
+     * 比较两个UTM投影是否相等
+     * @param {UTMProjection} projection 要比较的投影对象
+     * @returns {boolean} 如果投影参数相同则返回true
+     */
+    equals(projection: UTMProjection): boolean;
+    /**
+     * UTM投影的EPSG代码
+     * @type {string}
+     * @readonly
+     */
+    readonly get name(): string;
+    /**
+     * UTM带号
+     * @type {number}
+     * @readonly
+     */
+    readonly get zone(): number;
+    /**
+     * 是否为南半球
+     * @type {boolean}
+     * @readonly
+     */
+    readonly get isSouth(): boolean;
+    /**
+     * 地理边界框，定义了该UTM带的有效地理范围
+     * @type {Box3}
+     * @readonly
+     */
+    readonly get geoBoundingBox(): Box3;
 }
 import { Projection } from './Projection';

package/dist/types/util/WorkerTaskScheduler.d.ts

@@ -44,6 +44,7 @@ export class WorkerTaskScheduler {
      */
     onMessageCompleted(messagedata: any, message: any): Promise<any>;
     isMessageCompleted(messagedata: any, message: any): boolean;
+    isMessageRefreshed(messagedata: any, message: any): boolean;
     _handleWorkerMessage: (message: any) => Promise<void>;
     /**
      * 将消息发送给所有工作线程。

package/dist/types/util/gradientMap.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 创建默认的渐变贴图（蓝-绿-黄-红）
+ */
+export function createDefaultGradientTexture(width?: number, height?: number): any;
+export function createGradientTexture(gradient?: {}, width?: number, height?: number): any;
+/**
+ * 更新已有 CanvasTexture 的渐变内容
+ */
+export function updateGradientTexture(canvasTexture: any, gradient: any, width?: number, height?: number): void;

package/dist/types/util/graphics/bezier.d.ts

@@ -1 +1,8 @@
-export function getCurve(line: any, divisions?: number): any[][];
+/**
+ * 获取贝塞尔曲线点集
+ * @param {number[][]} line [[x,y,z], [x,y,z]]
+ * @param {number} divisions 分段数
+ * @param {number} heightRatio 控制点高度比例，越小越高
+ * @returns {number[][]}
+ */
+export function getCurve(line: number[][], options: any): number[][];

package/dist/types/util/object.d.ts

@@ -27,6 +27,10 @@ export function defined(value: any): boolean;
  * @returns 返回给定两个参数中第一个非undefined和非null的值，如果两个参数都是undefined或null，则返回undefined。
  */
 export function defaultValue(a: any, b: any): any;
+export namespace defaultValue {
+    let EMPTY_OBJECT: Readonly<{}>;
+    let EMPTY_MAT4: any;
+}
 /**
  * 深度合并对象
  * @internal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baidumap/mapv-three",
-  "version": "1.0.0",
+  "version": "1.1.3",
   "description": "A powerful 3D map engine.",
   "author": "mapopen-fe@baidu.com",
   "main": "dist/mapvthree.umd.js",
@@ -45,6 +45,7 @@
     "omggif": "^1.0.10",
     "pbf": "^3.2.1",
     "potpack": "^1.0.2",
+    "proj4": "^2.17.0",
     "rbush": "^3.0.1",
     "shader-particle-system": "^1.1.4",
     "simpleheat": "^0.4.0",