copper3d 3.5.0 → 3.6.0

package/dist/index.d.ts

@@ -17,6 +17,8 @@ import { GaussianSmoother } from "./Utils/segmentation/core/GaussianSmoother";
 import { Copper3dTrackballControls } from "./Controls/Copper3dTrackballControls";
 import { MeshNodeTool } from "./Utils/MeshNodeTool";
 import { removeGuiFolderChilden } from "./Utils/segmentation/coreTools/gui";
+import { SurfaceAnnotator } from "./Utils/surfaceAnnotation";
+import type { SurfaceAnnotatorOptions, Annotation, AnnotationMode, ExportOptions } from "./Utils/surfaceAnnotation";
 import { nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, exportPaintImageType, IOptVTKLoader, aligned4DSurfaceType, aligned4DOptsType, Aligned4DController } from "./types/types";
 import { IPaintImage, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates, IGuiMeta } from "./Utils/segmentation/core/types";
 import { NrrdState } from "./Utils/segmentation/coreTools/NrrdState";
@@ -26,6 +28,6 @@ import { CHANNEL_COLORS, CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_
 import type { LayerId, ChannelValue } from "./Utils/segmentation/core/index";
 import type { AiPromptTool, AiPromptPoint, AiPromptPayload, AiMaskResult } from "./Utils/segmentation/tools/AiAssistTool";
 import "./css/style.css";
-export declare const REVISION = "v3.5.0-beta";
-export { copperRenderer, copperRendererOnDemond, copperMSceneRenderer, setHDRFilePath, addLabelToScene, convert3DPostoScreenPos, convertScreenPosto3DPos, addBoxHelper, fullScreenListenner, configKiwriousHeart, copperScene, copperSceneOnDemond, copperMScene, CameraViewPoint, kiwrious, NrrdTools, loading, Copper3dTrackballControls, createTexture2D_NRRD, MeshNodeTool, throttle, removeGuiFolderChilden, CHANNEL_COLORS, CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, GaussianSmoother, };
-export type { positionType, screenPosType, optsType, nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, IPaintImage, exportPaintImageType, IOptVTKLoader, aligned4DSurfaceType, aligned4DOptsType, Aligned4DController, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates, NrrdState, GuiState, IGuiMeta, ToolMode, IAnnotationCallbacks, LayerId, ChannelValue, AiPromptTool, AiPromptPoint, AiPromptPayload, AiMaskResult, };
+export declare const REVISION = "v3.6.0-beta";
+export { copperRenderer, copperRendererOnDemond, copperMSceneRenderer, setHDRFilePath, addLabelToScene, convert3DPostoScreenPos, convertScreenPosto3DPos, addBoxHelper, fullScreenListenner, configKiwriousHeart, copperScene, copperSceneOnDemond, copperMScene, CameraViewPoint, kiwrious, NrrdTools, loading, Copper3dTrackballControls, createTexture2D_NRRD, MeshNodeTool, throttle, removeGuiFolderChilden, CHANNEL_COLORS, CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, GaussianSmoother, SurfaceAnnotator, };
+export type { positionType, screenPosType, optsType, nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, IPaintImage, exportPaintImageType, IOptVTKLoader, aligned4DSurfaceType, aligned4DOptsType, Aligned4DController, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates, NrrdState, GuiState, IGuiMeta, ToolMode, IAnnotationCallbacks, LayerId, ChannelValue, AiPromptTool, AiPromptPoint, AiPromptPayload, AiMaskResult, SurfaceAnnotatorOptions, Annotation, AnnotationMode, ExportOptions, };

package/dist/index.js

@@ -19,9 +19,10 @@ import { GaussianSmoother } from "./Utils/segmentation/core/GaussianSmoother";
 import { Copper3dTrackballControls } from "./Controls/Copper3dTrackballControls";
 import { MeshNodeTool } from "./Utils/MeshNodeTool";
 import { removeGuiFolderChilden } from "./Utils/segmentation/coreTools/gui";
+import { SurfaceAnnotator } from "./Utils/surfaceAnnotation";
 import { CHANNEL_COLORS, CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss } from "./Utils/segmentation/core/index";
 import "./css/style.css";
-export const REVISION = "v3.5.0-beta";
+export const REVISION = "v3.6.0-beta";
 console.log(`%cCopper3D Visualisation %cBeta:${REVISION}`, "padding: 3px;color:white; background:#023047", "padding: 3px;color:white; background:#f50a25");
-export { copperRenderer, copperRendererOnDemond, copperMSceneRenderer, setHDRFilePath, addLabelToScene, convert3DPostoScreenPos, convertScreenPosto3DPos, addBoxHelper, fullScreenListenner, configKiwriousHeart, copperScene, copperSceneOnDemond, copperMScene, CameraViewPoint, kiwrious, NrrdTools, loading, Copper3dTrackballControls, createTexture2D_NRRD, MeshNodeTool, throttle, removeGuiFolderChilden, CHANNEL_COLORS, CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, GaussianSmoother, };
+export { copperRenderer, copperRendererOnDemond, copperMSceneRenderer, setHDRFilePath, addLabelToScene, convert3DPostoScreenPos, convertScreenPosto3DPos, addBoxHelper, fullScreenListenner, configKiwriousHeart, copperScene, copperSceneOnDemond, copperMScene, CameraViewPoint, kiwrious, NrrdTools, loading, Copper3dTrackballControls, createTexture2D_NRRD, MeshNodeTool, throttle, removeGuiFolderChilden, CHANNEL_COLORS, CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, GaussianSmoother, SurfaceAnnotator, };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EACL,eAAe,EAGf,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAY,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,QAAQ,MAAM,iCAAiC,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AAC9E,iDAAiD;AAEjD,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAoB5E,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAS1J,OAAO,iBAAiB,CAAC;AAEzB,MAAM,CAAC,MAAM,QAAQ,GAAG,aAAa,CAAC;AAEtC,OAAO,CAAC,GAAG,CACT,mCAAmC,QAAQ,EAAE,EAC7C,8CAA8C,EAC9C,8CAA8C,CAC/C,CAAC;AAEF,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,SAAS,EACT,OAAO,EACP,yBAAyB,EACzB,oBAAoB,EACpB,YAAY,EACZ,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,SAAS,EACT,SAAS,EACT,gBAAgB,GACjB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EACL,eAAe,EAGf,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAY,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,QAAQ,MAAM,iCAAiC,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AAC9E,iDAAiD;AAEjD,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAE5E,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AA0B7D,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAS1J,OAAO,iBAAiB,CAAC;AAEzB,MAAM,CAAC,MAAM,QAAQ,GAAG,aAAa,CAAC;AAEtC,OAAO,CAAC,GAAG,CACT,mCAAmC,QAAQ,EAAE,EAC7C,8CAA8C,EAC9C,8CAA8C,CAC/C,CAAC;AAEF,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,SAAS,EACT,OAAO,EACP,yBAAyB,EACzB,oBAAoB,EACpB,YAAY,EACZ,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,gBAAgB,GACjB,CAAC"}

package/dist/types/Scene/copperScene.d.ts

@@ -6,6 +6,8 @@ import { baseScene } from "./baseScene";
 import { vtkModels } from "../types/types";
 import { TrackballControls } from "three/examples/jsm/controls/TrackballControls";
 import { ICopperSceneOpts, aligned4DOptsType, Aligned4DController } from "../types/types";
+import { SurfaceAnnotator } from "../Utils/surfaceAnnotation";
+import type { SurfaceAnnotatorOptions } from "../Utils/surfaceAnnotation";
 export declare class copperScene extends baseScene {
     clock: THREE.Clock;
     controls: Copper3dTrackballControls | OrbitControls | TrackballControls;
@@ -13,6 +15,7 @@ export declare class copperScene extends baseScene {
     private playRate;
     private modelReady;
     private clipAction;
+    private surfaceAnnotators;
     constructor(container: HTMLDivElement, renderer: THREE.WebGLRenderer, opt?: ICopperSceneOpts);
     loadGltf(url: string, callback?: (content: THREE.Group) => void): void;
     loadPureGLB(url: string, callback?: (mesh: THREE.Group) => void, opts?: {
@@ -20,6 +23,15 @@ export declare class copperScene extends baseScene {
         enhanceMaterial?: boolean;
     }): void;
     loadVtk(url: string): void;
+    /**
+     * 在给定模型表面创建标注器(画 contour / 放点 / 导出坐标)。
+     * target 可为单个 Mesh,或 Group/Object3D(自动选顶点数最多的 mesh)。
+     * 复用本 scene 的 camera / container / controls;几何非索引时内部自动焊接索引化。
+     */
+    createSurfaceAnnotator(target: THREE.Mesh | THREE.Object3D, opts?: Omit<SurfaceAnnotatorOptions, "scene" | "camera" | "container" | "controls" | "mesh">): SurfaceAnnotator;
+    private pickAnnotatableMesh;
+    /** 释放本 scene 创建的所有标注器(移除事件监听与标注对象)。 */
+    disposeSurfaceAnnotators(): void;
     loadVtks(models: Array<vtkModels>): void;
     /**
      * Load an aligned 4D scene: a cine MRI (one slice, N cardiac phases) rendered as a

package/dist/types/Utils/surfaceAnnotation/MeshGraph.d.ts

@@ -0,0 +1,40 @@
+import * as THREE from "three";
+/**
+ * 从 BufferGeometry 的索引构建顶点邻接图,用于模式 B(测地线)的最短路径。
+ * 顶点坐标按 local 存;传入的查询点需先转为 local(mesh.worldToLocal)。
+ *
+ * 说明:几何须为已索引(indexed)。modelLoader 用 mergeVertices 焊接重复顶点,
+ * 保证同一表面位置共享顶点,邻接图才连通。
+ *
+ * 性能:O(V²) Dijkstra + O(V) 最近顶点查找。对几万顶点单次点击可接受;
+ * 若过大可后续换二叉堆 + 空间网格加速(留作升级)。
+ */
+export declare class MeshGraph {
+    private positions;
+    private normals;
+    private adj;
+    readonly vertexCount: number;
+    constructor(geometry: THREE.BufferGeometry);
+    private px;
+    private py;
+    private pz;
+    /** 最近顶点(传入 local 坐标)。 */
+    nearestVertex(localPoint: THREE.Vector3): number;
+    /**
+     * 两顶点间最短路径(含端点的顶点索引序列)。二叉堆 Dijkstra,O(E log V)。
+     * 不连通时返回 [start,end] 兜底。
+     */
+    shortestPath(startV: number, endV: number): number[];
+    vertexWorld(i: number, matrixWorld: THREE.Matrix4): THREE.Vector3;
+    vertexNormalWorld(i: number, mesh: THREE.Mesh): THREE.Vector3;
+    /** 顶点的 local 坐标 + local 法线(图几何即 local 空间)。 */
+    vertexLocal(i: number): {
+        x: number;
+        y: number;
+        z: number;
+        nx: number;
+        ny: number;
+        nz: number;
+        faceIndex: number;
+    };
+}

package/dist/types/Utils/surfaceAnnotation/SurfaceAnnotator.d.ts

@@ -0,0 +1,103 @@
+import * as THREE from "three";
+import type { Annotation, AnnotationMode, ExportOptions } from "./types";
+import { AnnotationStore } from "./annotationStore";
+export interface SurfaceAnnotatorOptions {
+    scene: THREE.Scene;
+    camera: THREE.PerspectiveCamera;
+    container: HTMLElement;
+    controls: {
+        enabled: boolean;
+    };
+    mesh: THREE.Mesh;
+    /** 缺省时从 mesh 几何包围盒对角线自算。 */
+    bboxDiagonal?: number;
+    /** 自由手绘 contour 颜色,默认 #e5006e。 */
+    freehandColor?: string;
+    /** 测地线 contour 颜色,默认 #ffa24e。 */
+    geodesicColor?: string;
+    /** 放点标记颜色,默认 #ffd166。 */
+    pointColor?: string;
+    /** 线宽(像素),默认 3。 */
+    lineWidth?: number;
+    /** 标记小球半径,默认 bboxDiagonal*0.006。 */
+    markerRadius?: number;
+    onModeChange?: (m: AnnotationMode) => void;
+    /** 标注列表变化回调(增删/撤销/清空)。 */
+    onChange?: (annotations: Annotation[]) => void;
+}
+/**
+ * 表面标注主控制器(Phase 4):navigate / freehand / geodesic / point 四模式,
+ * Enter 闭合,数据交给 AnnotationStore 管理(多条带颜色标签、撤销/删除/清空、导出)。
+ * 渲染层据 store.list() 做场景对账(reconcile),撤销/删除自动加/移 three 对象。
+ */
+export declare class SurfaceAnnotator {
+    private o;
+    private mode;
+    private spaceHeld;
+    private pointerDown;
+    private readonly markerRadius;
+    private readonly epsilon;
+    private readonly minGap;
+    private graph;
+    private store;
+    private managed;
+    private seq;
+    private selectedId;
+    private activeStroke?;
+    private activeLine?;
+    private lastFreehand?;
+    private activeGeo?;
+    private activeGeoLine?;
+    constructor(opts: SurfaceAnnotatorOptions);
+    /** 窗口尺寸变化时更新所有 fat line 的像素分辨率,否则线宽会失真。 */
+    private onResize;
+    private get freehandColor();
+    private get geodesicColor();
+    private get pointColorVal();
+    getMode(): AnnotationMode;
+    setMode(m: AnnotationMode): void;
+    getStore(): AnnotationStore;
+    /** 当前标注列表快照。 */
+    getAnnotations(): Annotation[];
+    undo(): void;
+    clearAll(): void;
+    deleteAnnotation(id: string): void;
+    selectAnnotation(id: string | null): void;
+    /** 颜色变更后重画对应 three 对象。 */
+    refreshAnnotation(id: string): void;
+    exportJSON(modelName: string, opts?: ExportOptions): {
+        model: string;
+        exportedAt: string;
+        space: "local" | "world";
+        annotations: {
+            id: string;
+            type: "contour" | "points";
+            mode: "freehand" | "geodesic" | null;
+            label: string;
+            color: string;
+            closed: boolean;
+            points: number[][];
+        }[];
+    };
+    private applyCameraGating;
+    /** 据 store.list() 对账场景:补齐缺失对象、移除已删对象(不 dispose,留给撤销恢复)。 */
+    private reconcile;
+    private applySelection;
+    private disposeObject;
+    private nextId;
+    private hit;
+    /** 事件目标是否落在标注容器内(排除面板/页面其它区域的点击)。 */
+    private insideContainer;
+    private onPointerDown;
+    private onPointerMove;
+    private onPointerUp;
+    private closeLastContour;
+    /** 沿网格表面求 a→b 的测地路径(local 顶点),去掉与 a 重合的首点。a/b 已是 local。 */
+    private surfacePathBetween;
+    /** 结束当前测地线:闭合成环并落定为一条 contour。 */
+    private finishGeodesic;
+    private isTypingTarget;
+    private onKeyDown;
+    private onKeyUp;
+    dispose(): void;
+}

package/dist/types/Utils/surfaceAnnotation/annotationStore.d.ts

@@ -0,0 +1,37 @@
+import * as THREE from "three";
+import type { Annotation, ExportOptions } from "./types";
+/**
+ * 标注数据模型 + 撤销栈 + 导出。纯数据,无 three / DOM 依赖。
+ * 撤销只记录 add / remove 两类原子操作(满足"撤销最近添加 / 恢复删除")。
+ * 通过 subscribe 通知 UI 与渲染层(后者据 list() 做场景对账)。
+ */
+export declare class AnnotationStore {
+    private items;
+    private undoStack;
+    private subs;
+    private notify;
+    subscribe(cb: () => void): () => void;
+    add(a: Annotation): void;
+    remove(id: string): Annotation | undefined;
+    undo(): void;
+    /** 清空,返回被清掉的项(供渲染层 dispose three 对象)。 */
+    clear(): Annotation[];
+    list(): Annotation[];
+    get(id: string): Annotation | undefined;
+    setLabel(id: string, label: string): void;
+    setColor(id: string, color: string): void;
+    toJSON(modelName: string, mesh: THREE.Mesh, opts?: ExportOptions): {
+        model: string;
+        exportedAt: string;
+        space: "local" | "world";
+        annotations: {
+            id: string;
+            type: "contour" | "points";
+            mode: "freehand" | "geodesic" | null;
+            label: string;
+            color: string;
+            closed: boolean;
+            points: number[][];
+        }[];
+    };
+}

package/dist/types/Utils/surfaceAnnotation/contourRender.d.ts

@@ -0,0 +1,7 @@
+import * as THREE from "three";
+import { Line2 } from "three/examples/jsm/lines/Line2";
+import type { AnnotationVertex } from "./types";
+export declare function makeContourLine(verts: AnnotationVertex[], color: string, closed: boolean, container: HTMLElement, epsilon: number, mesh: THREE.Mesh): Line2;
+export declare function updateContourLine(line: Line2, verts: AnnotationVertex[], closed: boolean, epsilon: number, mesh: THREE.Mesh): void;
+/** 改变已有 contour 线的颜色。 */
+export declare function setContourColor(line: Line2, color: string): void;

package/dist/types/Utils/surfaceAnnotation/geodesicContour.d.ts

@@ -0,0 +1,19 @@
+import * as THREE from "three";
+import type { AnnotationVertex } from "./types";
+import { MeshGraph } from "./MeshGraph";
+/**
+ * 模式 B(测地线)状态机:逐次点击锚点,相邻锚点之间用 MeshGraph 求最短路径,
+ * 拼成一条贴合表面的折线。Enter 结束并可闭合(首尾再求一段)。
+ */
+export declare class GeodesicContour {
+    private graph;
+    private mesh;
+    private anchors;
+    private segments;
+    constructor(graph: MeshGraph, mesh: THREE.Mesh);
+    /** 传入 local 命中点,snap 到最近顶点并对上一锚点求路径。 */
+    addAnchor(localHitPoint: THREE.Vector3): void;
+    get anchorCount(): number;
+    /** 把所有路径顶点(world)+ 法线 拼成折线;closed 时补一段首尾路径。 */
+    buildVertices(closed: boolean): AnnotationVertex[];
+}

package/dist/types/Utils/surfaceAnnotation/index.d.ts

@@ -0,0 +1,3 @@
+export { SurfaceAnnotator } from "./SurfaceAnnotator";
+export type { SurfaceAnnotatorOptions } from "./SurfaceAnnotator";
+export type { Annotation, AnnotationMode, AnnotationVertex, SurfaceHit, ExportOptions, } from "./types";

package/dist/types/Utils/surfaceAnnotation/pointMarkers.d.ts

@@ -0,0 +1,7 @@
+import * as THREE from "three";
+import type { AnnotationVertex } from "./types";
+/**
+ * 在 local 顶点处生成一个标记小球(fiducial)。local→world 后沿 world 法线略外移,
+ * 避免一半埋进表面。radius 由调用方按模型 bbox 缩放传入。
+ */
+export declare function makePointMarker(v: AnnotationVertex, mesh: THREE.Mesh, color: string, radius: number): THREE.Mesh;

package/dist/types/Utils/surfaceAnnotation/raycastSurface.d.ts

@@ -0,0 +1,7 @@
+import * as THREE from "three";
+import type { SurfaceHit } from "./types";
+/**
+ * 把屏幕坐标(clientX/Y)投射到 mesh 表面,返回命中点、world-space 法线与 faceIndex。
+ * 未命中返回 null。本地实现,不依赖 Copper3D 未导出的 raycast 内部函数。
+ */
+export declare function raycastSurface(camera: THREE.PerspectiveCamera, container: HTMLElement, mesh: THREE.Mesh, clientX: number, clientY: number): SurfaceHit | null;

package/dist/types/Utils/surfaceAnnotation/strokeContour.d.ts

@@ -0,0 +1,19 @@
+import * as THREE from "three";
+import type { AnnotationVertex, SurfaceHit } from "./types";
+/**
+ * 模式 A(自由手绘)一笔的状态机。
+ * pointermove 时不断 addSample;与上一采样点世界距离 < minGap 的样本丢弃,避免过密。
+ * 顶点以 local 存(由 mesh 把世界命中点转 local)。
+ */
+export declare class StrokeContour {
+    private minGap;
+    private mesh;
+    private verts;
+    private last;
+    private has;
+    constructor(minGap: number, mesh: THREE.Mesh);
+    begin(): void;
+    addSample(hit: SurfaceHit): void;
+    get vertices(): AnnotationVertex[];
+    end(): AnnotationVertex[];
+}

package/dist/types/Utils/surfaceAnnotation/types.d.ts

@@ -0,0 +1,40 @@
+import * as THREE from "three";
+export type AnnotationMode = "navigate" | "freehand" | "geodesic" | "point";
+export interface SurfaceHit {
+    point: THREE.Vector3;
+    normal: THREE.Vector3;
+    faceIndex: number;
+}
+/** 标注顶点:位置与法线均为 **模型 local 空间**(单一真源,不受相机/摆放影响)。 */
+export interface AnnotationVertex {
+    x: number;
+    y: number;
+    z: number;
+    nx: number;
+    ny: number;
+    nz: number;
+    faceIndex: number;
+}
+export interface Annotation {
+    id: string;
+    type: "contour" | "points";
+    mode: "freehand" | "geodesic" | null;
+    label: string;
+    color: string;
+    closed: boolean;
+    vertices: AnnotationVertex[];
+    object3D: THREE.Object3D | null;
+}
+export interface ExportOptions {
+    /** 导出坐标空间,默认 "local"(模型空间,可复现、不受相机/摆放影响)。 */
+    space?: "local" | "world";
+    /** 是否在每个点附带法线 [x,y,z,nx,ny,nz]。 */
+    includeNormals?: boolean;
+}
+/** 世界系命中点 → local 顶点(位置 worldToLocal,法线用逆变换)。 */
+export declare function worldHitToLocalVertex(h: SurfaceHit, mesh: THREE.Mesh): AnnotationVertex;
+/** local 顶点 → world 位置 + world 法线(供渲染)。 */
+export declare function localVertexToWorld(v: AnnotationVertex, mesh: THREE.Mesh): {
+    p: THREE.Vector3;
+    n: THREE.Vector3;
+};

package/dist/types/index.d.ts

@@ -17,6 +17,8 @@ import { GaussianSmoother } from "./Utils/segmentation/core/GaussianSmoother";
 import { Copper3dTrackballControls } from "./Controls/Copper3dTrackballControls";
 import { MeshNodeTool } from "./Utils/MeshNodeTool";
 import { removeGuiFolderChilden } from "./Utils/segmentation/coreTools/gui";
+import { SurfaceAnnotator } from "./Utils/surfaceAnnotation";
+import type { SurfaceAnnotatorOptions, Annotation, AnnotationMode, ExportOptions } from "./Utils/surfaceAnnotation";
 import { nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, exportPaintImageType, IOptVTKLoader, aligned4DSurfaceType, aligned4DOptsType, Aligned4DController } from "./types/types";
 import { IPaintImage, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates, IGuiMeta } from "./Utils/segmentation/core/types";
 import { NrrdState } from "./Utils/segmentation/coreTools/NrrdState";
@@ -26,6 +28,6 @@ import { CHANNEL_COLORS, CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_
 import type { LayerId, ChannelValue } from "./Utils/segmentation/core/index";
 import type { AiPromptTool, AiPromptPoint, AiPromptPayload, AiMaskResult } from "./Utils/segmentation/tools/AiAssistTool";
 import "./css/style.css";
-export declare const REVISION = "v3.5.0-beta";
-export { copperRenderer, copperRendererOnDemond, copperMSceneRenderer, setHDRFilePath, addLabelToScene, convert3DPostoScreenPos, convertScreenPosto3DPos, addBoxHelper, fullScreenListenner, configKiwriousHeart, copperScene, copperSceneOnDemond, copperMScene, CameraViewPoint, kiwrious, NrrdTools, loading, Copper3dTrackballControls, createTexture2D_NRRD, MeshNodeTool, throttle, removeGuiFolderChilden, CHANNEL_COLORS, CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, GaussianSmoother, };
-export type { positionType, screenPosType, optsType, nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, IPaintImage, exportPaintImageType, IOptVTKLoader, aligned4DSurfaceType, aligned4DOptsType, Aligned4DController, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates, NrrdState, GuiState, IGuiMeta, ToolMode, IAnnotationCallbacks, LayerId, ChannelValue, AiPromptTool, AiPromptPoint, AiPromptPayload, AiMaskResult, };
+export declare const REVISION = "v3.6.0-beta";
+export { copperRenderer, copperRendererOnDemond, copperMSceneRenderer, setHDRFilePath, addLabelToScene, convert3DPostoScreenPos, convertScreenPosto3DPos, addBoxHelper, fullScreenListenner, configKiwriousHeart, copperScene, copperSceneOnDemond, copperMScene, CameraViewPoint, kiwrious, NrrdTools, loading, Copper3dTrackballControls, createTexture2D_NRRD, MeshNodeTool, throttle, removeGuiFolderChilden, CHANNEL_COLORS, CHANNEL_HEX_COLORS, AI_MASK_CHANNEL_COLORS, AI_CHANNEL_HEX_COLORS, rgbaToHex, rgbaToCss, GaussianSmoother, SurfaceAnnotator, };
+export type { positionType, screenPosType, optsType, nrrdMeshesType, nrrdSliceType, SensorDecodedValue_kiwrious, SensorReadResult_kiwrious, HeartRateResult_kiwrious, loadingBarType, IPaintImage, exportPaintImageType, IOptVTKLoader, aligned4DSurfaceType, aligned4DOptsType, Aligned4DController, ICommXYZ, IGUIStates, IGuiParameterSettings, INrrdStates, NrrdState, GuiState, IGuiMeta, ToolMode, IAnnotationCallbacks, LayerId, ChannelValue, AiPromptTool, AiPromptPoint, AiPromptPayload, AiMaskResult, SurfaceAnnotatorOptions, Annotation, AnnotationMode, ExportOptions, };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "copper3d",
   "description": "A 3d visualisation package base on threejs provides multiple scenes and Nrrd image load funtion.",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "main": "dist/bundle.umd.js",
   "moudle": "dist/bundle.esm.js",
   "types": "dist/types/index.d.ts",