@cornerstonejs/tools 1.51.5 → 1.52.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cornerstonejs/tools",
-  "version": "1.51.5",
+  "version": "1.52.0",
   "description": "Cornerstone3D Tools",
   "main": "src/index.ts",
   "types": "dist/types/index.d.ts",
@@ -29,7 +29,7 @@
     "webpack:watch": "webpack --mode development --progress --watch  --config ./.webpack/webpack.dev.js"
   },
   "dependencies": {
-    "@cornerstonejs/core": "^1.51.5",
+    "@cornerstonejs/core": "^1.52.0",
     "comlink": "^4.4.1",
     "lodash.clonedeep": "4.5.0",
     "lodash.get": "^4.4.2"
@@ -53,5 +53,5 @@
     "type": "individual",
     "url": "https://ohif.org/donate"
   },
-  "gitHead": "8ed54955b6c0c04818954dabb9a1d22d1bf4360e"
+  "gitHead": "f09289b1bbae632126eec5ba208dd89da1923a4d"
 }

package/src/drawingSvg/drawPolyline.ts

@@ -53,7 +53,7 @@ export default function drawPolyline(
   let pointsAttribute = '';
 
   for (const point of points) {
-    pointsAttribute += `${point[0]}, ${point[1]} `;
+    pointsAttribute += `${point[0].toFixed(1)}, ${point[1].toFixed(1)} `;
   }
 
   if (options.connectLastToFirst) {

package/src/enums/ChangeTypes.ts

@@ -27,6 +27,10 @@ enum ChangeTypes {
    * Completed occurs only for the annotation completed event, just to identify it
    */
   Completed = 'Completed',
+  /**
+   * Occurs when an interpolation result is updated with more tool specific data.
+   */
+  InterpolationUpdated = 'InterpolationUpdated',
 }
 
 export default ChangeTypes;

package/src/eventDispatchers/keyboardEventHandlers/keyDown.ts

@@ -40,7 +40,7 @@ export default function keyDown(evt: KeyDownEventType): void {
       // so that the method can depend on the specific configuration in use.
       const method =
         typeof value.method === 'function' ? value.method : key[value.method];
-      method.call(key, element, value);
+      method.call(key, element, value, evt);
     }
   }
 }

package/src/stateManagement/annotation/helpers/state.ts

@@ -4,7 +4,7 @@ import {
   eventTarget,
   getEnabledElementByIds,
 } from '@cornerstonejs/core';
-import { Events } from '../../../enums';
+import { Events, ChangeTypes } from '../../../enums';
 import { Annotation } from '../../../types/AnnotationTypes';
 import { getToolGroupsWithToolName } from '../../../store/ToolGroupManager';
 import {
@@ -85,7 +85,8 @@ function triggerAnnotationAddedForFOR(annotation: Annotation) {
  */
 function triggerAnnotationModified(
   annotation: Annotation,
-  element: HTMLDivElement
+  element: HTMLDivElement,
+  changeType = ChangeTypes.HandlesUpdated
 ): void {
   const enabledElement = getEnabledElement(element);
   const { viewportId, renderingEngineId } = enabledElement;
@@ -94,6 +95,7 @@ function triggerAnnotationModified(
     annotation,
     viewportId,
     renderingEngineId,
+    changeType,
   };
 
   triggerEvent(eventTarget, eventType, eventDetail);

package/src/tools/annotation/LivewireContourSegmentationTool.ts

@@ -1,8 +1,159 @@
+import type { Types } from '@cornerstonejs/core';
+import { utilities as csUtils } from '@cornerstonejs/core';
+
 import LivewireContourTool from './LivewireContourTool';
+import { LivewirePath } from '../../utilities/livewire/LiveWirePath';
+import { triggerAnnotationModified } from '../../stateManagement/annotation/helpers/state';
+import { ChangeTypes } from '../../enums';
+import type { ContourSegmentationAnnotation } from '../../types';
+import { drawPolyline as drawPolylineSvg } from '../../drawingSvg';
 
 class LivewireContourSegmentationTool extends LivewireContourTool {
   static toolName;
 
+  /**
+   * Updates the interpolated annotations with the currently displayed image data,
+   * performing hte livewire on the image data as generated.
+   * Note - this function is only called for interpolated livewire SEGMENTATION
+   * objects, and will return immediately otherwise.
+   *
+   * The work for the interpolation is performed in a microtask, enabling this
+   * method to return quickly for faster render speeds, but ensuring that the
+   * annotation data isn't updated before the changes are performed.  The removes
+   * some irritating flickering on navigation.
+   */
+  public updateInterpolatedAnnotation(
+    annotation: ContourSegmentationAnnotation,
+    enabledElement: Types.IEnabledElement
+  ) {
+    // The interpolation sources is used as a flag here - a true livewire
+    // behaviour would be to perform a livewire between the two planes
+    // closest to this plane for each point, and use that handle.  That is
+    // oblique, however, which is not currently supported.
+    if (
+      this.editData ||
+      !annotation.invalidated ||
+      !annotation.data.handles.interpolationSources
+    ) {
+      return;
+    }
+    annotation.data.contour.originalPolyline = annotation.data.contour.polyline;
+
+    // See docs above for why this is a microtask
+    queueMicrotask(() => {
+      if (!annotation.data.handles.interpolationSources) {
+        return;
+      }
+      const { points } = annotation.data.handles;
+
+      const { element } = enabledElement.viewport;
+      this.setupBaseEditData(points[0], element, annotation);
+      const { length: count } = points;
+      const { scissors } = this;
+      const { nearestEdge, repeatInterpolation } =
+        this.configuration.interpolation;
+      annotation.data.handles.originalPoints = points;
+      const { worldToSlice, sliceToWorld } = this.editData;
+      const handleSmoothing = [];
+
+      // New path generation - go through the handles and regenerate the polyline
+      if (nearestEdge) {
+        let lastPoint = worldToSlice(points[points.length - 1]);
+        // Nearest edge handling
+        points.forEach((point, hIndex) => {
+          const testPoint = worldToSlice(point);
+          lastPoint = testPoint;
+          handleSmoothing.push(testPoint);
+
+          // Fill the costs buffer and then find the minimum cost
+          // This is a little too aggressive about pulling the line in
+          scissors.startSearch(lastPoint);
+          scissors.findPathToPoint(testPoint);
+          // Fill the costs for a point a bit further along by searching for a
+          // point further along.
+          scissors.findPathToPoint(
+            worldToSlice(points[(hIndex + 3) % points.length])
+          );
+          const minPoint = scissors.findMinNearby(testPoint, nearestEdge);
+          if (!csUtils.isEqual(testPoint, minPoint)) {
+            handleSmoothing[hIndex] = minPoint;
+            lastPoint = minPoint;
+            points[hIndex] = sliceToWorld(minPoint);
+          }
+        });
+      }
+
+      // Regenerate the updated data based on the updated handles
+      const acceptedPath = new LivewirePath();
+      for (let i = 0; i < count; i++) {
+        scissors.startSearch(worldToSlice(points[i]));
+        const path = scissors.findPathToPoint(
+          worldToSlice(points[(i + 1) % count])
+        );
+        acceptedPath.addPoints(path);
+      }
+
+      // Now, update the rendering
+      this.updateAnnotation(element, acceptedPath);
+      this.scissors = null;
+      this.scissorsRight = null;
+      this.editData = null;
+      annotation.data.handles.interpolationSources = null;
+
+      if (repeatInterpolation) {
+        triggerAnnotationModified(
+          annotation,
+          enabledElement.viewport.element,
+          ChangeTypes.InterpolationUpdated
+        );
+      }
+    });
+  }
+
+  /**
+   * Adds the update to the interpolated annotaiton on render an instance,
+   * but otherwise just calls the parent render annotation instance.
+   */
+  protected renderAnnotationInstance(renderContext): boolean {
+    const { enabledElement, svgDrawingHelper } = renderContext;
+    const annotation =
+      renderContext.annotation as ContourSegmentationAnnotation;
+    const { annotationUID } = annotation;
+    const { viewport } = enabledElement;
+    const { worldToCanvas } = viewport;
+    const { showInterpolationPolyline } =
+      this.configuration.interpolation || {};
+
+    this.updateInterpolatedAnnotation?.(annotation, enabledElement);
+    const { originalPolyline } = annotation.data.contour;
+
+    const rendered = super.renderAnnotationInstance(renderContext);
+
+    if (
+      showInterpolationPolyline &&
+      originalPolyline &&
+      annotation.autoGenerated
+    ) {
+      const polylineCanvasPoints = originalPolyline.map(
+        worldToCanvas
+      ) as Types.Point2[];
+      polylineCanvasPoints.push(polylineCanvasPoints[0]);
+      drawPolylineSvg(
+        svgDrawingHelper,
+        annotationUID,
+        'interpolationContour-0',
+        polylineCanvasPoints,
+        {
+          color: '#70ffff',
+          lineWidth: 1,
+          fillOpacity: 0,
+        }
+      );
+    }
+
+    return rendered;
+  }
+
   protected isContourSegmentationTool(): boolean {
     // Re-enable contour segmentation behavior disabled by LivewireContourTool
     return true;

package/src/tools/annotation/LivewireContourTool.ts

@@ -1,20 +1,17 @@
 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 { resetElementCursor } from '../../cursors/elementCursor';
 import type {
-  Annotation,
   EventTypes,
   ToolHandle,
   PublicToolProps,
@@ -25,9 +22,9 @@ import { math, triggerAnnotationRenderForViewportIds } from '../../utilities';
 import findHandlePolylineIndex from '../../utilities/contours/findHandlePolylineIndex';
 import { LivewireContourAnnotation } from '../../types/ToolSpecificAnnotationTypes';
 import {
-  AnnotationCompletedEventDetail,
-  AnnotationModifiedEventDetail,
-} from '../../types/EventTypes';
+  triggerAnnotationModified,
+  triggerAnnotationCompleted,
+} from '../../stateManagement/annotation/helpers/state';
 import reverseIfAntiClockwise from '../../utilities/contours/reverseIfAntiClockwise';
 
 import { LivewireScissors } from '../../utilities/livewire/LivewireScissors';
@@ -35,15 +32,13 @@ import { LivewirePath } from '../../utilities/livewire/LiveWirePath';
 import { getViewportIdsWithToolToRender } from '../../utilities/viewportFilters';
 import ContourSegmentationBaseTool from '../base/ContourSegmentationBaseTool';
 
-const { isEqual } = csUtils;
-
 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;
@@ -72,6 +67,48 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
       supportedInteractionTypes: ['Mouse', 'Touch'],
       configuration: {
         preventHandleOutsideImage: false,
+        /**
+         * 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',
+              },
+            ],
+          },
+        },
       },
     }
   ) {
@@ -214,7 +251,7 @@ 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);
 
     this.setupBaseEditData(worldPos, element, annotation);
     this.addAnnotation(annotation, element);
@@ -335,7 +372,10 @@ 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;
 
@@ -353,10 +393,17 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
     const { renderingEngine } = enabledElement;
 
     if (
-      this.isHandleOutsideImage &&
-      this.configuration.preventHandleOutsideImage
+      (this.isHandleOutsideImage &&
+        this.configuration.preventHandleOutsideImage) ||
+      clearAnnotation
     ) {
       removeAnnotation(annotation.annotationUID);
+      this.clearEditData();
+      triggerAnnotationRenderForViewportIds(
+        renderingEngine,
+        viewportIdsToRender
+      );
+      return;
     }
 
     // Reverse the points if needed, ensuring both the handles and the
@@ -377,47 +424,15 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
       : ChangeTypes.HandlesUpdated;
 
     this.triggerChangeEvent(annotation, enabledElement, changeType);
+    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.
@@ -428,9 +443,13 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
     changeType = ChangeTypes.StatsUpdated
   ): void => {
     if (changeType === ChangeTypes.Completed) {
-      this.triggerAnnotationCompleted(annotation);
+      triggerAnnotationCompleted(annotation);
     } else {
-      this.triggerAnnotationModified(annotation, enabledElement, changeType);
+      triggerAnnotationModified(
+        annotation,
+        enabledElement.viewport.element,
+        changeType
+      );
     }
   };
 
@@ -485,25 +504,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 +536,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(element, this.editData.confirmedPath);
       this._endCallback(evt);
     }
 
@@ -624,7 +642,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}`
@@ -773,22 +791,22 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
     const { element } = viewport;
 
     // Update the annotation that is in editData (being edited)
-    this._updateAnnotation(element, this.editData?.currentPath);
+    this.updateAnnotation(element, 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 +816,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 +841,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,10 +885,7 @@ class LivewireContourTool extends ContourSegmentationBaseTool {
     return true;
   }
 
-  private _updateAnnotation(
-    element: HTMLDivElement,
-    livewirePath: LivewirePath
-  ) {
+  protected updateAnnotation(_, livewirePath: LivewirePath) {
     if (!this.editData || !livewirePath) {
       return;
     }

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 { 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 },
  * });
@@ -823,7 +824,11 @@ class PlanarFreehandROITool extends ContourSegmentationBaseTool {
       };
     }
 
-    triggerAnnotationModified(annotation, element);
+    triggerAnnotationModified(
+      annotation,
+      enabledElement.element,
+      ChangeTypes.StatsUpdated
+    );
 
     annotation.invalidated = false;
 

package/src/tools/annotation/SplineROITool.ts

@@ -814,9 +814,9 @@ class SplineROITool extends ContourSegmentationBaseTool {
 
     // Add an action to create a new spline data on creating an interpolated
     // instance.
-    let postInterpolateAction;
+    let onInterpolationComplete;
     if (this.configuration.interpolation?.enabled) {
-      postInterpolateAction = (annotation) => {
+      onInterpolationComplete = (annotation) => {
         annotation.data.spline ||= createSpline();
         this.createInterpolatedSplineControl(annotation);
       };
@@ -830,7 +830,7 @@ class SplineROITool extends ContourSegmentationBaseTool {
         spline: createSpline(),
         cachedStats: {},
       },
-      postInterpolateAction,
+      onInterpolationComplete,
     });
   }