iflow-engine-base 3.4.0 → 3.4.1

package/dist/index.d.ts

@@ -264,18 +264,34 @@ declare enum AnnotationType720 {
     LINK = "link"
 }
 
+declare interface BoundsLike {
+    min: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    max: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+
 declare class CameraModule {
+    private static readonly MIN_VISIBLE_HEIGHT;
+    private static readonly MIN_CAMERA_DISTANCE;
     private engine;
     perspectiveCamera: THREE.PerspectiveCamera;
     orthographicCamera: THREE.OrthographicCamera;
     constructor(engine: any);
-    switchCurrentCamera(): void;
+    private getCameraAspect;
+    private getPerspectiveVisibleHeight;
+    getOrthographicVisibleHeight(camera?: THREE.OrthographicCamera): number;
+    setOrthographicVisibleHeight(visibleHeight: number, camera?: THREE.OrthographicCamera): void;
+    private getViewDirection;
     private updateComposerCamera;
-    /**
-     * 将透视相机调成「效果接近正交」：通过缩小 FOV 减弱透视畸变。
-     * @param fov 垂直视野角（度），默认 60。设为 10~15 可得到近正交效果，越小越接近正交。
-     * @param options.adjustDistance 是否按 FOV 比例调整相机距离以保持取景一致，默认 true（缩小 FOV 时自动拉远）
-     */
+    private applySwitchedCamera;
+    switchCurrentCamera(): void;
     setPerspectiveFov(fov: number, options?: {
         adjustDistance?: boolean;
     }): void;
@@ -284,12 +300,6 @@ declare class CameraModule {
     getCameraType(): CameraType;
     getCameraPose(): ICameraPose;
     restoreCameraPose(pose: ICameraPose): void;
-    /**
-     * 根据视图原点与视线方向设置相机（用于打开剖面视图等）
-     * @param origin 目标点坐标 {x, y, z}
-     * @param direction 视线方向（相机看向的方向）{x, y, z}，会做归一化
-     * @param distance 相机到目标点的距离，不传则根据场景包围盒自动计算
-     */
     setViewFromOriginAndDirection(origin: {
         x: number;
         y: number;
@@ -495,6 +505,7 @@ declare enum CameraType {
 
 declare class Clipping {
     private engine;
+    private readonly clippingTolerance;
     sectionBox: any;
     sectionFace: any;
     clippingStencil: any;
@@ -509,6 +520,12 @@ declare class Clipping {
     recover(): void;
     reverse(): void;
     disActive(): void;
+    isPointInClippingRange(point: any, tolerance?: number): boolean;
+    filterIntersectionsByClipping<T extends {
+        point?: any;
+    }>(intersections: T[] | null | undefined, tolerance?: number): T[];
+    private getEffectiveClippingPlanes;
+    private isVector3Like;
     /**
      * 按视图原点与视线方向设置剖面（用于打开剖面视图）
      * 剖切面过 origin，法向指向相机侧，并生成与场景包围盒同大的剖切面
@@ -1290,6 +1307,7 @@ declare class EngineKernelV2 {
     minMap: MiniMap;
     grid: Grid;
     level: Level;
+    issueReport: IssueReport;
     text: Text_2;
     hdr: Hdr;
     ground: Ground;
@@ -1705,39 +1723,72 @@ declare class Grid {
     private rootGroup;
     private isVisible;
     private axes;
-    /**
-     * 坐标转换：BIM(X,Y,Z) → Three.js 世界坐标
-     * 默认规则：BIM X=水平, Y=水平深度, Z=高度
-     *         → Three.js X=水平, Y=高度, Z=-深度
-     * 可在外部替换此函数以适配不同坐标系。
-     */
     coordinateMapper: (p: GridAxisPoint) => THREE.Vector3;
     constructor(engine: any);
-    /** 传入轴网数据并在场景中构建对象 */
-    setData(data: GridAxisData[]): void;
-    /** 使用内置模拟数据（调试用） */
+    setData(data?: GridAxisData[]): void;
     setMockData(): void;
-    /** 显示轴网 */
     show(): void;
-    /** 隐藏轴网 */
     hide(): void;
-    /** 切换显示/隐藏 */
     toggle(): void;
+    update(): void;
     /**
-     * 每帧更新（在动画循环中调用）
-     * 根据正交相机缩放动态调整圆圈大小，保持屏幕上视觉尺寸恒定（约 30px）
+     * 根据三维点计算所在轴网区间。
+     * 支持传入 url 以限定到指定模型，避免多模型场景下轴网串用。
      */
-    update(): void;
-    /** 销毁，释放 Three.js 资源 */
+    getLocationByPoint(urlOrPoint: string | THREE.Vector3 | {
+        x: number;
+        y: number;
+        z: number;
+    }, point?: THREE.Vector3 | {
+        x: number;
+        y: number;
+        z: number;
+    }): GridPointLocation | null;
     dispose(): void;
     private _initRoot;
     private _clearAxes;
     private _buildAxis;
+    private _makeCircleSprite;
     /**
-     * 创建带文字的圆圈 Sprite
-     * Sprite 默认朝向相机（billboard），depthTest=false 保证始终可见
+     * 优先读取指定 url 对应模型的轴网数据；未指定时退回当前已加载轴网或全部模型轴网。
      */
-    private _makeCircleSprite;
+    private getGridData;
+    /**
+     * 兼容 getLocationByPoint(point) 和 getLocationByPoint(url, point) 两种调用方式。
+     */
+    private resolvePointLookupArgs;
+    /**
+     * 根据 url 查找当前引擎中的目标模型。
+     */
+    private findModelByUrl;
+    /**
+     * 将轴网按平面方向自动归并为两个主轴族。
+     */
+    private buildAxisFamilies;
+    private createProjection;
+    private normalizeDirection;
+    /**
+     * 在单个轴族内优先返回点位所属的最近轴网区间，避免落在线上时出现空描述。
+     */
+    private resolveFamilyLocation;
+    /**
+     * 点压在轴线上时，选取该轴与最近邻轴组成一个可用区间。
+     */
+    private pickAxisPairAroundIndex;
+    /**
+     * 点落在最外侧时，退化为该轴族最接近的一组边界轴，避免整体描述为空。
+     */
+    private pickNearestBoundaryPair;
+    /**
+     * 优先将字母轴放在前、数字轴放在后，便于输出 A-B交1-2 这种习惯格式。
+     */
+    private sortFamiliesForDisplay;
+    private getFamilySampleLabel;
+    private formatAxisPair;
+    private formatGridDescription;
+    private compareLabels;
+    private isNumericLabel;
+    private toVector3;
 }
 
 declare interface GridAxisData {
@@ -1752,6 +1803,28 @@ declare interface GridAxisPoint {
     Z: number;
 }
 
+declare interface GridFamilyLocation {
+    familyIndex: number;
+    description: string;
+    startAxisName: string | null;
+    endAxisName: string | null;
+    axisName: string | null;
+    pointOffset: number;
+    isOnAxis: boolean;
+    isInside: boolean;
+}
+
+declare interface GridPointLocation {
+    point: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    description: string;
+    families: GridFamilyLocation[];
+    isInside: boolean;
+}
+
 declare class Ground {
     private engine;
     private currentId;
@@ -1947,6 +2020,7 @@ declare interface ICameraPose {
         z: number;
     };
     zoom?: number;
+    orthographicHeight?: number;
 }
 
 /**
@@ -2037,6 +2111,105 @@ declare interface IRoamingPoint extends ICameraPose {
     stayTime?: number;
 }
 
+declare interface IssueCameraPose {
+    position: IssuePoint;
+    forwardDirection: IssuePoint;
+    upDirection: IssuePoint;
+}
+
+declare interface IssueContext {
+    url?: string;
+    point: IssuePoint;
+    grid: GridPointLocation | null;
+    level: LevelLocationResult | null;
+}
+
+declare interface IssuePoint {
+    x: number;
+    y: number;
+    z: number;
+}
+
+declare class IssueReport {
+    private readonly engine;
+    constructor(engine: any);
+    /**
+     * 根据构件信息提取中心点，并组装问题上报所需的数据。
+     */
+    getMoldePosition(model: any): {
+        Floor: string;
+        Axis: string;
+        ElementId: any;
+        ElementName: string;
+        modelJson: {
+            Url: any;
+            ids: any[];
+            camera: IssueCameraPose;
+            cameraRestorePose: ICameraPose;
+        };
+    } | null;
+    /**
+     * 统一归一化问题点坐标，便于上层直接持久化。
+     */
+    getPoint(point: THREE.Vector3 | IssuePoint): IssuePoint;
+    /**
+     * 语义化别名: 获取模型中的问题点位置。
+     */
+    getModelPosition(point: THREE.Vector3 | IssuePoint): IssuePoint;
+    /**
+     * 汇总问题点所在的轴网和标高上下文。
+     * 支持传入 url 以限定到指定模型，避免多模型场景下查询不准确。
+     */
+    getPointContext(urlOrPoint: string | THREE.Vector3 | IssuePoint, point?: THREE.Vector3 | IssuePoint): IssueContext;
+    /**
+     * 获取问题上报需要的简化相机参数。
+     * 只返回相机位置、朝向和顶部方向。
+     */
+    getCameraPose(): IssueCameraPose;
+    /**
+     * 语义化别名: 获取当前相机参数。
+     */
+    getCameraParams(): IssueCameraPose;
+    /**
+     * 获取完整相机姿态，专门用于视角恢复。
+     */
+    getCameraRestorePose(): ICameraPose;
+    /**
+     * 恢复相机到指定完整姿态。
+     */
+    restoreCameraPose(pose: ICameraPose): void;
+    /**
+     * 一次性抓取问题点上下文、简化相机参数和恢复用姿态。
+     */
+    capture(point: THREE.Vector3 | IssuePoint): IssueSnapshot;
+    /**
+     * 直接传入模型 url 和问题点，返回可用于问题上报的完整快照。
+     */
+    captureByUrlAndPoint(url: string, point: THREE.Vector3 | IssuePoint): IssueSnapshotWithUrl;
+    /**
+     * 按指定模型 url 抓取问题点上下文、简化相机参数和恢复用姿态。
+     */
+    captureWithUrl(url: string, point: THREE.Vector3 | IssuePoint): IssueSnapshot;
+    /**
+     * 支持直接传完整快照或单独完整姿态进行恢复。
+     */
+    restore(snapshotOrPose: IssueSnapshot | ICameraPose): void;
+    dispose(): void;
+    /**
+     * 兼容 getPointContext(point) 和 getPointContext(url, point) 两种调用方式。
+     */
+    private resolvePointLookupArgs;
+}
+
+declare interface IssueSnapshot extends IssueContext {
+    cameraPose: IssueCameraPose;
+    cameraRestorePose: ICameraPose;
+}
+
+declare interface IssueSnapshotWithUrl extends IssueSnapshot {
+    url: string;
+}
+
 declare class LayerManager {
     private engine;
     private layerMap;
@@ -2070,26 +2243,52 @@ declare class Level {
     private readonly COLOR;
     private readonly PLANE_OPACITY;
     constructor(engine: any);
-    private _initSvg;
-    /** 传入标高数据并渲染 */
-    setData(data: LevelData[], box: any): void;
-    /** 使用内置模拟数据（调试用） */
+    setData(data?: LevelData[], box?: BoundsLike): void;
     setMockData(): void;
-    /** 显示标高 */
     show(): void;
-    /** 隐藏标高 */
     hide(): void;
-    /** 切换显示/隐藏 */
     toggle(): void;
-    /** 每帧刷新（需在动画循环中调用） */
     update(): void;
-    /** 销毁，释放资源 */
+    /**
+     * 根据点位高度计算所属标高，描述统一输出为“标高X”。
+     * 支持传入 url 以限定到指定模型，避免多模型场景下标高串用。
+     */
+    getLocationByPoint(urlOrPoint: string | THREE.Vector3 | {
+        x: number;
+        y: number;
+        z: number;
+    }, point?: THREE.Vector3 | {
+        x: number;
+        y: number;
+        z: number;
+    }): LevelLocationResult | null;
     dispose(): void;
+    private _initSvg;
     private _initWorldToScreen;
     private _clearAll;
     private _buildThreeObject;
     private _updateSvgLabels;
     private _makeLabel;
+    /**
+     * 优先读取指定 url 对应模型的标高数据；未指定时退回当前已加载标高或全部模型标高。
+     */
+    private getLevelData;
+    /**
+     * 兼容 getLocationByPoint(point) 和 getLocationByPoint(url, point) 两种调用方式。
+     */
+    private resolvePointLookupArgs;
+    /**
+     * 根据 url 查找当前引擎中的目标模型。
+     */
+    private findModelByUrl;
+    /**
+     * 点位位于两个标高之间时，归属到距离最近的那个标高。
+     */
+    private pickNearestLevel;
+    /**
+     * 合并全部模型包围盒，作为标高辅助面的默认可视范围。
+     */
+    private getMergedBoundingBox;
 }
 
 declare interface LevelData {
@@ -2098,6 +2297,16 @@ declare interface LevelData {
     Elevation: number;
 }
 
+declare interface LevelLocationResult {
+    pointY: number;
+    description: string;
+    currentLevel: LevelData | null;
+    lowerLevel: LevelData | null;
+    upperLevel: LevelData | null;
+    isOnLevel: boolean;
+    isInside: boolean;
+}
+
 declare class LightModule {
     private engine;
     constructor(engine: any);

package/package.json

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