@baidumap/mapv-three 1.0.1 → 1.2.0

package/dist/types/threejs/objects/polygon/Polygon.d.ts

@@ -1,85 +1,219 @@
 export class Polygon extends GeoMesh {
     /**
-     * 构造函数
-     * @param {{
-     * extrude?: boolean, extrudeValue?: number,
-     * color?: string, vertexColors?: boolean, opacity?: number, emissive?: string,
-     * mapSrc?: string, mapScale?:number
-     * }} parameters 传入参数对象
-     * @param {boolean} parameters.extrude 是否拉伸，默认否
-     * @param {number} parameters.extrudeValue 拉伸高度，默认100
-     * @param {boolean} parameters.vertexHeights 是否通过数据携带高度配置，默认否
-     * @param {boolean} parameters.enableBottomFace 是否封闭底面
-     * @param {string} parameters.color 填充颜色
-     * @param {boolean} parameters.vertexColors 是否通过数据携带颜色配置，默认否
-     * @param {string} parameters.emissive 自发光颜色
-     * @param {number} parameters.opacity 整体透明度系数，默认1
-     * @param {string} parameters.mapSrc 赋值并设置geometry.useUV=true才可使用该图片作为纹理贴图，默认''
-     * @param {number} parameters.mapScale 贴图的缩放大小，仅在使用纹理贴图时有效，默认1
-     * @param {number} parameters.zOffset 整体高度抬升
-     * @param {number} parameter.normalOffset 沿法线方向抬升
-     * @param {boolean} parameter.perPositionHeight 使用顶点高度，若不指定，则即使设置了高度也当0处理, 默认为true
+     * 创建多边形渲染对象
+     * @param {Object} parameters 传入参数对象
+     * @param {boolean} [parameters.extrude=false] 是否拉伸，默认否
+     * @param {number} [parameters.extrudeValue=100] 拉伸高度，默认100
+     * @param {boolean} [parameters.vertexHeights=false] 是否通过数据携带高度配置，默认否
+     * @param {boolean} [parameters.enableBottomFace=true] 是否封闭底面
+     * @param {string} [parameters.color='#ffffff'] 填充颜色
+     * @param {boolean} [parameters.vertexColors=false] 是否通过数据携带颜色配置，默认否
+     * @param {string} [parameters.emissive='#000000'] 自发光颜色
+     * @param {number} [parameters.opacity=1] 整体透明度系数，默认1
+     * @param {string} [parameters.mapSrc=''] 纹理贴图，默认''
+     * @param {number} [parameters.mapScale=1] 贴图的缩放大小，仅在使用纹理贴图时有效，默认1
+     * @param {number} [parameters.zOffset=0] 整体高度抬升
+     * @param {number} [parameters.normalOffset=0] 沿法线方向抬升
+     * @param {boolean} [parameters.perPositionHeight=true] 使用顶点高度，若不指定，则即使设置了高度也当0处理, 默认为true
+     * @param {boolean} [parameters.isGroundPrimitive=false] 是否为贴地渲染
+     * @param {boolean} [parameters.isDynamic=false] 是否需要动态调整数据源，贴地时使用
+     * @param {Array} [parameters.excludeElements=[]] 排除的元素列表
+     * @param {number} [parameters.renderOrder=0] 渲染顺序
+     * @param {number} [parameters.nearScale=5] 深度图near值缩放系数
+     * @example
+     * ```javascript
+     * const polygon = new mapvthree.Polygon({
+     *     extrude: true,
+     *     extrudeValue: 150,
+     *     color: 'rgba(255, 0, 0, 0.8)',
+     *     vertexColors: true,
+     *     opacity: 0.9
+     * });
+     * ```
      */
     constructor(parameters?: {
-        extrude?: boolean;
-        extrudeValue?: number;
-        color?: string;
-        vertexColors?: boolean;
-        opacity?: number;
-        emissive?: string;
-        mapSrc?: string;
-        mapScale?: number;
+        extrude?: boolean | undefined;
+        extrudeValue?: number | undefined;
+        vertexHeights?: boolean | undefined;
+        enableBottomFace?: boolean | undefined;
+        color?: string | undefined;
+        vertexColors?: boolean | undefined;
+        emissive?: string | undefined;
+        opacity?: number | undefined;
+        mapSrc?: string | undefined;
+        mapScale?: number | undefined;
+        zOffset?: number | undefined;
+        normalOffset?: number | undefined;
+        perPositionHeight?: boolean | undefined;
+        isGroundPrimitive?: boolean | undefined;
+        isDynamic?: boolean | undefined;
+        excludeElements?: any[] | undefined;
+        renderOrder?: number | undefined;
+        nearScale?: number | undefined;
     });
-    isEventEntitySupported: boolean;
+    /**
+     * 是否支持返回的事件参数中携带entity实体数据
+     * @type {boolean}
+     * @readonly
+     */
+    readonly isEventEntitySupported: boolean;
     /** @protected */ protected geometry: any;
     /** @protected */ protected material: any;
-    /** boolean，是否拉伸 */
-    extrude: any;
-    /** number，拉伸高度 */
-    extrudeValue: any;
-    /** string，填充颜色 */
-    color: any;
-    /** boolean，是否通过数据携带颜色配置 */
-    vertexColors: any;
-    /** string，自发光颜色 */
-    emissive: any;
-    /** number，整体透明度系数 */
-    opacity: any;
-    /** string，赋值则使用该图片作为纹理贴图 */
-    mapSrc: any;
-    /** number，贴图的缩放大小，仅在使用纹理贴图时有效 */
-    mapScale: any;
+    /**
+     * 是否拉伸多边形
+     * @type {boolean}
+     * @example
+     * ```javascript
+     * polygon.extrude = true;
+     * ```
+     */
+    extrude: boolean;
+    /**
+     * 拉伸高度值
+     * @type {number}
+     * @example
+     * ```javascript
+     * polygon.extrudeValue = 200;
+     * ```
+     */
+    extrudeValue: number;
+    /**
+     * 填充颜色
+     * @type {string}
+     * @example
+     * ```javascript
+     * polygon.color = 'rgba(255, 0, 0, 0.8)';
+     * ```
+     */
+    color: string;
+    /**
+     * 是否通过数据携带颜色配置
+     * @type {boolean}
+     * @example
+     * ```javascript
+     * polygon.vertexColors = true;
+     * ```
+     */
+    vertexColors: boolean;
+    /**
+     * 自发光颜色
+     * @type {string}
+     * @example
+     * ```javascript
+     * polygon.emissive = 'rgba(0, 255, 0, 0.5)';
+     * ```
+     */
+    emissive: string;
+    /**
+     * 整体透明度系数
+     * @type {number}
+     * @example
+     * ```javascript
+     * polygon.opacity = 0.7;
+     * ```
+     */
+    opacity: number;
+    /**
+     * 贴图的缩放大小，仅在使用纹理贴图时有效
+     * @type {number}
+     * @example
+     * ```javascript
+     * polygon.mapScale = 2.0;
+     * ```
+     */
+    mapScale: number;
     isPolygon: boolean;
     parameters: {
-        extrude?: boolean;
-        extrudeValue?: number;
-        color?: string;
-        vertexColors?: boolean;
-        opacity?: number;
-        emissive?: string;
-        mapSrc?: string;
-        mapScale?: number;
+        extrude?: boolean | undefined;
+        extrudeValue?: number | undefined;
+        vertexHeights?: boolean | undefined;
+        enableBottomFace?: boolean | undefined;
+        color?: string | undefined;
+        vertexColors?: boolean | undefined;
+        emissive?: string | undefined;
+        opacity?: number | undefined;
+        mapSrc?: string | undefined;
+        mapScale?: number | undefined;
+        zOffset?: number | undefined;
+        normalOffset?: number | undefined;
+        perPositionHeight?: boolean | undefined;
+        isGroundPrimitive?: boolean | undefined;
+        isDynamic?: boolean | undefined;
+        excludeElements?: any[] | undefined;
+        renderOrder?: number | undefined;
+        nearScale?: number | undefined;
     };
-    _nearScale: any;
-    isGroundPrimitive: any;
-    isDynamic: any;
-    needReMapUv: any;
-    excludeElements: any;
+    _nearScale: number;
+    isGroundPrimitive: boolean | undefined;
+    isDynamic: boolean;
+    needReMapUv: boolean | undefined;
+    excludeElements: any[];
     _sharedResourcesId: string;
-    renderOrder: any;
+    renderOrder: number;
     depthRenderTarget: any;
-    onBeforeSceneRenderHook(engine: any, scene: any, camera: any, renderState: any): void;
-    computeRectangleBounds(): number[];
-    /** @protected */
+    /**
+     * 场景渲染前的钩子函数，用于生成深度图
+     * @param {Engine} engine 引擎实例
+     * @param {Scene} scene 场景对象
+     * @param {Camera} camera 相机对象
+     * @param {Object} renderState 渲染状态
+     * @protected
+     */
+    protected onBeforeSceneRenderHook(engine: Engine, scene: Scene, camera: Camera, renderState: Object): void;
+    /**
+     * 计算矩形边界
+     * @returns {Array<number>} 边界数组 [minX, minY, maxX, maxY]
+     * @private
+     */
+    private computeRectangleBounds;
+    /**
+     * 几何体更新后的处理
+     * @protected
+     */
     protected afterGeometryUpdate(): void;
-    /** @protected */
-    protected getEntityIndexByFace(faceIndex: any, pointIndex: any): any;
-    getSharedResourceFromExcludeElement(excludeElements: any): string;
-    set nearScale(value: any);
+    /**
+     * 根据面索引和点索引获取实体索引
+     * @param {number} faceIndex 面索引
+     * @param {number} pointIndex 点索引
+     * @returns {number} 实体索引
+     * @protected
+     */
+    protected getEntityIndexByFace(faceIndex: number, pointIndex: number): number;
+    /**
+     * 根据排除元素获取共享资源ID
+     * @param {Array} excludeElements 排除的元素列表
+     * @returns {string} 共享资源ID
+     * @private
+     */
+    private getSharedResourceFromExcludeElement;
+    /**
+     * 设置near缩放值
+     * @param {number} value near缩放值
+     */
+    set nearScale(value: number);
     /**
      * 控制near的值，默认5，在一些对深度要求比较高的场景需要调整near的值
+     * @type {number}
+     * @example
+     * ```javascript
+     * polygon.nearScale = 10; // 提高深度精度
+     * ```
+     */
+    get nearScale(): number;
+    /**
+     * 设置纹理贴图路径
+     * @param {string} value 纹理贴图路径
+     */
+    set mapSrc(value: string);
+    /**
+     * 纹理贴图图片路径
+     * @type {string}
+     * @example
+     * ```javascript
+     * polygon.mapSrc = 'textures/ground.jpg';
+     * ```
      */
-    get nearScale(): any;
+    get mapSrc(): string;
     raycast: any;
     _computeIntersections: any;
     getVertexPosition: any;

package/dist/types/threejs/objects/sphere/Cone.d.ts

@@ -1,64 +1,4 @@
-/**
- * 贴地椎
- * ![](media://cone.png)
- */
-export class Cone extends GeoInstancedPointMesh {
-    /**
-     * 构造函数
-     * @param {{opacity?: number, height?: number, radiusSegments?: number,
-     * heightSegments?: number, size?: number, vertexSizes?: boolean, vertexHeights?: boolean,
-     * gradient?: object, openEnded?: boolean}} parameters 传入的参数
-     * @param {number} parameters.opacity 整体透明度
-     * @param {number} parameters.height 椎体高度
-     * @param {number} parameters.radiusSegments 椎体边数
-     * @param {number} parameters.heightSegments 椎体高度
-     * @param {number} parameters.size 椎体底面半径大小
-     * @param {boolean} parameters.vertexSizes 是否通过数据携带椎体底面半径
-     * @param {boolean} parameters.vertexHeights 是否通过数据携带椎体高度
-     * @param {object} parameters.gradient 是否通过数据携带高度配置
-     * @param {boolean} parameters.openEnded 控制椎体底部是否封口，为false时封口,默认值为true
-     */
-    constructor(parameters: {
-        opacity?: number;
-        height?: number;
-        radiusSegments?: number;
-        heightSegments?: number;
-        size?: number;
-        vertexSizes?: boolean;
-        vertexHeights?: boolean;
-        gradient?: object;
-        openEnded?: boolean;
-    });
-    /** 整体透明度 */ opacity: any;
-    /** 椎体高度 */ height: any;
-    /** 椎体底面半径大小 */ size: any;
-    parameters: {
-        opacity?: number;
-        height?: number;
-        radiusSegments?: number;
-        heightSegments?: number;
-        size?: number;
-        vertexSizes?: boolean;
-        vertexHeights?: boolean;
-        gradient?: object;
-        openEnded?: boolean;
-    };
-    computeInstanceMorphMatrix(scale: any): any;
-    /**
-     * @protected
-     * 计算根据height和size计算模型矩阵模型矩阵
-     */
-    protected getInstanceLocalMatrix: (coordinates: any, dataItem: any, index: any) => any;
-    /**
-     * @internal
-     * 计算最大高度
-     * @returns
-     */
-    calcMaxHeight(): number | undefined;
-    /**
-     * @internal
-     * 顶部小圆球第一个顶点的索引
-     */
-    getSphereIndex(): void;
+export class Cone extends Pillar {
+    constructor(parameters: any);
 }
-import { GeoInstancedPointMesh } from '../point/GeoInstancedPointMesh';
+import { Pillar } from './Pillar';

package/dist/types/threejs/objects/sphere/Grid.d.ts

@@ -27,7 +27,7 @@ export class Grid extends GeoInstancedPointMesh {
      * @param {number} parameters.radialSegments 边数
      * @param {number} parameters.radiusTop 顶面半径
      * @param {number} parameters.radiusBottom 底面半径
-     * @param {boolean} parameters.openEnded 顶面是否封闭
+     * @param {boolean} parameters.openEnded 底面是否封闭
      * @param {number} parameters.heightSegments 沿圆柱高的分段切片
      * @param {boolean} parameters.isMultiColor 是否多色渐变
      * @param {Array<string>} parameters.multiColor 渐变颜色数组, heightSegments+1
@@ -52,7 +52,7 @@ export class Grid extends GeoInstancedPointMesh {
     /** 柱体的边数 */ radialSegments: any;
     /** 顶面半径 */ radiusTop: any;
     /** 底面半径 */ radiusBottom: any;
-    /** 圆柱顶底是否封闭 */ openEnded: any;
+    /** 柱体顶底是否封闭 */ openEnded: any;
     /** 沿圆柱高的分段切片 */ heightSegments: any;
     /** 是否多色渐变 */ isMultiColor: any;
     /** 渐变柱颜色数组, heightSegments+1 */ multiColor: any;
@@ -71,6 +71,7 @@ export class Grid extends GeoInstancedPointMesh {
         isLight?: boolean;
         lightPos?: number;
     };
+    computeInstanceMorphMatrix(): any;
     /**
      * @internal
      * 计算高度拉升模型矩阵

package/dist/types/threejs/objects/sphere/Pillar.d.ts

@@ -1,8 +1,45 @@
 /**
- * ![](media://pillar.png)
+ * 柱状体，支持柱形和锥形两种形状。
+ *
+ * @category Objects
+ * @example
+ * ```javascript
+ * // 创建柱形
+ * const pillar = engine.add(new mapvthree.Pillar({
+ *     shape: 'pillar',
+ *     color: 0xff0000,
+ *     height: 100,
+ *     radius: 10
+ * }));
+ *
+ * // 创建锥形
+ * const cone = engine.add(new mapvthree.Pillar({
+ *     shape: 'cone',
+ *     color: 0x00ff00,
+ *     height: 80,
+ *     radius: 15
+ * }));
+ * ```
  */
 export class Pillar extends GeoInstancedPointMesh {
-    constructor(parameters: any);
+    /**
+     * 构造函数
+     * @param {Object} parameters 配置参数
+     * @param {string} [parameters.shape='pillar'] 形状类型，支持'pillar'（柱形）和'cone'（锥形）
+     *
+     * @param {string} [parameters.color] 柱体颜色，支持十六进制颜色值或颜色名称，默认为[80, 20, 170, 0.8]
+     * @param {number} [parameters.opacity] 整体透明度，取值范围0-1，默认为1
+     * @param {number} [parameters.height] 柱体高度，默认为1
+     * @param {number} [parameters.radius] 柱体半径，默认为6
+     * @param {number} [parameters.radialSegments] 柱体边数，默认为4
+     * @param {number} [parameters.heightSegments] 柱体高度分段数，默认为1
+     * @param {boolean} [parameters.openEnded] 圆柱顶底是否打开，默认为true
+     * @param {boolean} [parameters.vertexHeights] 是否通过数据携带高度配置，默认为false
+     * @param {Object} [parameters.gradient] 颜色渐变配置对象
+     * @param {boolean} [parameter.colorMode] 颜色模式, 包含'gradient'(渐变)和'band'(颜色分带)
+     * @param {boolean} [parameter.heatmap] 是否开启热力模式, 默认开启
+     */
+    constructor(parameter: any);
     /** 整体透明度 */ opacity: any;
     /** 柱体高度 */ height: any;
     /** 柱体边数 */ radiusSegments: any;
@@ -10,17 +47,22 @@ export class Pillar extends GeoInstancedPointMesh {
     /** 颜色渐变 */ gradient: any;
     /** 是否通过数据携带高度配置 */ vertexHeights: any;
     /** 圆柱顶底是否打开 */ openEnded: any;
-    parameters: any;
-    computeInstanceMorphMatrix(scale: any): any;
+    /** 着色模式 */ colorMode: any;
+    /** 是否开启热力模式，默认开启 */ heatmap: any;
     /**
-     * @internal
-     * 计算高度拉升模型矩阵
+     * @protected
+     * 计算根据height和size计算模型矩阵模型矩阵
      */
-    getInstanceLocalMatrix: (coordinates: any, dataItem: any, index: any) => any;
+    protected getInstanceLocalMatrix: (coordinates: any, dataItem: any, index: any) => any;
     /**
      * @internal
      * 计算最大高度
      */
     addCustomAttributes: () => number | undefined;
+    /**
+     * @internal
+     * 顶部小圆球第一个顶点的索引
+     */
+    getSphereIndex(): void;
 }
 import { GeoInstancedPointMesh } from '../point/GeoInstancedPointMesh';

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

@@ -1,7 +1,7 @@
 export function nextPowOfTwo(number: any): number;
 export function getDefaultCharacterSet(): string[];
 export function setTextStyle(ctx: any, fontFamily: any, fontSize: any, fontWeight: any): void;
-export function buildMappingWithContext({ characterSet, context, fontHeight, buffer, maxCanvasWidth, mapping, xOffset, yOffset, defaultFontWeight, }: {
+export function buildMappingWithContext({ characterSet, context, fontHeight, buffer, maxCanvasWidth, mapping, xOffset, yOffset, defaultFontWeight, fontFamily, }: {
     characterSet: any;
     context: any;
     fontHeight: any;
@@ -11,6 +11,7 @@ export function buildMappingWithContext({ characterSet, context, fontHeight, buf
     xOffset?: number | undefined;
     yOffset?: number | undefined;
     defaultFontWeight: any;
+    fontFamily: any;
 }): {
     mapping: {};
     xOffset: number;
@@ -43,3 +44,9 @@ export function transformParagraph(text: any, paragraph: any, lineHeight: any, w
     textHeights: any[];
 };
 export function wrapText(ctx: any, text: any, font: any, em: any): any;
+/**
+ * 从字体名称中提取字体权重
+ * @param {string|Array<string>} fonts 字体名称或字体数组，例如 'Open Sans Bold' 或 ['Open Sans Bold', 'Arial Regular']
+ * @returns {number} 字体权重值，默认为 400
+ */
+export function getFontWeight(fonts: string | Array<string>): number;

package/dist/types/threejs/particles/Fireflies.d.ts

@@ -1,17 +1,37 @@
+/**
+ * 萤火虫粒子效果，创建跟随相机的萤火虫群效果。
+ *
+ * 萤火虫粒子会在相机周围随机分布，并具有自然的运动效果。
+ * 粒子系统会自动跟随相机位置，确保萤火虫始终在视野范围内。
+ *
+ * 注意：需要在引擎中启用动画循环 `rendering.enableAnimationLoop=true`
+ *
+ * @category Natural
+ * @example
+ * ```javascript
+ * // 创建萤火虫效果
+ * const fireflies = engine.add(new mapvthree.Fireflies({
+ *     color: new THREE.Color(0x0099aa),
+ *     size: 2,
+ *     countFactor: 0.6
+ * }));
+ * ```
+ */
 export class Fireflies {
     /**
-     * @param {{color?: string, size?: number, countFactor?: number}} options 参数对象
-     * @param {string} options.color 粒子颜色
-     * @param {number} options.size 萤火虫大小
-     * @param {number} options.countFactor 萤火虫数量因子，范围0~1
+     * 构造函数
+     * @param {Object} options 配置参数
+     * @param {string|THREE.Color} [options.color] 萤火虫颜色，支持十六进制颜色值或THREE.Color对象，默认为0x0099aa
+     * @param {number} [options.size] 萤火虫大小，默认为1
+     * @param {number} [options.countFactor] 萤火虫数量因子，范围0~1，控制活跃粒子数量，默认为0.5
      */
     constructor(options?: {
-        color?: string;
-        size?: number;
-        countFactor?: number;
+        color?: string | THREE.Color;
+        size?: number | undefined;
+        countFactor?: number | undefined;
     });
     /**
-     * 粒子数量的比例
+     * 粒子数量的比例因子
      * @private
      */
     private _countFactor;
@@ -22,34 +42,58 @@ export class Fireflies {
     /** @private */ private _system;
     /** @private */ private _options;
     /**
+     * 添加到引擎后的初始化
+     * @param {Engine} engine 引擎实例
      * @internal
      */
-    afterAddToEngine(engine: any): void;
+    afterAddToEngine(engine: Engine): void;
     /**
+     * 从引擎移除前的清理
      * @internal
      */
     beforeRemoveFromEngine(): void;
     /**
+     * 为材质添加自发光属性
+     * @param {Object} material 材质对象
      * @internal
      */
-    overrideMaterialWithEmissive(material: any): void;
+    overrideMaterialWithEmissive(material: Object): void;
     /**
+     * 渲染前的处理函数，更新萤火虫位置跟随相机
+     * @param {Engine} engine 引擎实例
      * @internal
      */
-    handleBeforeRender: (engine: any) => void;
+    handleBeforeRender: (engine: Engine) => void;
     /**
+     * 更新粒子系统
      * @internal
      */
     update: () => void;
     /**
+     * 创建粒子纹理
+     * @returns {THREE.Texture} 粒子纹理
      * @internal
      */
-    createSnow: () => any;
+    createSnow: () => THREE.Texture;
     /**
+     * 创建粒子发射器
+     * @returns {Emitter} 粒子发射器
      * @internal
      */
-    createEmitter: () => any;
+    createEmitter: () => Emitter;
+    /**
+     * 设置萤火虫数量因子
+     * @param {number} value 数量因子，范围0~1
+     */
     set countFactor(value: number);
+    /**
+     * 萤火虫数量因子
+     * @type {number}
+     */
     get countFactor(): number;
+    /**
+     * 释放资源
+     * 清理纹理和粒子系统
+     */
     dispose(): void;
 }

package/dist/types/threejs/utils/sprite.d.ts

@@ -1,3 +1,3 @@
 export function getFontSize(ctx: any, padding: any, text: any, width: any, height: any, lineNum?: number, fontSize?: number): any;
 export function createSprite(boxes: any, ctx: any, canvas: any, option?: {}): boolean;
-export function url2canvas(url: string | object, callback: Function): void;
+export function url2canvas(url: string | object, successCallback: Function, errorCallback: Function): void;