iflow-engine-base 3.11.8 → 3.12.0

package/dist/index.d.ts

@@ -501,6 +501,22 @@ declare interface BoundsLike {
     };
 }
 
+/**
+ * 基础几何类型定义
+ */
+declare interface Box3 {
+    min: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    max: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+
 declare type CadCursorStyle2d = 'full-crosshair' | 'short-crosshair';
 
 declare class CadCursorUI {
@@ -2455,6 +2471,8 @@ declare class EngineKernelV2 {
     calibration: Calibration;
     /** 管理第三方 GLB 的放置、编辑和场景还原。 */
     modelPlace: ModelPlace;
+    /** 基于当前引擎作为基准版本的模型差异比较器。 */
+    modelComparison: ModelComparison;
     models: any[];
     reactBoundingClientRect: {
         left: number;
@@ -2683,7 +2701,7 @@ declare class EngineStatus {
     isDisableContextMenu: boolean;
     disableModelInteractionHighlight: boolean;
     suppressNextOrbitOriginPick: boolean;
-    highlightModels: any[];
+    highlightModels: HighlightModelState[];
     hideModels: any[];
     translucentModels: any[];
     models: any[];
@@ -2913,7 +2931,7 @@ export declare enum EventType {
     ModelError = "model-error",
     SelectionChanged = "selection-changed",// data: { ids: string[], modelId: string }
     HoverChanged = "hover-changed",// data: { id: string | null, point: Vector3 }
-    Click = "click",// data: MouseEventData
+    Click = "click",// data: ModelClickEventItem[]
     MouseMove = "mouse-move",// data: MouseEventData - 鼠标移动事件
     ModelPlaceSelected = "model-place-selected",
     CameraChanged = "camera-changed",// 相机移动时持续触发
@@ -3738,6 +3756,13 @@ declare interface HdrItem {
     url?: string;
 }
 
+/** 当前高亮构件状态，ids 与 guids 按索引一一对应。 */
+export declare interface HighlightModelState {
+    url: string;
+    ids: any[];
+    guids: string[];
+}
+
 declare class HoverHighLight {
     private engine;
     private overlayMaterial;
@@ -3879,6 +3904,49 @@ export declare interface IGISEventModule {
     off<T = unknown>(event: EventTypeGIS_2 | string, callback: GISEventCallback<T>): void;
 }
 
+/**
+ * 资源加载模块接口
+ * 负责模型文件的加载、卸载以及多模型场景下的空间管理。
+ */
+export declare interface ILoaderModule {
+    /**
+     * 加载模型
+     * @param url 模型文件的 URL (.gltf, .glb, .bim, etc.)
+     * @param options 加载配置选项
+     * @returns Promise，解析为加载完成的模型对象
+     */
+    loadModel(url: string, options?: LoadModelOptions): Promise<IModel>;
+    loadModels(urls: string[], options?: LoadModelOptions): Promise<void>;
+    loadModelFile(files: File[], options?: LoadModelOptions): Promise<void>;
+    /**
+     * 卸载指定模型
+     * @param modelId 模型 ID
+     */
+    unloadModel(modelId: string): void;
+    /**
+     * 获取当前场景中所有已加载的模型
+     */
+    getAllModels(): IModel[];
+    /**
+     * 获取指定模型
+     */
+    getModel(modelId: string): IModel | undefined;
+}
+
+/**
+ * 运行时模型对象接口
+ */
+export declare interface IModel {
+    readonly id: string;
+    readonly uuid: string;
+    name: string;
+    visible: boolean;
+    /** 获取模型的包围盒 */
+    getBoundingBox(): Box3;
+    /** 更新模型矩阵 */
+    setMatrix(matrix: number[]): void;
+}
+
 declare class InteractionModule {
     private engine;
     private behavior;
@@ -3909,6 +3977,8 @@ declare class InteractionModule {
     handleMouseUp(event: any): void;
     getCatchMeshs(event: any, retainShow?: boolean): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>[] | null;
     handleMouseClick(event: any): void;
+    /** 根据模型地址和运行时节点 ID 获取点击构件的 GUID。 */
+    private getNodeGuid;
     handleMouseDoubleClick(event: any): void;
     private clearModelHighlightBeforeCameraFlight;
     handleMouseClickInstance(raycaster: any): any;
@@ -4650,6 +4720,10 @@ declare class LoaderModule {
      * 批量加载模型 URL。
      */
     loadModels(urls: string[], options?: LoadModelOptions): Promise<void>;
+    /**
+     * 下载未加密的轻量化整包 ZIP，解压并生成本地虚拟 URL 后复用常规模型加载链路。
+     */
+    private loadModelPackageUrls;
     /**
      * 直接加载用户在浏览器中选择的本地模型文件。
      * 支持两种输入：
@@ -4857,7 +4931,9 @@ declare type LoadingStyle2d = 1 | 2;
 /**
  * 模型加载配置项
  */
-declare interface LoadModelOptions {
+export declare interface LoadModelOptions {
+    /** URL 是否为未加密的轻量化整包 ZIP；开启后会先解压并转成本地虚拟 URL 再加载 */
+    isZipPackage?: boolean;
     /** 自定义模型 ID，若不提供则自动生成 UUID */
     id?: string;
     /** 初始名称 */
@@ -5271,6 +5347,185 @@ declare class MiniMap {
     dispose(): void;
 }
 
+/** 三维模型点击事件中的单个构件数据。 */
+export declare interface ModelClickEventItem {
+    url: string;
+    ids: Array<string | number>;
+    /** 与 ids 按索引一一对应的构件 GUID。 */
+    guids: string[];
+}
+
+/**
+ * 以当前引擎为基准版本，对另一个引擎的 nodesMap 进行手动差异比较。
+ * 模块不会在模型加载后自动执行，只有调用 compare 后才会开始或等待加载完成。
+ */
+export declare class ModelComparison {
+    private readonly engine;
+    private readonly listeners;
+    private activeRun;
+    private visualizationState;
+    private readonly loadingOverlays;
+    private nextRunId;
+    constructor(engine: any);
+    /** 订阅对比进度、完成、取消或异常事件；返回取消订阅函数。 */
+    on<K extends keyof ModelComparisonEventMap>(event: K, callback: (data: ModelComparisonEventMap[K]) => void): () => void;
+    /** 取消指定事件的监听。 */
+    off<K extends keyof ModelComparisonEventMap>(event: K, callback: (data: ModelComparisonEventMap[K]) => void): void;
+    /**
+     * 手动开始一次对比；当前引擎为基准版本，targetEngine 为待比较版本。
+     * 同一实例同一时间只允许一个任务，避免两个大模型扫描任务争抢主线程。
+     */
+    compare(targetEngine: any, options?: ModelComparisonOptions): Promise<ModelComparisonResult>;
+    /** 请求停止当前任务；批处理中的任务会在下一批开始前结束。 */
+    cancel(): boolean;
+    /** 恢复最近一次模型对比改动过的构件颜色与透明度，不影响其他构件。 */
+    restoreColors(): boolean;
+    /** 释放事件监听，并停止仍在运行的对比。 */
+    dispose(): void;
+    private normalizeOptions;
+    /** 在每个引擎自己的画布容器内创建精简的 DOM 等待层。 */
+    private showLoadingOverlays;
+    /** 创建一侧的等待层；无法定位画布容器时静默跳过，不影响无 DOM 场景下的对比。 */
+    private createLoadingOverlay;
+    /** 根据进度事件更新对应引擎；未指定引擎时同步更新两侧。 */
+    private updateLoadingOverlay;
+    /** 清理本次任务创建的 DOM 和动画，并还原容器定位样式。 */
+    private removeLoadingOverlays;
+    /** 等待至少一次实际绘制并短暂保留遮罩，保证小模型也能看到进度反馈。 */
+    private waitForLoadingOverlayPaint;
+    /** 仅在用户已发起 compare 后等待，避免加载完成事件驱动自动对比。 */
+    private waitForEngineReady;
+    /** 轻量模型以 loading_completed 为准；空模型也允许参与对比，从而得出全新增或全删除。 */
+    private isEngineReady;
+    /** 等待已取消任务的 finally 释放互斥状态，防止旧任务和新任务同时扫描同一批模型。 */
+    private waitForRunRelease;
+    private compareSnapshots;
+    /** 按 GUID 建立数值包围盒快照；原始节点 ID 仅保留给后续改色和定位。 */
+    private createSnapshot;
+    /** 兼容普通构件 infos、实例构件 info 与 MEP 节点的 min/max 数据。 */
+    private extractBox;
+    private toBox;
+    private toVector;
+    private isBoxEqual;
+    /**
+     * 以半透明白色弱化未变化构件，并在各自所属引擎内标记新增、删除和修改构件。
+     * 删除只存在于基准引擎，新增只存在于目标引擎，修改则在两侧都使用黄色。
+     */
+    private applyColors;
+    /** 按模型地址聚合 ID，以符合 modelToolModule 的 [{ url, ids }] 入参格式。 */
+    private toModelColorRefs;
+    /** 对比结果同时暴露 GUID，并保留运行时 ID 供定位和改色使用。 */
+    private toComparisonRef;
+    /** 空数组不调用工具模块，避免不必要地触发其状态清理逻辑。 */
+    private setColor;
+    /** 颜色或实例副本变化后主动请求渲染，避免空闲降帧导致第二次对比看起来未生效。 */
+    private requestRender;
+    private getNodeCount;
+    /** 输出精简诊断日志，帮助区分未比出差异与改色未落到模型两类问题。 */
+    private log;
+    /** 获取当前引擎模型及其 nodesMap 数量，不输出完整节点以避免控制台过载。 */
+    private describeEngineModels;
+    /** 仅输出加载状态摘要，定位等待阶段卡住的具体模型而不暴露大体量模型数据。 */
+    private describeLoadStatuses;
+    /** 汇总模型定位引用数量，用于核对传给改色接口的实际构件数。 */
+    private countModelRefs;
+    /** 查询 modelToolModule 已登记的改色记录；旧引擎未提供查询接口时也不会影响对比。 */
+    private describeCustomColors;
+    private createProgress;
+    private throwIfCancelled;
+    /** 分批让出浏览器主线程，保证页面能够绘制最新进度。 */
+    private yieldToBrowser;
+    private emit;
+}
+
+/** 包围盒使用数值数组保存，避免对比结果继续持有引擎对象的引用。 */
+export declare interface ModelComparisonBox {
+    min: [number, number, number];
+    max: [number, number, number];
+}
+
+/** 用户主动取消对比时抛出的可识别错误。 */
+export declare class ModelComparisonCancelledError extends Error {
+    constructor();
+}
+
+declare interface ModelComparisonEventMap {
+    progress: ModelComparisonProgress;
+    completed: ModelComparisonResult;
+    cancelled: ModelComparisonProgress;
+    error: Error;
+}
+
+/** 单个构件在某一引擎中的可比较快照。 */
+export declare interface ModelComparisonNode {
+    key: string;
+    modelKey: string;
+    /** 用于调用 modelToolModule 的运行时模型地址。 */
+    modelUrl: string;
+    /** 原始节点键仅用于改色和定位，不参与差异匹配。 */
+    nodeId: any;
+    /** 跨版本构件匹配使用的稳定 GUID。 */
+    guid: string;
+    box: ModelComparisonBox | null;
+}
+
+/** 用户可按版本、URL 或业务模型 ID 将两侧模型配对为同一个比较键。 */
+export declare interface ModelComparisonOptions {
+    /** 两个边界值差异不超过该阈值时视为未修改；默认 0.001。 */
+    boxTolerance?: number;
+    /** 每处理一批节点便让出一次主线程，使进度条和取消操作可以响应。 */
+    batchSize?: number;
+    /** 发起手动对比时，如引擎尚在加载则监听其完成事件；默认 true。 */
+    waitForEngines?: boolean;
+    /** 是否按差异类型改色；默认 false，开启后可通过 restoreColors() 恢复。 */
+    changeColor?: boolean;
+    /** 是否在两个引擎画布容器内显示对比等待层；默认 true。 */
+    showLoadingUI?: boolean;
+    /** 默认采用业务 key 或数组下标；模型顺序不一致时可通过该函数完成模型配对。 */
+    getModelKey?: (model: any, index: number, role: 'baseline' | 'target') => string;
+}
+
+/** 对比任务可直接用于页面进度条的数据。 */
+export declare interface ModelComparisonProgress {
+    runId: number;
+    stage: 'waiting' | 'snapshot' | 'diff' | 'completed' | 'cancelled' | 'error';
+    percent: number | null;
+    processed: number;
+    total: number;
+    message: string;
+    engine?: 'baseline' | 'target';
+}
+
+/** 面向调用方的构件定位结果，url 可直接作为 modelToolModule 的模型定位键。 */
+export declare interface ModelComparisonRef {
+    url: string;
+    id: any;
+    guid: string;
+}
+
+/** 模型对比的完整结果。 */
+export declare interface ModelComparisonResult {
+    runId: number;
+    /** 新增构件：只存在于目标引擎。 */
+    addedIds: ModelComparisonRef[];
+    /** 删除构件：只存在于基准引擎。 */
+    removedIds: ModelComparisonRef[];
+    /** 包围盒修改构件：同时保留基准与目标模型中的 url、运行时 id 与 guid。 */
+    modifiedBoxIds: ModifiedModelComparisonRef[];
+    added: ModelComparisonNode[];
+    removed: ModelComparisonNode[];
+    modifiedBox: ModifiedBoxNode[];
+    unchanged: UnchangedModelNode[];
+    boxUnavailable: ModelComparisonNode[];
+    summary: {
+        added: number;
+        removed: number;
+        modifiedBox: number;
+        unchanged: number;
+        boxUnavailable: number;
+    };
+}
+
 declare class ModelEdge {
     private engine;
     private isActive;
@@ -5625,13 +5880,24 @@ declare class ModelToolModule {
     private highlightMaterial;
     private translucentMaterial;
     private customModelColorRecords;
+    private customInstanceColorBatches;
     constructor(engine_: any);
     split_merge_model(model: any): void;
     un_split_merge_model(model: any): void;
     private shouldKeepSplitState;
     private areAllGroupsHidden;
+    /** 更新单个构件的材质/可见状态，真正的 geometry group 在一轮操作结束后统一重建。 */
+    private setSplitComponentState;
+    /** 获取拆分构件当前材质索引，供高亮恢复时保留自定义颜色。 */
+    private getSplitComponentMaterialIndex;
+    /** 将连续且材质相同的构件区间压缩为一个 group，减少改色、隔离后的 draw call。 */
+    private rebuildSplitModelGroups;
+    /** 一轮状态修改完成后统一压缩所有拆分网格，并在无特殊状态时恢复原始合批 geometry。 */
+    private rebatchSplitModels;
     private getEngineModelByUrl;
     private appendUniqueIds;
+    /** 按构件 ID 顺序从 nodesMap 读取 GUID，确保状态数组可通过相同索引关联。 */
+    private getModelGuids;
     private restoreSplitModelsOnIdle;
     getSceneModel(index: number): any;
     getModelCenter(models?: any[]): THREE.Vector3 | null;
@@ -5669,13 +5935,13 @@ declare class ModelToolModule {
     /** 还原序列化到 key 中的 id：纯数字字符串转回数字，其余保持原样（不同 loader 的 id 类型不统一）。 */
     private parseId;
     private setSimpleModelColor;
-    private restoreSimpleModelColor;
     private restoreSimpleColorRecord;
     private setInstanceModelColor;
-    private restoreInstanceModelColor;
     private restoreInstanceColorRecord;
     private getCustomColorRecordKey;
     private cloneModelRefs;
+    /** 返回目标构件中当前确实处于高亮态的部分，保持颜色恢复不影响无关选择。 */
+    private getHighlightedTargets;
     private removeModelsFromStatusList;
     private getCustomSimpleMaterialIndex;
     private getCustomColorMaterialIndex;
@@ -5683,8 +5949,10 @@ declare class ModelToolModule {
     private getOriginalInstanceMatrix;
     private isModelHighlighted;
     private isModelHidden;
-    private createCustomInstanceClone;
-    private removeCustomInstanceClone;
+    /** 按原始实例网格、颜色和透明度合并改色实例，避免每个构件产生一个 draw call。 */
+    private rebuildCustomInstanceColorBatches;
+    /** 创建同一颜色状态下的 InstancedMesh 批次。 */
+    private createCustomInstanceBatch;
     private normalizeOpacity;
     private clearMaterialTextures;
     translucentModel(models: any[]): void;
@@ -5768,6 +6036,23 @@ declare class ModelTree {
     getMajorTreeData(): any[];
 }
 
+/** 包围盒发生变化时，保留前后值以支持列表详情、定位或可视化。 */
+export declare interface ModifiedBoxNode {
+    key: string;
+    modelKey: string;
+    guid: string;
+    baselineBox: ModelComparisonBox;
+    targetBox: ModelComparisonBox;
+    baselineNode: ModelComparisonNode;
+    targetNode: ModelComparisonNode;
+}
+
+/** 修改构件同时返回两个版本中的定位信息。 */
+export declare interface ModifiedModelComparisonRef {
+    baseline: ModelComparisonRef;
+    target: ModelComparisonRef;
+}
+
 /** 基于 2D octree 的粗筛拾取管理器。 */
 declare class OctreeBox2d {
     private engine;
@@ -7357,6 +7642,12 @@ declare class ThreeDTilesModelLoaderGIS {
     private isPackageBlobPseudoUrl;
 }
 
+/** 两侧均存在且包围盒未变化的构件对。 */
+export declare interface UnchangedModelNode {
+    baselineNode: ModelComparisonNode;
+    targetNode: ModelComparisonNode;
+}
+
 /**
  * 视图边界
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iflow-engine-base",
-  "version": "3.11.8",
+  "version": "3.12.0",
   "description": "BIM Engine SDK for Vue2, Vue3, React and HTML",
   "main": "./dist/bim-engine-sdk.umd.js",
   "module": "./dist/bim-engine-sdk.es.js",