State Management

Cornerstone3DTools implements a FrameOfReference annotations state manager, where annotations use world coordinates for points.

Annotation Data

When a new annotation is created (addNewAnnotation method in the annotation tools), a new annotation data is created based on the metadata and the current state of the tool, and it gets added to the global annotation state.

In the following we show the annotation data for a ProbeTool instance. Other tools, basically follow the same pattern.

// ProbeTool Annotation Data
const annotation = {
  invalidated: boolean, // Whether the annotation data has been invalidated by e.g., moving its handles
  highlighted: boolean, // Whether the annotation is highlighted by mouse over
  annotationUID: string, // The UID of the annotation
  metadata: {
    viewPlaneNormal: Types.Point3, // The view plane normal of the camera
    viewUp: Types.Point3, // The view up vector of the camera
    FrameOfReferenceUID: string, // viewport's FrameOfReferenceUID the annotation has been drawn on
    referencedImageId?: string, // The image ID the annotation has been drawn on (if applicable)
    toolName: string, // The tool name
  },
  data: {
    handles: {
      points: [Types.Point3], // The handles points in world coordinates (probe tool = 1 handle = 1 x,y,z point)
    },
    cachedStats: {}, // Stored Statistics for the annotation
  },
}

Annotation State

Annotations state keeps track of the annotations for each FrameOfReference. The state is composed of a FrameOfReference-specific state object, in which each annotation-specific state is stored. Below, you can see a high-level overview of the state object.

API

You can get/add annotations using the following API:

// Adds annotation
cornerstone3DTools.annotation.state.addAnnotation(
  annotation,
  element,
  suppressEvents
);

// Remove the annotations given the annotation reference.
cornerstone3DTools.annotation.state.removeAnnotation(
  annotationUID,
  suppressEvents
);

// Returns the full annotations for a given Tool
cornerstone3DTools.annotation.state.getAnnotations(toolName, element);

// A helper which returns the single annotation entry matching the UID.
cornerstone3DTools.annotation.state.getAnnotation(annotationUID);

Read more

TIP

Read more about the state API here