@cornerstonejs/tools 0.56.1 → 0.56.3

package/src/store/ToolGroupManager/destroy.ts

@@ -0,0 +1,24 @@
+// `BaseManager` or IManager interface for duplicate API between ToolGroup/Synchronizer?
+import { state as csToolsState } from '../index';
+import destroyToolGroup from './destroyToolGroup';
+
+// ToolGroups function entirely by their "state" being queried and leveraged
+// removing a ToolGroup from state is equivalent to killing it. Calling
+// destroyToolGroup() to make sure the SegmentationDisplayTools
+// have been removed from the toolGroup Viewports. //Todo: this makes more sense
+// to be based on events, but we don't have any toolGroup created/removed events
+
+/**
+ * Destroy all tool groups
+ */
+function destroy(): void {
+  const toolGroups = [...csToolsState.toolGroups];
+
+  for (const toolGroup of toolGroups) {
+    destroyToolGroup(toolGroup.id);
+  }
+
+  csToolsState.toolGroups = [];
+}
+
+export default destroy;

package/src/store/ToolGroupManager/destroyToolGroup.ts

@@ -0,0 +1,26 @@
+import { state } from '../index';
+import { removeSegmentationsFromToolGroup } from '../../stateManagement/segmentation';
+import { segmentationRenderingEngine } from '../../utilities/segmentation/triggerSegmentationRender';
+// ToolGroups function entirely by their "state" being queried and leveraged
+// removing a ToolGroup from state is equivalent to killing it
+
+/**
+ * Given a tool group Id, destroy the toolGroup. It will also cleanup all segmentations
+ * associated with that tool group too
+ *
+ * @param toolGroupId - The Id of the tool group to be destroyed.
+ */
+function destroyToolGroup(toolGroupId: string): void {
+  const toolGroupIndex = state.toolGroups.findIndex(
+    (tg) => tg.id === toolGroupId
+  );
+
+  if (toolGroupIndex > -1) {
+    segmentationRenderingEngine.removeToolGroup(toolGroupId);
+    // Todo: this should not happen here)
+    removeSegmentationsFromToolGroup(toolGroupId);
+    state.toolGroups.splice(toolGroupIndex, 1);
+  }
+}
+
+export default destroyToolGroup;

package/src/store/ToolGroupManager/getAllToolGroups.ts

@@ -0,0 +1,12 @@
+import { state } from '../index';
+import { IToolGroup } from '../../types';
+
+/**
+ * Return the array of tool groups
+ * @returns An array of tool groups.
+ */
+function getAllToolGroups(): Array<IToolGroup> {
+  return state.toolGroups;
+}
+
+export default getAllToolGroups;

package/src/store/ToolGroupManager/getToolGroup.ts

@@ -0,0 +1,14 @@
+import { state } from '../index';
+import { IToolGroup } from '../../types';
+
+/**
+ * Given a tool group Id, return the tool group
+ * @param toolGroupId - The Id of the tool group to be retrieved.
+ * @returns The tool group that has the same id as the tool group id that was
+ * passed in.
+ */
+function getToolGroup(toolGroupId: string): IToolGroup | undefined {
+  return state.toolGroups.find((s) => s.id === toolGroupId);
+}
+
+export default getToolGroup;

package/src/store/ToolGroupManager/getToolGroupForViewport.ts

@@ -0,0 +1,44 @@
+import { state } from '../index';
+import { IToolGroup } from '../../types';
+
+/**
+ * Given a rendering engine Id and a viewport Id, return the tool group that
+ * contains that rendering engine and viewport. Note: A viewport can only be
+ * associated with a single tool group. You cannot have a viewport that belongs
+ * to multiple tool groups. To achieve so, create a new viewport and a new toolGroup
+ * for it. This will not impact memory usage much as the volume textures are
+ * shared across all viewports rendering the same image.
+ *
+ * @param viewportId - The Id of the viewport that the tool is being
+ * added to.
+ * @param renderingEngineId - The Id of the rendering engine that the
+ * tool group is associated with.
+ * @returns A tool group.
+ */
+function getToolGroupForViewport(
+  viewportId: string,
+  renderingEngineId: string
+): IToolGroup | undefined {
+  const toolGroupFilteredByIds = state.toolGroups.filter((tg) =>
+    tg.viewportsInfo.some(
+      (vp) =>
+        vp.renderingEngineId === renderingEngineId &&
+        (!vp.viewportId || vp.viewportId === viewportId)
+    )
+  );
+
+  if (!toolGroupFilteredByIds.length) {
+    return;
+  }
+
+  if (toolGroupFilteredByIds.length > 1) {
+    throw new Error(
+      `Multiple tool groups found for renderingEngineId: ${renderingEngineId} and viewportId: ${viewportId}. You should only
+      have one tool group per viewport in a renderingEngine.`
+    );
+  }
+
+  return toolGroupFilteredByIds[0];
+}
+
+export default getToolGroupForViewport;

package/src/store/ToolGroupManager/getToolGroupsWithToolName.ts

@@ -0,0 +1,33 @@
+import { state } from '../index';
+import { IToolGroup } from '../../types';
+import { ToolModes } from '../../enums';
+
+const MODES = [ToolModes.Active, ToolModes.Passive, ToolModes.Enabled];
+
+/**
+ * Returns the toolGroups that has the given toolName as active, passive
+ * or enabled.
+ * @param toolName - The name of the tool
+ * @returns An array of tool groups.
+ */
+function getToolGroupsWithToolName(toolName: string): IToolGroup[] | [] {
+  return state.toolGroups.filter(({ toolOptions }) => {
+    const toolGroupToolNames = Object.keys(toolOptions);
+
+    for (let i = 0; i < toolGroupToolNames.length; i++) {
+      if (toolName !== toolGroupToolNames[i]) continue;
+
+      /* filter out tools that don't have options */
+      if (!toolOptions[toolName]) {
+        continue;
+      }
+
+      if (MODES.includes(toolOptions[toolName].mode)) {
+        return true;
+      }
+    }
+    return false;
+  });
+}
+
+export default getToolGroupsWithToolName;

package/src/store/ToolGroupManager/index.ts

@@ -0,0 +1,17 @@
+import createToolGroup from './createToolGroup';
+import destroyToolGroup from './destroyToolGroup';
+import destroy from './destroy';
+import getToolGroup from './getToolGroup';
+import getToolGroupForViewport from './getToolGroupForViewport';
+import getAllToolGroups from './getAllToolGroups';
+import getToolGroupsWithToolName from './getToolGroupsWithToolName';
+
+export {
+  createToolGroup,
+  destroy,
+  destroyToolGroup,
+  getToolGroup,
+  getToolGroupForViewport,
+  getAllToolGroups,
+  getToolGroupsWithToolName,
+};

package/src/store/addEnabledElement.ts

@@ -0,0 +1,137 @@
+import { Types } from '@cornerstonejs/core';
+import {
+  mouseEventListeners,
+  wheelEventListener,
+  touchEventListeners,
+  keyEventListener,
+} from '../eventListeners';
+import {
+  imageRenderedEventDispatcher,
+  cameraModifiedEventDispatcher,
+  mouseToolEventDispatcher,
+  touchToolEventDispatcher,
+  keyboardToolEventDispatcher,
+  imageSpacingCalibratedEventDispatcher,
+} from '../eventDispatchers';
+import { state } from './state';
+
+import { annotationRenderingEngine } from '../utilities/triggerAnnotationRender';
+
+/**
+ * When an element is "enabled", add event listeners and dispatchers to it
+ * so we can use interactions to affect tool behaviors
+ *
+ * @param evt - The ELEMENT_ENABLED event
+ */
+export default function addEnabledElement(
+  evt: Types.EventTypes.ElementEnabledEvent
+): void {
+  const { element, viewportId } = evt.detail;
+  const svgLayer = _createSvgAnnotationLayer(viewportId);
+
+  // Reset/Create svgNodeCache for element
+  _setSvgNodeCache(element);
+  _appendChild(svgLayer, element);
+
+  // Add this element to the annotation rendering engine
+  annotationRenderingEngine.addViewportElement(viewportId, element);
+
+  // Listeners
+  mouseEventListeners.enable(element);
+  wheelEventListener.enable(element);
+  touchEventListeners.enable(element);
+  keyEventListener.enable(element);
+
+  // Dispatchers: renderer
+  imageRenderedEventDispatcher.enable(element);
+  cameraModifiedEventDispatcher.enable(element);
+  imageSpacingCalibratedEventDispatcher.enable(element);
+  // Dispatchers: interaction
+  mouseToolEventDispatcher.enable(element);
+  keyboardToolEventDispatcher.enable(element);
+  touchToolEventDispatcher.enable(element);
+
+  // labelmap
+  // State
+  state.enabledElements.push(element);
+}
+
+/**
+ *
+ */
+function _createSvgAnnotationLayer(viewportId: string): SVGElement {
+  const svgns = 'http://www.w3.org/2000/svg';
+  const svgLayer = document.createElementNS(svgns, 'svg');
+
+  const svgLayerId = `svg-layer-${viewportId}`;
+  svgLayer.classList.add('svg-layer');
+  svgLayer.setAttribute('id', svgLayerId);
+  svgLayer.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
+  svgLayer.style.width = '100%';
+  svgLayer.style.height = '100%';
+  svgLayer.style.pointerEvents = 'none';
+  svgLayer.style.position = 'absolute';
+  // TODO: we should test this on high-res monitors
+  //svgLayer.style.textRendering = 'optimizeSpeed'
+
+  // Single dropshadow config for now
+  const defs = document.createElementNS(svgns, 'defs');
+  const filter = document.createElementNS(svgns, 'filter');
+  const feOffset = document.createElementNS(svgns, 'feOffset');
+  const feColorMatrix = document.createElementNS(svgns, 'feColorMatrix');
+  const feBlend = document.createElementNS(svgns, 'feBlend');
+
+  //
+  filter.setAttribute('id', `shadow-${svgLayerId}`);
+  filter.setAttribute('filterUnits', 'userSpaceOnUse');
+
+  //
+  feOffset.setAttribute('result', 'offOut');
+  feOffset.setAttribute('in', 'SourceGraphic');
+  feOffset.setAttribute('dx', '0.5');
+  feOffset.setAttribute('dy', '0.5');
+
+  //
+  feColorMatrix.setAttribute('result', 'matrixOut');
+  feColorMatrix.setAttribute('in', 'offOut');
+  feColorMatrix.setAttribute('in2', 'matrix');
+  feColorMatrix.setAttribute(
+    'values',
+    '0.2 0 0 0 0 0 0.2 0 0 0 0 0 0.2 0 0 0 0 0 1 0'
+  );
+
+  //
+  feBlend.setAttribute('in', 'SourceGraphic');
+  feBlend.setAttribute('in2', 'matrixOut');
+  feBlend.setAttribute('mode', 'normal');
+
+  filter.appendChild(feOffset);
+  filter.appendChild(feColorMatrix);
+  filter.appendChild(feBlend);
+  defs.appendChild(filter);
+  svgLayer.appendChild(defs);
+
+  return svgLayer;
+}
+
+function _setSvgNodeCache(element) {
+  const { viewportUid: viewportId, renderingEngineUid: renderingEngineId } =
+    element.dataset;
+  const elementHash = `${viewportId}:${renderingEngineId}`;
+
+  // Create or reset
+  // TODO: If... Reset, we should blow out any nodes in DOM
+  state.svgNodeCache[elementHash] = {};
+}
+
+/**
+ *
+ * @param newNode
+ * @param referenceNode
+ */
+function _appendChild(
+  newNode: SVGElement,
+  referenceNode: HTMLDivElement
+): void {
+  referenceNode.querySelector('div.viewport-element').appendChild(newNode);
+}

package/src/store/addTool.ts

@@ -0,0 +1,56 @@
+import { state } from './state';
+
+/**
+ * Adds the tool class to the cornerstoneTools to be used later. This function
+ * should be called before creating the toolGroups and adding tools and setting their mode.
+ * The flow is:
+ * - addTool(ToolClass) // where ToolClass is the tool constructor imported from CornerstoneTools or created by a 3rd party
+ * - createToolGroup(toolGroupId)
+ * - toolGroup.addTool(${toolName}) // NOT THE TOOL CLASS
+ * - toolGroup.setToolActive(${toolName})
+ *
+ * @param ToolClass - A tool calls to instantiate.
+ * @param toolOptions - The tool-specific configuration options for the tool.
+ * @returns
+ */
+export function addTool(ToolClass): void {
+  // Check if tool exists and name is not undefined
+  const toolName = ToolClass.toolName;
+  const toolAlreadyAdded = state.tools[toolName] !== undefined;
+
+  if (!toolName) {
+    throw new Error(`No Tool Found for the ToolClass ${ToolClass.name}`);
+  }
+
+  if (toolAlreadyAdded) {
+    throw new Error(`${toolName} has already been added globally`);
+  }
+
+  // Stores the toolNames and ToolClass to be instantiated in the toolGroup on toolGroup.addTool
+  state.tools[toolName] = {
+    toolClass: ToolClass,
+  };
+}
+
+/**
+ * Removes the tool class from the cornerstoneTools.
+ *
+ * @param ToolClass - A tool calls to instantiate.
+ */
+export function removeTool(ToolClass): void {
+  const toolName = ToolClass.toolName;
+
+  if (!toolName) {
+    throw new Error(`No tool found for: ${ToolClass.name}`);
+  }
+
+  if (!state.tools[toolName] !== undefined) {
+    delete state.tools[toolName];
+  } else {
+    throw new Error(
+      `${toolName} cannot be removed because it has not been added`
+    );
+  }
+}
+
+export default addTool;

package/src/store/cancelActiveManipulations.ts

@@ -0,0 +1,30 @@
+import { ToolModes } from '../enums';
+import getToolsWithModesForElement from '../utilities/getToolsWithModesForElement';
+import filterToolsWithAnnotationsForElement from './filterToolsWithAnnotationsForElement';
+
+/**
+ * Cancel the current active manipulation that is being performed on the provided
+ * element. It filters all the active and passive tools for the enabledElement
+ * and calls cancel() method for all of them, and returns the tool that has executed its
+ * cancellation (returned its annotationUID), since tools that are not being manipulated will
+ * short circuit early. Note: not all tools currently implement a cancel method.
+ *
+ * @param element - canvas element
+ * @returns annotationUID that is cancelled
+ */
+export default function cancelActiveManipulations(
+  element: HTMLDivElement
+): string | undefined {
+  const tools = getToolsWithModesForElement(element, [
+    ToolModes.Active,
+    ToolModes.Passive,
+  ]);
+
+  const toolsWithData = filterToolsWithAnnotationsForElement(element, tools);
+  for (const { tool } of toolsWithData) {
+    const annotationUID = tool.cancel(element);
+    if (annotationUID) {
+      return annotationUID;
+    }
+  }
+}

package/src/store/filterMoveableAnnotationTools.ts

@@ -0,0 +1,61 @@
+import type { Types } from '@cornerstonejs/core';
+
+import {
+  ToolAnnotationPair,
+  ToolAnnotationsPair,
+} from '../types/InternalToolTypes';
+
+/**
+ * Filters an array of tools with annotations, returning the first annotation
+ * for each tool that is moveable and at the mouse location. It results in
+ * one annotation per tool.
+ *
+ *
+ * @param element - The HTML element
+ * @param ToolAndAnnotations - The input tool array.
+ * @param canvasCoords - The coordinates of the mouse position.
+ * @param interactionType - The type of interaction that is taking place.
+ * @returns The filtered array containing ToolAndAnnotation
+ */
+export default function filterMoveableAnnotationTools(
+  element: HTMLDivElement,
+  ToolAndAnnotations: ToolAnnotationsPair[],
+  canvasCoords: Types.Point2,
+  interactionType = 'mouse'
+): ToolAnnotationPair[] {
+  const proximity = interactionType === 'touch' ? 36 : 6;
+
+  // TODO - This could get pretty expensive pretty quickly. We don't want to fetch the camera
+  // And do world to canvas on each coord.
+
+  // We want to produce a matrix from canvas to world for the viewport and just do a matrix operation on each handle.
+  // This could still be expensive for ROIs, but we probably shouldn't have "handles" for them anyway.
+
+  const moveableAnnotationTools = [];
+
+  ToolAndAnnotations.forEach(({ tool, annotations }) => {
+    for (const annotation of annotations) {
+      if (annotation.isLocked || !annotation.isVisible) {
+        continue;
+      }
+
+      const near = tool.isPointNearTool(
+        element,
+        annotation,
+        canvasCoords,
+        proximity,
+        interactionType
+      );
+
+      if (near) {
+        moveableAnnotationTools.push({
+          tool,
+          annotation,
+        });
+        break;
+      }
+    }
+  });
+
+  return moveableAnnotationTools;
+}

package/src/store/filterToolsWithAnnotationsForElement.ts

@@ -0,0 +1,51 @@
+import { getAnnotations } from '../stateManagement/annotation/annotationState';
+import { ToolAnnotationsPair } from '../types/InternalToolTypes';
+import type AnnotationTool from '../tools/base/AnnotationTool';
+import BaseTool from '../tools/base/BaseTool';
+import { getEnabledElement } from '@cornerstonejs/core';
+
+/**
+ * Filters an array of tools, returning only tools which have annotation.
+ *
+ * @param element - The cornerstone3D enabled element.
+ * @param tools - The array of tools to check.
+ *
+ * @returns The array of tools with their found annotations.
+ */
+export default function filterToolsWithAnnotationsForElement(
+  element: HTMLDivElement,
+  tools: AnnotationTool[]
+): ToolAnnotationsPair[] {
+  const result = [];
+  for (let i = 0; i < tools.length; i++) {
+    const tool = tools[i];
+
+    if (!tool) {
+      console.warn('undefined tool in filterToolsWithAnnotationsForElement');
+      continue;
+    }
+
+    let annotations = getAnnotations(
+      (tool.constructor as typeof BaseTool).toolName,
+      element
+    );
+
+    if (!annotations?.length) {
+      continue;
+    }
+
+    if (typeof tool.filterInteractableAnnotationsForElement === 'function') {
+      // If the tool has a annotations filter (e.g. with in-plane-annotations-only filtering), use it.
+      annotations = tool.filterInteractableAnnotationsForElement(
+        element,
+        annotations
+      );
+    }
+
+    if (annotations.length > 0) {
+      result.push({ tool, annotations });
+    }
+  }
+
+  return result;
+}

package/src/store/filterToolsWithMoveableHandles.ts

@@ -0,0 +1,51 @@
+import type { Types } from '@cornerstonejs/core';
+
+import {
+  ToolAnnotationsPair,
+  ToolsWithMoveableHandles,
+} from '../types/InternalToolTypes';
+
+/**
+ * Filters an array of tools, returning only tools with moveable handles at the mouse location that are not locked
+ *
+ * @param element - The element
+ * @param ToolAndAnnotations - The input tool array.
+ * @param canvasCoords - The coordinates of the mouse position.
+ * @param interactionType - The type of interaction (e.g. 'mouse' or 'touch')
+ * @returns The filtered array.
+ */
+export default function filterToolsWithMoveableHandles(
+  element: HTMLDivElement,
+  ToolAndAnnotations: ToolAnnotationsPair[],
+  canvasCoords: Types.Point2,
+  interactionType = 'mouse'
+): ToolsWithMoveableHandles[] {
+  const proximity = interactionType === 'touch' ? 36 : 6;
+  const toolsWithMoveableHandles = [];
+
+  ToolAndAnnotations.forEach(({ tool, annotations }) => {
+    for (const annotation of annotations) {
+      if (annotation.isLocked || !annotation.isVisible) {
+        continue;
+      }
+
+      const handle = tool.getHandleNearImagePoint(
+        element,
+        annotation,
+        canvasCoords,
+        proximity
+      );
+
+      if (handle) {
+        toolsWithMoveableHandles.push({
+          tool,
+          annotation,
+          handle,
+        });
+        break;
+      }
+    }
+  });
+
+  return toolsWithMoveableHandles;
+}

package/src/store/index.ts

@@ -0,0 +1,29 @@
+import { addTool, removeTool } from './addTool';
+import addEnabledElement from './addEnabledElement';
+import removeEnabledElement from './removeEnabledElement';
+import cancelActiveManipulations from './cancelActiveManipulations';
+//
+
+import Synchronizer from './SynchronizerManager/Synchronizer';
+
+import svgNodeCache from './svgNodeCache';
+import state from './state';
+
+import * as ToolGroupManager from './ToolGroupManager';
+import * as SynchronizerManager from './SynchronizerManager';
+
+export {
+  // Store
+  state,
+  addTool,
+  removeTool,
+  addEnabledElement,
+  removeEnabledElement,
+  cancelActiveManipulations,
+  svgNodeCache,
+  // Managers
+  ToolGroupManager,
+  SynchronizerManager,
+  // Classes
+  Synchronizer,
+};