@cornerstonejs/tools 0.56.2 → 0.56.4

package/src/eventDispatchers/shared/getActiveToolForTouchEvent.ts

@@ -0,0 +1,64 @@
+import { ToolGroupManager } from '../../store';
+import { MouseBindings, ToolModes } from '../../enums';
+import { EventTypes } from '../../types';
+import getMouseModifier from './getMouseModifier';
+
+const { Active } = ToolModes;
+
+/**
+ * Iterate tool group tools until we find a tool that has a "ToolBinding"
+ * that matches our TouchEvent's `buttons`. It's possible there will be no match
+ * (no active tool for that touch button combination).
+ *
+ * @param evt - The event dispatcher touch event.
+ *
+ * @returns tool
+ */
+export default function getActiveToolForTouchEvent(
+  evt: EventTypes.NormalizedTouchEventType
+) {
+  // Todo: we should refactor this to use getToolsWithModesForTouchEvent instead
+  const { renderingEngineId, viewportId } = evt.detail;
+  const touchEvent = evt.detail.event;
+
+  const toolGroup = ToolGroupManager.getToolGroupForViewport(
+    viewportId,
+    renderingEngineId
+  );
+
+  if (!toolGroup) {
+    return null;
+  }
+
+  const toolGroupToolNames = Object.keys(toolGroup.toolOptions);
+
+  const numTouchPoints = Object.keys(touchEvent.touches).length;
+
+  // If any keyboard modifier key is also pressed
+  const modifierKey = getMouseModifier(touchEvent);
+
+  for (let j = 0; j < toolGroupToolNames.length; j++) {
+    const toolName = toolGroupToolNames[j];
+    const toolOptions = toolGroup.toolOptions[toolName];
+
+    const correctBinding =
+      toolOptions.bindings.length &&
+      /**
+       * TODO: setActiveTool treats MouseBindings.Primary in a special way
+       * which is analgous to numTouchPoints === 1 as the primary interaction
+       * for touch based applications. The ToolGroup set active and get active
+       * logic should be updated to account for numTouchPoints === 1
+       */
+      toolOptions.bindings.some(
+        (binding) =>
+          (binding.numTouchPoints === numTouchPoints ||
+            (numTouchPoints === 1 &&
+              binding.mouseButton === MouseBindings.Primary)) &&
+          binding.modifierKey === modifierKey
+      );
+
+    if (toolOptions.mode === Active && correctBinding) {
+      return toolGroup.getToolInstance(toolName);
+    }
+  }
+}

package/src/eventDispatchers/shared/getMouseModifier.ts

@@ -0,0 +1,30 @@
+import { KeyboardBindings as kb } from '../../enums';
+
+/**
+ * Gets the mouse modifier key from a mouse event.
+ * Supports Shift, Ctrl, Alt, in singly and in combinations of 2
+ * Supports Meta singly.
+ */
+const getMouseModifierKey = (evt) => {
+  // The logic is a hard coded key mapping
+  if (evt.shiftKey) {
+    if (evt.ctrlKey) return kb.ShiftCtrl;
+    if (evt.altKey) return kb.ShiftAlt;
+    if (evt.metaKey) return kb.ShiftMeta;
+    return kb.Shift;
+  }
+  if (evt.ctrlKey) {
+    if (evt.altKey) return kb.CtrlAlt;
+    if (evt.metaKey) return kb.CtrlMeta;
+    return kb.Ctrl;
+  }
+  if (evt.altKey) {
+    return (evt.metaKey && kb.AltMeta) || kb.Alt;
+  }
+  if (evt.metaKey) {
+    kb.Meta;
+  }
+  return undefined;
+};
+
+export default getMouseModifierKey;

package/src/eventDispatchers/shared/getToolsWithModesForMouseEvent.ts

@@ -0,0 +1,56 @@
+import { ToolGroupManager } from '../../store';
+import { ToolModes } from '../../enums';
+import { EventTypes } from '../../types';
+
+type ModesFilter = Array<ToolModes>;
+
+/**
+ * Given the normalized mouse event and a filter of modes,
+ * find all the tools on the element that are in one of the specified modes.
+ * If the evtButton is specified, only tools with a matching binding will be returned.
+ * @param evt - The normalized mouseDown event.
+ * @param modesFilter - An array of entries from the `ToolModes` enum.
+ */
+export default function getToolsWithModesForMouseEvent(
+  evt: EventTypes.MouseMoveEventType,
+  modesFilter: ModesFilter,
+  evtButton?: any
+) {
+  const { renderingEngineId, viewportId } = evt.detail;
+  const toolGroup = ToolGroupManager.getToolGroupForViewport(
+    viewportId,
+    renderingEngineId
+  );
+
+  if (!toolGroup) {
+    return [];
+  }
+
+  const enabledTools = [];
+
+  const toolGroupToolNames = Object.keys(toolGroup.toolOptions);
+
+  for (let j = 0; j < toolGroupToolNames.length; j++) {
+    const toolName = toolGroupToolNames[j];
+    const tool = toolGroup.toolOptions[toolName];
+
+    // tool has binding that matches the mouse button - we match those with
+    // any modifier keys too since they can be passively interacted with
+    const correctBinding =
+      evtButton != null && // not null or undefined
+      tool.bindings.length &&
+      tool.bindings.some((binding) => binding.mouseButton === evtButton);
+
+    if (
+      modesFilter.includes(tool.mode) &&
+      // Should not filter by event's button
+      // or should, and the tool binding includes the event's button
+      (!evtButton || correctBinding)
+    ) {
+      const toolInstance = toolGroup.getToolInstance(toolName);
+      enabledTools.push(toolInstance);
+    }
+  }
+
+  return enabledTools;
+}

package/src/eventDispatchers/shared/getToolsWithModesForTouchEvent.ts

@@ -0,0 +1,54 @@
+import { ToolGroupManager } from '../../store';
+import { ToolModes } from '../../enums';
+import { EventTypes } from '../../types';
+
+type ModesFilter = Array<ToolModes>;
+
+/**
+ * Given the normalized touch event and a filter of modes,
+ * find all the tools on the element that are in one of the specified modes.
+ * If the evtButton is specified, only tools with a matching binding will be returned.
+ * @param evt - The normalized touchStart event.
+ * @param modesFilter - An array of entries from the `ToolModes` enum.
+ */
+export default function getToolsWithModesForTouchEvent(
+  evt: EventTypes.NormalizedTouchEventType,
+  modesFilter: ModesFilter,
+  numTouchPoints?: number
+) {
+  const { renderingEngineId, viewportId } = evt.detail;
+  const toolGroup = ToolGroupManager.getToolGroupForViewport(
+    viewportId,
+    renderingEngineId
+  );
+
+  if (!toolGroup) {
+    return [];
+  }
+
+  const enabledTools = [];
+
+  const toolGroupToolNames = Object.keys(toolGroup.toolOptions);
+
+  for (let j = 0; j < toolGroupToolNames.length; j++) {
+    const toolName = toolGroupToolNames[j];
+    const tool = toolGroup.toolOptions[toolName];
+
+    const correctBinding =
+      numTouchPoints != null &&
+      tool.bindings.length &&
+      tool.bindings.some(
+        (binding) => binding.numTouchPoints === numTouchPoints
+      );
+
+    if (
+      modesFilter.includes(tool.mode) &&
+      (!numTouchPoints || correctBinding)
+    ) {
+      const toolInstance = toolGroup.getToolInstance(toolName);
+      enabledTools.push(toolInstance);
+    }
+  }
+
+  return enabledTools;
+}

package/src/eventDispatchers/touchEventHandlers/index.js

@@ -0,0 +1,15 @@
+import touchStart from './touchStart';
+import touchStartActivate from './touchStartActivate';
+import touchDrag from './touchDrag';
+import touchEnd from './touchEnd';
+import touchTap from './touchTap';
+import touchPress from './touchPress';
+
+export {
+  touchStart,
+  touchStartActivate,
+  touchDrag,
+  touchEnd,
+  touchTap,
+  touchPress,
+};

package/src/eventDispatchers/touchEventHandlers/touchDrag.ts

@@ -0,0 +1,23 @@
+import getActiveToolForTouchEvent from '../shared/getActiveToolForTouchEvent';
+import { state } from '../../store';
+import { TouchDragEventType } from '../../types/EventTypes';
+
+/**
+ * touchDrag - Event handler for touchDrag events. Uses `customCallbackHandler` to fire
+ * the `touchDragCallback` function on active tools.
+ */
+export default function touchDrag(evt: TouchDragEventType) {
+  if (state.isInteractingWithTool) {
+    return;
+  }
+
+  const activeTool = getActiveToolForTouchEvent(evt);
+
+  const noFoundToolOrDoesNotHaveTouchDragCallback =
+    !activeTool || typeof activeTool.touchDragCallback !== 'function';
+  if (noFoundToolOrDoesNotHaveTouchDragCallback) {
+    return;
+  }
+
+  activeTool.touchDragCallback(evt);
+}

package/src/eventDispatchers/touchEventHandlers/touchEnd.ts

@@ -0,0 +1,9 @@
+import customCallbackHandler from '../shared/customCallbackHandler';
+
+/**
+ * touchEnd - Event handler for touchEnd events. Uses `customCallbackHandler` to fire
+ * the `touchEndCallback` function on active tools.
+ */
+const touchEnd = customCallbackHandler.bind(null, 'Touch', 'touchEndCallback');
+
+export default touchEnd;

package/src/eventDispatchers/touchEventHandlers/touchPress.ts

@@ -0,0 +1,13 @@
+import customCallbackHandler from '../shared/customCallbackHandler';
+
+/**
+ * touchPress - Event handler for touch press events. Uses `customCallbackHandler` to fire
+ * the `touchPressCallback` function on active tools.
+ */
+const touchPress = customCallbackHandler.bind(
+  null,
+  'Touch',
+  'touchPressCallback'
+);
+
+export default touchPress;

package/src/eventDispatchers/touchEventHandlers/touchStart.ts

@@ -0,0 +1,174 @@
+import { state } from '../../store';
+import { ToolModes } from '../../enums';
+import { EventTypes } from '../../types';
+import {
+  ToolAnnotationPair,
+  ToolsWithMoveableHandles,
+} from '../../types/InternalToolTypes';
+
+import {
+  setAnnotationSelected,
+  isAnnotationSelected,
+} from '../../stateManagement/annotation/annotationSelection';
+
+import { isAnnotationLocked } from '../../stateManagement/annotation/annotationLocking';
+import { isAnnotationVisible } from '../../stateManagement/annotation/annotationVisibility';
+
+// Util
+import filterToolsWithMoveableHandles from '../../store/filterToolsWithMoveableHandles';
+import filterToolsWithAnnotationsForElement from '../../store/filterToolsWithAnnotationsForElement';
+import filterMoveableAnnotationTools from '../../store/filterMoveableAnnotationTools';
+import getActiveToolForTouchEvent from '../shared/getActiveToolForTouchEvent';
+import getToolsWithModesForTouchEvent from '../shared/getToolsWithModesForTouchEvent';
+
+const { Active, Passive } = ToolModes;
+
+/**
+ * touchStart - Event handler for touchStart events. Uses `customCallbackHandler` to fire
+ * the `touchStartCallback` function on active tools.
+ */
+export default function touchStart(evt: EventTypes.TouchStartEventType) {
+  if (state.isInteractingWithTool) {
+    return;
+  }
+  const activeTool = getActiveToolForTouchEvent(evt);
+
+  // Check for preTouchStartCallbacks,
+  // If the tool claims it consumed the event, prevent further checks.
+  if (activeTool && typeof activeTool.preTouchStartCallback === 'function') {
+    const consumedEvent = activeTool.preTouchStartCallback(evt);
+
+    if (consumedEvent) {
+      return;
+    }
+  }
+
+  const isPrimaryClick = Object.keys(evt.detail.event.touches).length === 1;
+  const activeToolsWithEventBinding = getToolsWithModesForTouchEvent(
+    evt,
+    [Active],
+    Object.keys(evt.detail.event.touches).length
+  );
+  const passiveToolsIfEventWasPrimaryTouchButton = isPrimaryClick
+    ? getToolsWithModesForTouchEvent(evt, [Passive])
+    : undefined;
+  const applicableTools = [
+    ...(activeToolsWithEventBinding || []),
+    ...(passiveToolsIfEventWasPrimaryTouchButton || []),
+    activeTool,
+  ];
+
+  const eventDetail = evt.detail;
+  const { element } = eventDetail;
+
+  // Filter tools with annotations for this element
+  const annotationToolsWithAnnotations = filterToolsWithAnnotationsForElement(
+    element,
+    applicableTools
+  );
+
+  const canvasCoords = eventDetail.currentPoints.canvas;
+
+  // For the canvas coordinates, find all tools that might respond to this touch start
+  // on their handles. This filter will call getHandleNearImagePoint for each tool
+  // instance (each annotation)
+  const annotationToolsWithMoveableHandles = filterToolsWithMoveableHandles(
+    element,
+    annotationToolsWithAnnotations,
+    canvasCoords,
+    'touch'
+  );
+
+  const isMultiSelect = false;
+
+  // If there are annotation tools whose handle is near the touch, select the first one
+  // that isn't locked. If there's only one annotation tool, select it.
+  if (annotationToolsWithMoveableHandles.length > 0) {
+    const { tool, annotation, handle } = getAnnotationForSelection(
+      annotationToolsWithMoveableHandles
+    ) as ToolsWithMoveableHandles;
+
+    toggleAnnotationSelection(annotation.annotationUID, isMultiSelect);
+    tool.handleSelectedCallback(evt, annotation, handle, 'Touch');
+
+    return;
+  }
+
+  // If there were no annotation tools whose handle was near the touch, try to check
+  // if any of the annotation tools are interactable (e.g. moving an entire length annotation)
+  const moveableAnnotationTools = filterMoveableAnnotationTools(
+    element,
+    annotationToolsWithAnnotations,
+    canvasCoords,
+    'touch'
+  );
+
+  // If there are annotation tools that are interactable, select the first one
+  // that isn't locked. If there's only one annotation tool, select it.
+  if (moveableAnnotationTools.length > 0) {
+    const { tool, annotation } = getAnnotationForSelection(
+      moveableAnnotationTools
+    );
+
+    toggleAnnotationSelection(annotation.annotationUID, isMultiSelect);
+    tool.toolSelectedCallback(evt, annotation, 'Touch');
+
+    return;
+  }
+
+  // Run the postTouchStartCallback for the active tool if it exists
+  if (activeTool && typeof activeTool.postTouchStartCallback === 'function') {
+    const consumedEvent = activeTool.postTouchStartCallback(evt);
+
+    if (consumedEvent) {
+      // If the tool claims it consumed the event, prevent further checks.
+      return;
+    }
+  }
+
+  // Don't stop propagation so that touchStartActivate can handle the event
+}
+
+/**
+ * If there are multiple annotation tools, return the first one that isn't locked neither hidden.
+ * If there's only one annotation tool, return it
+ * @param annotationTools - An array of tools and annotation.
+ * @returns The candidate for selection
+ */
+function getAnnotationForSelection(
+  toolsWithMovableHandles: ToolAnnotationPair[]
+): ToolAnnotationPair {
+  return (
+    (toolsWithMovableHandles.length > 1 &&
+      toolsWithMovableHandles.find(
+        (item) =>
+          !isAnnotationLocked(item.annotation) &&
+          isAnnotationVisible(item.annotation.annotationUID)
+      )) ||
+    toolsWithMovableHandles[0]
+  );
+}
+
+/**
+ * If the annotation is selected, deselect it. If it's not selected, select it
+ * @param annotationUID - The AnnotationUID that we
+ * want to toggle the selection of.
+ * @param isMultiSelect - If true, the annotation. will be deselected if it is
+ * already selected, or deselected if it is selected.
+ */
+function toggleAnnotationSelection(
+  annotationUID: string,
+  isMultiSelect = false
+): void {
+  if (isMultiSelect) {
+    if (isAnnotationSelected(annotationUID)) {
+      setAnnotationSelected(annotationUID, false);
+    } else {
+      const preserveSelected = true;
+      setAnnotationSelected(annotationUID, true, preserveSelected);
+    }
+  } else {
+    const preserveSelected = false;
+    setAnnotationSelected(annotationUID, true, preserveSelected);
+  }
+}

package/src/eventDispatchers/touchEventHandlers/touchStartActivate.ts

@@ -0,0 +1,36 @@
+import { state } from '../../store';
+import { EventTypes } from '../../types';
+import { setAnnotationSelected } from '../../stateManagement/annotation/annotationSelection';
+
+import getActiveToolForTouchEvent from '../shared/getActiveToolForTouchEvent';
+
+/**
+ * If the `touchStart` handler does not consume an event,
+ * activate the creation loop of the active tool, if one is found for the
+ * touch button pressed.
+ *
+ * @param evt - The normalized touchStart event.
+ */
+export default function touchStartActivate(
+  evt: EventTypes.TouchStartActivateEventType
+) {
+  // If a tool has locked the current state it is dealing with an interaction within its own eventLoop.
+  if (state.isInteractingWithTool) {
+    return;
+  }
+
+  const activeTool = getActiveToolForTouchEvent(evt);
+
+  if (!activeTool) {
+    return;
+  }
+
+  if (state.isMultiPartToolActive) {
+    return;
+  }
+
+  if (activeTool.addNewAnnotation) {
+    const annotation = activeTool.addNewAnnotation(evt, 'touch');
+    setAnnotationSelected(annotation.annotationUID);
+  }
+}

package/src/eventDispatchers/touchEventHandlers/touchTap.ts

@@ -0,0 +1,9 @@
+import customCallbackHandler from '../shared/customCallbackHandler';
+
+/**
+ * touchTap - Event handler for touch tap events. Uses `customCallbackHandler` to fire
+ * the `touchTapCallback` function on active tools.
+ */
+const touchTap = customCallbackHandler.bind(null, 'Touch', 'touchTapCallback');
+
+export default touchTap;

package/src/eventDispatchers/touchToolEventDispatcher.ts

@@ -0,0 +1,51 @@
+import Events from '../enums/Events';
+
+import {
+  touchStart,
+  touchStartActivate,
+  touchDrag,
+  touchEnd,
+  touchTap,
+  touchPress,
+} from './touchEventHandlers';
+
+/**
+ * Enable these listeners are emitted in order, and can be cancelled/prevented from bubbling
+ * by any previous event.
+ *
+ * @param element - The element to add the event listeners to.
+ */
+const enable = function (element: HTMLDivElement): void {
+  element.addEventListener(Events.TOUCH_START, touchStart as EventListener);
+  element.addEventListener(
+    Events.TOUCH_START_ACTIVATE,
+    touchStartActivate as EventListener
+  );
+  element.addEventListener(Events.TOUCH_DRAG, touchDrag as EventListener);
+  element.addEventListener(Events.TOUCH_END, touchEnd as EventListener);
+  element.addEventListener(Events.TOUCH_TAP, touchTap as EventListener);
+  element.addEventListener(Events.TOUCH_PRESS, touchPress as EventListener);
+};
+
+/**
+ * Disable and Remove the MouseToolEventDispatcher handlers from the element.
+ *
+ * @param element - HTMLDivElement
+ */
+const disable = function (element: HTMLDivElement) {
+  element.removeEventListener(Events.TOUCH_START, touchStart as EventListener);
+  element.removeEventListener(
+    Events.TOUCH_START_ACTIVATE,
+    touchStartActivate as EventListener
+  );
+  element.removeEventListener(Events.TOUCH_DRAG, touchDrag as EventListener);
+  element.removeEventListener(Events.TOUCH_END, touchEnd as EventListener);
+  element.removeEventListener(Events.TOUCH_PRESS, touchPress as EventListener);
+};
+
+const touchToolEventDispatcher = {
+  enable,
+  disable,
+};
+
+export default touchToolEventDispatcher;

package/src/eventListeners/annotations/annotationModifiedListener.ts

@@ -0,0 +1,22 @@
+import { getRenderingEngine } from '@cornerstonejs/core';
+import triggerAnnotationRenderForViewportIds from '../../utilities/triggerAnnotationRenderForViewportIds';
+
+/**
+ * This is a callback function that is called when an annotation is modified.
+ * Since we are throttling the cachedStats calculation for annotation tools,
+ * we need to trigger a final render for the annotation. so that the annotation
+ * textBox is updated.
+ * Todo: This will trigger all the annotation tools to re-render, although DOM
+ * will update those that have changed, but more efficient would be to only
+ * update the changed annotation.
+ * Todo: A better way is to extract the textBox render logic from the renderAnnotation
+ * of all tools and just trigger a render for that (instead of the entire annotation., even if
+ * no svg update happens since the attributes for handles are the same)
+ */
+function annotationModifiedListener(evt): void {
+  const { viewportId, renderingEngineId } = evt.detail;
+  const renderingEngine = getRenderingEngine(renderingEngineId);
+  triggerAnnotationRenderForViewportIds(renderingEngine, [viewportId]);
+}
+
+export default annotationModifiedListener;

package/src/eventListeners/annotations/annotationSelectionListener.ts

@@ -0,0 +1,29 @@
+import { getRenderingEngines } from '@cornerstonejs/core';
+import { triggerAnnotationRenderForViewportIds } from '../../utilities';
+
+/**
+ * When an annotation is deselected, trigger an annotation render for all viewports.
+ * The reason for this is that, drawing an annotation in a different viewport
+ * should deselect all other annotations in other viewports. In order to achieve
+ * this, we need to trigger an annotation render for all viewports.
+ * Todo: Although this is inefficient, but since annotations are only rendered if necessary,
+ * it's probably not going to have a noticeable impact on performance.
+ * @param evt - The event object.
+ */
+function annotationSelectionListener(evt): void {
+  const deselectedAnnotation = evt.detail.removed;
+
+  if (!deselectedAnnotation.length) {
+    return;
+  }
+
+  const renderingEngines = getRenderingEngines();
+
+  renderingEngines.forEach((renderingEngine) => {
+    const viewports = renderingEngine.getViewports();
+    const viewportIds = viewports.map((vp) => vp.id);
+    triggerAnnotationRenderForViewportIds(renderingEngine, viewportIds);
+  });
+}
+
+export default annotationSelectionListener;

package/src/eventListeners/annotations/index.ts

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

package/src/eventListeners/index.ts

@@ -0,0 +1,28 @@
+import mouseEventListeners from './mouse';
+import touchEventListeners from './touch';
+import wheelEventListener from './wheel';
+import keyEventListener from './keyboard';
+import {
+  segmentationDataModifiedEventListener,
+  segmentationRepresentationModifiedEventListener,
+  segmentationRepresentationRemovedEventListener,
+  segmentationModifiedListener,
+} from './segmentation';
+import {
+  annotationSelectionListener,
+  annotationModifiedListener,
+} from './annotations';
+//import touchEventListeners from './touchEventListeners';
+
+export {
+  mouseEventListeners,
+  touchEventListeners,
+  wheelEventListener,
+  keyEventListener,
+  segmentationRepresentationModifiedEventListener,
+  segmentationModifiedListener,
+  segmentationRepresentationRemovedEventListener,
+  segmentationDataModifiedEventListener,
+  annotationSelectionListener,
+  annotationModifiedListener,
+};

package/src/eventListeners/keyboard/index.ts

@@ -0,0 +1,16 @@
+import keyDownListener, { getModifierKey } from './keyDownListener';
+
+function enable(element: HTMLDivElement): void {
+  disable(element);
+  element.addEventListener('keydown', keyDownListener);
+}
+
+function disable(element: HTMLDivElement): void {
+  element.removeEventListener('keydown', keyDownListener);
+}
+
+export default {
+  enable,
+  disable,
+  getModifierKey,
+};