iflow-engine-base 3.10.1 → 3.10.5

package/dist/index.d.ts

@@ -122,11 +122,200 @@ declare class AngleMeasure2d extends BaseMeasureTool2d {
     handleMove(point: THREE.Vector3): void;
 }
 
+/** 统一管理点线面体标记、特效和原生 HTML 窗体。 */
+declare class Annotation3d {
+    private readonly engine;
+    private readonly rootGroup;
+    private readonly records;
+    private readonly textureLoader;
+    private readonly occlusionRaycaster;
+    private readonly normalizer;
+    private readonly materialFactory;
+    private readonly geometryBuilder;
+    private readonly effectsController;
+    private readonly panelLayer;
+    private readonly interaction;
+    private currentTime;
+    /** 初始化标记根节点、DOM 面板层以及交互控制器。 */
+    constructor(engine: any);
+    /** 新增单个标记并返回最终 id。 */
+    add(config: Annotation3dData): string;
+    /** 批量新增标记。 */
+    addMany(configs: Annotation3dData[]): string[];
+    /** 更新标记时直接重建几何和窗体，保持内部状态简单且可预测。 */
+    update(id: string, patch: Partial<Annotation3dData>): boolean;
+    /** 删除单个标记。 */
+    remove(id: string): boolean;
+    /** 清空所有标记及其 DOM 面板。 */
+    clear(): void;
+    /** 获取单个运行时实例。 */
+    get(id: string): Annotation3dInstance | undefined;
+    /** 获取全部运行时实例。 */
+    getAll(): Annotation3dInstance[];
+    /** 显示指定标记。 */
+    show(id: string): boolean;
+    /** 隐藏指定标记。 */
+    hide(id: string): boolean;
+    /** 统一控制标记显隐，并同步其面板状态。 */
+    setVisible(id: string, visible: boolean): boolean;
+    /** 手动打开面板，适用于 manual / click 等模式。 */
+    showPanel(id: string): boolean;
+    /** 手动关闭面板。 */
+    hidePanel(id: string): boolean;
+    /** 切换面板开关状态。 */
+    togglePanel(id: string): boolean;
+    /** 更新面板文本、HTML、样式或 actions。 */
+    updatePanel(id: string, patch: Partial<Annotation3dPanel>): boolean;
+    /** 导出纯数据快照，供保存和恢复。 */
+    getData(): Annotation3dData[];
+    /** 从纯数据快照恢复整套标记。 */
+    restoreData(data: Annotation3dData[]): void;
+    /** 每帧刷新特效和窗体投影位置。 */
+    updateFrame(deltaTime?: number): void;
+    /** 释放事件、几何和 DOM 资源。 */
+    dispose(): void;
+    /** 组装运行时记录，并将几何与面板初始化好。 */
+    private buildRecord;
+    /** 新记录统一走同一挂载流程，减少 add / update 重复代码。 */
+    private attachRecord;
+    /** 内部删除会负责资源回收和 hover 状态清理。 */
+    private removeInternal;
+    /** 标记显隐变化时，同时同步渲染顺序和面板显示。 */
+    private applyVisibility;
+    /** 统一生成对外事件 payload。 */
+    private toEventPayload;
+    /** 统一向引擎事件总线派发标记事件。 */
+    private emit;
+}
+
+/** 创建或恢复标记使用的纯数据结构。 */
+export declare interface Annotation3dData {
+    id?: string;
+    type: Annotation3dType;
+    points: AnnotationPoint3d[];
+    visible?: boolean;
+    selectable?: boolean;
+    style?: Annotation3dStyle;
+    effect?: Annotation3dEffect;
+    panel?: Annotation3dPanel;
+    data?: any;
+}
+
+/** 点线面体统一的特效配置。 */
+export declare interface Annotation3dEffect {
+    gradient?: AnnotationGradientEffect;
+    glow?: AnnotationGlowEffect;
+    flow?: AnnotationFlowEffect;
+    pulse?: AnnotationPulseEffect;
+    ripple?: AnnotationRippleEffect;
+    pillar?: AnnotationPillarEffect;
+    baseRing?: AnnotationBaseRingEffect;
+    layers?: AnnotationLayersEffect;
+    scan?: AnnotationScanEffect;
+}
+
+/** 引擎运行时实例，包含根节点和交互状态。 */
+export declare interface Annotation3dInstance {
+    id: string;
+    type: Annotation3dType;
+    points: AnnotationPoint3d[];
+    visible: boolean;
+    selectable: boolean;
+    style: Annotation3dStyle;
+    effect: Annotation3dEffect;
+    panel?: Omit<Annotation3dPanel, 'actions'>;
+    data?: any;
+    panelVisible: boolean;
+    hovered: boolean;
+    root: THREE.Group;
+}
+
+/** 标记关联的原生 HTML 窗体配置。 */
+export declare interface Annotation3dPanel {
+    visible?: boolean;
+    trigger?: 'manual' | 'hover' | 'click' | 'always';
+    mode?: 'text' | 'html';
+    text?: string;
+    html?: string;
+    anchor?: 'self' | 'top' | 'center' | 'start' | 'end' | 'centroid';
+    offset?: AnnotationPanelOffset3d;
+    screenOffset?: AnnotationPanelOffset2d;
+    className?: string;
+    style?: Record<string, string>;
+    interactive?: boolean;
+    occlusion?: 'show' | 'hide';
+    actions?: Record<string, (ctx: AnnotationActionContext) => void>;
+}
+
+/** 点线面体统一样式。 */
+export declare interface Annotation3dStyle {
+    color?: string;
+    opacity?: number;
+    depthTest?: boolean;
+    alwaysOnTop?: boolean;
+    lineWidth?: number;
+    fillColor?: string;
+    fillOpacity?: number;
+    point?: AnnotationPointStyle;
+    line?: AnnotationLineStyle;
+    polygon?: AnnotationPolygonStyle;
+    volume?: AnnotationVolumeStyle;
+}
+
+/** 支持的三维标记类型。 */
+export declare type Annotation3dType = 'point' | 'polyline' | 'polygon' | 'extrudePolygon' | 'box';
+
+/** 面板 action 回调上下文。 */
+export declare interface AnnotationActionContext {
+    engine: any;
+    id: string;
+    annotation: Annotation3dInstance;
+    action: string;
+    element: HTMLElement;
+    originalEvent: MouseEvent;
+}
+
+/** 底环效果配置。 */
+declare interface AnnotationBaseRingEffect {
+    enabled: boolean;
+    radius?: number;
+    rotateSpeed?: number;
+}
+
 /**
  * 标注联合类型
  */
 declare type AnnotationConfig720 = IconAnnotationConfig | TextAnnotationConfig | LinkAnnotationConfig;
 
+/** 流动效果配置。 */
+declare interface AnnotationFlowEffect {
+    enabled: boolean;
+    speed?: number;
+    width?: number;
+    direction?: 'forward' | 'backward' | 'up';
+}
+
+/** 发光效果配置。 */
+declare interface AnnotationGlowEffect {
+    enabled: boolean;
+    color?: string;
+    intensity?: number;
+}
+
+/** 渐变色效果配置。 */
+declare interface AnnotationGradientEffect {
+    enabled: boolean;
+    direction?: 'vertical' | 'horizontal' | 'path';
+    stops?: AnnotationGradientStop[];
+}
+
+/** 渐变色 stop。 */
+declare interface AnnotationGradientStop {
+    offset: number;
+    color: string;
+    alpha?: number;
+}
+
 /**
  * 标注实例（包含 DOM 元素）
  */
@@ -146,6 +335,19 @@ declare interface AnnotationInstance {
     visible: boolean;
 }
 
+/** 多层围栏线效果配置。 */
+declare interface AnnotationLayersEffect {
+    enabled: boolean;
+    count?: number;
+    offsetY?: number;
+}
+
+/** 线样式。 */
+declare interface AnnotationLineStyle {
+    dashed?: boolean;
+    closed?: boolean;
+}
+
 /**
  * 标注管理器 - 管理全景图中的标注点
  * 支持图标、文字、超链接三种类型的标注
@@ -265,6 +467,50 @@ declare class AnnotationManager720 {
     private generateId;
 }
 
+/** 面板屏幕偏移。 */
+declare interface AnnotationPanelOffset2d {
+    x?: number;
+    y?: number;
+}
+
+/** 面板三维偏移。 */
+declare interface AnnotationPanelOffset3d {
+    x?: number;
+    y?: number;
+    z?: number;
+}
+
+/** 光柱效果配置。 */
+declare interface AnnotationPillarEffect {
+    enabled: boolean;
+    height?: number;
+    width?: number;
+}
+
+/** 三维空间点。 */
+declare interface AnnotationPoint3d {
+    x: number;
+    y: number;
+    z: number;
+}
+
+/** 点位样式。 */
+declare interface AnnotationPointStyle {
+    mode?: 'sprite' | 'hybrid';
+    icon?: string;
+    size?: number;
+    iconSize?: number;
+    billboard?: boolean;
+    anchorY?: number;
+}
+
+/** 面样式。 */
+declare interface AnnotationPolygonStyle {
+    showEdge?: boolean;
+    edgeColor?: string;
+    edgeWidth?: number;
+}
+
 /**
  * 标注位置信息（球面坐标）
  */
@@ -274,6 +520,29 @@ declare interface AnnotationPosition {
     radius?: number;
 }
 
+/** 呼吸闪烁效果配置。 */
+declare interface AnnotationPulseEffect {
+    enabled: boolean;
+    speed?: number;
+    minOpacity?: number;
+    maxOpacity?: number;
+}
+
+/** 波纹扩散效果配置。 */
+declare interface AnnotationRippleEffect {
+    enabled: boolean;
+    count?: number;
+    speed?: number;
+    maxRadius?: number;
+}
+
+/** 扫描效果配置。 */
+declare interface AnnotationScanEffect {
+    enabled: boolean;
+    speed?: number;
+    width?: number;
+}
+
 /**
  * 标注类型枚举
  */
@@ -283,6 +552,15 @@ declare enum AnnotationType720 {
     LINK = "link"
 }
 
+/** 体样式。 */
+declare interface AnnotationVolumeStyle {
+    height?: number;
+    showTop?: boolean;
+    showSide?: boolean;
+    showBottom?: boolean;
+    edgeColor?: string;
+}
+
 declare class AreaMeasure2d extends BaseMeasureTool2d {
     /** 三点及以上可以闭合面积，双击或 Enter 结束。 */
     handleClick(point: THREE.Vector3): void;
@@ -692,12 +970,25 @@ declare class Clipping {
     filterIntersectionsByClipping<T extends {
         point?: any;
     }>(intersections: T[] | null | undefined, tolerance?: number): T[];
+    /**
+     * 判断包围盒是否仍与当前可见剖切区域相交。
+     * 只要包围盒被任一剖切平面完全裁掉，就可以在八叉树阶段提前跳过。
+     */
+    doesBoxIntersectClippingRange(box: THREE.Box3 | {
+        min: any;
+        max: any;
+    } | null | undefined, tolerance?: number): boolean;
     getClippedBoundingBox(baseBox?: THREE.Box3): THREE.Box3 | null;
     private getEffectiveClippingPlanes;
     private toBox3;
     private getBoxBoundaryPlanes;
     private intersectThreePlanes;
     private isPointInsidePlanes;
+    /**
+     * 取包围盒在平面法线方向上的最远顶点；
+     * 如果这个点仍落在平面外侧，说明整个包围盒都已经被该平面剔除。
+     */
+    private isBoxVisibleAgainstPlane;
     private pushUniquePoint;
     private isVector3Like;
     /**
@@ -911,6 +1202,7 @@ declare class ControlModule {
     init(): void;
     active(): void;
     disActive(): void;
+    private setEngineControls;
     setMoveSpeed(value: number): void;
     getMoveSpeed(): number;
     setApplyCollision(value: boolean): void;
@@ -2092,7 +2384,11 @@ declare class EngineKernelV2 {
     private animationId;
     private isDisposed;
     private isRenderingPaused;
+    private suppressComposerRenderWhenFree;
+    private pendingComposerRender;
     private controlsEnabledBeforePause;
+    private boundControl;
+    private controlEventHandlers;
     private animate;
     private onWindowResize;
     private _fpsFrameCount;
@@ -2160,6 +2456,7 @@ declare class EngineKernelV2 {
     drawingPin: DrawingPin;
     modelLink3d: ModelLink3d;
     label: Label;
+    annotation3d: Annotation3d;
     calibration: Calibration;
     models: any[];
     reactBoundingClientRect: {
@@ -2170,7 +2467,10 @@ declare class EngineKernelV2 {
     private versionEl;
     private container;
     constructor(options: any);
+    changeHandelBehavedMode(): void;
     updateVersionDisplay(): void;
+    bindControlEvents(control: any): void;
+    requestComposerRender(): void;
     /**
      * 通过 viewToken 解析 3D 模型地址，再复用现有 loaderModule URL 加载逻辑。
      */
@@ -2364,6 +2664,7 @@ declare interface EngineSettings {
 declare class EngineStatus {
     private engine;
     isFree: boolean;
+    editModel: boolean;
     isForceFree: boolean;
     isDisableContextMenu: boolean;
     disableModelInteractionHighlight: boolean;
@@ -3570,7 +3871,7 @@ declare class InteractionModule {
     handelKeyEscDown(): void;
     handleMouseMove(event: any): void;
     handleMouseUp(event: any): void;
-    getCatchMeshs(event: any, retainShow?: boolean): any;
+    getCatchMeshs(event: any, retainShow?: boolean): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>[] | null;
     handleMouseClick(event: any): void;
     handleMouseDoubleClick(event: any): void;
     private clearModelHighlightBeforeCameraFlight;
@@ -3597,6 +3898,8 @@ declare class InteractionModule {
     private keepHighlightedModels;
     private removeModelsFromHighlightState;
     private getNodeWorldBox;
+    private getNodeCatchMeshes;
+    private createInstanceCatchMesh;
     private getInstanceWorldBox;
     private projectBoxToScreenRect;
     private containsRect;
@@ -3784,19 +4087,14 @@ declare interface IssueSnapshotWithUrl extends IssueSnapshot {
     url: string;
 }
 
-/**
- * 3D 标签管理器，负责模型空间坐标拾取、DOM 标签投影和点击事件转发。
- */
 declare class Label {
     private readonly engine;
     private readonly manager;
     private readonly worldToScreen;
     private readonly raycaster;
     constructor(engine: any);
-    /** 开启一次 3D 模型点选，返回命中的世界坐标。 */
     pickPoint(): Promise<LabelCoordinate | null>;
     startPickPoint(callback?: (coordinate: LabelCoordinate | null) => void): Promise<LabelCoordinate | null>;
-    /** 创建 3D 标签，坐标使用模型世界坐标 x/y/z。 */
     createLabel(options: LabelCreateOptions): string;
     updateLabel(id: string, options: LabelUpdateOptions): boolean;
     deleteLabel(id: string): boolean;
@@ -3806,7 +4104,6 @@ declare class Label {
     getLabels(): LabelInstance[];
     onLabelClick(callback: LabelClickCallback): () => void;
     offLabelClick(callback: LabelClickCallback): void;
-    /** 每帧同步标签位置，避免相机旋转后标签滞留。 */
     update(): void;
     dispose(): void;
     private projectCoordinate;
@@ -4096,6 +4393,10 @@ declare interface LevelLocationResult {
     isInside: boolean;
 }
 
+/**
+ * 管理场景基础光照和动态阴影相机范围。
+ * 主要职责是创建环境光、补光、投影灯，并随视图和模型范围更新阴影覆盖区域。
+ */
 declare class LightModule {
     private engine;
     private lastShadowHalfSize;
@@ -4103,24 +4404,133 @@ declare class LightModule {
     private lastShadowFar;
     private lastLightPosition;
     private lastLightTarget;
+    private lastShadowIntensity;
+    private shadowCasterPolicyChecked;
+    private lastShadowCasterPolicySceneSize;
+    /**
+     * 创建光照模块。
+     * @param engine BIM 引擎实例，内部会从中读取 scene、controls、octreeBox 等对象。
+     */
     constructor(engine: any);
-    /** 初始化场景基础光照，并保留投影灯的稳定引用。 */
+    /**
+     * 初始化场景基础光照，并把投影灯引用挂到 scene 上供后续更新使用。
+     */
     init(): void;
-    /** 兼容旧调用名：更新定向光阴影的有效覆盖范围。 */
+    /**
+     * 兼容旧调用名：更新定向光阴影的有效覆盖范围。
+     * @param camera 当前渲染相机；传 null 时只按场景范围或默认值更新。
+     */
     updateShadowCameraRange(camera: THREE.Camera | null): void;
-    /** 根据当前视图和模型范围移动投影灯、target 与阴影相机。 */
+    /**
+     * 根据当前视图和模型范围移动投影灯、target 与阴影相机。
+     * @param camera 当前渲染相机，用于估算屏幕可视范围；传 null 时退回到场景范围。
+     */
     updateDirectionalShadow(camera: THREE.Camera | null): void;
+    /**
+     * 计算场景范围对阴影相机半边长的贡献。
+     * @param sceneHalfExtent 场景包围盒最大边的一半，单位为世界坐标。
+     * @param cameraHalfExtent 当前相机可视范围最大半边长，单位为世界坐标。
+     * @returns 阴影相机应考虑的场景半边长。
+     */
     private getSceneShadowHalfSize;
+    /**
+     * 根据阴影相机范围动态调整 bias，平衡阴影条纹和阴影悬浮。
+     * @param light 负责投影的定向光。
+     * @param shadowHalfSize 阴影正交相机半边长，单位为世界坐标。
+     * @param shadowDepthRange 阴影相机深度范围。
+     */
     private updateShadowBias;
+    /**
+     * 计算阴影相机沿光照方向的 near/far 范围。
+     * @param sceneBox 当前场景包围盒；为 null 时使用兜底范围。
+     * @param lightPosition 投影灯世界坐标。
+     * @param target 投影灯 target 世界坐标。
+     * @param sceneDepth 场景包围盒对角线长度，用于兜底 far 估算。
+     * @param shadowHalfSize 阴影相机半边长，用于兜底 far 估算。
+     * @returns 阴影相机深度范围。
+     */
     private getShadowDepthRange;
+    /**
+     * 获取包围盒 8 个顶点。
+     * @param box 需要拆分顶点的 three.js 包围盒。
+     * @returns 包围盒所有角点的世界坐标数组。
+     */
     private getBoxCorners;
+    /**
+     * 从场景中找到当前负责投影的定向光。
+     * @returns 可投影的 DirectionalLight；找不到时返回 null。
+     */
     private getShadowDirectionalLight;
+    /**
+     * 获取当前场景的有效包围盒。
+     * @returns 有效模型包围盒；场景为空或范围异常时返回 null。
+     */
     private getSceneBoundingBox;
+    /**
+     * 规范化包围盒最小点和最大点，兼容 min/max 顺序被反转的输入。
+     * @param min 原始最小点。
+     * @param max 原始最大点。
+     * @returns 规范化后的包围盒；坐标非法或范围异常时返回 null。
+     */
     private normalizeBox;
+    /**
+     * 校验包围盒是否可用于阴影计算。
+     * @param box 候选包围盒。
+     * @returns 有效包围盒；过小、过大或异常时返回 null。
+     */
     private validateBox;
+    /**
+     * 估算当前相机视图在目标点附近需要覆盖的半边长。
+     * @param camera 当前渲染相机。
+     * @param fallbackTarget 没有 controls.target 时用于估算距离的目标点。
+     * @returns 相机视图最大半边长；没有有效相机时返回 0。
+     */
     private getCameraHalfExtent;
+    /**
+     * 解析阴影应跟随的目标点。
+     * @param camera 当前渲染相机。
+     * @param fallbackTarget 优先级低于 controls.target 的兜底目标点。
+     * @returns 用于定位投影灯 target 的世界坐标。
+     */
     private resolveShadowTarget;
+    /**
+     * 获取投影灯相对 target 的方向。
+     * @returns 标准化后的世界空间光源偏移方向。
+     */
     private getLightOffsetDirection;
+    /**
+     * 根据当前视角和阴影贴图密度计算最终显示强度。
+     * @param camera 当前渲染相机。
+     * @param lightDirection 投影灯相对 target 的方向。
+     * @param shadowHalfSize 阴影正交相机半边长。
+     * @param mapWidth 阴影贴图宽度。
+     * @returns 本帧应使用的阴影强度。
+     */
+    private getShadowDisplayIntensity;
+    /**
+     * 把阴影 target 对齐到阴影贴图 texel 网格。
+     * @param target 原始阴影目标点。
+     * @param lightDirection 投影灯相对 target 的方向。
+     * @param shadowHalfSize 阴影正交相机半边长。
+     * @param mapWidth 阴影贴图宽度。
+     * @returns 对齐后的 target，减少相机远距离移动时的阴影采样抖动和规则纹理。
+     */
+    private snapShadowTargetToTexel;
+    /**
+     * 自动降低大面积薄片构件的投影风险。
+     * @param sceneBox 当前场景包围盒，用于判断场景尺寸是否变化。
+     */
+    private updateShadowCasterPolicy;
+    /**
+     * 对单个 mesh 应用投影策略。
+     * @param mesh 候选投影对象。
+     */
+    private applyShadowCasterPolicy;
+    /**
+     * 对仍参与投影的实体使用背面写入阴影，降低封闭体表面的自投影条纹。
+     * @param material mesh 材质或材质数组。
+     */
+    private setBackSideShadowCasting;
 }
 
 /**
@@ -4192,9 +4602,59 @@ declare interface LoaderModel2d {
 }
 
 declare class LoaderModule {
+    private static localRequestMap;
+    private static localObjectUrls;
+    private static interceptorInstalled;
     private engine;
     constructor(engine: any);
+    /**
+     * 批量加载模型 URL。
+     */
     loadModels(urls: string[], options?: LoadModelOptions): Promise<void>;
+    /**
+     * 直接加载用户在浏览器中选择的本地模型文件。
+     * 支持两种输入：
+     * 1. 直接选择 `info / property / edge / lod0...` 这组模型包文件。
+     * 2. 选择一个外层 zip，zip 内部包含上述模型包文件或解压后的同名目录。
+     */
+    loadModelFile(files: File[], options?: LoadModelOptions): Promise<void>;
+    /**
+     * 把浏览器 File 列表整理成现有加载器可识别的本地虚拟模型入口。
+     */
+    private buildLocalModelEntries;
+    /**
+     * 展开输入文件。
+     * 已经是模型包文件时直接保留；仅把“外层容器 zip”解包成内部条目。
+     */
+    private collectSourceEntries;
+    /**
+     * 识别已经打好的模型包文件，例如 `info`、`lod0.zip`。
+     */
+    private parseDirectPackageEntry;
+    /**
+     * 识别解压后的模型目录，例如 `lod0/nodes.json`、`info/info.json`。
+     */
+    private parseExtractedPackageEntry;
+    /**
+     * 把解压目录重新打包成 zip Blob，复用现有按包加载的实现。
+     */
+    private packEntriesAsZip;
+    /**
+     * 注册 axios 拦截器，把虚拟模型地址改写为对应的 Blob URL。
+     */
+    private static ensureLocalRequestInterceptor;
+    /**
+     * 为某个虚拟请求地址生成 Blob URL 映射。
+     */
+    private static registerLocalRequest;
+    /**
+     * 统一规范虚拟请求 key，兼容传入绝对地址或带 query 的地址。
+     */
+    private static normalizeRequestKey;
+    /**
+     * 生成稳定且不会冲突的本地模型虚拟 ID。
+     */
+    private static createLocalModelId;
 }
 
 declare class LoaderModule2d {