@realsee/dnalogel 3.81.21 → 3.81.23

package/CHANGELOG.md

@@ -1,4 +1,33 @@
+## 3.81.23
+
+- 放大镜新增近景视角、近景旋转取景与双击快速测量。
+- 放大镜按设备像素读回选点，接入全景像素源并使用自适应取景窗口。
+- 改善远点与斜向表面的放大预览，保持原有测量入口及数据格式兼容。
+
+## 3.81.22
+
+- 发布独立空间测量 V2 和全景测量 V2，新增边缘吸附及选点可视化；原入口保持兼容。
+- 修复 V2 Mixed 公开删除后再次保存恢复线段、Shift 切换后立即确认使用旧吸附位置。
+- 保留主干标尺可见性及遮挡修复。
+
 # CHANGELOG
+## 未发布（MeasurePluginV2）
+
+- 全景 V2 的 Edit/Mixed 清空均重置工作上下文；加载数据先结束旧会话，避免待保存线段混入导入结果。
+- 空间 V2 结束测量时释放临时 Shift 状态；固定准心按屏幕中心计算吸附，开关吸附立即刷新选点。
+- V2 默认触摸配置使用固定准心、可添加点的移动控件和小尺寸放大镜；两个 V2 示例提供手机底部操作面板与吸附开关。
+- 修复全景 V2 中心点测量清空后保存恢复旧线段的问题；清空同时丢弃未完成起点，并保持测量工具开启。
+- 修复 Mixed/Watch 模式按住 Shift 无法暂停吸附的问题；松开恢复吸附，失焦或销毁时释放修饰键状态与监听。
+- 修复全景 V2 测量中的动态预览线：保持前景可见，并同步最后一次选点位置。
+- 新增独立 `PanoMeasurePluginV2`，桌面编辑、移动端中心点测量、已有端点拖动复用空间测量 V2 的选点、模型边缘吸附、锁定评分与坐标轴/平面框提示。
+- 原 `PanoMeasurePlugin` 的默认组件、公开接口和 JSON 格式保持不变；V2 继续使用原模型、事件与 load/save/toJson，补充新旧数据互读和模式切换测试。
+- 原版与 V2 全景测量提供两个独立示例；V2 支持撤销、保存和中心点测量验收。
+
+- 新增独立 `MeasurePluginV2`：模型边缘吸附、锁定评分、放大镜坐标轴和平面框、场景光标仅在 V2 生效；原 `MeasurePlugin` 配置及选点行为保持不变。
+- V2 默认开启边缘吸附，可通过 `edgeSnap: false` 或 `setEdgeSnapEnabled(false)` 关闭。
+- 修复约束平面负侧边线被错误接受、候选集合为空时提前丢失锁定边的问题。
+- 虚拟点和无法线点隐藏场景表面提示，返回真实表面后恢复；移除覆盖绿色端点的蓝色 CSS 球。
+- 原版与 V2 使用独立示例入口，并补充原版兼容性和 V2 回归测试。
 
 ## 3.81.21
 

package/dist/MeasurePlugin/Controller.d.ts

@@ -20,6 +20,8 @@ export type MeasurePluginEventMap = {
 export declare class MeasureController extends Subscribe<MeasurePluginEventMap> {
     readonly name = "MeasurePlugin";
     currentMeasureMesh?: MeasureMesh | null;
+    /** 双击快速测量结束后，用命中点继续下一段测量（由当前测量会话提供） */
+    protected continueMeasureFrom?: (end: THREE.Vector3) => void;
     private five;
     private group;
     private currentEndReason;
@@ -35,6 +37,7 @@ export declare class MeasureController extends Subscribe<MeasurePluginEventMap>
     private publishInteraction;
     get pointSelector(): PointSelector;
     private _pointSelector;
+    protected createPointSelector(): PointSelector;
     private get fiveDomEvents();
     private _fiveDomEvents;
     private get cursor();
@@ -49,6 +52,11 @@ export declare class MeasureController extends Subscribe<MeasurePluginEventMap>
      * @description Initialize event listeners for all existing meshes
      */
     initEventListeners: () => void;
+    /**
+     * 取消所有测量结果的选中态。
+     * 组内还并存着预览用的临时对象（点 / 线 / 多边形），它们没有选中态，需要跳过。
+     */
+    private unselectAllMeasureMeshes;
     /**
      * @description 开始测量
      */

package/dist/MeasurePlugin/utils/MeasureMesh.d.ts

@@ -3,6 +3,11 @@ import { IObject3D } from '../../shared-utils/three/IObject3D';
 import { LineWithDotsMesh } from '../../Sculpt/Meshes/LineWithDots';
 import { PolygonMesh, type PolygonStyle } from '../../Sculpt/Meshes/Polygon';
 import type { LineMeshStyle } from '../../Sculpt/typings';
+/**
+ * 判断对象是否为测量结果。
+ * MeasureGroup 内除测量结果外还并存着预览用的临时对象（点 / 线 / 多边形），它们没有选中态等测量接口。
+ */
+export declare function isMeasureMesh(item: unknown): item is MeasureMesh;
 export declare class MeasureMesh extends IObject3D {
     readonly name = "MeasureMesh";
     readonly isMeasureMesh = true;

package/dist/MeasurePluginV2/Controller.d.ts

@@ -0,0 +1,58 @@
+import type { Five } from '@realsee/five';
+import { MeasurePointSelector } from './PointSelector';
+import { MeasureController } from '../MeasurePlugin/Controller';
+import type { MeasurePluginConfig } from '../MeasurePlugin';
+import { MeasureMagnifier } from './Magnifier';
+import { type EdgeSnapOptions } from './edgeSnap';
+/**
+ * 量尺插件 V2：把放大镜和场景里的小光标换成带「红 / 绿 / 蓝坐标轴 + 红色截面框」的版本。
+ *
+ * 复用 MeasureController 的测量流程，通过工厂创建独立的 V2 选点器，并替换两个渲染组件：
+ * - pointSelectorHelper.magnifier → MeasureMagnifier（多画一层叠加层）
+ * - pointSelectorHelper.pointHelper → MeasurePointHelperV2（同样的红 / 绿 / 蓝 + 截面框）
+ *
+ * 两个替换件都沿用原实例的全部参数（宽高、缩放、autoFixPCPosition、dragEnabled、挂载容器），
+ * 所以放大镜出现的位置、跟随方式、是否吃鼠标事件都和原插件一致，不会挡住在原本能选中的点位。
+ */
+/** V2 配置：在原 MeasurePlugin 配置上增加模型边缘吸附 */
+export type MeasurePluginV2Config = MeasurePluginConfig & {
+    /**
+     * @description 模型边缘吸附（试验能力）：落点靠近模型边线时自动吸到边上。
+     * 传 `false` 可关闭；不传默认开启。
+     */
+    edgeSnap?: boolean | EdgeSnapOptions;
+    /**
+     * @description 双击快速测量（仅鼠标）：双击起点时沿所在平面的法线测到对面，例如墙到对面墙。
+     * 传 `false` 可关闭；不传默认开启。
+     */
+    quickMeasure?: boolean;
+};
+export declare class MeasureControllerV2 extends MeasureController {
+    /** 最近一次查询到的候选边数量，示例页 / 调试用 */
+    lastEdgeSnapEdgeCount: number;
+    private v2Five;
+    private v2Magnifier?;
+    private v2Attached;
+    private readonly edgeSnapOptions;
+    private readonly edgeSnapCache;
+    private readonly quickMeasureEnabled;
+    private quickMeasure?;
+    constructor(five: Five, config?: MeasurePluginV2Config);
+    get edgeSnapEnabled(): boolean;
+    /** 运行时开关模型边缘吸附（不需要重开测量） */
+    setEdgeSnapEnabled(enabled: boolean): void;
+    /** V2 的放大镜实例；需要临时关掉叠加层做对比时，可以 magnifier.setOverlayEnabled(false) */
+    get magnifier(): MeasureMagnifier;
+    protected createPointSelector(): MeasurePointSelector;
+    get pointSelector(): MeasurePointSelector;
+    private attachOverlayRenderers;
+    private attachMagnifier;
+    private attachPointHelper;
+    /** 双击快速测量：只在测量过程中生效，选点链路仍由原 MeasureController 负责 */
+    private attachQuickMeasure;
+    /**
+     * 模型边缘吸附：每次选点器计算吸附前，按当前落点取附近的模型边界线。
+     * 真正的吸附判断（3D 距离 / 屏幕距离）仍在 PointSelector 里，这里只负责供线。
+     */
+    private attachEdgeSnap;
+}

package/dist/MeasurePluginV2/Magnifier.d.ts

@@ -0,0 +1,74 @@
+import type { Five } from '@realsee/five';
+import * as THREE from 'three';
+import { Magnifier, type MagnifierParameter, type PointIntersection } from '../shared-utils';
+export { CLOSEUP_DISTANCE } from './closeupView';
+/** 近景取景方式 */
+export type MeasureCloseupMode = 
+/** 只旋转、不平移：与主视图共用机位，无新增视差；默认 */
+'rotate'
+/** 旧行为：把相机推到落点附近 0.6m，再朝法线偏转；放大倍率高，但会产生视差 */
+ | 'push'
+/** 完全沿用主相机，只放大局部像素 */
+ | 'off';
+export interface MeasureMagnifierOptions extends MagnifierParameter {
+    /** 是否绘制坐标轴 / 平面框叠加层，默认 true（关掉后行为与现状 Magnifier 完全一致） */
+    overlayEnabled?: boolean;
+    /** 兼容旧参数：false 等价于 closeupMode='off' */
+    closeupEnabled?: boolean;
+    /** 近景取景方式，默认 'rotate' */
+    closeupMode?: MeasureCloseupMode;
+}
+/**
+ * 量尺 V2 用的放大镜。
+ *
+ * 完全复用 Magnifier 的「读像素 + 放大」逻辑（直接 super.render()），
+ * 只是在其之后往同一个 2D canvas 上叠加坐标轴与落点平面框。
+ */
+export declare class MeasureMagnifier extends Magnifier {
+    /** 父类把 five 存成了 private，这里自己留一份，叠加层投影时要用 */
+    private overlayFive;
+    /** 父类把 context 存成了 private；getContext('2d') 拿到的是同一个实例 */
+    private overlayContext;
+    /** 由 PointSelector 的 intersectionUpdate 事件注入 */
+    private overlayIntersection;
+    private overlayEnabled;
+    private closeupMode;
+    /** 本次渲染实际使用的相机（推近后的副本），叠加层投影必须和它一致 */
+    private overlayCamera;
+    /** 本次放大镜渲染的落点；相机取向以它为准，避免和交点数据错帧 */
+    private renderPoint;
+    /** 近景视角的平滑状态 */
+    private closeupState;
+    constructor(five: Five, options?: MeasureMagnifierOptions);
+    renderWithPoint(point: THREE.Vector3): void;
+    /** 每次交点更新时调用；传 null 表示当前没有命中任何模型 */
+    setIntersection(intersection: PointIntersection | null): void;
+    /** 开关叠加层，用于灰度 / 排查问题 */
+    setOverlayEnabled(enabled: boolean): void;
+    /** 开关近景 3D 视角，用于灰度 / 对比；开启时使用默认的 rotate 模式 */
+    setCloseupEnabled(enabled: boolean): void;
+    /** 切换近景取景方式，用于三种模式的对比 */
+    setCloseupMode(mode: MeasureCloseupMode): void;
+    getCloseupMode(): MeasureCloseupMode;
+    render(): void;
+    private renderOverlay;
+    /**
+     * 近景 3D 视角：读像素前调整相机取向，让视线朝落点所在表面的法线偏一点
+     * （斜向 / 侧向的表面在放大镜里以更接近正面的角度呈现），读完立即还原。
+     *
+     * 两种模式：
+     * - rotate（默认）：只旋转、不平移。与主视图共用同一机位，不产生视差，全景 / 模型都按同一视点采样；
+     * - push（旧行为）：把相机推到落点附近 0.6m，放大倍率更高，但会产生视差和近距透视形变。
+     *
+     * 姿态由主相机绕落点做最小旋转得到：偏转角有上限、画面不翻滚。
+     */
+    private moveCameraCloseup;
+    /** 只记录投影要用的矩阵；Five 的相机 clone() 开销大，也不保证可用 */
+    private snapshotOverlayCamera;
+    private getOverlayContext;
+    /**
+     * 还原 Magnifier.render() 内部的取值，用来把世界坐标映射到放大镜 canvas 坐标。
+     * 这些换算必须和父类保持一致，父类改动时需要同步。
+     */
+    private getOverlayViewport;
+}

package/dist/MeasurePluginV2/PointHelper.d.ts

@@ -0,0 +1,22 @@
+import type { Five } from '@realsee/five';
+import type { Intersection } from '../typings/typings';
+import { PointHelper2 } from '../shared-utils/three/PointSelector/utils/PointHelper2';
+/**
+ * 场景里的小光标（选点处那团白圈 + 法线管）的 V2 版本。
+ *
+ * 完全继承 PointHelper2，只做两件事：
+ * 1. 把那根浅蓝色的法线管换成绿色（PRD 里绿色 = Z 轴）；
+ * 2. 按和放大镜同一套平面坐标系（buildPlaneFrame）补上红色 X、蓝色 Y 和红色截面框。
+ *
+ * 选点算法（射线、吸附、打点）全都在 PointSelector 里，这里只负责画，不参与任何选点判断。
+ */
+export declare class MeasurePointHelperV2 extends PointHelper2 {
+    /** 只放 V2 新增的红 / 蓝轴和截面框，拿不到法线时整体隐藏 */
+    private readonly overlayGroup;
+    constructor(five: Five);
+    updateWithIntersect(intersect: Intersection): void;
+    /** 不挂载 cssBallMesh，避免蓝色小球盖住绿色 Z 轴端点 */
+    show(): void;
+    hide(): void;
+    private paintAxisMesh;
+}

package/dist/MeasurePluginV2/PointOverlay.d.ts

@@ -0,0 +1,93 @@
+import * as THREE from 'three';
+import type { PointIntersection } from '../shared-utils';
+/**
+ * 放大镜内的叠加绘制：坐标轴（PRD M1）+ 落点平面框（PRD M2）
+ *
+ * 为什么画在 2D canvas 上而不是往场景里加 THREE 物体：
+ * 放大镜并不是「再渲染一遍场景」，而是用 five.getPixels() 读一小块像素，翻转后 putImageData 到 2D canvas 上。
+ * 所以场景里加什么物体都不会出现在放大镜里，只有 putImageData 之后在 2D context 上画的才会出现。
+ */
+/** PRD 五、视觉与设计规范 */
+export declare const OVERLAY_STYLE: {
+    /** M1-2 X 轴颜色 */
+    readonly axisXColor: "#EC4A4E";
+    /** M1-2 Y 轴颜色 */
+    readonly axisYColor: "#1677FF";
+    /** M1-2 Z 轴颜色 */
+    readonly axisZColor: "#065C08";
+    /** M1-5 线条宽度 */
+    readonly axisLineWidth: 1.5;
+    /** 轴线不透明度 */
+    readonly axisOpacity: 0.9;
+    /** M1-4 轴线长度 = 放大镜半径 × 0.9 */
+    readonly axisLengthRadiusScale: 0.9;
+    /** Z 轴端点（朝外的一端）绿色圆点半径 = 放大镜半径 × 该系数 */
+    readonly axisTipDotRadiusScale: 0.03;
+    /** M2 平面框边框颜色 */
+    readonly planeBorderColor: "#FF4D4F";
+    /** M2-3 边框宽度 */
+    readonly planeBorderWidth: 1.5;
+    /** M2-3 边框不透明度 */
+    readonly planeBorderOpacity: 0.9;
+    /** M2-2 轴对齐面框边长 = 放大镜半径 × 1.2 */
+    readonly planeSideRadiusScale: 1.2;
+    /** M2 轴对齐判定：表面法线与最近世界轴的夹角小于该值即视为墙 / 地 / 顶 */
+    readonly axisSnapAngle: 15;
+};
+/**
+ * 放大镜把渲染目标上的一块矩形区域拉伸到了 canvas 上，这里描述这块区域以及映射关系。
+ * 字段取值与 Magnifier.render() 内部完全一致，父类改动时需要同步。
+ */
+export interface MagnifierViewport {
+    camera: THREE.Camera;
+    /** 渲染目标尺寸，与 Magnifier.render() 里 getSize() 的结果一致 */
+    renderSize: THREE.Vector2;
+    /** 读取区域左边缘在渲染目标像素坐标系中的横坐标 */
+    readLeft: number;
+    /** 读取区域下边缘的纵坐标（渲染目标像素坐标系 y 轴向上，与 Magnifier.render() 里的同名量一致） */
+    readTop: number;
+    /** 读取区域的高度（渲染目标像素） */
+    readPixelsHeight: number;
+    /** 一个渲染像素在放大镜 canvas 上重复的倍数 */
+    pixelRadio: number;
+    /** 放大镜 canvas 的宽高（设备像素） */
+    canvasWidth: number;
+    canvasHeight: number;
+    /**
+     * 叠加层线宽缩放：canvas 设备像素 / CSS 像素。
+     * 高清读回时 canvas 变大，固定线宽需要同步放大，否则轴线和平面框会变细。
+     */
+    lineScale?: number;
+}
+/**
+ * 求交点的世界坐标系法线。
+ * 点云等拿不到 face 的情况返回 null（此时只画坐标轴，不画平面框）。
+ *
+ * 注意：这里不能再乘模型的法线矩阵。THREE.Mesh.raycast 在生成相交结果时已经把面法线
+ * 用 normalMatrix 变换到世界坐标系了；PointSelector 吸附到平面时合成的 Face3 更是直接写入
+ * 世界坐标系的平面法线。再乘一次会让法线偏离真实表面法线，红色平面框也就不再贴合选点所在面。
+ */
+export declare function getWorldNormal(intersection: PointIntersection): THREE.Vector3 | null;
+export interface PlaneFrame {
+    /** 平面法线，也就是绿色 Z 轴的方向（朝表面外侧） */
+    normal: THREE.Vector3;
+    /** 平面内的水平方向 = 红色 X 轴 */
+    xAxis: THREE.Vector3;
+    /** 平面内最接近竖直的方向 = 蓝色 Y 轴 */
+    yAxis: THREE.Vector3;
+    /** 轴对齐面吸附到的世界轴下标（0=X / 1=Y / 2=Z），斜面为 -1 */
+    alignedAxisIndex: number;
+}
+/**
+ * 由表面法线构造落点所在平面的坐标系。
+ * 绿色 Z 轴 = 法线；蓝色 Y 轴取平面内最接近「世界向上」的方向；红色 X 轴 = 剩下的那条平面内方向。
+ * 平面接近水平（地板 / 天花板）时平面内没有竖直方向，退化为用世界 Z 当蓝色轴。
+ *
+ * 放大镜里的叠加层和场景里的小光标共用这一份坐标系，保证两处看到的红 / 绿 / 蓝完全一致。
+ */
+export declare function buildPlaneFrame(normal: THREE.Vector3): PlaneFrame;
+/**
+ * 绘制落点叠加层。
+ * 调用时机：Magnifier.render() 里 putImageData 之后。
+ */
+export declare function drawMeasureOverlay(context: CanvasRenderingContext2D, viewport: MagnifierViewport, intersection: PointIntersection): void;

package/dist/MeasurePluginV2/PointSelector.d.ts

@@ -0,0 +1,55 @@
+import * as THREE from 'three';
+import { PointSelector, type PointIntersection } from '../shared-utils/three/PointSelector';
+/** V2 snapping only. The original PointSelector keeps its existing algorithm. */
+export declare class MeasurePointSelector extends PointSelector {
+    /**
+     * @description 动态吸附线提供器：每次选点更新、吸附计算前调用，返回本次参与吸附的线段，不会写回 adhereLine。
+     * 适合按光标位置实时从模型提取的边线。返回的线按有限线段处理（clampToLine），
+     * 与 adhereLine 里的无限轴线（如量尺的 XYZ 轴）区分开。
+     */
+    adhereLineProvider: ((params: {
+        intersection: PointIntersection;
+        pointSelector: PointSelector;
+    }) => THREE.Line3[]) | null;
+    /**
+     * @description 动态吸附线的屏幕吸附半径（像素）
+     * 动态线按「光标到线段投影的屏幕距离」取最近的一条，而不是按 3D 距离排序后让远边覆盖近边
+     */
+    dynamicAdhereScreenRadius: number;
+    /**
+     * @description 已吸附后保持吸附的屏幕半径（像素），略大于进入半径，避免在阈值边界来回跳动
+     */
+    dynamicAdhereKeepScreenRadius: number;
+    /**
+     * @description 动态吸附线允许的最大 3D 距离（米），用于排除画面深处或明显不在落点附近的边
+     */
+    dynamicAdhereMaxDistance: number;
+    /**
+     * 上一次吸住的动态线。候选线集合会随查询球心移动而变化，
+     * 把吸住的边单独留住，光标在保持半径内时优先继续用它，避免在相邻边之间来回跳。
+     */
+    private dynamicAdhereLine;
+    protected get mouseNdcPosition(): {
+        x: number;
+        y: number;
+    };
+    refresh(): void;
+    private readonly onFocusLost;
+    enable(): void;
+    disable(): void;
+    clearDynamicAdhereLine(): void;
+    protected updatePointSelectorHelperIntersect: (intersect?: PointIntersection | null) => void;
+    /**
+     * @description 计算一条静态吸附线的吸附结果（3D 距离优先，其次屏幕距离）
+     */
+    private getLineAdhereResult;
+    /**
+     * @description 在动态吸附线（模型边）中选出屏幕上离光标最近的一条。
+     *
+     * 三个要点：
+     * 1. 用射线与线段的最近点求落点，避免透视投影下屏幕比例回推 3D 点造成的偏差；
+     * 2. 光标贴着已吸住的边时直接锁定，不让相邻边参与评分，消除来回跳；
+     * 3. 需要换边时按「屏幕距离 + 深度惩罚」择优，避免吸到屏幕上重叠、但实际更远的边。
+     */
+    private getBestDynamicAdhereResult;
+}

package/dist/MeasurePluginV2/closeupView.d.ts

@@ -0,0 +1,69 @@
+import * as THREE from 'three';
+/**
+ * 放大镜近景视角的取向计算。
+ *
+ * 目标（与 MP 的观感一致）：放大镜不是主视图的简单放大。落点所在表面没有正对相机时，
+ * 视角会朝表面法线偏一点，让斜面 / 侧面在放大镜里以更接近正面的角度呈现；
+ * 同时要保证它始终是「主视图那台相机绕落点转了一点」——不换机位、不翻滚、偏转角有上限。
+ *
+ * 这里只做纯数学，相机怎么临时改、怎么还原由调用方负责。
+ */
+/** 近景相机到落点的距离（米） */
+export declare const CLOSEUP_DISTANCE = 0.6;
+/** 朝表面转正的比例：把「主视线到正对表面」的夹角消掉这么多 */
+export declare const CLOSEUP_NORMAL_BLEND = 0.5;
+/** 近景视角相对主视图的最大偏转角（弧度）。超过就封顶，避免侧视时像换了个机位 */
+export declare const CLOSEUP_MAX_DEVIATION: number;
+/** 判定法线朝向时的滞回区间（点积）：视线接近贴着表面时沿用上一帧朝向，避免来回翻 */
+export declare const CLOSEUP_FLIP_EPSILON = 0.05;
+/** 跨帧状态：目前只用于法线朝向的滞回 */
+export interface CloseupViewState {
+    /** 本帧的视线方向（单位向量） */
+    direction: THREE.Vector3;
+    /** 本帧的落点 */
+    point: THREE.Vector3;
+    /** 本帧法线的朝向：1 = 与传入的法线同向，-1 = 反向，null = 没有法线 */
+    normalSign: 1 | -1 | null;
+}
+export interface CloseupViewOptions {
+    /** 落点（世界坐标） */
+    point: THREE.Vector3;
+    /** 落点所在表面的法线（世界坐标，方向不限）；拿不到时传 null，只推近不偏转 */
+    normal: THREE.Vector3 | null;
+    /** 主相机位置 */
+    cameraPosition: THREE.Vector3;
+    /** 主相机世界四元数；近景姿态由它绕落点做最小旋转得到，因此不会翻滚 */
+    cameraQuaternion: THREE.Quaternion;
+    /** 近景距离，默认 CLOSEUP_DISTANCE；主相机比这更近时保持原距离。translate=false 时忽略 */
+    distance?: number;
+    /**
+     * 是否把相机沿最终视线移动到落点附近。
+     * true = 旧行为（推到 0.6m）；false = 只旋转、不平移，放大镜与主视图共用同一机位，
+     * 不会产生视差，也不会让全景球心偏移导致画面扭曲。
+     */
+    translate?: boolean;
+    /** 朝法线偏转的比例，默认 CLOSEUP_NORMAL_BLEND */
+    blend?: number;
+    /** 最大偏转角（弧度），默认 CLOSEUP_MAX_DEVIATION */
+    maxDeviation?: number;
+    /** 上一帧的状态，只用于法线朝向的滞回；第一帧传 null */
+    previous?: CloseupViewState | null;
+}
+export interface CloseupView {
+    /** 近景相机位置 */
+    position: THREE.Vector3;
+    /** 近景相机视线方向（单位向量） */
+    direction: THREE.Vector3;
+    /** 近景相机世界四元数（视线方向与 direction 一致，roll 由主相机继承） */
+    quaternion: THREE.Quaternion;
+    /** 供下一次调用使用的状态 */
+    state: CloseupViewState;
+}
+/**
+ * 计算近景相机的位姿：
+ * 1. translate=true 时相机落在「落点后方 distance 处、朝向落点」这条线上，落点因此仍在画面正中；
+ *    translate=false 时保持原机位，只改变朝向（放大镜与主视图共用视点，不产生视差）；
+ * 2. 姿态 = 主相机姿态先把视线校正到落点，再朝「正对表面」的方向转一小段（有上限）；
+ * 3. 因为是绕相机的旋转，画面不会翻滚，观感就是「同一台相机微微转了个角度」。
+ */
+export declare function resolveCloseupView(options: CloseupViewOptions): CloseupView | null;

package/dist/MeasurePluginV2/edgeSnap.d.ts

@@ -0,0 +1,53 @@
+import * as THREE from 'three';
+/**
+ * 模型边缘吸附（试验能力）。
+ *
+ * 选点器本身已经支持吸附到 `THREE.Line3`，five 的 Model 也提供了 `getEdgesBySphere()`，
+ * 这里只做两件事：
+ * 1. 把光标附近的模型边界线取出来、按离落点的距离排序并限量；
+ * 2. 缓存查询结果，避免每次 mousemove 都重走一遍 BVH。
+ *
+ * 取出来的线交给 `PointSelector.adhereLineProvider`，由选点器完成真正的吸附。
+ */
+export interface EdgeSnapOptions {
+    /** 是否启用，默认 true */
+    enabled?: boolean;
+    /** 查询球半径（米），只在这个范围内找模型边线，默认 0.3 */
+    radius?: number;
+    /** 面片夹角阈值（度），越小越只保留硬边，默认 30 */
+    threshold?: number;
+    /** 单次最多参与吸附的边数，默认 240 */
+    maxEdges?: number;
+    /** 光标移动超过该距离（米）才重新查询，默认 0.12 */
+    cacheStep?: number;
+}
+export interface ResolvedEdgeSnapOptions extends Required<EdgeSnapOptions> {
+}
+export declare const DEFAULT_EDGE_SNAP_OPTIONS: ResolvedEdgeSnapOptions;
+export declare function resolveEdgeSnapOptions(options?: boolean | EdgeSnapOptions): ResolvedEdgeSnapOptions;
+/** 只依赖 getEdgesBySphere，避免把 dnalogel 绑死在某个 five 版本上 */
+type EdgeSource = {
+    getEdgesBySphere?: (sphere: THREE.Sphere, threshold?: number) => THREE.Line3[];
+};
+/**
+ * 取落点附近的模型边界线，按离落点从近到远排序，最多 maxEdges 条。
+ * five 的 getEdgesBySphere 返回的是世界坐标线段，可以直接交给 PointSelector。
+ *
+ * 注意：getEdgesBySphere 是按「三角形与球相交」筛选的，大三角形的边可能落在球外很远，
+ * 所以这里再按「点到线段」的真实距离过滤一次，避免把远处的边也当成候选。
+ */
+export declare function collectNearbyEdges(model: EdgeSource | null | undefined, point: THREE.Vector3, options: ResolvedEdgeSnapOptions): THREE.Line3[];
+/**
+ * `getEdgesBySphere` 每次都要遍历可见瓦片、合几何、重建邻接关系，开销不低；
+ * 光标在 cacheStep 范围内移动时复用上一次结果，足够贴近“附近有哪些边”的事实。
+ */
+export declare class EdgeSnapCache {
+    private center;
+    private edges;
+    private valid;
+    query(model: EdgeSource | null | undefined, point: THREE.Vector3, options: ResolvedEdgeSnapOptions): THREE.Line3[];
+    clear(): void;
+    /** 最近一次查询到的边数，调试 / 示例页展示用 */
+    get size(): number;
+}
+export {};

package/dist/MeasurePluginV2/index.d.ts

@@ -0,0 +1,28 @@
+import type { Five } from '@realsee/five';
+import { MeasureControllerV2 } from './Controller';
+/**
+ * 量尺插件 V2 —— 点位选择可视化（对应 PRD《量尺点位选择器优化》）
+ *
+ * 与 MeasurePlugin 的关系：V2 是试点 fork，完全继承 MeasurePlugin 的控制器，
+ * 新吸附算法、放大镜叠加层和场景光标仅在 V2 中生效，原插件继续使用原选点器。
+ *
+ * 使用方式（Console / 编辑器等接入方）：
+ * ```ts
+ * import { MeasureV2 } from '@realsee/dnalogel'
+ * const measure = MeasureV2.MeasurePluginV2(five, { unit: 'm' })
+ * ```
+ */
+export { MeasureControllerV2 } from './Controller';
+export type { MeasurePluginV2Config } from './Controller';
+export { MeasureMagnifier } from './Magnifier';
+export type { MeasureMagnifierOptions } from './Magnifier';
+export { drawMeasureOverlay, getWorldNormal, OVERLAY_STYLE } from './PointOverlay';
+export type { MagnifierViewport } from './PointOverlay';
+export { collectNearbyEdges, EdgeSnapCache, DEFAULT_EDGE_SNAP_OPTIONS } from './edgeSnap';
+export type { EdgeSnapOptions, ResolvedEdgeSnapOptions } from './edgeSnap';
+export { validatePolygon } from '../MeasurePlugin';
+export type { MeasureEndReason, MeasurePluginConfig, MeasurePluginEventMap } from '../MeasurePlugin';
+export type MeasureControllerV2Interface = InstanceType<typeof MeasureControllerV2>;
+export type MeasurePluginV2ParamsInterface = ConstructorParameters<typeof MeasureControllerV2>[1];
+export declare const MeasurePluginV2: (five: Five, config?: MeasurePluginV2ParamsInterface) => MeasureControllerV2;
+export default MeasurePluginV2;

package/dist/MeasurePluginV2/normalMeasure.d.ts

@@ -0,0 +1,116 @@
+import * as THREE from 'three';
+/**
+ * 双击快速测量：从落点沿所在平面的法线发一条射线，取第一个打到的模型表面作为终点。
+ * 典型场景是双击墙面直接得到墙到对面墙的垂直距离。
+ */
+/** 射线起点离开表面的距离（米），避免射线一出发就打中落点所在的面 */
+export declare const NORMAL_RAY_START_OFFSET = 0.01;
+/** 终点离起点太近（米）视为无效，例如打中了落点旁边的小凸起 */
+export declare const NORMAL_RAY_MIN_DISTANCE = 0.02;
+/** 射线最远距离（米），超过视为没打到 */
+export declare const NORMAL_RAY_MAX_DISTANCE = 100;
+/** 双击判定：两次抬起的最大间隔（毫秒） */
+export declare const DOUBLE_CLICK_INTERVAL = 350;
+/** 双击判定：两次抬起的最大屏幕距离（像素） */
+export declare const DOUBLE_CLICK_MAX_MOVE = 6;
+export interface RaycastHit {
+    point: THREE.Vector3;
+    distance: number;
+    /** 命中面；THREE.Intersection 的 face.normal 已经是世界坐标系法线 */
+    face?: {
+        normal?: THREE.Vector3 | null;
+    } | null;
+}
+/** 法线快速测量的命中结果 */
+export interface NormalMeasureHit {
+    /** 终点 */
+    point: THREE.Vector3;
+    /** 终点所在表面的世界坐标系法线；拿不到时为 null */
+    normal: THREE.Vector3 | null;
+}
+/** 对模型做射线检测，返回按距离排序的命中结果 */
+export type ModelRaycast = (raycaster: THREE.Raycaster) => RaycastHit[];
+/**
+ * 沿法线求快速测量的命中点。
+ * @param point - 起点（双击的落点）
+ * @param normal - 起点所在平面的法线（世界坐标，朝向表面外侧，即朝向相机这一侧）
+ * @returns 命中点及其表面法线；法线无效或没打到模型时返回 null
+ */
+export declare function findNormalMeasureHit(point: THREE.Vector3, normal: THREE.Vector3, raycast: ModelRaycast): NormalMeasureHit | null;
+/** 只要终点时用这个 */
+export declare function findNormalMeasureEnd(point: THREE.Vector3, normal: THREE.Vector3, raycast: ModelRaycast): THREE.Vector3 | null;
+/**
+ * 识别「第二下点在刚打下的点上」的双击。
+ * 只记录上一次抬起的时间和屏幕位置；时间和位置都足够近才算双击，命中后清空，三连击不会触发两次。
+ */
+export declare class DoubleClickDetector {
+    private readonly interval;
+    private readonly maxMove;
+    private last;
+    constructor(interval?: number, maxMove?: number);
+    /** 每次单击抬起时调用；返回 true 表示与上一次构成双击 */
+    hit(x: number, y: number, time: number): boolean;
+    reset(): void;
+}
+/** 双击时第二下离起点的最大屏幕距离（像素）。起点可能被吸附偏离光标几像素，所以比双击判定宽一些 */
+export declare const START_POINT_HIT_RADIUS = 16;
+interface QuickMeasureCamera {
+    position: THREE.Vector3;
+}
+export interface QuickNormalMeasureOptions {
+    /** 当前相机；朝向判断和屏幕投影都用它 */
+    getCamera: () => THREE.Camera & QuickMeasureCamera;
+    /** five 画布，用来把世界坐标换算成屏幕坐标 */
+    getElement: () => HTMLElement | null | undefined;
+    /** 对模型做射线检测 */
+    raycast: ModelRaycast;
+    /** 正在测量的点；不在测量中返回 null */
+    getMeasuringPoints: () => THREE.Vector3[] | null;
+    /**
+     * 打到对面：用起点和终点生成测量。
+     * 返回 true 表示测量会话继续（控制器以终点作为下一段的起点），此时命中面的法线会留作下一段的起始法线。
+     */
+    finish: (start: THREE.Vector3, end: THREE.Vector3) => boolean | void;
+    /** 没打到：撤掉起点，回到未打点状态 */
+    cancelStart: () => void;
+}
+/** 由 PointSelector 的 wantsSelect 事件驱动，返回 false 表示取消这次选点 */
+type WantsSelectHandler = (intersection?: {
+    point?: THREE.Vector3;
+    face?: {
+        normal?: THREE.Vector3 | null;
+    } | null;
+} | null) => boolean | void;
+/**
+ * 双击快速测量（只处理鼠标，触屏不触发）。
+ *
+ * 规则与 MP 一致：
+ * - 第一下单击照常打下起点 A，不延迟；第二下在双击时间内又点在 A 上，就从 A 沿法线测到对面，直接完成这条测量；
+ * - A 已经打下一段时间后，再双击 A 也会快速测量：落在 A 上的单击不会再打一个重合的点；
+ * - 已经开始连线（两个点及以上）时双击按普通单击处理；法线没打到模型时撤掉 A，不生成测量；
+ * - 快速测量完成后不退出选点：控制器以命中点为新一段的起点（finish 返回 true），继续选择下一个点位。
+ */
+export declare class QuickNormalMeasure {
+    private readonly options;
+    private readonly detector;
+    private lastMouseUp;
+    /** 起点 A 所在平面的法线，在打下 A 的那次选点里记下 */
+    private startNormal;
+    private attached;
+    constructor(options: QuickNormalMeasureOptions);
+    attach(pointSelector: {
+        on: (name: 'wantsSelect', callback: WantsSelectHandler) => unknown;
+    }): void;
+    detach(pointSelector: {
+        off: (name: 'wantsSelect', callback: WantsSelectHandler) => unknown;
+    }): void;
+    reset(): void;
+    private onMouseUp;
+    private onWantsSelect;
+    /** 只认刚刚发生的鼠标抬起，用完即清，避免触屏选点误用上一次鼠标的位置 */
+    private consumeMouseUp;
+    private isOnStartPoint;
+    /** 面法线可能朝向表面内侧；射线要往相机这一侧（空的一侧）发 */
+    private orientTowardCamera;
+}
+export {};