@cornerstonejs/tools 1.20.2 → 1.21.0

package/src/tools/AdvancedMagnifyViewportManager.ts

@@ -0,0 +1,291 @@
+import { vec3 } from 'gl-matrix';
+import {
+  eventTarget,
+  Enums,
+  getRenderingEngine,
+  CONSTANTS,
+} from '@cornerstonejs/core';
+import type { Types } from '@cornerstonejs/core';
+import { AnnotationRemovedEventType } from '../types/EventTypes';
+import { Events as cstEvents } from '../enums';
+import {
+  AdvancedMagnifyViewport,
+  AutoPanCallback,
+} from './AdvancedMagnifyViewport';
+import { AdvancedMagnifyAnnotation } from '../types/ToolSpecificAnnotationTypes';
+
+// Defined the tool name internally instead of importing
+// AdvangedMagnifyTool due to cyclic dependency
+const ADVANCED_MAGNIFY_TOOL_NAME = 'AdvancedMagnify';
+
+const PARALLEL_THRESHOLD = 1 - CONSTANTS.EPSILON;
+const { Events } = Enums;
+
+export type MagnifyViewportInfo = {
+  // Viewport id to be used or new v4 compliant GUID is used instead
+  magnifyViewportId?: string;
+  // Enabled element where the magnifying glass shall be added to
+  sourceEnabledElement: Types.IEnabledElement;
+  // Magnifying glass position (center)
+  position: Types.Point2;
+  // Magnifying glass radius (pixels)
+  radius: number;
+  // Amount of magnification applied to the magnifying glass image compared to the source viewport.
+  zoomFactor: number;
+  // Allow panning the viewport when moving an annotation point close to the border of the magnifying glass
+  autoPan: {
+    // Enable or disable auto pan
+    enabled: boolean;
+    // Minimum distance to the border before start auto panning
+    padding: number;
+    // Callback function responsible for updating the annotation (circle)
+    // that contains the magnifying viewport
+    callback: AutoPanCallback;
+  };
+};
+
+type MagnifyViewportsMapEntry = {
+  annotation: AdvancedMagnifyAnnotation;
+  magnifyViewport: AdvancedMagnifyViewport;
+};
+
+/**
+ * Manager responsible for creating, storing and destroying magnifying glass
+ * viewports. There are no restrictions to create a new instance of it but it
+ * should be accessed through getInstance() method.
+ */
+class AdvancedMagnifyViewportManager {
+  private static _singleton: AdvancedMagnifyViewportManager;
+  private _magnifyViewportsMap: Map<string, MagnifyViewportsMapEntry>;
+
+  constructor() {
+    this._magnifyViewportsMap = new Map();
+    this._initialize();
+  }
+
+  /**
+   * Creates a new magnifying glass viewport manager instance when this method is
+   * called for the first time or return the instance previously created for
+   * any subsequent call (singleton pattern).
+   * @returns A magnifying viewport manager instance
+   */
+  public static getInstance(): AdvancedMagnifyViewportManager {
+    AdvancedMagnifyViewportManager._singleton =
+      AdvancedMagnifyViewportManager._singleton ??
+      new AdvancedMagnifyViewportManager();
+
+    return AdvancedMagnifyViewportManager._singleton;
+  }
+
+  /**
+   * Creates a new magnifying glass viewport instance
+   * @param viewportInfo - Viewport data used when creating a new magnifying glass viewport
+   * @returns A magnifying glass viewport instance
+   */
+  public createViewport = (
+    annotation: AdvancedMagnifyAnnotation,
+    viewportInfo: MagnifyViewportInfo
+  ): AdvancedMagnifyViewport => {
+    const {
+      magnifyViewportId,
+      sourceEnabledElement,
+      position,
+      radius,
+      zoomFactor,
+      autoPan,
+    } = viewportInfo;
+    const { viewport: sourceViewport } = sourceEnabledElement;
+    const { element: sourceElement } = sourceViewport;
+
+    const magnifyViewport = new AdvancedMagnifyViewport({
+      magnifyViewportId,
+      sourceEnabledElement,
+      radius,
+      position,
+      zoomFactor,
+      autoPan,
+    });
+
+    this._addSourceElementEventListener(sourceElement);
+    this._magnifyViewportsMap.set(magnifyViewport.viewportId, {
+      annotation,
+      magnifyViewport,
+    });
+
+    return magnifyViewport;
+  };
+
+  /**
+   * Find and return a magnifying glass viewport based on its id
+   * @param magnifyViewportId - Magnifying glass viewport id
+   * @returns A magnifying glass viewport instance
+   */
+  public getViewport(magnifyViewportId: string): AdvancedMagnifyViewport {
+    return this._magnifyViewportsMap.get(magnifyViewportId)?.magnifyViewport;
+  }
+
+  /**
+   * Release all magnifying glass viewport instances and remove all event
+   * listeners making all objects available to be garbage collected.
+   */
+  public dispose() {
+    this._removeEventListeners();
+    this._destroyViewports();
+  }
+
+  private _destroyViewport(magnifyViewportId: string) {
+    const magnifyViewportMapEntry =
+      this._magnifyViewportsMap.get(magnifyViewportId);
+
+    if (magnifyViewportMapEntry) {
+      const { magnifyViewport } = magnifyViewportMapEntry;
+      const { viewport: sourceViewport } = magnifyViewport.sourceEnabledElement;
+      const { element: sourceElement } = sourceViewport;
+
+      this._removeSourceElementEventListener(sourceElement);
+
+      magnifyViewport.dispose();
+      this._magnifyViewportsMap.delete(magnifyViewportId);
+    }
+  }
+
+  private _destroyViewports() {
+    const magnifyViewportIds = Array.from(this._magnifyViewportsMap.keys());
+
+    magnifyViewportIds.forEach((magnifyViewportId) =>
+      this._destroyViewport(magnifyViewportId)
+    );
+  }
+
+  private _annotationRemovedCallback = (evt: AnnotationRemovedEventType) => {
+    const { annotation } = evt.detail;
+
+    if (annotation.metadata.toolName !== ADVANCED_MAGNIFY_TOOL_NAME) {
+      return;
+    }
+
+    this._destroyViewport(annotation.data.magnifyViewportId);
+  };
+
+  private _getMagnifyViewportsMapEntriesBySourceViewportId(sourceViewportId) {
+    const magnifyViewportsMapEntries = Array.from(
+      this._magnifyViewportsMap.values()
+    );
+
+    return magnifyViewportsMapEntries.filter(({ magnifyViewport }) => {
+      const { viewport } = magnifyViewport.sourceEnabledElement;
+      return viewport.id === sourceViewportId;
+    });
+  }
+
+  private _newStackImageCallback = (
+    evt: Types.EventTypes.StackNewImageEvent
+  ) => {
+    const { viewportId: sourceViewportId, imageId } = evt.detail;
+    const magnifyViewportsMapEntries =
+      this._getMagnifyViewportsMapEntriesBySourceViewportId(sourceViewportId);
+
+    magnifyViewportsMapEntries.forEach(({ annotation }) => {
+      annotation.metadata.referencedImageId = imageId;
+      annotation.invalidated = true;
+    });
+  };
+
+  private _newVolumeImageCallback = (
+    evt: Types.EventTypes.VolumeNewImageEvent
+  ) => {
+    const { renderingEngineId, viewportId: sourceViewportId } = evt.detail;
+    const renderingEngine = getRenderingEngine(renderingEngineId);
+    const sourceViewport = renderingEngine.getViewport(sourceViewportId);
+    const { viewPlaneNormal: currentViewPlaneNormal } =
+      sourceViewport.getCamera();
+
+    const magnifyViewportsMapEntries =
+      this._getMagnifyViewportsMapEntriesBySourceViewportId(sourceViewportId);
+
+    magnifyViewportsMapEntries.forEach(({ annotation }) => {
+      const { viewPlaneNormal } = annotation.metadata;
+
+      // Compare the normal to make sure the volume is not rotate in 3D space
+      const isParallel =
+        Math.abs(vec3.dot(viewPlaneNormal, currentViewPlaneNormal)) >
+        PARALLEL_THRESHOLD;
+
+      if (!isParallel) {
+        return;
+      }
+
+      const { handles } = annotation.data;
+      const worldImagePlanePoint = sourceViewport.canvasToWorld([0, 0]);
+      const vecHandleToImagePlane = vec3.sub(
+        vec3.create(),
+        worldImagePlanePoint,
+        handles.points[0]
+      );
+      const worldDist = vec3.dot(vecHandleToImagePlane, currentViewPlaneNormal);
+      const worldDelta = vec3.scale(
+        vec3.create(),
+        currentViewPlaneNormal,
+        worldDist
+      );
+
+      // Move all handle points to the image plane to make the annotation visible
+      for (let i = 0, len = handles.points.length; i < len; i++) {
+        const point = handles.points[i];
+
+        point[0] += worldDelta[0];
+        point[1] += worldDelta[1];
+        point[2] += worldDelta[2];
+      }
+
+      annotation.invalidated = true;
+    });
+  };
+
+  private _addEventListeners() {
+    eventTarget.addEventListener(
+      cstEvents.ANNOTATION_REMOVED,
+      this._annotationRemovedCallback
+    );
+  }
+
+  private _removeEventListeners() {
+    eventTarget.removeEventListener(
+      cstEvents.ANNOTATION_REMOVED,
+      this._annotationRemovedCallback
+    );
+  }
+
+  private _addSourceElementEventListener(element) {
+    element.addEventListener(
+      Events.STACK_NEW_IMAGE,
+      this._newStackImageCallback
+    );
+
+    element.addEventListener(
+      Events.VOLUME_NEW_IMAGE,
+      this._newVolumeImageCallback
+    );
+  }
+
+  private _removeSourceElementEventListener(element) {
+    element.removeEventListener(
+      Events.STACK_NEW_IMAGE,
+      this._newStackImageCallback
+    );
+
+    element.removeEventListener(
+      Events.VOLUME_NEW_IMAGE,
+      this._newVolumeImageCallback
+    );
+  }
+
+  private _initialize() {
+    this._addEventListeners();
+  }
+}
+
+export {
+  AdvancedMagnifyViewportManager as default,
+  AdvancedMagnifyViewportManager,
+};

package/src/tools/annotation/EllipticalROITool.ts

@@ -125,7 +125,7 @@ class EllipticalROITool extends AnnotationTool {
     viewportIdsToRender: Array<string>;
     handleIndex?: number;
     movingTextBox?: boolean;
-    centerCanvas?: Array<number>;
+    centerWorld?: Array<number>;
     canvasWidth?: number;
     canvasHeight?: number;
     originalHandleCanvas?: Array<number>;
@@ -238,7 +238,7 @@ class EllipticalROITool extends AnnotationTool {
     this.editData = {
       annotation,
       viewportIdsToRender,
-      centerCanvas: canvasPos,
+      centerWorld: worldPos,
       newAnnotation: true,
       hasMoved: false,
     };
@@ -365,6 +365,7 @@ class EllipticalROITool extends AnnotationTool {
     let handleIndex;
 
     let centerCanvas;
+    let centerWorld;
     let canvasWidth;
     let canvasHeight;
     let originalHandleCanvas;
@@ -373,8 +374,8 @@ class EllipticalROITool extends AnnotationTool {
       movingTextBox = true;
     } else {
       const { points } = data.handles;
-      const enabledElement = getEnabledElement(element);
-      const { worldToCanvas } = enabledElement.viewport;
+      const { viewport } = getEnabledElement(element);
+      const { worldToCanvas, canvasToWorld } = viewport;
 
       handleIndex = points.findIndex((p) => p === handle);
 
@@ -389,6 +390,8 @@ class EllipticalROITool extends AnnotationTool {
         (pointsCanvas[2][0] + pointsCanvas[3][0]) / 2,
         (pointsCanvas[0][1] + pointsCanvas[1][1]) / 2,
       ];
+
+      centerWorld = canvasToWorld(centerCanvas);
     }
 
     // Find viewports to render on drag.
@@ -403,7 +406,7 @@ class EllipticalROITool extends AnnotationTool {
       handleIndex,
       canvasWidth,
       canvasHeight,
-      centerCanvas,
+      centerWorld,
       originalHandleCanvas,
       movingTextBox,
     };
@@ -480,7 +483,8 @@ class EllipticalROITool extends AnnotationTool {
     const { canvasToWorld } = viewport;
 
     //////
-    const { annotation, viewportIdsToRender, centerCanvas } = this.editData;
+    const { annotation, viewportIdsToRender, centerWorld } = this.editData;
+    const centerCanvas = viewport.worldToCanvas(centerWorld as Types.Point3);
     const { data } = annotation;
 
     const dX = Math.abs(currentCanvasPoints[0] - centerCanvas[0]);
@@ -554,17 +558,18 @@ class EllipticalROITool extends AnnotationTool {
   _dragHandle = (evt: EventTypes.InteractionEventType): void => {
     const eventDetail = evt.detail;
     const { element } = eventDetail;
-    const enabledElement = getEnabledElement(element);
-    const { canvasToWorld } = enabledElement.viewport;
+    const { viewport } = getEnabledElement(element);
+    const { canvasToWorld, worldToCanvas } = viewport;
 
     const {
       annotation,
       canvasWidth,
       canvasHeight,
       handleIndex,
-      centerCanvas,
+      centerWorld,
       originalHandleCanvas,
     } = this.editData;
+    const centerCanvas = viewport.worldToCanvas(centerWorld as Types.Point3);
     const { data } = annotation;
     const { points } = data.handles;
 

package/src/tools/index.ts

@@ -10,6 +10,7 @@ import VolumeRotateMouseWheelTool from './VolumeRotateMouseWheelTool';
 import MIPJumpToClickTool from './MIPJumpToClickTool';
 import CrosshairsTool from './CrosshairsTool';
 import MagnifyTool from './MagnifyTool';
+import AdvancedMagnifyTool from './AdvancedMagnifyTool';
 import ReferenceLinesTool from './ReferenceLinesTool';
 import OverlayGridTool from './OverlayGridTool';
 //
@@ -82,6 +83,7 @@ export {
   RectangleROIStartEndThresholdTool,
   BrushTool,
   MagnifyTool,
+  AdvancedMagnifyTool,
   ReferenceLines,
   PaintFillTool,
   ScaleOverlayTool,

package/src/types/EventTypes.ts

@@ -5,6 +5,7 @@ import ITouchPoints from './ITouchPoints';
 import IDistance from './IDistance';
 import { SetToolBindingsType } from './ISetToolModeOptions';
 import { Swipe } from '../enums/Touch';
+import { ToolModes } from '../enums';
 
 /**
  * The normalized interaction event detail
@@ -71,6 +72,20 @@ type InteractionStartEventDetail = InteractionEventDetail;
 
 type InteractionEndEventDetail = InteractionEventDetail;
 
+/**
+ * The data that is passed to the event handler when tool mode changes
+ */
+type ToolModeChangedEventDetail = {
+  /** unique id of the toolGroup */
+  toolGroupId: string;
+  /** Tool name */
+  toolName: string;
+  /** Tool mode */
+  mode: ToolModes;
+  /** Tool binding options */
+  toolBindingsOptions?: SetToolBindingsType;
+};
+
 /**
  * The data that is passed to the event handler when a tool is activated.
  */
@@ -424,6 +439,12 @@ type NormalizedMouseEventType = Types.CustomEventType<MouseCustomEventDetail>;
  */
 type NormalizedTouchEventType = Types.CustomEventType<TouchCustomEventDetail>;
 
+/**
+ * The ToolModeChanged event type
+ */
+type ToolModeChangedEventType =
+  Types.CustomEventType<ToolModeChangedEventDetail>;
+
 /**
  * The ToolActivated event type
  */
@@ -629,6 +650,8 @@ export {
   NormalizedInteractionEventDetail,
   NormalizedMouseEventType,
   NormalizedTouchEventType,
+  ToolModeChangedEventDetail,
+  ToolModeChangedEventType,
   ToolActivatedEventDetail,
   ToolActivatedEventType,
   AnnotationAddedEventDetail,

package/src/types/IToolGroup.ts

@@ -75,4 +75,11 @@ export default interface IToolGroup {
   getDefaultMousePrimary: {
     (): MouseBindings;
   };
+
+  clone: {
+    (
+      newToolGroupId: string,
+      fnToolFilter: (toolName: string) => boolean
+    ): IToolGroup;
+  };
 }

package/src/types/ToolAction.ts

@@ -0,0 +1,54 @@
+import type { Annotation } from './AnnotationTypes';
+import type { InteractionEventType } from './EventTypes';
+import type { SetToolBindingsType } from './ISetToolModeOptions';
+
+/**
+ * An action that may be defined at the tool configuration level
+ *
+ * Annotations can have actions that run a specific task (ex: showing a dropdown
+ * containing a list of all predefined zoom levels - advanced magnifier glass).
+ * Each action must have at least one binding option (mouse button + [modifier(s)])
+ * and a action runs if and only if no other tool is using that same binding options
+ * to draw an annotation because action has lower priority.
+ *
+ * Actions are defined in the following way in a annotation tool constructor:
+ *
+ * class MyAnnotationTool extends AnnotationTool {
+ *   constructor(
+ *     toolProps: PublicToolProps = {},
+ *     defaultToolProps: ToolProps = {
+ *       configuration: {
+ *         actions: [
+ *           {
+ *             method: 'myAction',
+ *             bindings: [
+ *               {
+ *                 mouseButton: MouseBindings.Secondary,
+ *                 modifierKey: KeyboardBindings.Shift,
+ *               }
+ *             ]
+ *           }
+ *         ]
+ *       }
+ *     }
+ *   ) {
+ *     super(toolProps, defaultToolProps);
+ *   }
+ *
+ *   public myAction(evt: EventTypes.InteractionEventType, annotation: MyAnnotation) {
+ *     // action code
+ *   }
+ * }
+ *
+ * The "method" property may be a string or a javascript function. In case it is
+ * a string a function with same name must exists in the tool class. In both ways
+ * (string or function) the function is called in the tool's context (`this`)
+ */
+type ToolAction = {
+  method:
+    | string
+    | ((evt: InteractionEventType, annotation: Annotation) => void);
+  bindings: SetToolBindingsType[];
+};
+
+export default ToolAction;

package/src/types/ToolSpecificAnnotationTypes.ts

@@ -78,6 +78,18 @@ export interface LengthAnnotation extends Annotation {
   };
 }
 
+export interface AdvancedMagnifyAnnotation extends Annotation {
+  data: {
+    zoomFactor: number;
+    sourceViewportId: string;
+    magnifyViewportId: string;
+    handles: {
+      points: Types.Point3[]; // [top, right, bottom, left]
+      activeHandleIndex: number | null;
+    };
+  };
+}
+
 export interface CircleROIAnnotation extends Annotation {
   data: {
     handles: {

package/src/types/index.ts

@@ -21,6 +21,7 @@ import type * as AnnotationStyle from './AnnotationStyle';
 import type ToolHandle from './ToolHandle';
 import type { AnnotationHandle, TextBoxHandle } from './ToolHandle';
 import type InteractionTypes from './InteractionTypes';
+import type ToolAction from './ToolAction';
 import type {
   ToolProps,
   PublicToolProps,
@@ -84,6 +85,7 @@ export type {
   SetToolBindingsType,
   ToolOptionsType,
   InteractionTypes,
+  ToolAction,
   //
   IToolGroup,
   IToolClassReference,