@realsee/dnalogel 3.81.15 → 3.81.16-dev.1

package/CHANGELOG.md

@@ -1,10 +1,11 @@
 # CHANGELOG
+## 3.81.16-dev.1
 
-## 3.81.15
-
-- 测量插件新增 `interactionState` 与 `interactionChange`，通知绘制、长按等待、端点调整和确认／取消状态，供宿主按当前操作更新提示。
-- 提供已完成测量数与当前绘制点数，覆盖选点、撤销、载入、清空和删除后的可用操作。
-- 保持既有手势和数据格式，新增状态转换回归测试。
+- feat(MeasurePluginV2): 新增量尺插件 V2 试点版本，对应 PRD《量尺点位选择器优化》M1 / M2。
+- feat(MeasurePluginV2): 放大镜内叠加落点所在平面的坐标系 —— 绿色 Z 轴 = 平面法线（只画朝外的一半，端点带绿色圆点），红色 X / 蓝色 Y 为平面内两条方向、贯穿落点画整条，轴长固定为放大镜半径 × 0.9。
+- feat(MeasurePluginV2): 绘制落点平面框，法线与最近世界轴夹角小于 15° 时吸附成正四边形，斜面贴合法线；1.5px #FF4D4F、不透明度 90%、只描边不填充。
+- feat(MeasurePluginV2): 与既有 MeasurePlugin 完全独立，通过 `MeasureV2.MeasurePluginV2(five, config)` 接入，不改动原插件的任何行为；`magnifier.setOverlayEnabled(false)` 可关闭叠加层做对比。
+- docs(examples): 新增 MeasurePluginV2 示例页，可在 examples 站点查看放大镜内的坐标轴与平面框效果。
 
 ## 3.81.14
 

package/README.md

@@ -122,13 +122,3 @@ Add the extension to the request.
 - 转动视角：避开测量点，按住画面拖动。
 - 调整测量点：按住测量线一端的圆点不动，等约半秒，再拖到新位置；松开确认。
 - 桌面端按 Esc 取消本次调整。触摸设备沿用长按选点的绘制方式。
-
-
-### 按操作状态更新提示
-
-读取 `measure.interactionState` 初始化 UI，订阅 `measure.on('interactionChange', state => ...)` 后续变化。销毁 UI 前调用订阅返回的取消函数。
-
-- `phase` 为 `idle`、`drawing`、`holding` 或 `editing`，分别表示浏览、绘制、按住端点等待和调整端点。
-- `measurementCount` 为已完成的测量数量；`pointCount` 为正在绘制的点数。
-- 确认或取消调整后回到 `idle`，`result` 分别为 `confirmed` 或 `cancelled`。事件在坐标提交或还原、指针监听清理后发出。
-- 绘制选点、撤销、载入、清空和删除测量都会同步状态，宿主可以据此展示当前可用操作。

package/dist/MeasurePlugin/Controller.d.ts

@@ -5,17 +5,9 @@ import { MeasureMesh } from './utils/MeasureMesh';
 import { Subscribe } from '../shared-utils/Subscribe';
 import type { MeasurePluginConfig } from '.';
 export type MeasureEndReason = 'enter' | 'escape' | 'polygon' | 'mode_change' | 'pano_move' | 'floor_change' | 'points_insufficient' | 'external';
-/** Current actions available to a measurement UI. */
-export type MeasureInteractionState = Readonly<{
-    phase: 'idle' | 'drawing' | 'holding' | 'editing';
-    measurementCount: number;
-    pointCount: number;
-    result?: 'confirmed' | 'cancelled';
-}>;
 export type MeasurePluginEventMap = {
     measureEnd: (reason: MeasureEndReason, points: THREE.Vector3[]) => void;
     undo: () => void;
-    interactionChange: (state: MeasureInteractionState) => void;
 };
 export declare class MeasureController extends Subscribe<MeasurePluginEventMap> {
     readonly name = "MeasurePlugin";
@@ -29,10 +21,6 @@ export declare class MeasureController extends Subscribe<MeasurePluginEventMap>
     private cleanupRepositioningListeners?;
     private endpointPointerElement?;
     private endpointPressHandlers;
-    private interactionPhase;
-    private interactionResult?;
-    get interactionState(): MeasureInteractionState;
-    private publishInteraction;
     get pointSelector(): PointSelector;
     private _pointSelector;
     private get fiveDomEvents();

package/dist/MeasurePlugin/index.d.ts

@@ -12,6 +12,6 @@ export type MeasurePluginConfig = {
      */
     precision?: number;
 };
-export type { MeasureEndReason, MeasurePluginEventMap, MeasureInteractionState } from './Controller';
+export type { MeasureEndReason, MeasurePluginEventMap } from './Controller';
 export { validatePolygon } from './utils/validatePolygon';
 export declare const MeasurePlugin: (five: Five, config?: MeasurePluginConfig) => MeasureController;

package/dist/MeasurePluginV2/Controller.d.ts

@@ -0,0 +1,20 @@
+import type { Five } from '@realsee/five';
+import { PointSelector } from '../shared-utils';
+import { MeasureController } from '../MeasurePlugin/Controller';
+import type { MeasurePluginConfig } from '../MeasurePlugin';
+import { MeasureMagnifier } from './Magnifier';
+/**
+ * 量尺插件 V2：把放大镜换成带「坐标轴 + 落点平面框」的版本。
+ *
+ * 放大镜是在 PointSelector 的 helper 里创建的，所以这里只覆盖 pointSelector 这个 getter，
+ * 其余选点 / 吸附 / 打点 / 撤销 / 重定位逻辑全部沿用 MeasureController，不改动原插件的任何代码。
+ */
+export declare class MeasureControllerV2 extends MeasureController {
+    private v2Five;
+    private v2PointSelector?;
+    private v2Magnifier?;
+    constructor(five: Five, config?: MeasurePluginConfig);
+    /** V2 的放大镜实例；需要临时关掉叠加层做对比时，可以 magnifier.setOverlayEnabled(false) */
+    get magnifier(): MeasureMagnifier;
+    get pointSelector(): PointSelector;
+}

package/dist/MeasurePluginV2/Magnifier.d.ts

@@ -0,0 +1,36 @@
+import type { Five } from '@realsee/five';
+import { Magnifier, type MagnifierParameter, type PointIntersection } from '../shared-utils';
+export interface MeasureMagnifierOptions extends MagnifierParameter {
+    /** 是否绘制坐标轴 / 平面框叠加层，默认 true（关掉后行为与现状 Magnifier 完全一致） */
+    overlayEnabled?: boolean;
+}
+/**
+ * 量尺 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;
+    constructor(five: Five, options?: MeasureMagnifierOptions);
+    /** 每次交点更新时调用；传 null 表示当前没有命中任何模型 */
+    setIntersection(intersection: PointIntersection | null): void;
+    /** 开关叠加层，用于灰度 / 排查问题 */
+    setOverlayEnabled(enabled: boolean): void;
+    render(): void;
+    private renderOverlay;
+    private getOverlayContext;
+    /**
+     * 还原 Magnifier.render() 内部的取值，用来把世界坐标映射到放大镜 canvas 坐标。
+     * 这些换算必须和父类保持一致，父类改动时需要同步。
+     */
+    private getOverlayViewport;
+    /** 父类的 scale 是 private，只能这样读；它是真值来源，避免自己再维护一份副本 */
+    private getMagnifierScale;
+}

package/dist/MeasurePluginV2/PointOverlay.d.ts

@@ -0,0 +1,66 @@
+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;
+}
+/**
+ * 求交点的世界坐标系法线。
+ * 点云等拿不到 face 的情况返回 null（此时只画坐标轴，不画平面框）。
+ */
+export declare function getWorldNormal(intersection: PointIntersection): THREE.Vector3 | null;
+/**
+ * 绘制落点叠加层。
+ * 调用时机：Magnifier.render() 里 putImageData 之后。
+ */
+export declare function drawMeasureOverlay(context: CanvasRenderingContext2D, viewport: MagnifierViewport, intersection: PointIntersection): void;

package/dist/MeasurePluginV2/index.d.ts

@@ -0,0 +1,25 @@
+import type { Five } from '@realsee/five';
+import { MeasureControllerV2 } from './Controller';
+/**
+ * 量尺插件 V2 —— 点位选择可视化（对应 PRD《量尺点位选择器优化》）
+ *
+ * 与 MeasurePlugin 的关系：V2 是试点 fork，完全继承 MeasurePlugin 的控制器，
+ * 只在放大镜里多画「坐标轴（M1）+ 落点平面高亮（M2）」，不改动原插件的任何代码、不影响线上既有行为。
+ *
+ * 使用方式（Console / 编辑器等接入方）：
+ * ```ts
+ * import { MeasureV2 } from '@realsee/dnalogel'
+ * const measure = MeasureV2.MeasurePluginV2(five, { unit: 'm' })
+ * ```
+ */
+export { MeasureControllerV2 } from './Controller';
+export { MeasureMagnifier } from './Magnifier';
+export type { MeasureMagnifierOptions } from './Magnifier';
+export { drawMeasureOverlay, getWorldNormal, OVERLAY_STYLE } from './PointOverlay';
+export type { MagnifierViewport } from './PointOverlay';
+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;