@cornerstonejs/tools 1.51.5 → 1.53.0

package/src/tools/annotation/LivewireContourTool.ts

@@ -1,49 +1,46 @@
 import { vec3 } from 'gl-matrix';
-
 import {
   getEnabledElement,
-  triggerEvent,
-  eventTarget,
   utilities as csUtils,
   VolumeViewport,
 } from '@cornerstonejs/core';
 import type { Types } from '@cornerstonejs/core';
+
 import { removeAnnotation } from '../../stateManagement/annotation/annotationState';
 import { drawHandles as drawHandlesSvg } from '../../drawingSvg';
 import { state } from '../../store';
-import { Events, ChangeTypes } from '../../enums';
+import { Events, KeyboardBindings, ChangeTypes } from '../../enums';
 import { resetElementCursor } from '../../cursors/elementCursor';
 import type {
-  Annotation,
   EventTypes,
   ToolHandle,
   PublicToolProps,
   ToolProps,
   SVGDrawingHelper,
 } from '../../types';
+import getMouseModifierKey from '../../eventDispatchers/shared/getMouseModifier';
 import { math, triggerAnnotationRenderForViewportIds } from '../../utilities';
 import findHandlePolylineIndex from '../../utilities/contours/findHandlePolylineIndex';
 import { LivewireContourAnnotation } from '../../types/ToolSpecificAnnotationTypes';
+import { ContourWindingDirection } from '../../types/ContourAnnotation';
 import {
-  AnnotationCompletedEventDetail,
-  AnnotationModifiedEventDetail,
-} from '../../types/EventTypes';
-import reverseIfAntiClockwise from '../../utilities/contours/reverseIfAntiClockwise';
+  triggerAnnotationModified,
+  triggerContourAnnotationCompleted,
+} from '../../stateManagement/annotation/helpers/state';
 
 import { LivewireScissors } from '../../utilities/livewire/LivewireScissors';
 import { LivewirePath } from '../../utilities/livewire/LiveWirePath';
 import { getViewportIdsWithToolToRender } from '../../utilities/viewportFilters';
 import ContourSegmentationBaseTool from '../base/ContourSegmentationBaseTool';
-
-const { isEqual } = csUtils;
+import updateContourPolyline from '../../utilities/contours/updateContourPolyline';
 
 const CLICK_CLOSE_CURVE_SQR_DIST = 10 ** 2; // px
 
 class LivewireContourTool extends ContourSegmentationBaseTool {
   public static toolName: string;
-  private scissors: LivewireScissors;
+  protected scissors: LivewireScissors;
   /** The scissors from the right handle, used for editing */
-  private scissorsRight: LivewireScissors;
+  protected scissorsRight: LivewireScissors;
 
   touchDragCallback: any;
   mouseDragCallback: any;
@@ -62,6 +59,7 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
     worldToSlice?: (point: Types.Point3) => Types.Point2;
     sliceToWorld?: (point: Types.Point2) => Types.Point3;
     originalPath?: Types.Point3[];
+    contourHoleProcessingEnabled?: boolean;
   } | null;
   isDrawing: boolean;
   isHandleOutsideImage = false;
@@ -72,13 +70,67 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
       supportedInteractionTypes: ['Mouse', 'Touch'],
       configuration: {
         preventHandleOutsideImage: false,
+        /**
+         * Specify which modifier key is used to add a hole to a contour. The
+         * modifier must be pressed when the first point of a new contour is added.
+         */
+        contourHoleAdditionModifierKey: KeyboardBindings.Shift,
+
+        /**
+         * Configuring this to a value larger than 0 will snap handles to nearby
+         * livewire points, within the given rectangle surrounding the clicked point.
+         * If set to 0, then the exact clicked point will be used instead, which may
+         * not be an edge and can result in jagged outlines.
+         * The unit is image pixels (index).
+         */
+        snapHandleNearby: 2,
+
+        /**
+         * Interpolation is only available for segmentation versions of these
+         * tools.  To use it on the segmentation tools, set enabled to true,
+         * and create two livewire contours in the same segment index, separated
+         * by at least one slice.
+         */
+        interpolation: {
+          enabled: false,
+
+          /**
+           * Set the nearestEdge to snap interpolated handles to an edge within
+           * the given number of pixels.  Setting to 0 disables snap to pixel
+           * for interpolation and the interpolated point will be used directly.
+           * Setting to too large a value may result in many points outside the contour
+           * being chosen.
+           */
+          nearestEdge: 2,
+          /**
+           * Set to true to show the interpolated polyline, which can be useful
+           * when understanding the nearest edge and
+           */
+          showInterpolationPolyline: false,
+        },
+        actions: {
+          undo: {
+            method: 'undo',
+            bindings: [
+              {
+                key: 'Escape',
+              },
+            ],
+          },
+        },
       },
     }
   ) {
     super(toolProps, defaultToolProps);
   }
 
-  protected setupBaseEditData(worldPos, element, annotation, rightPos?) {
+  protected setupBaseEditData(
+    worldPos,
+    element,
+    annotation,
+    rightPos?,
+    contourHoleProcessingEnabled?
+  ) {
     const enabledElement = getEnabledElement(element);
     const { viewport } = enabledElement;
 
@@ -196,6 +248,7 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
         this.editData?.handleIndex ?? annotation.handles?.activeHandleIndex,
       worldToSlice,
       sliceToWorld,
+      contourHoleProcessingEnabled,
     };
   }
 
@@ -214,9 +267,18 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
     const { currentPoints, element } = eventDetail;
     const { world: worldPos } = currentPoints;
     const { renderingEngine } = getEnabledElement(element);
-    const annotation = this.createAnnotation(evt) as LivewireContourAnnotation;
+    const annotation = this.createAnnotation(evt);
+    const contourHoleProcessingEnabled =
+      getMouseModifierKey(evt.detail.event) ===
+      this.configuration.contourHoleAdditionModifierKey;
 
-    this.setupBaseEditData(worldPos, element, annotation);
+    this.setupBaseEditData(
+      worldPos,
+      element,
+      annotation,
+      undefined,
+      contourHoleProcessingEnabled
+    );
     this.addAnnotation(annotation, element);
 
     this._activateDraw(element);
@@ -335,11 +397,19 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
     evt.preventDefault();
   };
 
-  _endCallback = (evt: EventTypes.InteractionEventType): void => {
+  _endCallback = (
+    evt: EventTypes.InteractionEventType,
+    clearAnnotation = false
+  ): void => {
     const eventDetail = evt.detail;
     const { element } = eventDetail;
 
-    const { annotation, viewportIdsToRender, newAnnotation } = this.editData;
+    const {
+      annotation,
+      viewportIdsToRender,
+      newAnnotation,
+      contourHoleProcessingEnabled,
+    } = this.editData;
     const { data } = annotation;
 
     data.handles.activeHandleIndex = null;
@@ -353,21 +423,17 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
     const { renderingEngine } = enabledElement;
 
     if (
-      this.isHandleOutsideImage &&
-      this.configuration.preventHandleOutsideImage
+      (this.isHandleOutsideImage &&
+        this.configuration.preventHandleOutsideImage) ||
+      clearAnnotation
     ) {
       removeAnnotation(annotation.annotationUID);
-    }
-
-    // Reverse the points if needed, ensuring both the handles and the
-    // polyline is also reversed.
-    const { worldToSlice } = this.editData;
-    if (worldToSlice) {
-      reverseIfAntiClockwise(
-        data.handles.points.map(worldToSlice),
-        data.handles.points,
-        data.contour.polyline
+      this.clearEditData();
+      triggerAnnotationRenderForViewportIds(
+        renderingEngine,
+        viewportIdsToRender
       );
+      return;
     }
 
     triggerAnnotationRenderForViewportIds(renderingEngine, viewportIdsToRender);
@@ -376,48 +442,21 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
       ? ChangeTypes.Completed
       : ChangeTypes.HandlesUpdated;
 
-    this.triggerChangeEvent(annotation, enabledElement, changeType);
+    this.triggerChangeEvent(
+      annotation,
+      enabledElement,
+      changeType,
+      contourHoleProcessingEnabled
+    );
+    this.clearEditData();
+  };
 
+  protected clearEditData() {
     this.editData = null;
     this.scissors = null;
     this.scissorsRight = null;
     this.isDrawing = false;
-  };
-
-  /**
-   * Triggers an annotation completed event.
-   */
-  triggerAnnotationCompleted = (
-    annotation: LivewireContourAnnotation
-  ): void => {
-    const eventType = Events.ANNOTATION_COMPLETED;
-    const eventDetail: AnnotationCompletedEventDetail = {
-      annotation,
-      changeType: ChangeTypes.Completed,
-    };
-
-    triggerEvent(eventTarget, eventType, eventDetail);
-  };
-
-  /**
-   * Triggers an annotation modified event.
-   */
-  triggerAnnotationModified = (
-    annotation: LivewireContourAnnotation,
-    enabledElement: Types.IEnabledElement,
-    changeType = ChangeTypes.StatsUpdated
-  ): void => {
-    const { viewportId, renderingEngineId } = enabledElement;
-    const eventType = Events.ANNOTATION_MODIFIED;
-    const eventDetail: AnnotationModifiedEventDetail = {
-      annotation,
-      viewportId,
-      renderingEngineId,
-      changeType,
-    };
-
-    triggerEvent(eventTarget, eventType, eventDetail);
-  };
+  }
 
   /**
    * Triggers an annotation complete or modified event based on changeType.
@@ -425,12 +464,20 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
   triggerChangeEvent = (
     annotation: LivewireContourAnnotation,
     enabledElement: Types.IEnabledElement,
-    changeType = ChangeTypes.StatsUpdated
+    changeType = ChangeTypes.StatsUpdated,
+    contourHoleProcessingEnabled = false
   ): void => {
     if (changeType === ChangeTypes.Completed) {
-      this.triggerAnnotationCompleted(annotation);
+      triggerContourAnnotationCompleted(
+        annotation,
+        contourHoleProcessingEnabled
+      );
     } else {
-      this.triggerAnnotationModified(annotation, enabledElement, changeType);
+      triggerAnnotationModified(
+        annotation,
+        enabledElement.viewport.element,
+        changeType
+      );
     }
   };
 
@@ -485,25 +532,24 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
       }
     }
 
-    this.editData.closed = this.editData.closed || closePath;
-    this.editData.confirmedPath = this.editData.currentPath;
-
-    const smoothPathCount = this.scissors.smoothPathCount(
-      this.editData.confirmedPath.pointArray,
-      this.editData.currentPath.getLastControlPoint()
-    );
-    if (smoothPathCount) {
-      this.editData.currentPath.removeLastPoints(smoothPathCount);
-      annotation.data.contour.polyline.splice(
-        annotation.data.contour.polyline.length - smoothPathCount,
-        smoothPathCount
+    const { snapHandleNearby } = this.configuration;
+    // Snap the handles as they get created, but not during edit
+    if (snapHandleNearby && !this.editData.closed) {
+      const currentPath = new LivewirePath();
+      const snapPoint = this.scissors.findMinNearby(
+        worldToSlice(worldPosOriginal),
+        1
       );
-      worldPos =
-        annotation.data.contour.polyline[
-          annotation.data.contour.polyline.length - 1
-        ];
+      const pathPoints = this.scissors.findPathToPoint(snapPoint);
+      currentPath.addPoints(pathPoints);
+      currentPath.prependPath(this.editData.confirmedPath);
+      worldPos = sliceToWorld(snapPoint);
+      this.editData.currentPath = currentPath;
     }
 
+    this.editData.closed = this.editData.closed || closePath;
+    this.editData.confirmedPath = this.editData.currentPath;
+
     // Add the current cursor position as a new control point after clicking
     const lastPoint = this.editData.currentPath.getLastPoint();
 
@@ -518,7 +564,7 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
 
     if (this.editData.closed) {
       // Update the annotation because `editData` will be set to null
-      this._updateAnnotation(element, this.editData.confirmedPath);
+      this.updateAnnotation(this.editData.confirmedPath);
       this._endCallback(evt);
     }
 
@@ -624,7 +670,7 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
 
     const { activeHandleIndex } = data.handles;
     if (activeHandleIndex === null || activeHandleIndex === undefined) {
-      data.handle.activeHandleIndex = handleIndex;
+      data.handles.activeHandleIndex = handleIndex;
     } else if (activeHandleIndex !== handleIndex) {
       throw new Error(
         `Trying to edit a different handle than the one currently being edited ${handleIndex}!==${data.handles.activeHandleIndex}`
@@ -769,26 +815,23 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
     enabledElement: Types.IEnabledElement,
     svgDrawingHelper: SVGDrawingHelper
   ): boolean {
-    const { viewport } = enabledElement;
-    const { element } = viewport;
-
     // Update the annotation that is in editData (being edited)
-    this._updateAnnotation(element, this.editData?.currentPath);
+    this.updateAnnotation(this.editData?.currentPath);
 
     return super.renderAnnotation(enabledElement, svgDrawingHelper);
   }
 
   protected isContourSegmentationTool(): boolean {
-    // Disable contour segmenatation behavior because it shall be activated only
+    // Disable contour segmentation behavior because it shall be activated only
     // for LivewireContourSegmentationTool
     return false;
   }
 
-  protected createAnnotation(evt: EventTypes.InteractionEventType): Annotation {
+  protected createAnnotation(evt: EventTypes.InteractionEventType) {
     const contourSegmentationAnnotation = super.createAnnotation(evt);
     const { world: worldPos } = evt.detail.currentPoints;
 
-    return <LivewireContourAnnotation>csUtils.deepMerge(
+    const annotation = <LivewireContourAnnotation>csUtils.deepMerge(
       contourSegmentationAnnotation,
       {
         data: {
@@ -798,6 +841,21 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
         },
       }
     );
+    return annotation;
+  }
+
+  /**
+   * Clears any in progress edits, mostly used to get rid of accidentally started
+   * contours that happen on clicking not quite the right handle point.
+   * Eventually this is to be replaced with a proper undo, once that framework
+   * is available.
+   */
+  public undo(element, config, evt) {
+    if (!this.editData) {
+      // TODO - proper undo
+      return;
+    }
+    this._endCallback(evt, true);
   }
 
   /**
@@ -808,14 +866,15 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
   protected renderAnnotationInstance(renderContext: {
     enabledElement: Types.IEnabledElement;
     targetId: string;
-    annotation: Annotation;
+    annotation: LivewireContourAnnotation;
     annotationStyle: Record<string, any>;
     svgDrawingHelper: SVGDrawingHelper;
   }): boolean {
-    const { enabledElement, svgDrawingHelper, annotationStyle } = renderContext;
+    const { annotation, enabledElement, svgDrawingHelper, annotationStyle } =
+      renderContext;
+
     const { viewport } = enabledElement;
     const { worldToCanvas } = viewport;
-    const annotation = renderContext.annotation as LivewireContourAnnotation;
     const { annotationUID, data, highlighted } = annotation;
     const { handles } = data;
     const newAnnotation = this.editData?.newAnnotation;
@@ -851,30 +910,29 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
     return true;
   }
 
-  private _updateAnnotation(
-    element: HTMLDivElement,
-    livewirePath: LivewirePath
-  ) {
+  protected updateAnnotation(livewirePath: LivewirePath) {
     if (!this.editData || !livewirePath) {
       return;
     }
 
     const { annotation, sliceToWorld } = this.editData;
+    let { pointArray: imagePoints } = livewirePath;
 
-    const { pointArray: imagePoints } = livewirePath;
-    const worldPolylinePoints: Types.Point3[] = [];
-
-    for (let i = 0, len = imagePoints.length; i < len; i++) {
-      const imagePoint = imagePoints[i];
-      const worldPoint = sliceToWorld(imagePoint);
-      worldPolylinePoints.push(worldPoint);
+    if (imagePoints.length > 1) {
+      imagePoints = [...imagePoints, imagePoints[0]];
     }
 
-    if (worldPolylinePoints.length > 1) {
-      worldPolylinePoints.push([...worldPolylinePoints[0]]);
-    }
-
-    annotation.data.contour.polyline = worldPolylinePoints;
+    updateContourPolyline(
+      annotation,
+      {
+        points: imagePoints,
+        closed: annotation.data.contour.closed,
+        targetWindingDirection: ContourWindingDirection.Clockwise,
+      },
+      {
+        canvasToWorld: sliceToWorld,
+      }
+    );
   }
 }
 

package/src/tools/annotation/PlanarFreehandROITool.ts

@@ -46,6 +46,7 @@ import { isViewportPreScaled } from '../../utilities/viewport/isViewportPreScale
 import { getModalityUnit } from '../../utilities/getModalityUnit';
 import { BasicStatsCalculator } from '../../utilities/math/basic';
 import ContourSegmentationBaseTool from '../base/ContourSegmentationBaseTool';
+import { KeyboardBindings, ChangeTypes } from '../../enums';
 
 const { pointCanProjectOnLine } = polyline;
 const { EPSILON } = CONSTANTS;
@@ -79,7 +80,7 @@ const PARALLEL_THRESHOLD = 1 - EPSILON;
  *
  * The result of smoothing will be removal of some of the outliers
  * Changing tool configuration (see below) you can fine-tune the smoothing process by changing knotsRatioPercentageOnAdd and knotsRatioPercentageOnEdit value, which smaller values produces a more agressive smoothing.
- * A smaller value of knotsRatioPercentageOnAdd/knotsRatioPercentageOnEdit produces a more agressive smoothing.
+ * A smaller value of knotsRatioPercentageOnAdd/knotsRatioPercentageOnEdit produces a more aggressive smoothing.
  *
  * ```js
  * cornerstoneTools.addTool(PlanarFreehandROITool)
@@ -98,7 +99,7 @@ const PARALLEL_THRESHOLD = 1 - EPSILON;
  *   ],
  * })
  *
- * // set smoothing agressiveness while adding new annotation (ps: this does not change if smoothing is ON or OFF)
+ * // set smoothing aggressiveness while adding new annotation (ps: this does not change if smoothing is ON or OFF)
  * toolGroup.setToolConfiguration(PlanarFreehandROITool.toolName, {
  *   smoothing: { knotsRatioPercentageOnAdd: 30 },
  * });
@@ -177,6 +178,11 @@ class PlanarFreehandROITool extends ContourSegmentationBaseTool {
       configuration: {
         shadow: true,
         preventHandleOutsideImage: false,
+        /**
+         * Specify which modifier key is used to add a hole to a contour. The
+         * modifier must be pressed when the first point of a new contour is added.
+         */
+        contourHoleAdditionModifierKey: KeyboardBindings.Shift,
         alwaysRenderOpenContourHandles: {
           // When true, always render end points when you have an open contour, rather
           // than just rendering a line.
@@ -823,7 +829,11 @@ class PlanarFreehandROITool extends ContourSegmentationBaseTool {
       };
     }
 
-    triggerAnnotationModified(annotation, element);
+    triggerAnnotationModified(
+      annotation,
+      enabledElement.element,
+      ChangeTypes.StatsUpdated
+    );
 
     annotation.invalidated = false;