Copper3D Surface Annotation API — English ​

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();

// Load a model with a copper loader, create the annotator in the callback
scene.loadOBJ("/models/heart.obj", (group) => {
  const annotator = scene.createSurfaceAnnotator(group);

  annotator.setMode("freehand"); // or "geodesic" / "point" / "navigate"

  // Export (local coordinates by default)
  // 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();

// Load a model with a copper loader, create the annotator in the callback
scene.loadOBJ("/models/heart.obj", (group) => {
  const annotator = scene.createSurfaceAnnotator(group);

  annotator.setMode("freehand"); // or "geodesic" / "point" / "navigate"

  // Export (local coordinates by default)
  // const data = annotator.exportJSON("heart.obj");
});

createSurfaceAnnotator(
  target: THREE.Mesh | THREE.Object3D,
  opts?: {
    freehandColor?: string;   // freehand color, default "#e5006e"
    geodesicColor?: string;   // geodesic color, default "#ffa24e"
    pointColor?: string;      // marker color, default "#ffd166"
    lineWidth?: number;       // line width (px), default 3
    markerRadius?: number;    // sphere radius, default bboxDiagonal * 0.0032
    bboxDiagonal?: number;    // size reference; auto-computed from geometry if omitted
    onModeChange?: (mode: AnnotationMode) => void;
    onChange?: (annotations: Annotation[]) => void; // fired on add/delete/undo/clear
    onInteractionChange?: (s: InteractionState) => void; // fired when drawing/armed/lock/editing changes (see §4)
    onSelectionChange?: (id: string | null) => void;     // fired when the ENGINE changes the selection itself (delete, deselect-on-navigate) — mirror it into your list UI
  }
): SurfaceAnnotator

createSurfaceAnnotator(
  target: THREE.Mesh | THREE.Object3D,
  opts?: {
    freehandColor?: string;   // freehand color, default "#e5006e"
    geodesicColor?: string;   // geodesic color, default "#ffa24e"
    pointColor?: string;      // marker color, default "#ffd166"
    lineWidth?: number;       // line width (px), default 3
    markerRadius?: number;    // sphere radius, default bboxDiagonal * 0.0032
    bboxDiagonal?: number;    // size reference; auto-computed from geometry if omitted
    onModeChange?: (mode: AnnotationMode) => void;
    onChange?: (annotations: Annotation[]) => void; // fired on add/delete/undo/clear
    onInteractionChange?: (s: InteractionState) => void; // fired when drawing/armed/lock/editing changes (see §4)
    onSelectionChange?: (id: string | null) => void;     // fired when the ENGINE changes the selection itself (delete, deselect-on-navigate) — mirror it into your list UI
  }
): SurfaceAnnotator

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

interface AnnotationVertex {       // position and normal are in model-LOCAL space
  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; // null for points
  label: string;
  color: string;                         // hex
  closed: boolean;
  visible: boolean;                      // per-annotation show/hide (default true)
  vertices: AnnotationVertex[];
  anchors?: AnnotationVertex[];          // geodesic contours only: the control points, so a committed contour can be re-opened for editing (survives export/import)
  object3D: THREE.Object3D | null;       // render object reference
}

interface ExportOptions {
  space?: "local" | "world";   // default "local"
  includeNormals?: boolean;    // when true, points are [x,y,z,nx,ny,nz]
}

// Live interaction state, emitted by onInteractionChange (see §4)
interface InteractionState {
  drawing: boolean;            // true while strokes/clicks draw (Space held or draw-lock on)
  armed: AnnotationMode;       // the tool that will draw — "freehand" | "geodesic" | "point"
  locked: boolean;             // draw-lock is on (toggled by tapping Space)
  editing: boolean;            // a geodesic is editable now (in-progress or a re-opened committed one) → its anchors can be dragged/deleted/inserted; use it to show an edit hint
}

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

interface AnnotationVertex {       // position and normal are in model-LOCAL space
  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; // null for points
  label: string;
  color: string;                         // hex
  closed: boolean;
  visible: boolean;                      // per-annotation show/hide (default true)
  vertices: AnnotationVertex[];
  anchors?: AnnotationVertex[];          // geodesic contours only: the control points, so a committed contour can be re-opened for editing (survives export/import)
  object3D: THREE.Object3D | null;       // render object reference
}

interface ExportOptions {
  space?: "local" | "world";   // default "local"
  includeNormals?: boolean;    // when true, points are [x,y,z,nx,ny,nz]
}

// Live interaction state, emitted by onInteractionChange (see §4)
interface InteractionState {
  drawing: boolean;            // true while strokes/clicks draw (Space held or draw-lock on)
  armed: AnnotationMode;       // the tool that will draw — "freehand" | "geodesic" | "point"
  locked: boolean;             // draw-lock is on (toggled by tapping Space)
  editing: boolean;            // a geodesic is editable now (in-progress or a re-opened committed one) → its anchors can be dragged/deleted/inserted; use it to show an edit hint
}

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), // refresh your UI on change
    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); // required to update the 3D color
}

let annotator;
scene.loadOBJ("/models/heart.obj", (group) => {
  annotator = scene.createSurfaceAnnotator(group, {
    onChange: (annotations) => renderList(annotations), // refresh your UI on change
    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); // required to update the 3D color
}

const local = annotator.exportJSON("heart.obj");                       // local (default)
const world = annotator.exportJSON("heart.obj", { space: "world" });   // world space
const withN = annotator.exportJSON("heart.obj", { includeNormals: true });

// Trigger a download (note: the <a> must be in the DOM to fire in some browsers)
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 (default)
const world = annotator.exportJSON("heart.obj", { space: "world" });   // world space
const withN = annotator.exportJSON("heart.obj", { includeNormals: true });

// Trigger a download (note: the <a> must be in the DOM to fire in some browsers)
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);

  // Re-hydrate previously exported annotations (e.g. fetched from a backend)
  const saved = await (await fetch("/api/annotations/heart.json")).json();
  const n = annotator.importAnnotations(saved); // returns how many were rebuilt

  // Hide / show a single annotation without deleting it
  annotator.setVisible(saved.annotations[0].id, false);
});

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

  // Re-hydrate previously exported annotations (e.g. fetched from a backend)
  const saved = await (await fetch("/api/annotations/heart.json")).json();
  const n = annotator.importAnnotations(saved); // returns how many were rebuilt

  // Hide / show a single annotation without deleting it
  annotator.setVisible(saved.annotations[0].id, false);
});

scene.createSurfaceAnnotator(group, {
  onInteractionChange: ({ drawing, armed, locked, editing }) => {
    badge.textContent = drawing ? `Drawing — ${armed}${locked ? " (locked)" : ""}` : "Navigate";
    editHint.hidden = !editing; // show "drag move · right-click delete · click line insert" while editing a geodesic
  },
  onSelectionChange: (id) => refreshListHighlight(id), // engine may deselect on its own (delete / navigate)
});

scene.createSurfaceAnnotator(group, {
  onInteractionChange: ({ drawing, armed, locked, editing }) => {
    badge.textContent = drawing ? `Drawing — ${armed}${locked ? " (locked)" : ""}` : "Navigate";
    editHint.hidden = !editing; // show "drag move · right-click delete · click line insert" while editing a geodesic
  },
  onSelectionChange: (id) => refreshListHighlight(id), // engine may deselect on its own (delete / navigate)
});

// on component unmount / model switch
annotator.dispose();          // or scene.disposeSurfaceAnnotators();
appRenderer.dispose();

// on component unmount / model switch
annotator.dispose();          // or scene.disposeSurfaceAnnotators();
appRenderer.dispose();

// Load several models of the same case into ONE scene. Each gets its own
// annotator; only one is "active" (editable) at a time. Dormant models keep
// their contours visible but ignore input.
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();                 // dormant on load — no camera/lighting/framing here (that's yours)
  annotators.set(id, a);
}

function setActive(id: string) {
  if (activeId) annotators.get(activeId)?.deactivate(); // commits/cleans up the old one
  annotators.get(id)?.activate();                       // this model now owns Space / tools
  activeId = id;
}

// Per-model "hide all annotations" toggle (distinct from hiding the surface mesh)
function hideAllAnnotations(id: string, hidden: boolean) {
  annotators.get(id)?.setAllVisible(!hidden);
}

// Teardown one model, or the whole case
function removeModel(id: string) {
  annotators.get(id)?.dispose();  // removes its contours + listeners
  annotators.delete(id);
  if (activeId === id) activeId = null;
}

// Load several models of the same case into ONE scene. Each gets its own
// annotator; only one is "active" (editable) at a time. Dormant models keep
// their contours visible but ignore input.
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();                 // dormant on load — no camera/lighting/framing here (that's yours)
  annotators.set(id, a);
}

function setActive(id: string) {
  if (activeId) annotators.get(activeId)?.deactivate(); // commits/cleans up the old one
  annotators.get(id)?.activate();                       // this model now owns Space / tools
  activeId = id;
}

// Per-model "hide all annotations" toggle (distinct from hiding the surface mesh)
function hideAllAnnotations(id: string, hidden: boolean) {
  annotators.get(id)?.setAllVisible(!hidden);
}

// Teardown one model, or the whole case
function removeModel(id: string) {
  annotators.get(id)?.dispose();  // removes its contours + listeners
  annotators.delete(id);
  if (activeId === id) activeId = null;
}

import {
  SurfaceAnnotator,            // value (for instanceof / typing)
} from "copper3d_visualisation";
import type {
  SurfaceAnnotatorOptions,
  Annotation,
  AnnotationMode,
  ExportOptions,
  InteractionState,
} from "copper3d_visualisation";

import {
  SurfaceAnnotator,            // value (for instanceof / typing)
} from "copper3d_visualisation";
import type {
  SurfaceAnnotatorOptions,
  Annotation,
  AnnotationMode,
  ExportOptions,
  InteractionState,
} from "copper3d_visualisation";