iflow-engine-base 3.10.2 → 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;
@@ -640,6 +918,9 @@ declare class CameraModuleGaussian {
     dispose(): void;
 }
 
+/**
+ * 相机姿态信息
+ */
 declare interface CameraPose {
     theta: number;
     phi: number;
@@ -689,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;
     /**
@@ -908,6 +1202,7 @@ declare class ControlModule {
     init(): void;
     active(): void;
     disActive(): void;
+    private setEngineControls;
     setMoveSpeed(value: number): void;
     getMoveSpeed(): number;
     setApplyCollision(value: boolean): void;
@@ -1412,7 +1707,6 @@ declare interface DWGMetadata {
  */
 declare interface Engine2dOptions {
     containerId: string;
-    interactionMode?: EngineInteractionMode;
     backgroundColor?: number;
     gridEnabled?: boolean;
     axesEnabled?: boolean;
@@ -1437,25 +1731,43 @@ declare interface Engine2dOptions {
     showMouseCoordinates?: boolean;
 }
 
+/**
+ * 720 全景引擎配置选项
+ */
 declare interface Engine720Options {
+    /** 容器 ID */
     containerId: string;
-    interactionMode?: EngineInteractionMode;
+    /** 覆盖 SDK 内置资源根路径，默认使用固定 CDN。 */
     assetBaseUrl?: string;
+    /** 初始视野角度（默认 75） */
     fov?: number;
+    /** 是否启用缩放（默认 true） */
     enableZoom?: boolean;
+    /** 是否启用旋转（默认 true） */
     enableRotate?: boolean;
+    /** 最小 FOV（默认 30，最大缩放） */
     minFov?: number;
+    /** 最大 FOV（默认 90，最小缩放） */
     maxFov?: number;
+    /** 球体半径（默认 500） */
     sphereRadius?: number;
+    /** 旋转速度（默认 0.5） */
     rotateSpeed?: number;
+    /** 缩放速度（默认 1.0） */
     zoomSpeed?: number;
+    /** 是否启用阻尼效果（默认 true） */
     enableDamping?: boolean;
+    /** 阻尼系数（默认 0.05） */
     dampingFactor?: number;
 }
 
+/**
+ * Gaussian 高斯点云引擎配置项。
+ * 结构参考 core720，由 EngineKernel 统一装配各模块。
+ */
 declare interface EngineGaussianOptions {
     containerId: string;
-    interactionMode?: EngineInteractionMode;
+    /** 覆盖 SDK 内置资源根路径，默认使用固定 CDN。 */
     assetBaseUrl?: string;
     cameraUp?: GaussianVector3;
     initialCameraPosition?: GaussianVector3;
@@ -1470,19 +1782,26 @@ declare interface EngineGaussianOptions {
     viewerOptions?: Record<string, any>;
 }
 
+/**
+ * GIS 引擎初始化参数。
+ * 默认 provider 为 cesium，后续可在不破坏公开 API 的前提下扩展其他地图内核。
+ */
 export declare interface EngineGISOptions extends GISContainerOptions {
-    interactionMode?: EngineInteractionMode;
+    /** 覆盖 SDK 内置资源根路径，默认使用固定 CDN。 */
     assetBaseUrl?: string;
     provider?: 'cesium';
     accessToken?: string;
     cesiumBaseUrl?: string;
     imageryUrl?: string;
+    /** Maximum imagery tile level. Higher zooms reuse this level so imagery stays visible, though blurred. */
     imageryMaximumLevel?: number;
     terrainMode?: GISTerrainMode;
     terrain?: GISTerrainOptions;
     initialView?: GISCameraView;
     showCredit?: boolean;
+    /** 是否显示右上角紧凑性能监视器。 */
     showStats?: boolean;
+    /** 性能监视器详细配置，优先级高于 showStats。 */
     performanceMonitor?: boolean | {
         enabled?: boolean;
         updateInterval?: number;
@@ -1510,8 +1829,6 @@ declare class EngineInfo {
     };
 }
 
-export declare type EngineInteractionMode = 'standard' | 'browse';
-
 declare class EngineKernel2d {
     private options;
     private container;
@@ -1552,7 +1869,6 @@ declare class EngineKernel2d {
     renderer: THREE.WebGLRenderer | null;
     dwgData: DWGData | null;
     version: string;
-    private interactionMode;
     constructor(options: Engine2dOptions);
     /**
      * 初始化引擎
@@ -1663,9 +1979,6 @@ declare class EngineKernel2d {
     getZoom(): number;
     /** 刷新右下角版本号展示，便于外部修改 version 后同步 UI。 */
     updateVersionDisplay(): void;
-    setInteractionMode(mode?: EngineInteractionMode): void;
-    getInteractionMode(): EngineInteractionMode;
-    isModelInteractionEnabled(): boolean;
     /**
      * 获取性能统计
      * @returns 性能统计信息
@@ -1742,7 +2055,6 @@ declare class EngineKernel720 {
     worldToScreen: WorldToScreen;
     private isInitialized;
     private readonly version;
-    private interactionMode;
     constructor(options: Engine720Options);
     /**
      * 初始化引擎
@@ -1856,8 +2168,6 @@ declare class EngineKernel720 {
      * 获取版本
      */
     getVersion(): string;
-    setInteractionMode(mode?: EngineInteractionMode): void;
-    getInteractionMode(): EngineInteractionMode;
     /**
      * 销毁引擎
      */
@@ -1882,11 +2192,8 @@ declare class EngineKernelGaussian {
     private isInitialized;
     private readonly options;
     private readonly version;
-    private interactionMode;
     constructor(options: EngineGaussianOptions);
     private initialize;
-    setInteractionMode(mode?: EngineInteractionMode): void;
-    getInteractionMode(): EngineInteractionMode;
     loadModel(url: string, options?: GaussianSceneOptions): Promise<GaussianSceneInfo>;
     /**
      * 通过 viewToken 解析 Gaussian 资源地址，再复用现有 URL 加载逻辑。
@@ -1923,7 +2230,6 @@ export declare class EngineKernelGIS {
     private isInitialized;
     private readonly version;
     private cameraChangedHandler?;
-    private interactionMode;
     constructor(options: EngineGISOptions);
     /**
      * 初始化 GIS 引擎。
@@ -2058,8 +2364,6 @@ export declare class EngineKernelGIS {
      * 获取 GIS 模块版本。
      */
     getVersion(): string;
-    setInteractionMode(mode?: EngineInteractionMode): void;
-    getInteractionMode(): EngineInteractionMode;
     /**
      * 销毁 GIS 引擎。
      */
@@ -2080,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;
@@ -2148,6 +2456,7 @@ declare class EngineKernelV2 {
     drawingPin: DrawingPin;
     modelLink3d: ModelLink3d;
     label: Label;
+    annotation3d: Annotation3d;
     calibration: Calibration;
     models: any[];
     reactBoundingClientRect: {
@@ -2156,13 +2465,12 @@ declare class EngineKernelV2 {
     };
     version: string;
     private versionEl;
-    private interactionMode;
     private container;
     constructor(options: any);
+    changeHandelBehavedMode(): void;
     updateVersionDisplay(): void;
-    setInteractionMode(mode?: EngineInteractionMode): void;
-    getInteractionMode(): EngineInteractionMode;
-    isModelInteractionEnabled(): boolean;
+    bindControlEvents(control: any): void;
+    requestComposerRender(): void;
     /**
      * 通过 viewToken 解析 3D 模型地址，再复用现有 loaderModule URL 加载逻辑。
      */
@@ -2356,9 +2664,9 @@ declare interface EngineSettings {
 declare class EngineStatus {
     private engine;
     isFree: boolean;
+    editModel: boolean;
     isForceFree: boolean;
     isDisableContextMenu: boolean;
-    modelInteractionEnabled: boolean;
     disableModelInteractionHighlight: boolean;
     highlightModels: any[];
     hideModels: any[];
@@ -2967,6 +3275,9 @@ export declare interface GISCalibrationOptions {
     rotationUnit?: 'radians' | 'degrees';
 }
 
+/**
+ * GIS 视角参数，统一使用 WGS84 经纬度。
+ */
 export declare interface GISCameraView {
     longitude: number;
     latitude: number;
@@ -2976,6 +3287,10 @@ export declare interface GISCameraView {
     roll?: number;
 }
 
+/**
+ * GIS 引擎容器配置。
+ * 优先支持 HTMLElement，保留 containerId 以贴近 core720 的调用习惯。
+ */
 declare interface GISContainerOptions {
     container?: HTMLElement;
     containerId?: string;
@@ -2990,6 +3305,9 @@ export declare interface GISElevationCalibrationOptions {
     heightOffset: number;
 }
 
+/**
+ * GIS 事件回调类型。
+ */
 export declare type GISEventCallback<T = unknown> = (data: T) => void;
 
 declare type GISGeographicOffset = {
@@ -3517,6 +3835,9 @@ declare interface IDrawingPinState {
     capturePoint?: IDrawingPinCapturePoint | null;
 }
 
+/**
+ * GIS 事件模块对外契约。
+ */
 export declare interface IGISEventModule {
     on<T = unknown>(event: EventTypeGIS_2 | string, callback: GISEventCallback<T>): void;
     off<T = unknown>(event: EventTypeGIS_2 | string, callback: GISEventCallback<T>): void;
@@ -3541,8 +3862,6 @@ declare class InteractionModule {
     init(): void;
     active(): void;
     disActive(): void;
-    isModelInteractionEnabled(): boolean;
-    shouldSkipRaycast(): boolean;
     dispose(): void;
     handelKeyCtrlUp(): void;
     handelKeyCtrlDown(): void;
@@ -3552,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;
@@ -3579,6 +3898,8 @@ declare class InteractionModule {
     private keepHighlightedModels;
     private removeModelsFromHighlightState;
     private getNodeWorldBox;
+    private getNodeCatchMeshes;
+    private createInstanceCatchMesh;
     private getInstanceWorldBox;
     private projectBoxToScreenRect;
     private containsRect;
@@ -3595,7 +3916,6 @@ declare class InteractionModule2d {
     init(): void;
     active(): void;
     disActive(): void;
-    shouldSkipRaycast(): boolean;
     private oldId;
     handleMouseMove(event: any): void;
     handelKeyEscDown(_event: any): void;
@@ -3609,6 +3929,9 @@ declare class InteractionModule2d {
     dispose(): void;
 }
 
+/**
+ * 交互灵敏度等动态配置
+ */
 declare interface InteractionOptions720 {
     rotateSpeed?: number;
     zoomSpeed?: number;
@@ -3764,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;
@@ -3786,7 +4104,6 @@ declare class Label {
     getLabels(): LabelInstance[];
     onLabelClick(callback: LabelClickCallback): () => void;
     offLabelClick(callback: LabelClickCallback): void;
-    /** 每帧同步标签位置，避免相机旋转后标签滞留。 */
     update(): void;
     dispose(): void;
     private projectCoordinate;