iflow-engine-base 3.12.4 → 3.12.5

package/dist/index.d.ts

@@ -551,17 +551,24 @@ declare class Calibration {
     private static readonly sourceColor;
     private static readonly targetColor;
     private readonly matrices;
+    private readonly histories;
+    private readonly historyOrder;
     private pointCalibrationUrl;
     private pointCalibrationPoints;
+    private pointCalibrationCallback;
     private behavior;
+    private readonly onKeyDown;
     /** 供 handelBehaved 判断不同工具切换时释放当前鼠标监听。 */
     readonly type = "point-calibration";
     constructor(engine: any);
+    /** 释放校准管理器的全局快捷键监听。 */
+    dispose(): void;
     /**
      * 应用模型校准矩阵。
      * flat 16 数组按 Three.js 列主序处理；二维 4x4 数组按常见行主序处理。
      */
     apply(options: CalibrationOptions): boolean;
+    private applyInternal;
     /**
      * 兼容业务侧更直观的命名。
      */
@@ -605,18 +612,57 @@ declare class Calibration {
     /**
      * 清除指定模型的校准。
      */
-    clear(url: string): boolean;
+    clear(url: string, onChange?: CalibrationChangeCallback): boolean;
+    /** 撤回最近一次模型校准；传 url 时只撤回指定模型，不传时撤回最后变更的模型。 */
+    undo(url?: string, onChange?: CalibrationChangeCallback): boolean;
+    private pushHistory;
+    private findLatestHistoryUrl;
+    private notifyChange;
+    private createChangeEvent;
+    private handleKeyDown;
+    /** Ctrl+Z / Command+Z 撤回最近一次主模型校准，输入框焦点下保留原生编辑行为。 */
+    private isUndoShortcut;
     private updateCachedModelBox;
     private clearRuntimeWorldBoxCache;
     private toThreeMatrix;
     private toVector3;
 }
 
+export declare type CalibrationChangeCallback = (event: CalibrationChangeEvent) => void;
+
+/** 3D 主模型校准变化回调数据。 */
+export declare interface CalibrationChangeEvent {
+    url: string;
+    source: CalibrationChangeSource;
+    /** 模型根节点当前平移值，单位沿用引擎世界坐标。 */
+    offset: CalibrationVector3Array;
+    /** 模型根节点当前欧拉角，单位为角度，数组第 4 位保留 Three.js 的旋转顺序。 */
+    rotation: CalibrationEulerArray;
+    /** 模型根节点当前欧拉角，单位为弧度，供需要 Three.js 原始单位的业务使用。 */
+    rotationRadians: CalibrationEulerArray;
+    /** 便于 UI 直接显示的三轴角度制旋转值。 */
+    rotationDegrees: CalibrationVector3Array;
+    /** 模型根节点当前缩放，矩阵校准包含缩放时用于业务侧兜底保存。 */
+    scale: CalibrationVector3Array;
+    /** 当前 4x4 校准矩阵，按 Three.js 列主序导出。 */
+    matrix: number[];
+    /** 本次变更前的 4x4 校准矩阵，按 Three.js 列主序导出。 */
+    previousMatrix: number[];
+    /** 是否由 Ctrl+Z 或 undo 触发。 */
+    isUndo: boolean;
+}
+
+export declare type CalibrationChangeSource = 'apply' | 'segment' | 'point' | 'clear' | 'undo';
+
+declare type CalibrationEulerArray = [number, number, number, THREE.EulerOrder];
+
 declare type CalibrationMatrixInput = THREE.Matrix4 | number[] | ArrayLike<number> | number[][];
 
 export declare interface CalibrationOptions {
     url: string;
     matrix: CalibrationMatrixInput;
+    /** 校准成功后返回当前模型的偏移、旋转和矩阵，便于业务侧保存手动调节结果。 */
+    onChange?: CalibrationChangeCallback;
 }
 
 declare type CalibrationPointInput = THREE.Vector3 | [number, number, number] | {
@@ -634,6 +680,8 @@ declare interface CalibrationSegmentInput {
     end: CalibrationPointInput;
 }
 
+declare type CalibrationVector3Array = [number, number, number];
+
 declare class CameraModule {
     private static readonly MIN_VISIBLE_HEIGHT;
     private static readonly MIN_CAMERA_DISTANCE;
@@ -2482,6 +2530,8 @@ declare class EngineKernelV2 {
     modelComparison: ModelComparison;
     /** 管理模型炸开代理对象，并保持炸开后的构件交互身份。 */
     modelExplode: ModelExplode;
+    /** 材质编辑器，提供 DOM 面板、材质修改记录读取和一键还原能力。 */
+    materialTool: MaterialTool;
     models: any[];
     reactBoundingClientRect: {
         left: number;
@@ -2943,6 +2993,7 @@ export declare enum EventType {
     Click = "click",// data: ModelClickEventItem[]
     MouseMove = "mouse-move",// data: MouseEventData - 鼠标移动事件
     ModelPlaceSelected = "model-place-selected",
+    ModelCalibrationChanged = "model-calibration-changed",
     CameraChanged = "camera-changed",// 相机移动时持续触发
     CameraIdle = "camera-idle",// 相机静止后触发
     ViewportResize = "viewport-resize",// 窗口大小变化
@@ -4678,6 +4729,8 @@ declare class LinkElement2d3d {
     private disActive;
     dispose(): void;
     private readonly listenElementClick;
+    /** 二三维模型联动开启时保持 3D 引擎全帧渲染，避免等待空闲限帧间隔。 */
+    private readonly listenLinkStateChange;
 }
 
 declare class LinkView2d3d {
@@ -5094,6 +5147,132 @@ declare interface Markup2dStyle {
 
 declare type Markup2dType = 'line' | 'arrow' | 'rect' | 'ellipse' | 'text' | 'polygon' | 'cloudline';
 
+export declare interface MaterialEditorMaterialInfo {
+    id: string;
+    name: string;
+    type: string;
+    color?: string;
+    opacity: number;
+    transparent: boolean;
+    roughness?: number;
+    metalness?: number;
+    emissive?: string;
+    emissiveIntensity?: number;
+    side: number;
+    wireframe?: boolean;
+    textures: MaterialTextureInfo[];
+}
+
+export declare interface MaterialEditorOptions {
+    visible?: boolean;
+    title?: string;
+    width?: number;
+}
+
+export declare interface MaterialEditorTarget {
+    url: string;
+    ids?: Array<string | number>;
+}
+
+export declare type MaterialMapSlot = 'map' | 'normalMap' | 'roughnessMap' | 'metalnessMap' | 'alphaMap' | 'aoMap' | 'bumpMap' | 'emissiveMap';
+
+export declare interface MaterialModificationRecord {
+    id: string;
+    name: string;
+    type: string;
+    objectNames: string[];
+    changes: Record<string, {
+        before: unknown;
+        after: unknown;
+    }>;
+}
+
+declare interface MaterialOption {
+    material: THREE.Material;
+    materials?: THREE.Material[];
+    owners: THREE.Object3D[];
+}
+
+export declare interface MaterialTextureInfo {
+    slot: MaterialMapSlot;
+    name: string;
+    url: string;
+    hasTexture: boolean;
+}
+
+/** 材质编辑器入口，负责对外 API、事件绑定和材质资源生命周期。 */
+export declare class MaterialTool {
+    private readonly engine;
+    options: Required<MaterialEditorOptions>;
+    selectedMaterials: MaterialOption[];
+    selectedMaterialId: string | null;
+    targetText: string;
+    visible: boolean;
+    private readonly textureLoader;
+    private readonly ownedTextures;
+    private readonly objectUrls;
+    private readonly collector;
+    private readonly snapshots;
+    private readonly panel;
+    private isDisposed;
+    private eventsBound;
+    private readonly handleSelectionChanged;
+    private readonly handleClick;
+    private readonly handleLoadingCompleted;
+    constructor(engine: any, options?: MaterialEditorOptions);
+    /** 初始化 DOM 和事件监听；默认隐藏，业务可调用 show() 打开。 */
+    init(options?: MaterialEditorOptions): void;
+    /** 显示编辑器，可同时传入目标对象或构件选择信息。 */
+    show(target?: THREE.Object3D | MaterialEditorTarget): void;
+    /** 隐藏编辑器但保留已有修改记录。 */
+    hide(): void;
+    /** 切换编辑器显示状态。 */
+    toggle(target?: THREE.Object3D | MaterialEditorTarget): void;
+    /** 根据场景对象读取其下所有材质并刷新面板。 */
+    selectObject(object: THREE.Object3D): MaterialEditorMaterialInfo[];
+    /** 根据当前引擎选择数据读取构件材质。 */
+    selectTarget(target: MaterialEditorTarget): MaterialEditorMaterialInfo[];
+    /** 只读取目标对象材质，不改变当前 UI 选择。 */
+    getMaterialsByObject(object: THREE.Object3D): MaterialEditorMaterialInfo[];
+    /** 只读取指定构件材质，不改变当前 UI 选择。 */
+    getMaterialsByTarget(target: MaterialEditorTarget): MaterialEditorMaterialInfo[];
+    /** 读取当前场景中所有可编辑材质。 */
+    getAllSceneMaterials(): MaterialEditorMaterialInfo[];
+    /** 返回当前选择对象上可编辑的材质信息。 */
+    getSelectedMaterials(): MaterialEditorMaterialInfo[];
+    /** 返回全场景相对快照发生变化的材质信息。 */
+    getModifiedMaterials(): MaterialModificationRecord[];
+    /** 重建当前场景基准快照；通常在模型加载完成后由编辑器自动调用。 */
+    captureSceneSnapshot(): void;
+    /** 批量更新材质参数。 */
+    updateMaterial(materialId: string, patch: Partial<Record<string, unknown>>): void;
+    /** 通过 URL 或 File 修改指定贴图槽；传入 null 时清除贴图。 */
+    setTexture(materialId: string, slot: MaterialMapSlot, source: string | File | null): Promise<void>;
+    /** 一键还原所有有基准快照的场景材质。 */
+    restoreAll(): void;
+    /** 兼容常见命名：重置所有材质修改。 */
+    resetAll(): void;
+    /** 还原单个材质。 */
+    restoreMaterial(materialId: string): void;
+    /** 获取当前面板正在编辑的材质。 */
+    getActiveMaterial(): THREE.Material | null;
+    /** 刷新 DOM 面板。 */
+    render(): void;
+    /** 销毁 DOM、事件监听和编辑器创建的贴图资源。 */
+    dispose(): void;
+    private bindEvents;
+    private setSelectedMaterials;
+    /** 内容完全相同的材质只保留一个卡片，并合并它关联的对象和实际材质实例。 */
+    private dedupeMaterials;
+    private collectSceneMaterials;
+    private findMaterialById;
+    private findMaterialGroupById;
+    private replaceTexture;
+    private loadTexture;
+    private requestRender;
+    private disposeOwnedTextures;
+}
+
 declare class Measure {
     private isActive;
     private engine;
@@ -5862,6 +6041,8 @@ declare class ModelLink3d {
     isApplyingLinkedEvent(): boolean;
     dispose(): void;
     private normalizeOptions;
+    /** 模型联动开启后需要持续响应外部视图变化，不能进入空闲限帧。 */
+    private syncIdleFrameRateExempt;
     private createViewerGuid;
     private wrapModelToolMethods;
     private restoreModelToolMethods;
@@ -6890,6 +7071,8 @@ declare interface PerformanceStats {
 /** 启动四点捕捉校准所需参数。 */
 export declare interface PointCalibrationOptions {
     url: string;
+    /** 四点采集完成并应用校准后触发。 */
+    onChange?: CalibrationChangeCallback;
 }
 
 /**
@@ -7572,6 +7755,8 @@ export declare interface SegmentCalibrationOptions {
     url: string;
     source: CalibrationSegmentInput;
     target: CalibrationSegmentInput;
+    /** 校准成功后返回当前模型的偏移、旋转和矩阵，便于业务侧保存手动调节结果。 */
+    onChange?: CalibrationChangeCallback;
 }
 
 /**

package/package.json

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