Copper3D 表面标注 API（Surface Annotation）— 中文文档 ​

import * as Copper from "copper3d_visualisation";

const appRenderer = new Copper.copperRenderer(container, { guiOpen: false });
const scene = appRenderer.createScene("annot") as Copper.copperScene;
appRenderer.setCurrentScene(scene);
appRenderer.animate();

// 加载模型（用 copper 自带 loader），在回调里创建标注器
scene.loadOBJ("/models/heart.obj", (group) => {
  const annotator = scene.createSurfaceAnnotator(group);

  // 武装一个工具；随后按住/轻点 Space 进入绘制（见 §4）
  annotator.setMode("freehand"); // 或 "geodesic" / "point" / "navigate"

  // 导出（默认 local 坐标）
  // const data = annotator.exportJSON("heart.obj");
});

import * as Copper from "copper3d_visualisation";

const appRenderer = new Copper.copperRenderer(container, { guiOpen: false });
const scene = appRenderer.createScene("annot") as Copper.copperScene;
appRenderer.setCurrentScene(scene);
appRenderer.animate();

// 加载模型（用 copper 自带 loader），在回调里创建标注器
scene.loadOBJ("/models/heart.obj", (group) => {
  const annotator = scene.createSurfaceAnnotator(group);

  // 武装一个工具；随后按住/轻点 Space 进入绘制（见 §4）
  annotator.setMode("freehand"); // 或 "geodesic" / "point" / "navigate"

  // 导出（默认 local 坐标）
  // const data = annotator.exportJSON("heart.obj");
});

createSurfaceAnnotator(
  target: THREE.Mesh | THREE.Object3D,
  opts?: {
    freehandColor?: string;   // 自由手绘色，默认 "#e5006e"
    geodesicColor?: string;   // 测地线色，默认 "#ffa24e"
    pointColor?: string;      // 标记点色，默认 "#ffd166"
    lineWidth?: number;       // 线宽(像素)，默认 3
    markerRadius?: number;    // 小球半径，默认 bbox 对角线 * 0.0032
    bboxDiagonal?: number;    // 手动指定尺寸基准，缺省自动从几何算
    onModeChange?: (mode: AnnotationMode) => void;
    onChange?: (annotations: Annotation[]) => void; // 标注列表增删/撤销/清空时触发
    onInteractionChange?: (s: InteractionState) => void; // 绘制状态/武装工具/锁定/编辑态变化时触发（见 §4）
    onSelectionChange?: (id: string | null) => void;     // 引擎自身改变选中时触发（删除、回到 navigate 时取消选中）—— 用于同步你的列表 UI 高亮
  }
): SurfaceAnnotator

createSurfaceAnnotator(
  target: THREE.Mesh | THREE.Object3D,
  opts?: {
    freehandColor?: string;   // 自由手绘色，默认 "#e5006e"
    geodesicColor?: string;   // 测地线色，默认 "#ffa24e"
    pointColor?: string;      // 标记点色，默认 "#ffd166"
    lineWidth?: number;       // 线宽(像素)，默认 3
    markerRadius?: number;    // 小球半径，默认 bbox 对角线 * 0.0032
    bboxDiagonal?: number;    // 手动指定尺寸基准，缺省自动从几何算
    onModeChange?: (mode: AnnotationMode) => void;
    onChange?: (annotations: Annotation[]) => void; // 标注列表增删/撤销/清空时触发
    onInteractionChange?: (s: InteractionState) => void; // 绘制状态/武装工具/锁定/编辑态变化时触发（见 §4）
    onSelectionChange?: (id: string | null) => void;     // 引擎自身改变选中时触发（删除、回到 navigate 时取消选中）—— 用于同步你的列表 UI 高亮
  }
): SurfaceAnnotator

type AnnotationMode = "navigate" | "freehand" | "geodesic" | "point";

interface AnnotationVertex {       // 位置与法线均为模型 local 空间
  x: number; y: number; z: number;
  nx: number; ny: number; nz: number;
  faceIndex: number;
}

interface Annotation {
  id: string;
  type: "contour" | "points";
  mode: "freehand" | "geodesic" | null; // points 为 null
  label: string;
  color: string;                         // hex
  closed: boolean;
  visible: boolean;                      // 单条显示/隐藏（默认 true）
  vertices: AnnotationVertex[];
  anchors?: AnnotationVertex[];          // 仅测地线轮廓：控制点，使已提交的轮廓可被重新打开编辑（随导出/导入一同保存）
  object3D: THREE.Object3D | null;       // 渲染对象引用
}

interface ExportOptions {
  space?: "local" | "world";   // 默认 "local"
  includeNormals?: boolean;    // true 时点为 [x,y,z,nx,ny,nz]
}

// 实时交互状态，由 onInteractionChange 发出（见 §4）
interface InteractionState {
  drawing: boolean;            // 正在绘制时为 true（按住 Space 或处于 draw-lock）
  armed: AnnotationMode;       // 将要绘制的工具 —— "freehand" | "geodesic" | "point"
  locked: boolean;             // draw-lock 是否开启（轻点 Space 切换）
  editing: boolean;            // 当前有可编辑的测地线（正在绘制或重新打开的已提交轮廓）→ 其锚点可拖拽/删除/插入；可据此显示编辑提示
}

type AnnotationMode = "navigate" | "freehand" | "geodesic" | "point";

interface AnnotationVertex {       // 位置与法线均为模型 local 空间
  x: number; y: number; z: number;
  nx: number; ny: number; nz: number;
  faceIndex: number;
}

interface Annotation {
  id: string;
  type: "contour" | "points";
  mode: "freehand" | "geodesic" | null; // points 为 null
  label: string;
  color: string;                         // hex
  closed: boolean;
  visible: boolean;                      // 单条显示/隐藏（默认 true）
  vertices: AnnotationVertex[];
  anchors?: AnnotationVertex[];          // 仅测地线轮廓：控制点，使已提交的轮廓可被重新打开编辑（随导出/导入一同保存）
  object3D: THREE.Object3D | null;       // 渲染对象引用
}

interface ExportOptions {
  space?: "local" | "world";   // 默认 "local"
  includeNormals?: boolean;    // true 时点为 [x,y,z,nx,ny,nz]
}

// 实时交互状态，由 onInteractionChange 发出（见 §4）
interface InteractionState {
  drawing: boolean;            // 正在绘制时为 true（按住 Space 或处于 draw-lock）
  armed: AnnotationMode;       // 将要绘制的工具 —— "freehand" | "geodesic" | "point"
  locked: boolean;             // draw-lock 是否开启（轻点 Space 切换）
  editing: boolean;            // 当前有可编辑的测地线（正在绘制或重新打开的已提交轮廓）→ 其锚点可拖拽/删除/插入；可据此显示编辑提示
}

scene.loadOBJ("/models/heart.obj", (group) => {
  const annotator = scene.createSurfaceAnnotator(group);
  annotator.setMode("geodesic");
});

scene.loadOBJ("/models/heart.obj", (group) => {
  const annotator = scene.createSurfaceAnnotator(group);
  annotator.setMode("geodesic");
});

scene.loadPureGLB("/models/heart.glb", (group) => {
  const annotator = scene.createSurfaceAnnotator(group, {
    freehandColor: "#00e5ff",
    geodesicColor: "#ff3b6b",
    pointColor: "#ffe066",
    lineWidth: 4,
  });
});

scene.loadPureGLB("/models/heart.glb", (group) => {
  const annotator = scene.createSurfaceAnnotator(group, {
    freehandColor: "#00e5ff",
    geodesicColor: "#ff3b6b",
    pointColor: "#ffe066",
    lineWidth: 4,
  });
});

let annotator;
scene.loadOBJ("/models/heart.obj", (group) => {
  annotator = scene.createSurfaceAnnotator(group, {
    onChange: (annotations) => renderList(annotations), // 列表变化时刷新你的 UI
    onModeChange: (mode) => updateModeButtons(mode),
  });
});

// 选中 / 改名 / 改色
function onSelect(id) { annotator.selectAnnotation(id); }
function onRename(id, label) { annotator.getStore().setLabel(id, label); }
function onRecolor(id, color) {
  annotator.getStore().setColor(id, color);
  annotator.refreshAnnotation(id); // 必须，更新 3D 颜色
}

let annotator;
scene.loadOBJ("/models/heart.obj", (group) => {
  annotator = scene.createSurfaceAnnotator(group, {
    onChange: (annotations) => renderList(annotations), // 列表变化时刷新你的 UI
    onModeChange: (mode) => updateModeButtons(mode),
  });
});

// 选中 / 改名 / 改色
function onSelect(id) { annotator.selectAnnotation(id); }
function onRename(id, label) { annotator.getStore().setLabel(id, label); }
function onRecolor(id, color) {
  annotator.getStore().setColor(id, color);
  annotator.refreshAnnotation(id); // 必须，更新 3D 颜色
}

const local = annotator.exportJSON("heart.obj");                       // 默认 local
const world = annotator.exportJSON("heart.obj", { space: "world" });   // 世界系
const withN = annotator.exportJSON("heart.obj", { includeNormals: true });

// 触发下载（注意：a 必须挂到 DOM 才能在部分浏览器触发）
function download(obj, filename = "annotations.json") {
  const blob = new Blob([JSON.stringify(obj, null, 2)], { type: "application/json" });
  const url = URL.createObjectURL(blob);
  const a = document.createElement("a");
  a.href = url; a.download = filename;
  document.body.appendChild(a); a.click(); a.remove();
  URL.revokeObjectURL(url);
}
download(local);

const local = annotator.exportJSON("heart.obj");                       // 默认 local
const world = annotator.exportJSON("heart.obj", { space: "world" });   // 世界系
const withN = annotator.exportJSON("heart.obj", { includeNormals: true });

// 触发下载（注意：a 必须挂到 DOM 才能在部分浏览器触发）
function download(obj, filename = "annotations.json") {
  const blob = new Blob([JSON.stringify(obj, null, 2)], { type: "application/json" });
  const url = URL.createObjectURL(blob);
  const a = document.createElement("a");
  a.href = url; a.download = filename;
  document.body.appendChild(a); a.click(); a.remove();
  URL.revokeObjectURL(url);
}
download(local);

scene.loadOBJ("/models/heart.obj", (group) => {
  const annotator = scene.createSurfaceAnnotator(group);

  // 重建此前导出的标注（例如从后端取回）
  const saved = await (await fetch("/api/annotations/heart.json")).json();
  const n = annotator.importAnnotations(saved); // 返回重建条数

  // 不删除，仅隐藏某一条
  annotator.setVisible(saved.annotations[0].id, false);
});

scene.loadOBJ("/models/heart.obj", (group) => {
  const annotator = scene.createSurfaceAnnotator(group);

  // 重建此前导出的标注（例如从后端取回）
  const saved = await (await fetch("/api/annotations/heart.json")).json();
  const n = annotator.importAnnotations(saved); // 返回重建条数

  // 不删除，仅隐藏某一条
  annotator.setVisible(saved.annotations[0].id, false);
});

scene.createSurfaceAnnotator(group, {
  onInteractionChange: ({ drawing, armed, locked, editing }) => {
    badge.textContent = drawing ? `Drawing — ${armed}${locked ? "（锁定）" : ""}` : "Navigate";
    editHint.hidden = !editing; // editing 时显示「拖拽移动·右键删除·点线段插入」提示
  },
  onSelectionChange: (id) => refreshListHighlight(id), // 引擎可能自行取消选中（删除 / 回到 navigate）
});

scene.createSurfaceAnnotator(group, {
  onInteractionChange: ({ drawing, armed, locked, editing }) => {
    badge.textContent = drawing ? `Drawing — ${armed}${locked ? "（锁定）" : ""}` : "Navigate";
    editHint.hidden = !editing; // editing 时显示「拖拽移动·右键删除·点线段插入」提示
  },
  onSelectionChange: (id) => refreshListHighlight(id), // 引擎可能自行取消选中（删除 / 回到 navigate）
});

// 组件卸载 / 切换模型时
annotator.dispose();          // 或 scene.disposeSurfaceAnnotators();
appRenderer.dispose();

// 组件卸载 / 切换模型时
annotator.dispose();          // 或 scene.disposeSurfaceAnnotators();
appRenderer.dispose();

// 把同一 case 的多个模型加载进同一个 scene。每个模型一个标注器，
// 同一时刻只有一个「活动」（可编辑），休眠的模型轮廓保持可见但不响应输入。
const annotators = new Map<string, Copper.SurfaceAnnotator>();
let activeId: string | null = null;

function addModel(id: string, group: THREE.Object3D) {
  const a = scene.createSurfaceAnnotator(group);
  a.deactivate();                 // 加载即休眠 —— 取景/光照/框选仍由你负责
  annotators.set(id, a);
}

function setActive(id: string) {
  if (activeId) annotators.get(activeId)?.deactivate(); // 提交并清理旧的
  annotators.get(id)?.activate();                       // 此模型接管 Space / 工具
  activeId = id;
}

// 每个模型的「一键隐藏所有标注」（区别于隐藏模型表面网格）
function hideAllAnnotations(id: string, hidden: boolean) {
  annotators.get(id)?.setAllVisible(!hidden);
}

// 拆除单个模型，或整个 case
function removeModel(id: string) {
  annotators.get(id)?.dispose();  // 移除它的轮廓 + 监听
  annotators.delete(id);
  if (activeId === id) activeId = null;
}

// 把同一 case 的多个模型加载进同一个 scene。每个模型一个标注器，
// 同一时刻只有一个「活动」（可编辑），休眠的模型轮廓保持可见但不响应输入。
const annotators = new Map<string, Copper.SurfaceAnnotator>();
let activeId: string | null = null;

function addModel(id: string, group: THREE.Object3D) {
  const a = scene.createSurfaceAnnotator(group);
  a.deactivate();                 // 加载即休眠 —— 取景/光照/框选仍由你负责
  annotators.set(id, a);
}

function setActive(id: string) {
  if (activeId) annotators.get(activeId)?.deactivate(); // 提交并清理旧的
  annotators.get(id)?.activate();                       // 此模型接管 Space / 工具
  activeId = id;
}

// 每个模型的「一键隐藏所有标注」（区别于隐藏模型表面网格）
function hideAllAnnotations(id: string, hidden: boolean) {
  annotators.get(id)?.setAllVisible(!hidden);
}

// 拆除单个模型，或整个 case
function removeModel(id: string) {
  annotators.get(id)?.dispose();  // 移除它的轮廓 + 监听
  annotators.delete(id);
  if (activeId === id) activeId = null;
}

import {
  SurfaceAnnotator,            // 值(用于 instanceof / 类型)
} from "copper3d_visualisation";
import type {
  SurfaceAnnotatorOptions,
  Annotation,
  AnnotationMode,
  ExportOptions,
  InteractionState,
} from "copper3d_visualisation";

import {
  SurfaceAnnotator,            // 值(用于 instanceof / 类型)
} from "copper3d_visualisation";
import type {
  SurfaceAnnotatorOptions,
  Annotation,
  AnnotationMode,
  ExportOptions,
  InteractionState,
} from "copper3d_visualisation";