gltf-parser-plugin 1.1.6 → 1.1.8

package/build/index.d.ts

@@ -1,16 +1,38 @@
 import { Box3 } from 'three';
 import { Color } from 'three';
+import { Euler } from 'three';
 import { EventDispatcher } from 'three';
 import { Intersection } from 'three';
 import { Material } from 'three';
 import { Mesh } from 'three';
 import { Texture } from 'three';
+import { Tileset } from '3d-tiles-renderer/core';
 import { TilesRenderer } from '3d-tiles-renderer';
 import { Vector3 } from 'three';
 import { WebGLRenderer } from 'three';
 
+/**
+ * 与 StyleHelper 中 `show`、`conditions` 条件项的表达式求值一致
+ * 在 propertyData 的键作为变量名的上下文中执行 `Boolean(expr)`
+ *
+ * 实现：对每个表达式字符串只编译一次 `new Function('data', 'with(d){...}')`，
+ * 避免按「表达式 × 属性键集合」重复编译，也避免每次求值排序/拼接 cacheKey。
+ */
+/**
+ * 清空表达式编译缓存（热更新或单测可调用）
+ */
+export declare function clearStyleConditionCache(): void;
+
+/** 可解析为 THREE.Color 的输入 */
 export declare type ColorInput = number | string | Color;
 
+/**
+ * 同步解析 `data:application/x-gzip;base64,...`：base64 → 二进制 → gunzip → UTF-8 文本。
+ */
+export declare function decodeGzipBase64DataUriSync(dataUri: string): string;
+
+export declare function evaluateStyleCondition(expr: string | boolean, propertyData: Record<string, unknown> | null): boolean;
+
 /**
  * Hit object feature information interface
  */
@@ -23,6 +45,9 @@ export declare interface FeatureInfo {
     error?: string;
 }
 
+/** 从 tileset 取内嵌 structure 的 data URI（优先 MapTalks：`asset.extras.maptalks.structureUri`） */
+export declare function getStructureDataUriFromTileset(root: Tileset | null): string | null;
+
 export declare class GLTFParserPlugin implements MeshHelperHost {
     name: string;
     private tiles;
@@ -31,18 +56,21 @@ export declare class GLTFParserPlugin implements MeshHelperHost {
     private readonly _options;
     private _structureData;
     private _oidNodeMap;
-    private _structurePromise;
+    /** rootTileset 已存在且已尝试过内嵌解析后仍为 null，则不再重复 gunzip */
+    private _structureEmbedResolved;
     private _modelInfo;
     private _modelInfoPromise;
     private _interactionFilter;
     private _partColorHelper;
     private _partBlinkHelper;
     private _partFrameHelper;
+    private _styleHelper;
+    private _partHighlightHelper;
     oids: number[];
-    private renderer;
+    /** WebGLRenderer 实例，用于 mesh helper 等扩展 */
+    get renderer(): WebGLRenderer | null;
+    private _renderer;
     private splitMeshCache;
-    private maxUniformVectors;
-    private featureIdCount;
     private collectors;
     private collectorCache;
     /**
@@ -54,6 +82,7 @@ export declare class GLTFParserPlugin implements MeshHelperHost {
      * Plugin initialization, called by TilesRenderer
      */
     init(tiles: TilesRenderer): void;
+    private _createPartEffectHost;
     /**
      * Fetch tile data with IndexedDB caching support
      */
@@ -63,42 +92,51 @@ export declare class GLTFParserPlugin implements MeshHelperHost {
      */
     clearCache(): Promise<void>;
     parseTile(buffer: ArrayBuffer, tile: any, extension: any, uri: string, abortSignal: AbortSignal): Promise<any>;
-    private _getStructureUrl;
+    /** 与 tileset 同目录的侧车 JSON，如 structure.json / modelInfo.json */
+    private _sidecarJsonUrl;
     private _buildOidNodeMap;
-    private _fetchStructureData;
-    private _ensureStructureLoaded;
+    /** 仅根 tileset 变化时重解析 structureUri（子 tileset 的 load-tileset 不会触发） */
+    private _onLoadRootTilesetCB;
     /**
-     * 根据 oid 获取 structure.json 中对应的节点树数据
-     * 包含 bbox、children、name 等完整结构信息
-     * 首次调用时会自动从 tileset URL 推导并请求 structure.json
+     * 从已加载根 tileset 的内嵌 structure（优先 asset.extras.maptalks.structureUri）同步解压并建索引。
+     * rootTileset 尚未就绪时返回 null，可稍后再次调用；已成功或已判定无内嵌数据后见 _structureEmbedResolved。
      */
-    getNodeTreeByOid(oid: number): Promise<StructureNode | null>;
+    private _syncStructureFromTileset;
     /**
-     * 根据 oid 数组批量获取 structure.json 中对应的节点树数据
+     * 根据 oid 获取结构树节点（数据来自 tileset 内嵌 structureUri 同步解压）
      */
-    getNodeTreeByOids(oids: number[]): Promise<Map<number, StructureNode>>;
+    getNodeTreeByOid(oid: number): StructureNode | null;
     /**
-     * 获取完整的 structure.json 数据
-     * 首次调用时会自动请求
+     * 根据 oid 数组批量获取结构树节点
      */
-    getStructureData(): Promise<StructureData | null>;
+    getNodeTreeByOids(oids: number[]): Map<number, StructureNode>;
     /**
-     * 选择包围盒范围内的构件（包含相交和包含两种情况）
-     * @param box 查询用的 Box3 范围，坐标系与 structure.json 中 bbox 一致
-     * @returns 范围内所有构件的 oid 数组
+     * 根据 oid 从结构数据取轴对齐包围盒（`bbox` 为 `[minX,minY,minZ,maxX,maxY,maxZ]`，与 `selectByBox` 一致）
+     * @returns 无对应节点或缺少有效 bbox 时返回 `null`
      */
-    selectByBox(box: Box3): Promise<number[]>;
+    getBoundingBoxByOid(oid: number): Box3 | null;
     /**
-     * 选择多边形（平面投影）范围内的构件（包含相交和包含两种情况）
-     * @param polygon 多边形顶点数组（Vector3），按顺序连接构成闭合多边形
-     * @param axis 投影平面，决定使用 bbox 的哪两个轴做 2D 判定
-     *   - 'xz'（默认）：俯视图，取 bbox 的 x/z 坐标
-     *   - 'xy'：正视图，取 bbox 的 x/y 坐标
-     *   - 'yz'：侧视图，取 bbox 的 y/z 坐标
-     * @returns 范围内所有构件的 oid 数组
+     * 计算给定 OID 集合的几何中心（世界坐标系与结构 bbox / 瓦片 mesh 一致）。
+     * 优先合并结构树中的轴对齐 bbox；若无有效 bbox 则合并对应 split mesh 的世界包围盒。
      */
-    selectByPolygon(polygon: Vector3[], axis?: "xy" | "xz" | "yz"): Promise<number[]>;
-    private _getModelInfoUrl;
+    getCenterByOids(oids: readonly number[]): Vector3 | null;
+    /**
+     * 按属性条件筛选构件（语义同 `setStyle` 的 `show` / conditions 中的表达式字符串），
+     * 返回筛选结果的整体中心点；合并方式同 {@link getCenterByOids}。
+     */
+    getCenterByCondition(condition: string): Vector3 | null;
+    /**
+     * 完整结构数据（与内嵌 structure JSON 一致）
+     */
+    getStructureData(): StructureData | null;
+    /**
+     * 选择包围盒范围内的构件（坐标系与结构 bbox 一致）
+     */
+    selectByBox(box: Box3): number[];
+    /**
+     * 选择多边形（平面投影）范围内的构件
+     */
+    selectByPolygon(polygon: Vector3[], axis?: "xy" | "xz" | "yz"): number[];
     private _fetchModelInfo;
     private _ensureModelInfoLoaded;
     /**
@@ -119,13 +157,12 @@ export declare class GLTFParserPlugin implements MeshHelperHost {
     private _notifyCollectors;
     _registerCollector(collector: MeshCollector): void;
     _unregisterCollector(collector: MeshCollector): void;
-    private _updateWebGLLimits;
     /**
-     * Dynamically calculate FEATURE_ID_COUNT based on WebGL limits and current oid count
+     * 遍历所有已加载瓦片，应用可见性过滤
      */
-    private _calculateFeatureIdCount;
+    private _applyVisibilityToAllTiles;
     /**
-     * Set up shader modification for hiding specific features
+     * 设置材质（DoubleSide 等基础配置）
      */
     private _setupMaterial;
     /**
@@ -146,23 +183,45 @@ export declare class GLTFParserPlugin implements MeshHelperHost {
     unisolate(): void;
     getIsolatedOids(): number[];
     /**
-     * 内部方法：根据 oid 获取 mesh 数组
+     * 合并 OID 列表对应的结构 bbox；若无可用 bbox 则使用 split mesh 世界包围盒并求中心。
+     */
+    private _getCenterFromOidList;
+    /**
+     * 按 OID 集合：每个瓦片 mesh 只生成 **一个** 合并后的 split mesh（同一组 oid / condition 一条几何）
+     */
+    private _getMergedSplitMeshesForOidSet;
+    /**
+     * 内部方法：根据单个 oid 获取 split mesh（每瓦片合并为一条）
      */
     _getMeshesByOidInternal(oid: number): Mesh[];
     /**
-     * 根据 oid 获取 MeshCollector
-     * MeshCollector 会监听瓦片变化，自动更新 meshes 并触发 mesh-change 事件
-     * 内部缓存：相同 oid 多次调用会返回同一个 collector 实例
+     * 内部方法：根据多个 oid 获取合并 split mesh（每瓦片一条，而非每 oid 一条）
+     */
+    _getMeshesByOidsInternal(oids: readonly number[]): Mesh[];
+    /**
+     * 按查询收集 mesh：可只传 oids、只传 condition（全场景 OID 上筛选）、或两者组合
+     * condition 与 setStyle 的 show / conditions 中字符串表达式语义一致
+     */
+    _getMeshesForCollectorQueryInternal(params: {
+        oids: readonly number[];
+        condition?: string;
+    }): Mesh[];
+    /**
+     * 根据查询获取 MeshCollector（oids + 可选 condition，缓存键相同则复用实例）
+     */
+    getMeshCollectorByCondition(query: MeshCollectorQuery): MeshCollector;
+    /**
+     * 根据单个 oid 获取 MeshCollector（等价于 getMeshCollectorByCondition({ oids: [oid] })）
      */
     getMeshCollectorByOid(oid: number): MeshCollector;
     /**
      * Hide the corresponding part of the original mesh according to the OID array
      */
-    hideByOids(oids: number[]): void;
+    hidePartsByOids(oids: number[]): void;
     /**
      * Restore the display of the corresponding mesh according to the OID array
      */
-    unhideByOids(oids: number[]): void;
+    showPartsByOids(oids: number[]): void;
     /**
      * 根据 oid 数组设置构件颜色
      * 隐藏原 mesh，将 split mesh 替换材质后加入场景（使用 tiles.group）
@@ -172,7 +231,7 @@ export declare class GLTFParserPlugin implements MeshHelperHost {
     setPartColorByOids(oids: number[], color: ColorInput): void;
     /**
      * 恢复指定构件的颜色
-     * 从场景移除 split mesh，unhide 原 mesh
+     * 从场景移除 split mesh，恢复原 mesh 显示
      * @param oids 构件 OID 数组
      */
     restorePartColorByOids(oids: number[]): void;
@@ -215,12 +274,51 @@ export declare class GLTFParserPlugin implements MeshHelperHost {
      * 清除所有线框显示构件
      */
     clearAllFrameParts(): void;
+    /**
+     * 设置指定构件的线框填充颜色
+     * @param oids 构件 OID 数组
+     * @param color 颜色值，支持 hex 数字、颜色字符串（如 "#ff0000"）、THREE.Color 对象
+     */
+    setFrameFillColor(oids: number[], color: ColorInput): void;
+    /**
+     * 设置指定构件的线框边框颜色
+     * @param oids 构件 OID 数组
+     * @param color 颜色值，支持 hex 数字、颜色字符串（如 "#ff0000"）、THREE.Color 对象
+     */
+    setFrameEdgeColor(oids: number[], color: ColorInput): void;
+    /**
+     * 设置构件样式（条件可见性 + 条件材质）
+     * @param style 样式配置，传 null 清除样式
+     */
+    setStyle(style: StyleConfig | null): void;
+    /**
+     * 当前样式配置，只读
+     */
+    get style(): StyleConfig | null;
+    /**
+     * 清除构件样式
+     */
+    clearStyle(): void;
+    /**
+     * 高亮指定构件（语义与 setStyle 一致：show、conditions、可选 oids，另需 name 标识分组）
+     * @param options 高亮配置
+     */
+    highlight(options: HighlightOptions): void;
+    /**
+     * 取消指定名称的高亮
+     * @param name 高亮组名称
+     */
+    cancelHighlight(name: string): void;
+    /**
+     * 取消所有高亮
+     */
+    cancelAllHighlight(): void;
     /**
      * Restore the original materials of the mesh
      */
-    unhide(): void;
+    showAllParts(): void;
     /**
-     * Get the current feature ID count
+     * 获取当前隐藏的 OID 数量（兼容旧 API）
      */
     getFeatureIdCount(): number;
     /**
@@ -234,7 +332,7 @@ export declare class GLTFParserPlugin implements MeshHelperHost {
  */
 export declare interface GLTFParserPluginOptions {
     /**
-     * WebGLRenderer instance, required for mesh helper features (hideByOids, etc.)
+     * WebGLRenderer instance, required for mesh helper features (hidePartsByOids, etc.)
      */
     renderer?: WebGLRenderer;
     /**
@@ -266,6 +364,35 @@ export declare interface GLTFParserPluginOptions {
     useIndexedDB?: boolean;
 }
 
+/** 条件命中后的外观：材质可为简写，位姿与 setStyle 一致 */
+export declare interface HighlightAppearance {
+    material: HighlightMaterial;
+    translation?: StyleVec3Input;
+    scale?: StyleVec3Input;
+    rotation?: StyleEulerInput;
+    origin?: StyleVec3Input;
+}
+
+export declare type HighlightCondition = [string | boolean, HighlightAppearance];
+
+/** 高亮材质：Three.js Material 或 { color, opacity } */
+export declare type HighlightMaterial = Material | {
+    color?: ColorInput;
+    opacity?: number;
+};
+
+/** 高亮配置：语义与 setStyle 一致，并多一个 name 用于命名分组 */
+export declare interface HighlightOptions {
+    /** 高亮组名称，用于 cancelHighlight(name) 取消 */
+    name: string;
+    /** 可见性表达式，仅满足条件的构件参与高亮，如 'foo === bar' */
+    show?: string;
+    /** 条件外观数组，第一个满足条件的应用对应外观；[true, appearance] 为默认 */
+    conditions?: HighlightCondition[];
+    /** 若指定，仅在这些 OID 与属性数据的交集中应用（与 conditions 组合） */
+    oids?: number[];
+}
+
 declare type MaterialBuilder = (matData: unknown, textureMap: Map<number, Texture>) => Material;
 
 export declare interface MeshChangeEvent {
@@ -274,18 +401,25 @@ export declare interface MeshChangeEvent {
 }
 
 /**
- * MeshCollector - 用于监听和收集特定 oid 对应的 mesh
- * 随着瓦片变化，会自动更新 meshes 并触发 mesh-change 事件
+ * MeshCollector - 按查询条件监听并收集 split mesh
  */
 export declare class MeshCollector extends EventDispatcher<MeshCollectorEventMap> {
-    private oid;
+    private readonly queryOids;
+    private readonly condition;
+    private readonly cacheKey;
     private plugin;
     private _meshes;
     private _disposed;
-    constructor(oid: number, plugin: MeshHelperHost);
+    constructor(query: MeshCollectorQuery, plugin: MeshHelperHost);
+    getCacheKey(): string;
+    /** 查询里显式传入的 OID（规范化后）；仅用 condition 筛选时可能为空数组 */
+    getOids(): readonly number[];
+    /** 有显式 OID 时返回第一个；否则无意义（可能为 undefined） */
+    getOid(): number | undefined;
     get meshes(): Mesh[];
+    /** 与 setStyle 一致的条件表达式（若有） */
+    getCondition(): string | undefined;
     _updateMeshes(): void;
-    getOid(): number;
     dispose(): void;
 }
 
@@ -293,10 +427,33 @@ export declare type MeshCollectorEventMap = {
     "mesh-change": MeshChangeEvent;
 };
 
-declare interface MeshHelperHost {
+/** @deprecated 请使用 meshCollectorQueryCacheKey({ oids }) */
+export declare function meshCollectorGroupKey(oids: readonly number[]): string;
+
+/** 收集器查询：OID 范围 + 可选属性条件（语义同 setStyle 的 show / conditions 中的表达式字符串） */
+export declare interface MeshCollectorQuery {
+    /**
+     * 限定在这些 OID 内收集；不传或空数组时，若提供 condition 则从全场景 OID 中筛选
+     */
+    oids?: readonly number[];
+    /**
+     * 属性表达式，如 `type === "wall"`，与 setStyle 里 `show` 或 `conditions[i][0]`（为 string 时）相同
+     */
+    condition?: string;
+}
+
+/**
+ * 与 MeshCollector.getCacheKey()、插件 collectorCache 键一致
+ */
+export declare function meshCollectorQueryCacheKey(query: MeshCollectorQuery): string;
+
+export declare interface MeshHelperHost {
     _registerCollector(collector: MeshCollector): void;
     _unregisterCollector(collector: MeshCollector): void;
-    _getMeshesByOidInternal(oid: number): Mesh[];
+    _getMeshesForCollectorQueryInternal(params: {
+        oids: readonly number[];
+        condition?: string;
+    }): Mesh[];
 }
 
 /**
@@ -312,6 +469,18 @@ export declare interface ModelInfo {
     vertices: number;
 }
 
+/** 去重并排序 OID */
+export declare function normalizeMeshCollectorOids(oids: readonly number[]): number[];
+
+/**
+ * 从已加载的根 tileset 读取内嵌 structure（`asset.extras.maptalks.structureUri`，
+ * 若无则回退根级 `structureUri`），同步解码并解析。
+ * - 无有效 URI 或解析失败时返回 `null`（不抛错）。
+ */
+export declare function parseEmbeddedStructureDataFromTilesSync(tiles: {
+    rootTileset: Tileset | null;
+}): StructureData | null;
+
 /**
  * structure.json 的完整数据结构
  */
@@ -332,4 +501,34 @@ export declare interface StructureNode {
     [key: string]: unknown;
 }
 
+/** 条件命中后的外观：材质必填，位姿可选（未传则不改对应分量） */
+export declare interface StyleAppearance {
+    material: Material;
+    translation?: StyleVec3Input;
+    scale?: StyleVec3Input;
+    rotation?: StyleEulerInput;
+    /** mesh 局部空间中的枢轴；未传则 (0,0,0) */
+    origin?: StyleVec3Input;
+}
+
+/** 条件项：[条件表达式或 true, 外观对象] */
+export declare type StyleCondition = [string | boolean, StyleAppearance];
+
+/** 样式配置 */
+export declare interface StyleConfig {
+    show?: string;
+    conditions?: StyleCondition[];
+}
+
+/** 与 Euler 等价：Three 的 Euler，或 [x,y,z] / [x,y,z,order] */
+export declare type StyleEulerInput = Euler | readonly number[];
+
+/** 与 Vector3 等价：Three 的 Vector3 或长度≥3 的 [x,y,z] 数组 */
+export declare type StyleVec3Input = Vector3 | readonly number[];
+
+/** 兼容：少数 tileset 在根级挂 structureUri */
+export declare type TilesetWithStructureUri = Tileset & {
+    structureUri?: string;
+};
+
 export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gltf-parser-plugin",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "A plugin for parsing GLTF files",
   "type": "module",
   "main": "./build/gltf-parser-plugin.module.js",
@@ -30,18 +30,19 @@
   "devDependencies": {
     "@types/node": "^25.5.0",
     "@types/three": "^0.183.1",
-    "@typescript-eslint/eslint-plugin": "^8.57.0",
-    "@typescript-eslint/parser": "^8.57.0",
-    "eslint": "^10.0.3",
-    "typescript": "^5.9.3",
-    "vite": "^8.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.2",
+    "@typescript-eslint/parser": "^8.57.2",
+    "eslint": "^10.1.0",
+    "typescript": "^5.8.2",
+    "vite": "^8.0.2",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.1"
   },
   "dependencies": {
-    "3d-tiles-renderer": "^0.4.22",
+    "3d-tiles-renderer": "^0.4.23",
     "@maptalks/gltf-loader": "^0.124.4",
     "@maptalks/transcoders.draco": "^0.124.4",
+    "fflate": "^0.8.2",
     "three": "^0.183.2"
   }
 }