@cornerstonejs/tools 0.56.2 → 0.56.3

package/src/tools/base/AnnotationTool.ts

@@ -0,0 +1,307 @@
+import { getEnabledElement } from '@cornerstonejs/core';
+import type { Types } from '@cornerstonejs/core';
+
+import { vec2 } from 'gl-matrix';
+
+import AnnotationDisplayTool from './AnnotationDisplayTool';
+import { isAnnotationLocked } from '../../stateManagement/annotation/annotationLocking';
+import { isAnnotationVisible } from '../../stateManagement/annotation/annotationVisibility';
+import {
+  Annotation,
+  Annotations,
+  EventTypes,
+  ToolHandle,
+  InteractionTypes,
+} from '../../types';
+import { StyleSpecifier } from '../../types/AnnotationStyle';
+
+/**
+ * Abstract class for tools which create and display annotations on the
+ * cornerstone3D canvas. In addition, it provides a base class for segmentation
+ * tools that require drawing an annotation before running the segmentation strategy
+ * for instance threshold segmentation based on an area and a threshold.
+ * Annotation tools make use of drawing utilities to draw SVG elements on the viewport.
+ *
+ * To create a new annotation tool, derive from this class and implement the
+ * abstract methods.
+ */
+abstract class AnnotationTool extends AnnotationDisplayTool {
+  static toolName;
+  // ===================================================================
+  // Abstract Methods - Must be implemented.
+  // ===================================================================
+
+  /**
+   * @abstract addNewAnnotation Creates a new annotation based on the clicked mouse position
+   *
+   * @param evt - The normalized mouse event
+   * @param interactionType -  The interaction type used to add the annotation.
+   */
+  abstract addNewAnnotation(
+    evt: EventTypes.InteractionEventType,
+    interactionType: InteractionTypes
+  ): Annotation;
+
+  /**
+   * @abstract cancel Used to cancel the ongoing tool drawing and manipulation
+   *
+   */
+  abstract cancel(element: HTMLDivElement);
+
+  /**
+   * handleSelectedCallback Custom callback for when a handle is selected.
+   *
+   * @param evt - The normalized mouse event
+   * @param annotation - The annotation selected.
+   * @param handle - The selected handle (either Types.Point3 in space for annotations, or TextBoxHandle object for text boxes).
+   * @param interactionType - The interaction type the handle was selected with.
+   */
+  abstract handleSelectedCallback(
+    evt: EventTypes.InteractionEventType,
+    annotation: Annotation,
+    handle: ToolHandle,
+    interactionType: InteractionTypes
+  ): void;
+
+  /**
+   * Custom callback for when an annotation is selected
+   *
+   * @param evt - The normalized mouse event
+   * @param annotation - The `Annotation` to check.
+   * @param interactionType - The interaction type used to select the tool.
+   */
+  abstract toolSelectedCallback(
+    evt: EventTypes.InteractionEventType,
+    annotation: Annotation,
+    interactionType: InteractionTypes
+  ): void;
+
+  /**
+   * Returns true if the provided canvas coordinate tool is near the annotation
+   *
+   * @param element - The HTML element
+   * @param annotation - The annotation to check
+   * @param canvasCoords - The canvas coordinate to check
+   * @param proximity - The minimum proximity to consider the point near
+   * @param interactionType - The interaction type used to select the tool.
+   *
+   * @returns boolean if the point is near.
+   */
+  abstract isPointNearTool(
+    element: HTMLDivElement,
+    annotation: Annotation,
+    canvasCoords: Types.Point2,
+    proximity: number,
+    interactionType: string
+  ): boolean;
+
+  /**
+   * @virtual Event handler for Cornerstone MOUSE_MOVE event.
+   *
+   *
+   * @param evt - The normalized mouse event
+   * @param filteredAnnotations - The annotations to check for hover interactions
+   * @returns True if the annotation needs to be re-drawn by the annotationRenderingEngine.
+   */
+  public mouseMoveCallback = (
+    evt: EventTypes.MouseMoveEventType,
+    filteredAnnotations?: Annotations
+  ): boolean => {
+    if (!filteredAnnotations) {
+      return false;
+    }
+
+    const { element, currentPoints } = evt.detail;
+    const canvasCoords = currentPoints.canvas;
+    let annotationsNeedToBeRedrawn = false;
+
+    for (const annotation of filteredAnnotations) {
+      // Do not do anything if the annotation is locked or hidden.
+      if (
+        isAnnotationLocked(annotation) ||
+        !isAnnotationVisible(annotation.annotationUID)
+      ) {
+        continue;
+      }
+
+      const { data } = annotation;
+      const activateHandleIndex = data.handles
+        ? data.handles.activeHandleIndex
+        : undefined;
+
+      // Perform tool specific imagePointNearToolOrHandle to determine if the mouse
+      // is near the tool or its handles or its textBox.
+      const near = this._imagePointNearToolOrHandle(
+        element,
+        annotation,
+        canvasCoords,
+        6 // Todo: This should come from the state
+      );
+
+      const nearToolAndNotMarkedActive = near && !annotation.highlighted;
+      const notNearToolAndMarkedActive = !near && annotation.highlighted;
+      if (nearToolAndNotMarkedActive || notNearToolAndMarkedActive) {
+        annotation.highlighted = !annotation.highlighted;
+        annotationsNeedToBeRedrawn = true;
+      } else if (
+        data.handles &&
+        data.handles.activeHandleIndex !== activateHandleIndex
+      ) {
+        // Active handle index has changed, re-render.
+        annotationsNeedToBeRedrawn = true;
+      }
+    }
+
+    return annotationsNeedToBeRedrawn;
+  };
+
+  /**
+   * It checks if the mouse click is near TextBoxHandle or AnnotationHandle itself, and
+   * return either it. It prioritize TextBoxHandle over AnnotationHandle. If
+   * the mouse click is not near any of the handles, it does not return anything.
+   *
+   * @param element - The element that the tool is attached to.
+   * @param annotation - The annotation object associated with the annotation
+   * @param canvasCoords - The coordinates of the mouse click on canvas
+   * @param proximity - The distance from the mouse cursor to the point
+   * that is considered "near".
+   * @returns The handle that is closest to the cursor, or null if the cursor
+   * is not near any of the handles.
+   */
+  getHandleNearImagePoint(
+    element: HTMLDivElement,
+    annotation: Annotation,
+    canvasCoords: Types.Point2,
+    proximity: number
+  ): ToolHandle | undefined {
+    const enabledElement = getEnabledElement(element);
+    const { viewport } = enabledElement;
+
+    const { data } = annotation;
+    const { points, textBox } = data.handles;
+    const { worldBoundingBox } = textBox;
+
+    if (worldBoundingBox) {
+      const canvasBoundingBox = {
+        topLeft: viewport.worldToCanvas(worldBoundingBox.topLeft),
+        topRight: viewport.worldToCanvas(worldBoundingBox.topRight),
+        bottomLeft: viewport.worldToCanvas(worldBoundingBox.bottomLeft),
+        bottomRight: viewport.worldToCanvas(worldBoundingBox.bottomRight),
+      };
+
+      if (
+        canvasCoords[0] >= canvasBoundingBox.topLeft[0] &&
+        canvasCoords[0] <= canvasBoundingBox.bottomRight[0] &&
+        canvasCoords[1] >= canvasBoundingBox.topLeft[1] &&
+        canvasCoords[1] <= canvasBoundingBox.bottomRight[1]
+      ) {
+        data.handles.activeHandleIndex = null;
+        return textBox;
+      }
+    }
+
+    for (let i = 0; i < points.length; i++) {
+      const point = points[i];
+      const annotationCanvasCoordinate = viewport.worldToCanvas(point);
+
+      const near =
+        vec2.distance(canvasCoords, annotationCanvasCoordinate) < proximity;
+
+      if (near === true) {
+        data.handles.activeHandleIndex = i;
+        return point;
+      }
+    }
+
+    data.handles.activeHandleIndex = null;
+  }
+
+  /**
+   * It returns the style for the text box
+   * @param styleSpecifier - An object containing the specifications such as viewportId,
+   * toolGroupId, toolName and annotationUID which are used to get the style if the level of specificity is
+   * met (hierarchy is checked from most specific to least specific which is
+   * annotationLevel -> viewportLevel -> toolGroupLevel -> default.
+   * @param annotation - The annotation for the tool that is
+   * currently active.
+   * @returns An object of the style settings for the text box.
+   */
+  public getLinkedTextBoxStyle(
+    specifications: StyleSpecifier,
+    annotation?: Annotation
+  ): Record<string, unknown> {
+    // Todo: this function can be used to set different styles for different toolMode
+    // for the textBox.
+
+    return {
+      fontFamily: this.getStyle(
+        'textBoxFontFamily',
+        specifications,
+        annotation
+      ),
+      fontSize: this.getStyle('textBoxFontSize', specifications, annotation),
+      color: this.getStyle('textBoxColor', specifications, annotation),
+      shadow: this.getStyle('textBoxShadow', specifications, annotation),
+      background: this.getStyle(
+        'textBoxBackground',
+        specifications,
+        annotation
+      ),
+      lineWidth: this.getStyle(
+        'textBoxLinkLineWidth',
+        specifications,
+        annotation
+      ),
+      lineDash: this.getStyle(
+        'textBoxLinkLineDash',
+        specifications,
+        annotation
+      ),
+    };
+  }
+
+  /**
+   * Returns true if the `canvasCoords` are near a handle or selectable part of the tool
+   *
+   * @param element - The HTML element
+   * @param annotation - The annotation to check
+   * @param canvasCoords - The canvas coordinates to check
+   * @param proximity - The proximity to consider
+   *
+   * @returns If the point is near.
+   */
+  private _imagePointNearToolOrHandle(
+    element: HTMLDivElement,
+    annotation: Annotation,
+    canvasCoords: Types.Point2,
+    proximity: number
+  ): boolean {
+    // Based on the tool instance type, check if the point is near the tool handles
+    const handleNearImagePoint = this.getHandleNearImagePoint(
+      element,
+      annotation,
+      canvasCoords,
+      proximity
+    );
+
+    if (handleNearImagePoint) {
+      return true;
+    }
+
+    // If the point is not near the handles, check if the point is near the tool
+    const toolNewImagePoint = this.isPointNearTool(
+      element,
+      annotation,
+      canvasCoords,
+      proximity,
+      'mouse'
+    );
+
+    if (toolNewImagePoint) {
+      return true;
+    }
+  }
+}
+
+AnnotationTool.toolName = 'AnnotationTool';
+export default AnnotationTool;

package/src/tools/base/BaseTool.ts

@@ -0,0 +1,215 @@
+import { StackViewport, VolumeViewport, utilities } from '@cornerstonejs/core';
+import { Types } from '@cornerstonejs/core';
+import { ToolModes } from '../../enums';
+import { InteractionTypes, ToolProps, PublicToolProps } from '../../types';
+
+export interface IBaseTool {
+  /** ToolGroup ID the tool instance belongs to */
+  toolGroupId: string;
+  /** Tool supported interaction types */
+  supportedInteractionTypes: InteractionTypes[];
+  /** Tool Mode : Active, Passive, Enabled, Disabled */
+  mode: ToolModes;
+  /** Tool Configuration */
+  configuration: {
+    preventHandleOutsideImage?: boolean;
+    strategies?: Record<string, any>;
+    defaultStrategy?: string;
+    activeStrategy?: string;
+    strategyOptions?: Record<string, unknown>;
+  };
+}
+
+/**
+ * Abstract base class from which all tools derive.
+ * Deals with cleanly merging custom and default configuration, and strategy
+ * application.
+ */
+abstract class BaseTool implements IBaseTool {
+  static toolName;
+  /** Supported Interaction Types - currently only Mouse */
+  public supportedInteractionTypes: InteractionTypes[];
+  public configuration: Record<string, any>;
+  /** ToolGroup ID the tool instance belongs to */
+  public toolGroupId: string;
+  /** Tool Mode - Active/Passive/Enabled/Disabled/ */
+  public mode: ToolModes;
+
+  constructor(toolProps: PublicToolProps, defaultToolProps: ToolProps) {
+    const initialProps = utilities.deepMerge(defaultToolProps, toolProps);
+
+    const {
+      configuration = {},
+      supportedInteractionTypes,
+      toolGroupId,
+    } = initialProps;
+
+    // If strategies are not initialized in the tool config
+    if (!configuration.strategies) {
+      configuration.strategies = {};
+      configuration.defaultStrategy = undefined;
+      configuration.activeStrategy = undefined;
+      configuration.strategyOptions = {};
+    }
+
+    this.toolGroupId = toolGroupId;
+    this.supportedInteractionTypes = supportedInteractionTypes || [];
+    this.configuration = Object.assign({}, configuration);
+    this.mode = ToolModes.Disabled;
+  }
+
+  /**
+   * Returns the name of the tool
+   * @returns The name of the tool.
+   */
+  public getToolName(): string {
+    // Since toolName is static we get it from the class constructor
+    return (<typeof BaseTool>this.constructor).toolName;
+  }
+
+  /**
+   * It applies the active strategy to the enabled element.
+   * @param enabledElement - The element that is being operated on.
+   * @param operationData - The data that needs to be passed to the strategy.
+   * @returns The result of the strategy.
+   */
+  public applyActiveStrategy(
+    enabledElement: Types.IEnabledElement,
+    operationData: unknown
+  ): any {
+    const { strategies, activeStrategy } = this.configuration;
+    return strategies[activeStrategy].call(this, enabledElement, operationData);
+  }
+
+  /**
+   * merges the new configuration with the tool configuration
+   * @param configuration - toolConfiguration
+   */
+  public setConfiguration(newConfiguration: Record<string, any>): void {
+    this.configuration = utilities.deepMerge(
+      this.configuration,
+      newConfiguration
+    );
+  }
+
+  /**
+   * Sets the active strategy for a tool. Strategies are
+   * multiple implementations of tool behavior that can be switched by tool
+   * configuration.
+   *
+   * @param strategyName - name of the strategy to be set as active
+   */
+  public setActiveStrategy(strategyName: string): void {
+    this.setConfiguration({ activeStrategy: strategyName });
+  }
+
+  /**
+   * Returns the volumeId for the volume viewport. It will grabbed the volumeId
+   * from the volumeId if particularly specified in the tool configuration, or if
+   * not, the first actorUID in the viewport is returned as the volumeId. NOTE: for
+   * segmentations, actorUID is not necessarily the volumeId since the segmentation
+   * can have multiple representations, use segmentation helpers to get the volumeId
+   * based on the actorUID.
+   *
+   * @param viewport - Volume viewport
+   * @returns the volumeId for the viewport if specified in the tool configuration,
+   * or the first actorUID in the viewport if not.
+   */
+  private getTargetVolumeId(viewport: Types.IViewport): string | undefined {
+    if (this.configuration.volumeId) {
+      return this.configuration.volumeId;
+    }
+
+    // If volume not specified, then return the actorUID for the
+    // default actor - first actor
+    const actorEntries = viewport.getActors();
+
+    if (!actorEntries) {
+      return;
+    }
+
+    // find the first image actor of instance type vtkVolume
+    return actorEntries.find(
+      (actorEntry) => actorEntry.actor.getClassName() === 'vtkVolume'
+    )?.uid;
+  }
+
+  /**
+   * Get the image that is displayed for the targetId in the cachedStats
+   * which can be either imageId:<imageId> or volumeId:<volumeId>
+   *
+   * @param targetId - annotation targetId stored in the cached stats
+   * @param renderingEngine - The rendering engine
+   * @returns The image data for the target.
+   */
+  protected getTargetIdImage(
+    targetId: string,
+    renderingEngine: Types.IRenderingEngine
+  ): Types.IImageData | Types.CPUIImageData | Types.IImageVolume {
+    if (targetId.startsWith('imageId:')) {
+      const imageId = targetId.split('imageId:')[1];
+      const imageURI = utilities.imageIdToURI(imageId);
+      let viewports = utilities.getViewportsWithImageURI(
+        imageURI,
+        renderingEngine.id
+      );
+
+      if (!viewports || !viewports.length) {
+        return;
+      }
+
+      viewports = viewports.filter((viewport) => {
+        return viewport.getCurrentImageId() === imageId;
+      });
+
+      if (!viewports || !viewports.length) {
+        return;
+      }
+
+      return viewports[0].getImageData();
+    } else if (targetId.startsWith('volumeId:')) {
+      const volumeId = targetId.split('volumeId:')[1];
+      const viewports = utilities.getViewportsWithVolumeId(
+        volumeId,
+        renderingEngine.id
+      );
+
+      if (!viewports || !viewports.length) {
+        return;
+      }
+
+      return viewports[0].getImageData();
+    } else {
+      throw new Error(
+        'getTargetIdImage: targetId must start with "imageId:" or "volumeId:"'
+      );
+    }
+  }
+
+  /**
+   * Get the target Id for the viewport which will be used to store the cached
+   * statistics scoped to that target in the annotations.
+   * For StackViewport, targetId is the viewportId, but for the volume viewport,
+   * the targetId will be grabbed from the volumeId if particularly specified
+   * in the tool configuration, or if not, the first actorUID in the viewport.
+   *
+   * @param viewport - viewport to get the targetId for
+   * @returns targetId
+   */
+  protected getTargetId(viewport: Types.IViewport): string | undefined {
+    if (viewport instanceof StackViewport) {
+      return `imageId:${viewport.getCurrentImageId()}`;
+    } else if (viewport instanceof VolumeViewport) {
+      return `volumeId:${this.getTargetVolumeId(viewport)}`;
+    } else {
+      throw new Error(
+        'getTargetId: viewport must be a StackViewport or VolumeViewport'
+      );
+    }
+  }
+}
+
+// Note: this is a workaround since terser plugin does not support static blocks
+// yet and we can't easily say static toolName = "BaseTool" in the class definition.
+BaseTool.toolName = 'BaseTool';
+export default BaseTool;

package/src/tools/base/index.ts

@@ -0,0 +1,4 @@
+import BaseTool from './BaseTool';
+import AnnotationTool from './AnnotationTool';
+
+export { BaseTool, AnnotationTool };

package/src/tools/displayTools/Contour/addContourToElement.ts

@@ -0,0 +1,135 @@
+import { getEnabledElement, Types, Enums } from '@cornerstonejs/core';
+import vtkPolyData from '@kitware/vtk.js/Common/DataModel/PolyData';
+import vtkCellArray from '@kitware/vtk.js/Common/Core/CellArray';
+import vtkPoints from '@kitware/vtk.js/Common/Core/Points';
+import vtkMapper from '@kitware/vtk.js/Rendering/Core/Mapper';
+import vtkActor from '@kitware/vtk.js/Rendering/Core/Actor';
+
+// Todo: this seems to have performance issues when there are many contours
+// Maybe we should not create one actor per contour, but rather one actor per
+// contourSet?
+function addContourToElement(
+  element: HTMLDivElement,
+  contour: Types.IContour,
+  actorUID: string
+): void {
+  const enabledElement = getEnabledElement(element);
+  const { renderingEngine, viewport } = enabledElement;
+  const { id: viewportId } = viewport;
+
+  // Default to true since we are setting a new segmentation, however,
+  // in the event listener, we will make other segmentations visible/invisible
+  // based on the config
+  const visibility = true;
+  const immediateRender = false;
+  const suppressEvents = true;
+
+  const pointList = contour.getPoints();
+  const flatPoints = contour.getFlatPointsArray();
+  const color = contour.getColor();
+  const type = contour.getType();
+
+  const p = pointList.map((_, i) => i);
+
+  if (type === Enums.ContourType.CLOSED_PLANAR) {
+    p.push(0);
+  }
+
+  const var1 = Float32Array.from(flatPoints);
+  const var2 = Uint32Array.from([p.length, ...p]);
+
+  const colorToUse = color.map((c) => c / 255);
+
+  const points = vtkPoints.newInstance();
+  points.setData(var1, 3);
+
+  const lines = vtkCellArray.newInstance();
+  // @ts-ignore
+  lines.setData(var2, 3);
+
+  const polygon = vtkPolyData.newInstance();
+  polygon.setPoints(points);
+  polygon.setLines(lines);
+
+  const mapper1 = vtkMapper.newInstance();
+  mapper1.setInputData(polygon);
+  const actor1 = vtkActor.newInstance();
+  actor1.setMapper(mapper1);
+  actor1.getProperty().setLineWidth(4);
+  actor1.getProperty().setColor(colorToUse[0], colorToUse[1], colorToUse[2]);
+
+  viewport.addActor({ actor: actor1, uid: actorUID });
+}
+
+function addContourSetToElement(
+  element: HTMLDivElement,
+  contourSet: Types.IContourSet,
+  actorUID: string
+): void {
+  const enabledElement = getEnabledElement(element);
+  const { renderingEngine, viewport } = enabledElement;
+  const { id: viewportId } = viewport;
+
+  // Default to true since we are setting a new segmentation, however,
+  // in the event listener, we will make other segmentations visible/invisible
+  // based on the config
+  const visibility = true;
+  const immediateRender = false;
+  const suppressEvents = true;
+
+  const actor1 = vtkActor.newInstance();
+  let color;
+
+  const pointArray = [];
+
+  const points = vtkPoints.newInstance();
+  const lines = vtkCellArray.newInstance();
+
+  // this variable will indicate the index of the first point in the current line
+  // so we can correctly generate the point index list to add in the cellArray
+  let pointIndex = 0;
+  contourSet.getContours().forEach((contour: Types.IContour) => {
+    const pointList = contour.getPoints();
+    const flatPoints = contour.getFlatPointsArray();
+    color = contour.getColor();
+    const type = contour.getType();
+
+    // creating a point index list that defines a line
+    const pointIndexes = pointList.map((_, i) => i + pointIndex);
+
+    // if close planar, add the first point index to the list
+    if (type === Enums.ContourType.CLOSED_PLANAR) {
+      pointIndexes.push(pointIndexes[0]);
+    }
+
+    const linePoints = Float32Array.from(flatPoints);
+    // add the curent points into the point list
+    pointArray.push(...linePoints);
+    // add the point indexes into the cell array
+    lines.insertNextCell([...pointIndexes]);
+    // update the first point index
+    pointIndex = pointIndex + pointList.length;
+  });
+
+  // converts the pointArray into vtkPoints
+  points.setData(pointArray, 3);
+
+  // creates the polydata
+  const polygon = vtkPolyData.newInstance();
+  polygon.setPoints(points);
+  polygon.setLines(lines);
+
+  const mapper1 = vtkMapper.newInstance();
+  mapper1.setInputData(polygon);
+  actor1.setMapper(mapper1);
+  actor1.getProperty().setLineWidth(4);
+
+  // despite each contour can have its own color, we assign the last color to
+  // all contours
+  const colorToUse = color.map((c) => c / 255);
+  actor1.getProperty().setColor(colorToUse[0], colorToUse[1], colorToUse[2]);
+
+  viewport.addActor({ actor: actor1, uid: actorUID });
+}
+
+export { addContourToElement, addContourSetToElement };