@cornerstonejs/tools 1.36.3 → 1.37.0

package/src/tools/segmentation/BrushTool.ts

@@ -1,5 +1,5 @@
 import { utilities as csUtils, getEnabledElement } from '@cornerstonejs/core';
-import { vec3 } from 'gl-matrix';
+import { vec3, vec2 } from 'gl-matrix';
 
 import type { Types } from '@cornerstonejs/core';
 import type {
@@ -19,7 +19,12 @@ import {
   fillInsideCircle,
 } from './strategies/fillCircle';
 import { eraseInsideCircle } from './strategies/eraseCircle';
-import { Events, ToolModes, SegmentationRepresentations } from '../../enums';
+import {
+  Events,
+  ToolModes,
+  SegmentationRepresentations,
+  StrategyCallbacks,
+} from '../../enums';
 import { drawCircle as drawCircleSvg } from '../../drawingSvg';
 import {
   resetElementCursor,
@@ -40,6 +45,22 @@ import {
 } from '../../types/LabelmapTypes';
 import { isVolumeSegmentation } from './strategies/utils/stackVolumeCheck';
 
+/**
+ * A type for preview data/information, used to setup previews on hover, or
+ * maintain the preview information.
+ */
+export type PreviewData = {
+  /**
+   *  The preview data returned from the strategy
+   */
+  preview: unknown;
+  timer?: number;
+  timerStart: number;
+  startPoint: Types.Point2;
+  element: HTMLDivElement;
+  isDrag: boolean;
+};
+
 /**
  * @public
  */
@@ -62,6 +83,15 @@ class BrushTool extends BaseTool {
     centerCanvas?: Array<number>;
   };
 
+  private _previewData?: PreviewData = {
+    preview: null,
+    element: null,
+    timerStart: 0,
+    timer: null,
+    startPoint: [NaN, NaN],
+    isDrag: false,
+  };
+
   constructor(
     toolProps: PublicToolProps = {},
     defaultToolProps: ToolProps = {
@@ -76,20 +106,53 @@ class BrushTool extends BaseTool {
           THRESHOLD_INSIDE_SPHERE: thresholdInsideSphere,
         },
         strategySpecificConfiguration: {
-          THRESHOLD_INSIDE_CIRCLE: {
+          THRESHOLD: {
             threshold: [-150, -70], // E.g. CT Fat // Only used during threshold strategies.
           },
         },
         defaultStrategy: 'FILL_INSIDE_CIRCLE',
         activeStrategy: 'FILL_INSIDE_CIRCLE',
         brushSize: 25,
+        preview: {
+          // Have to enable the preview to use this
+          enabled: false,
+          previewColors: {},
+          // The time before showing a preview
+          previewTimeMs: 250,
+          // The distance to move to show a preview before preview time expired
+          previewMoveDistance: 8,
+          // The distance to drag before being considered a drag rather than click
+          dragMoveDistance: 4,
+          // The time to consider a mouse click a drag when moved less than dragMoveDistance
+          dragTimeMs: 500,
+        },
+        // Whether to show a center circle/position.  Set to null to not show
+        centerRadius: 2,
+        actions: {
+          [StrategyCallbacks.AcceptPreview]: {
+            method: StrategyCallbacks.AcceptPreview,
+            bindings: [
+              {
+                key: 'Enter',
+              },
+            ],
+          },
+          [StrategyCallbacks.RejectPreview]: {
+            method: StrategyCallbacks.RejectPreview,
+            bindings: [
+              {
+                key: 'Escape',
+              },
+            ],
+          },
+        },
       },
     }
   ) {
     super(toolProps, defaultToolProps);
   }
 
-  onSetToolPassive = () => {
+  onSetToolPassive = (evt) => {
     this.disableCursor();
   };
 
@@ -97,20 +160,16 @@ class BrushTool extends BaseTool {
     this.disableCursor();
   };
 
-  onSetToolDisabled = () => {
+  onSetToolDisabled = (evt) => {
     this.disableCursor();
   };
 
   private disableCursor() {
     this._hoverData = undefined;
+    this.rejectPreview();
   }
 
-  preMouseDownCallback = (
-    evt: EventTypes.MouseDownActivateEventType
-  ): boolean => {
-    const eventData = evt.detail;
-    const { element } = eventData;
-
+  createEditData(element) {
     const enabledElement = getEnabledElement(element);
     const { viewport, renderingEngine } = enabledElement;
 
@@ -151,7 +210,7 @@ class BrushTool extends BaseTool {
       // First volume actor for now.
       const firstVolumeActorUID = actors[0].uid;
 
-      this._editData = {
+      return {
         volumeId,
         referencedVolumeId: firstVolumeActorUID,
         segmentsLocked,
@@ -181,49 +240,128 @@ class BrushTool extends BaseTool {
         );
         return;
 
-        // Todo: add sphere manipulation support for stacks of images
+        // Todo: add sphere (volumetric) manipulation support for stacks of images
         // we should basically check if the stack constructs a valid volume
         // meaning all the metadata is present and consistent
-        // then we should create a volume and use it as a reference
-        // ideally a tiny volume that does not exceeds the boundary of the
-        // sphere brush size
+        // then we use a VoxelManager mapping to map a volume like appearance
+        // for the stack data.
         // csUtils.isValidVolume(referencedImageIds
       }
 
-      this._editData = {
+      return {
         imageIdReferenceMap,
         segmentsLocked,
         segmentationRepresentationUID,
       };
     }
+  }
+
+  preMouseDownCallback = (
+    evt: EventTypes.MouseDownActivateEventType
+  ): boolean => {
+    const eventData = evt.detail;
+    const { element } = eventData;
+    const enabledElement = getEnabledElement(element);
+    const { renderingEngine } = enabledElement;
 
+    this._editData = this.createEditData(element);
     this._activateDraw(element);
 
     hideElementCursor(element);
 
     evt.preventDefault();
 
+    // This might be a mouse down
+    this._previewData.isDrag = false;
+    this._previewData.timerStart = Date.now();
+
     triggerAnnotationRenderForViewportUIDs(
       renderingEngine,
-      viewportIdsToRender
+      this._hoverData.viewportIdsToRender
+    );
+
+    this.applyActiveStrategyCallback(
+      enabledElement,
+      this.getOperationData(element),
+      StrategyCallbacks.OnInteractionStart
     );
 
     return true;
   };
 
+  /**
+   * This call will be made when the mouse moves and the tool is active, but
+   * not actually drawing at the moment.
+   * The behavior is:
+   *    1. Update the cursor
+   *    2. Call the active strategy event 'preview' and 'rejectPreview'
+   *       on the mouse cursor position on a periodic basis to create a preview
+   *       when configured to do so.
+   *
+   * The preview will be shown after the mouse has been stationary for 250 ms.
+   * Any preview will be cancelled (immediately) after moving outside the center
+   * distance.
+   * As well, if the mouse moves but stays inside the center area for 250 ms,
+   * then the cancel will happen with a new preview being added.
+   *
+   * See mouse up details for how the preview gets accepted.
+   *
+   * The preview also needs to be cancelled on changing tools.
+   */
   mouseMoveCallback = (evt: EventTypes.InteractionEventType): void => {
     if (this.mode === ToolModes.Active) {
       this.updateCursor(evt);
+      if (!this.configuration.preview.enabled) {
+        return;
+      }
+      const { previewTimeMs, previewMoveDistance, dragMoveDistance } =
+        this.configuration.preview;
+      const { currentPoints, element } = evt.detail;
+      const { canvas } = currentPoints;
+
+      const { preview, startPoint, timer, timerStart, isDrag } =
+        this._previewData;
+      const delta = vec2.distance(canvas, startPoint);
+      const time = Date.now() - timerStart;
+      if (
+        delta > previewMoveDistance ||
+        (time > previewTimeMs && delta > dragMoveDistance)
+      ) {
+        if (timer) {
+          window.clearTimeout(timer);
+          this._previewData.timer = null;
+        }
+        if (preview && !isDrag) {
+          this.rejectPreview(element);
+        }
+      }
+      if (!this._previewData.timer) {
+        const timer = window.setTimeout(this.previewCallback, 250);
+        Object.assign(this._previewData, {
+          timerStart: Date.now(),
+          timer,
+          startPoint: canvas,
+          element,
+        });
+      }
     }
   };
 
-  private updateCursor(evt: EventTypes.InteractionEventType) {
-    const eventData = evt.detail;
-    const { element } = eventData;
-    const { currentPoints } = eventData;
-    const centerCanvas = currentPoints.canvas;
+  previewCallback = () => {
+    if (this._previewData.preview) {
+      return;
+    }
+    this._previewData.timer = null;
+    this._previewData.preview = this.applyActiveStrategyCallback(
+      getEnabledElement(this._previewData.element),
+      this.getOperationData(this._previewData.element),
+      StrategyCallbacks.Preview
+    );
+  };
+
+  private createHoverData(element, centerCanvas?) {
     const enabledElement = getEnabledElement(element);
-    const { renderingEngine, viewport } = enabledElement;
+    const { viewport } = enabledElement;
 
     const camera = viewport.getCamera();
     const { viewPlaneNormal, viewUp } = camera;
@@ -266,7 +404,7 @@ class BrushTool extends BaseTool {
       data: {},
     };
 
-    this._hoverData = {
+    return {
       brushCursor,
       centerCanvas,
       segmentIndex,
@@ -275,43 +413,88 @@ class BrushTool extends BaseTool {
       segmentColor,
       viewportIdsToRender,
     };
+  }
+
+  /**
+   * Updates the cursor position and whether it is showing or not.
+   * Can be over-ridden to add more cursor details or a preview.
+   */
+  protected updateCursor(evt: EventTypes.InteractionEventType) {
+    const eventData = evt.detail;
+    const { element } = eventData;
+    const { currentPoints } = eventData;
+    const centerCanvas = currentPoints.canvas;
+    this._hoverData = this.createHoverData(element, centerCanvas);
 
     this._calculateCursor(element, centerCanvas);
 
     triggerAnnotationRenderForViewportUIDs(
-      renderingEngine,
-      viewportIdsToRender
+      getEnabledElement(element).renderingEngine,
+      this._hoverData.viewportIdsToRender
     );
   }
 
   private _dragCallback = (evt: EventTypes.InteractionEventType): void => {
     const eventData = evt.detail;
-    const { element } = eventData;
+    const { element, currentPoints } = eventData;
     const enabledElement = getEnabledElement(element);
     const { renderingEngine } = enabledElement;
 
     this.updateCursor(evt);
 
-    const {
-      segmentIndex,
-      segmentationId,
-      segmentationRepresentationUID,
-      brushCursor,
-      viewportIdsToRender,
-    } = this._hoverData;
-
-    const { data } = brushCursor;
-    const { viewPlaneNormal, viewUp } = brushCursor.metadata;
+    const { viewportIdsToRender } = this._hoverData;
 
     triggerAnnotationRenderForViewportUIDs(
       renderingEngine,
       viewportIdsToRender
     );
 
+    const delta = vec2.distance(
+      currentPoints.canvas,
+      this._previewData.startPoint
+    );
+    const { dragTimeMs, dragMoveDistance } = this.configuration.preview;
+    if (
+      !this._previewData.isDrag &&
+      this._previewData.preview &&
+      Date.now() - this._previewData.timerStart < dragTimeMs &&
+      delta < dragMoveDistance
+    ) {
+      // If we are showing a preview, then don't start dragging quite immediately
+      // so that click up can accept the preview.
+      return;
+    }
+
+    this._previewData.preview = this.applyActiveStrategy(
+      enabledElement,
+      this.getOperationData()
+    );
+    this._previewData.element = element;
+    // Add a bit of time to the timer start so small accidental movements dont
+    // cause issues on clicking
+    this._previewData.timerStart = Date.now() + dragTimeMs;
+    this._previewData.isDrag = true;
+    this._previewData.startPoint = currentPoints.canvas;
+  };
+
+  protected getOperationData(element?) {
+    const editData = this._editData || this.createEditData(element);
+
+    const {
+      segmentIndex,
+      segmentationId,
+      segmentationRepresentationUID,
+      brushCursor,
+    } = this._hoverData || this.createHoverData(element);
+    const { data, metadata = {} } = brushCursor || {};
+    const { viewPlaneNormal, viewUp } = metadata;
     const operationData = {
-      ...this._editData,
-      points: data.handles.points,
+      ...editData,
+      points: data?.handles?.points,
       segmentIndex,
+      previewColors: this.configuration.preview.enabled
+        ? this.configuration.preview.previewColors
+        : null,
       viewPlaneNormal,
       toolGroupId: this.toolGroupId,
       segmentationId,
@@ -319,10 +502,11 @@ class BrushTool extends BaseTool {
       viewUp,
       strategySpecificConfiguration:
         this.configuration.strategySpecificConfiguration,
+      // Provide the preview information so that data can be used directly
+      preview: this._previewData?.preview,
     };
-
-    this.applyActiveStrategy(enabledElement, operationData);
-  };
+    return operationData;
+  }
 
   private _calculateCursor(element, centerCanvas) {
     const enabledElement = getEnabledElement(element);
@@ -382,46 +566,77 @@ class BrushTool extends BaseTool {
     data.invalidated = false;
   }
 
+  /**
+   * The end callback call is made when the mouse is released.  This will
+   * perform another active strategy render event to render the final position.
+   * As well, the finish strategy callback will be made during this time.
+   */
   private _endCallback = (evt: EventTypes.InteractionEventType): void => {
     const eventData = evt.detail;
     const { element } = eventData;
+    const enabledElement = getEnabledElement(element);
 
-    const {
-      segmentIndex,
-      segmentationId,
-      segmentationRepresentationUID,
-      brushCursor,
-    } = this._hoverData;
-
-    const { data } = brushCursor;
-    const { viewPlaneNormal, viewUp } = brushCursor.metadata;
+    const operationData = this.getOperationData(element);
+    // Don't re-fill when the preview is showing and the user clicks again
+    // otherwise the new area of hover may get filled, which is unexpected
+    if (!this._previewData.preview && !this._previewData.isDrag) {
+      this.applyActiveStrategy(enabledElement, operationData);
+    }
 
     this._deactivateDraw(element);
 
     resetElementCursor(element);
 
-    const enabledElement = getEnabledElement(element);
-
     this.updateCursor(evt);
 
-    const operationData = {
-      points: data.handles.points,
-      ...this._editData,
-      segmentIndex,
-      viewPlaneNormal,
-      toolGroupId: this.toolGroupId,
-      segmentationId,
-      segmentationRepresentationUID,
-      viewUp,
-      strategySpecificConfiguration:
-        this.configuration.strategySpecificConfiguration,
-    };
-
     this._editData = null;
 
-    this.applyActiveStrategy(enabledElement, operationData);
+    this.applyActiveStrategyCallback(
+      enabledElement,
+      operationData,
+      StrategyCallbacks.OnInteractionEnd
+    );
+
+    if (!this._previewData.isDrag) {
+      this.acceptPreview(element);
+    }
   };
 
+  /**
+   * Cancels any preview view being shown, resetting any segments being shown.
+   */
+  public rejectPreview(element = this._previewData.element) {
+    if (!element || !this._previewData.preview) {
+      return;
+    }
+    const enabledElement = getEnabledElement(element);
+    this.applyActiveStrategyCallback(
+      enabledElement,
+      this.getOperationData(element),
+      StrategyCallbacks.RejectPreview
+    );
+    this._previewData.preview = null;
+    this._previewData.isDrag = false;
+  }
+
+  /**
+   * Accepts a preview, marking it as the active segment.
+   */
+  public acceptPreview(element = this._previewData.element) {
+    if (!element) {
+      return;
+    }
+    const enabledElement = getEnabledElement(element);
+
+    this.applyActiveStrategyCallback(
+      enabledElement,
+      this.getOperationData(element),
+      StrategyCallbacks.AcceptPreview
+    );
+    this._previewData.isDrag = false;
+    this._previewData.preview = null;
+  }
+
   /**
    * Add event handlers for the modify event loop, and prevent default event propagation.
    */
@@ -529,6 +744,21 @@ class BrushTool extends BaseTool {
         color,
       }
     );
+
+    const { centerRadius } = this.configuration;
+    if (centerRadius >= 0) {
+      const circleUID1 = '1';
+      drawCircleSvg(
+        svgDrawingHelper,
+        annotationUID,
+        circleUID1,
+        center as Types.Point2,
+        2,
+        {
+          color,
+        }
+      );
+    }
   }
 }
 

package/src/tools/segmentation/CircleScissorsTool.ts

@@ -10,6 +10,7 @@ import {
 } from '../../types';
 
 import { fillInsideCircle } from './strategies/fillCircle';
+import { eraseInsideCircle } from './strategies/eraseCircle';
 import { Events } from '../../enums';
 import { drawCircle as drawCircleSvg } from '../../drawingSvg';
 import {
@@ -69,7 +70,7 @@ class CircleScissorsTool extends BaseTool {
       configuration: {
         strategies: {
           FILL_INSIDE: fillInsideCircle,
-          // ERASE_INSIDE: eraseInsideCircle,
+          ERASE_INSIDE: eraseInsideCircle,
         },
         defaultStrategy: 'FILL_INSIDE',
         activeStrategy: 'FILL_INSIDE',
@@ -275,6 +276,7 @@ class CircleScissorsTool extends BaseTool {
       points: data.handles.points,
       viewPlaneNormal,
       viewUp,
+      strategySpecificConfiguration: {},
     };
 
     this.editData = null;

package/src/tools/segmentation/SphereScissorsTool.ts

@@ -10,6 +10,7 @@ import {
 } from '../../types';
 
 import { fillInsideSphere } from './strategies/fillSphere';
+import { eraseInsideSphere } from './strategies/eraseSphere';
 import { Events, SegmentationRepresentations } from '../../enums';
 import { drawCircle as drawCircleSvg } from '../../drawingSvg';
 import {
@@ -71,6 +72,7 @@ class SphereScissorsTool extends BaseTool {
       configuration: {
         strategies: {
           FILL_INSIDE: fillInsideSphere,
+          ERASE_INSIDE: eraseInsideSphere,
         },
         defaultStrategy: 'FILL_INSIDE',
         activeStrategy: 'FILL_INSIDE',
@@ -153,6 +155,7 @@ class SphereScissorsTool extends BaseTool {
       centerCanvas: canvasPos,
       segmentationRepresentationUID,
       segmentIndex,
+      segmentationId,
       segmentsLocked,
       segmentColor,
       toolGroupId,