@cornerstonejs/tools 0.56.1 → 0.56.3

package/src/utilities/drawing/getTextBoxCoordsCanvas.ts

@@ -0,0 +1,45 @@
+import type { Types } from '@cornerstonejs/core';
+
+/**
+ * Determine the coordinates that will place the textbox to the right of the
+ * annotation.
+ *
+ * @param annotationCanvasPoints - The canvas points of the annotation's handles.
+ * @returns - The coordinates for default placement of the textbox.
+ */
+export default function getTextBoxCoordsCanvas(
+  annotationCanvasPoints: Array<Types.Point2>
+): Types.Point2 {
+  const corners = _determineCorners(annotationCanvasPoints);
+  const centerY = (corners.top[1] + corners.bottom[1]) / 2;
+  const textBoxCanvas = <Types.Point2>[corners.right[0], centerY];
+
+  return textBoxCanvas;
+}
+
+/**
+ * Determine the handles that have the min/max x and y values.
+ *
+ * @param canvasPoints - The canvas points of the annotation's handles.
+ * @returns - The top, left, bottom, and right handles.
+ */
+function _determineCorners(canvasPoints: Array<Types.Point2>) {
+  const handlesLeftToRight = [canvasPoints[0], canvasPoints[1]].sort(_compareX);
+  const handlesTopToBottom = [canvasPoints[0], canvasPoints[1]].sort(_compareY);
+  const right = handlesLeftToRight[handlesLeftToRight.length - 1];
+  const top = handlesTopToBottom[0];
+  const bottom = handlesTopToBottom[handlesTopToBottom.length - 1];
+
+  return {
+    top,
+    bottom,
+    right,
+  };
+
+  function _compareX(a, b) {
+    return a[0] < b[0] ? -1 : 1;
+  }
+  function _compareY(a, b) {
+    return a[1] < b[1] ? -1 : 1;
+  }
+}

package/src/utilities/drawing/index.ts

@@ -0,0 +1,3 @@
+import getTextBoxCoordsCanvas from './getTextBoxCoordsCanvas';
+
+export { getTextBoxCoordsCanvas };

package/src/utilities/dynamicVolume/getDataInTime.ts

@@ -0,0 +1,110 @@
+import { utilities, cache, Types } from '@cornerstonejs/core';
+
+/**
+ * Gets the scalar data for a series of time points for either a single
+ * coordinate or a segmentation mask, it will return the an array of scalar
+ * data for a single coordinate or an array of arrays for a segmentation.
+ *
+ * @param dynamicVolume: 4D volume to compute time point data from
+ * @param options: frameNumbers: which frames to use as timepoints, if left
+ * blank, gets data timepoints over all frames
+ * maskVolumeId: segmentationId to get timepoint data of
+ * imageCoordinate: world coordinate to get timepoint data of
+ * @returns
+ */
+function getDataInTime(
+  dynamicVolume: Types.IDynamicImageVolume,
+  options: {
+    frameNumbers?;
+    maskVolumeId?;
+    imageCoordinate?;
+  }
+): number[] | number[][] {
+  let dataInTime;
+
+  // if frameNumbers is not provided, all frames are selected
+  const frames = options.frameNumbers || [
+    ...Array(dynamicVolume.numTimePoints).keys(),
+  ];
+
+  // You only need to provide either maskVolumeId OR imageCoordinate.
+  // Throws error if neither maskVolumeId or imageCoordinate is given,
+  // throws error if BOTH maskVolumeId and imageCoordinate is given
+  if (!options.maskVolumeId && !options.imageCoordinate) {
+    throw new Error('No ROI provided');
+  }
+
+  if (options.maskVolumeId && options.imageCoordinate) {
+    throw new Error('Please provide only one ROI');
+  }
+
+  if (options.maskVolumeId) {
+    const segmentationVolume = cache.getVolume(options.maskVolumeId);
+
+    // Get the index of every non-zero voxel in mask by mapping indexes to
+    // new array, then using the array to filter
+    const indexArray = segmentationVolume
+      .getScalarData()
+      .map((_, i) => i)
+      .filter((i) => segmentationVolume.getScalarData()[i] !== 0);
+    const dataInTime = _getTimePointDataMask(frames, indexArray, dynamicVolume);
+
+    return dataInTime;
+  }
+
+  if (options.imageCoordinate) {
+    const dataInTime = _getTimePointDataCoordinate(
+      frames,
+      options.imageCoordinate,
+      dynamicVolume
+    );
+
+    return dataInTime;
+  }
+
+  return dataInTime;
+}
+
+function _getTimePointDataCoordinate(frames, coordinate, volume) {
+  const { dimensions, imageData } = volume;
+  const index = imageData.worldToIndex(coordinate);
+
+  index[0] = Math.floor(index[0]);
+  index[1] = Math.floor(index[1]);
+  index[2] = Math.floor(index[2]);
+
+  if (!utilities.indexWithinDimensions(index, dimensions)) {
+    throw new Error('outside bounds');
+  }
+
+  // calculate offset for index
+  const yMultiple = dimensions[0];
+  const zMultiple = dimensions[0] * dimensions[1];
+  const allScalarData = volume.getScalarDataArrays();
+  const value = [];
+
+  for (let i = frames[0]; i < frames[0] + frames.length; i++) {
+    const activeScalarData = allScalarData[i];
+    const scalarIndex = index[2] * zMultiple + index[1] * yMultiple + index[0];
+    value.push(activeScalarData[scalarIndex]);
+  }
+
+  return value;
+}
+
+function _getTimePointDataMask(frames, indexArray, volume) {
+  const allScalarData = volume.getScalarDataArrays();
+  const value = [];
+
+  for (let i = 0; i < indexArray.length; i++) {
+    const indexValues = [];
+    for (let j = frames[0]; j < frames[0] + frames.length; j++) {
+      const activeScalarData = allScalarData[j];
+      indexValues.push(activeScalarData[indexArray[i]]);
+    }
+    value.push(indexValues);
+  }
+  return value;
+}
+
+export default getDataInTime;

package/src/utilities/dynamicVolume/index.ts

@@ -0,0 +1,2 @@
+import getDataInTime from './getDataInTime';
+export { getDataInTime };

package/src/utilities/getAnnotationNearPoint.ts

@@ -0,0 +1,130 @@
+import { getEnabledElement } from '@cornerstonejs/core';
+import type { Types } from '@cornerstonejs/core';
+
+import { AnnotationTool, BaseTool } from '../tools';
+import { Annotation } from '../types';
+import { getAnnotations } from '../stateManagement/annotation/annotationState';
+import * as ToolGroupManager from '../store/ToolGroupManager';
+
+/**
+ * Get the annotation that is close to the provided canvas point, it will return
+ * the first annotation that is found.
+ *
+ * @param element - The element to search for an annotation on.
+ * @param canvasPoint - The canvasPoint on the page where the user clicked.
+ * @param proximity - The distance from the canvasPoint to the annotation.
+ * @returns The annotation for the element
+ */
+function getAnnotationNearPoint(
+  element: HTMLDivElement,
+  canvasPoint: Types.Point2,
+  proximity = 5
+): Annotation | null {
+  // Todo: this function should return closest annotation, BUT, we are not using
+  // the function anywhere.
+  const enabledElement = getEnabledElement(element);
+  if (!enabledElement) {
+    throw new Error('getAnnotationNearPoint: enabledElement not found');
+  }
+
+  return getAnnotationNearPointOnEnabledElement(
+    enabledElement,
+    canvasPoint,
+    proximity
+  );
+}
+
+/**
+ * "Find the annotation near the point on the enabled element." it will return the
+ * first annotation that is found.
+ *
+ * @param enabledElement - The element that is currently active.
+ * @param point - The point to search near.
+ * @param proximity - The distance from the point that the annotation must
+ * be within.
+ * @returns A Annotation object.
+ */
+function getAnnotationNearPointOnEnabledElement(
+  enabledElement: Types.IEnabledElement,
+  point: Types.Point2,
+  proximity: number
+): Annotation | null {
+  // Todo: this function should return closest annotation, BUT, we are not using
+  // the function anywhere.
+  const { renderingEngineId, viewportId } = enabledElement;
+  const toolGroup = ToolGroupManager.getToolGroupForViewport(
+    viewportId,
+    renderingEngineId
+  );
+
+  if (!toolGroup) {
+    return null;
+  }
+
+  const { _toolInstances: tools } = toolGroup;
+  for (const name in tools) {
+    const found = findAnnotationNearPointByTool(
+      tools[name],
+      enabledElement,
+      point,
+      proximity
+    );
+    if (found) {
+      return found;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * For the provided toolClass, it will find the annotation that is near the point,
+ * it will return the first annotation that is found.
+ *
+ * @param tool - AnnotationTool
+ * @param enabledElement - The element that is currently active.
+ * @param point - The point in the image where the user clicked.
+ * @param proximity - The distance from the point that the tool must be
+ * within to be considered "near" the point.
+ * @returns The annotation object that is being returned is the annotation object that
+ * is being used in the tool.
+ */
+function findAnnotationNearPointByTool(
+  tool: AnnotationTool,
+  enabledElement: Types.IEnabledElement,
+  point: Types.Point2,
+  proximity: number
+): Annotation | null {
+  // Todo: this function does not return closest annotation. It just returns
+  // the first annotation that is found in the proximity. BUT, we are not using
+  // the function anywhere.
+  const { viewport } = enabledElement;
+
+  const annotations = getAnnotations(
+    (tool.constructor as typeof BaseTool).toolName,
+    viewport?.element
+  );
+  const currentId = viewport?.getCurrentImageId?.();
+  if (annotations?.length) {
+    const { element } = enabledElement.viewport;
+    for (const annotation of annotations) {
+      const referencedImageId = annotation.metadata?.referencedImageId;
+      if (
+        (currentId && referencedImageId && currentId !== referencedImageId) ||
+        !tool.isPointNearTool
+      ) {
+        continue;
+      }
+
+      if (
+        tool.isPointNearTool(element, annotation, point, proximity, '') ||
+        tool.getHandleNearImagePoint(element, annotation, point, proximity)
+      ) {
+        return annotation;
+      }
+    }
+  }
+  return null;
+}
+
+export { getAnnotationNearPoint, getAnnotationNearPointOnEnabledElement };

package/src/utilities/getModalityUnit.ts

@@ -0,0 +1,11 @@
+function getModalityUnit(modality: string, isPreScaled: boolean): string {
+  if (modality === 'CT') {
+    return 'HU';
+  } else if (modality === 'PT' && isPreScaled === true) {
+    return 'SUV';
+  } else {
+    return '';
+  }
+}
+
+export { getModalityUnit };

package/src/utilities/getToolsWithModesForElement.ts

@@ -0,0 +1,52 @@
+import { ToolGroupManager } from '../store';
+import { ToolModes } from '../enums';
+import { getEnabledElement } from '@cornerstonejs/core';
+
+type ModesFilter = Array<ToolModes>;
+
+/**
+ * Finds the enabled element, and iterates over the tools inside its
+ * toolGroup. Returns the list of tool instances that are valid based
+ * on the provided tool mode.
+ *
+ * @param element Canvas element
+ * @param modesFilter tool modes: active, passive, enabled, disabled
+ * @returns enabled tool instances
+ */
+export default function getToolsWithModesForElement(
+  element: HTMLDivElement,
+  modesFilter: ModesFilter
+) {
+  const enabledElement = getEnabledElement(element);
+  const { renderingEngineId, viewportId } = enabledElement;
+
+  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 toolOptions = toolGroup.toolOptions[toolName];
+
+    /* filter out tools that don't have options */
+    if (!toolOptions) {
+      continue;
+    }
+
+    if (modesFilter.includes(toolOptions.mode)) {
+      const toolInstance = toolGroup.getToolInstance(toolName);
+      enabledTools.push(toolInstance);
+    }
+  }
+
+  return enabledTools;
+}

package/src/utilities/index.ts

@@ -0,0 +1,68 @@
+import {
+  getAnnotationNearPoint,
+  getAnnotationNearPointOnEnabledElement,
+} from './getAnnotationNearPoint';
+
+// Lodash/common JS functionality
+import debounce from './debounce';
+import throttle from './throttle';
+import isObject from './isObject';
+import clip from './clip';
+import calibrateImageSpacing from './calibrateImageSpacing';
+import triggerAnnotationRenderForViewportIds from './triggerAnnotationRenderForViewportIds';
+import triggerAnnotationRender from './triggerAnnotationRender';
+import jumpToSlice from './viewport/jumpToSlice';
+
+import pointInShapeCallback from './pointInShapeCallback';
+import pointInSurroundingSphereCallback from './pointInSurroundingSphereCallback';
+import scroll from './scroll';
+
+// name spaces
+import * as segmentation from './segmentation';
+import * as drawing from './drawing';
+import * as math from './math';
+import * as planar from './planar';
+import * as viewportFilters from './viewportFilters';
+import * as orientation from './orientation';
+import * as cine from './cine';
+import * as boundingBox from './boundingBox';
+import * as planarFreehandROITool from './planarFreehandROITool';
+import * as rectangleROITool from './rectangleROITool';
+import * as stackPrefetch from './stackPrefetch';
+import * as viewport from './viewport';
+import * as touch from './touch';
+import * as dynamicVolume from './dynamicVolume';
+
+// Events
+import { triggerEvent } from '@cornerstonejs/core';
+
+export {
+  math,
+  planar,
+  viewportFilters,
+  drawing,
+  debounce,
+  dynamicVolume,
+  throttle,
+  orientation,
+  isObject,
+  touch,
+  triggerEvent,
+  calibrateImageSpacing,
+  segmentation,
+  triggerAnnotationRenderForViewportIds,
+  triggerAnnotationRender,
+  pointInShapeCallback,
+  pointInSurroundingSphereCallback,
+  getAnnotationNearPoint,
+  getAnnotationNearPointOnEnabledElement,
+  jumpToSlice,
+  viewport,
+  cine,
+  clip,
+  boundingBox,
+  rectangleROITool,
+  planarFreehandROITool,
+  stackPrefetch,
+  scroll,
+};

package/src/utilities/isObject.js

@@ -0,0 +1,29 @@
+/**
+ * Checks if `value` is the
+ * [language type](http://www.ecma-international.org/ecma-262/7.0/#sec-ecmascript-language-types)
+ * of `Object`. (e.g. arrays, functions, objects, regexes, `new Number(0)`, and `new String('')`)
+ *
+ * @since 0.1.0
+ * @param {*} value The value to check.
+ * @returns {boolean} Returns `true` if `value` is an object, else `false`.
+ * @example
+ *
+ * isObject({})
+ * // => true
+ *
+ * isObject([1, 2, 3])
+ * // => true
+ *
+ * isObject(Function)
+ * // => true
+ *
+ * isObject(null)
+ * // => false
+ */
+function isObject(value) {
+  const type = typeof value;
+
+  return value !== null && (type === 'object' || type === 'function');
+}
+
+export default isObject;

package/src/utilities/math/angle/angleBetweenLines.ts

@@ -0,0 +1,29 @@
+import type { Types } from '@cornerstonejs/core';
+import { vec3 } from 'gl-matrix';
+
+type Line = [Types.Point3, Types.Point3];
+
+/**
+ * It returns the angle between two lines in degrees.
+ * @param line1 - Line = [p1, p2]
+ * @param line2 - Line = [p3, p4]
+ * @returns The angle between two lines in degrees.
+ */
+export default function angleBetweenLines(line1: Line, line2: Line): number {
+  const [p1, p2] = line1;
+  const [p3, p4] = line2;
+
+  const v1 = vec3.sub(vec3.create(), p2, p1);
+  const v2 = vec3.sub(vec3.create(), p3, p4);
+
+  const dot = vec3.dot(v1, v2);
+
+  const v1Length = vec3.length(v1);
+  const v2Length = vec3.length(v2);
+
+  const cos = dot / (v1Length * v2Length);
+
+  const radian = Math.acos(cos);
+
+  return (radian * 180) / Math.PI;
+}

package/src/utilities/math/circle/_types.ts

@@ -0,0 +1,6 @@
+import type { Types } from '@cornerstonejs/core';
+
+export type canvasCoordinates = [
+  Types.Point2, // center
+  Types.Point2 // end
+];

package/src/utilities/math/circle/getCanvasCircleCorners.ts

@@ -0,0 +1,23 @@
+import type { Types } from '@cornerstonejs/core';
+import { distanceToPoint } from '../point';
+import { canvasCoordinates } from './_types';
+
+/**
+ * It takes the canvas coordinates of the circle corners (wrapping square rectangle)
+ * and returns the top left and bottom right
+ * corners of it
+ *
+ * @param circleCanvasPoints - The coordinates of the circle in the canvas.
+ * @returns An array of two points.
+ */
+export default function getCanvasCircleCorners(
+  circleCanvasPoints: canvasCoordinates
+): Array<Types.Point2> {
+  const [center, end] = circleCanvasPoints;
+  const radius = distanceToPoint(center, end);
+
+  const topLeft = <Types.Point2>[center[0] - radius, center[1] - radius];
+  const bottomRight = <Types.Point2>[center[0] + radius, center[1] + radius];
+
+  return [topLeft, bottomRight];
+}

package/src/utilities/math/circle/getCanvasCircleRadius.ts

@@ -0,0 +1,16 @@
+import { distanceToPoint } from '../point';
+import { canvasCoordinates } from './_types';
+
+/**
+ * It takes the canvas coordinates of the circle corners and returns the top left and bottom right
+ * corners of it
+ *
+ * @param circleCanvasPoints - The coordinates of the circle in the canvas.
+ * @returns An array of two points.
+ */
+export default function getCanvasCircleRadius(
+  circleCanvasPoints: canvasCoordinates
+): number {
+  const [center, end] = circleCanvasPoints;
+  return distanceToPoint(center, end);
+}

package/src/utilities/math/circle/index.ts

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

package/src/utilities/math/ellipse/getCanvasEllipseCorners.ts

@@ -0,0 +1,26 @@
+import type { Types } from '@cornerstonejs/core';
+
+type canvasCoordinates = [
+  Types.Point2, // bottom
+  Types.Point2, // top
+  Types.Point2, // left
+  Types.Point2 // right
+];
+
+/**
+ * It takes the canvas coordinates of the ellipse corners and returns the top left and bottom right
+ * corners of it
+ *
+ * @param ellipseCanvasPoints - The coordinates of the ellipse in the canvas.
+ * @returns An array of two points.
+ */
+export default function getCanvasEllipseCorners(
+  ellipseCanvasPoints: canvasCoordinates
+): Array<Types.Point2> {
+  const [bottom, top, left, right] = ellipseCanvasPoints;
+
+  const topLeft = <Types.Point2>[left[0], top[1]];
+  const bottomRight = <Types.Point2>[right[0], bottom[1]];
+
+  return [topLeft, bottomRight];
+}

package/src/utilities/math/ellipse/index.ts

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

package/src/utilities/math/ellipse/pointInEllipse.ts

@@ -0,0 +1,38 @@
+import type { Types } from '@cornerstonejs/core';
+
+type Ellipse = {
+  center: Types.Point3;
+  xRadius: number;
+  yRadius: number;
+  zRadius: number;
+};
+
+/**
+ * Given an ellipse and a point, return true if the point is inside the ellipse
+ * @param ellipse - The ellipse object to check against.
+ * @param pointLPS - The point in LPS space to test.
+ * @returns A boolean value.
+ */
+export default function pointInEllipse(
+  ellipse: Ellipse,
+  pointLPS: Types.Point3
+): boolean {
+  const { center: circleCenterWorld, xRadius, yRadius, zRadius } = ellipse;
+  const [x, y, z] = pointLPS;
+  const [x0, y0, z0] = circleCenterWorld;
+
+  let inside = 0;
+  if (xRadius !== 0) {
+    inside += ((x - x0) * (x - x0)) / (xRadius * xRadius);
+  }
+
+  if (yRadius !== 0) {
+    inside += ((y - y0) * (y - y0)) / (yRadius * yRadius);
+  }
+
+  if (zRadius !== 0) {
+    inside += ((z - z0) * (z - z0)) / (zRadius * zRadius);
+  }
+
+  return inside <= 1;
+}

package/src/utilities/math/ellipse/pointInEllipsoidWithConstraint.ts

@@ -0,0 +1,35 @@
+import type { Types } from '@cornerstonejs/core';
+
+type ellipsoid = {
+  center: [number, number, number];
+  width: number;
+  height: number;
+  depth: number;
+};
+
+/**
+ * Checks whether the point is inside the provided ellipse with constraint of a plane (viewPlane).
+ * @param ellipse - ellipse object including {center, width, height, depth}
+ * @param point - [x,y,z] of the point
+ * @param viewPlane - camera viewPlane
+ * @returns whether the point is inside the ellipse
+ */
+export default function pointInEllipsoidWithConstraint(
+  ellipsoid: ellipsoid,
+  point: Types.Point3,
+  viewPlane: Types.Point3 // constraint
+) {
+  // Todo: This implementation should be used for oblique planes segmentation tools
+  // but still not a priority
+  // const { center, width, height, depth } = ellipsoid
+  // const [x, y, z] = point
+  // const [x0, y0, z0] = center
+  // const inside =
+  //   ((x - x0) * (x - x0)) / (width * width) +
+  //     ((y - y0) * (y - y0)) / (height * height) +
+  //     ((z - z0) * (z - z0)) / (depth * depth) <=
+  //   1
+  // const onPlane =
+  //   Math.abs(n1 * (x - x0) + n2 * (y - y0) + n3 * (z - z0)) <= 1e-3
+  // return inside
+}

package/src/utilities/math/index.ts

@@ -0,0 +1,8 @@
+import * as vec2 from './vec2';
+import * as ellipse from './ellipse';
+import * as lineSegment from './line';
+import * as rectangle from './rectangle';
+import * as polyline from './polyline';
+import * as point from './point';
+
+export { vec2, ellipse, lineSegment, rectangle, polyline, point };

package/src/utilities/math/line/distanceToPoint.ts

@@ -0,0 +1,24 @@
+import distanceToPointSquared from './distanceToPointSquared';
+import type { Types } from '@cornerstonejs/core';
+
+/**
+ * Calculates the distance of a point to a line
+ *
+ * @param lineStart - x,y coordinates of the start of the line
+ * @param lineEnd - x,y coordinates of the end of the line
+ * @param point - x,y of the point
+ * @returns distance
+ */
+export default function distanceToPoint(
+  lineStart: Types.Point2,
+  lineEnd: Types.Point2,
+  point: Types.Point2
+): number {
+  if (lineStart.length !== 2 || lineEnd.length !== 2 || point.length !== 2) {
+    throw Error(
+      'lineStart, lineEnd, and point should have 2 elements of [x, y]'
+    );
+  }
+
+  return Math.sqrt(distanceToPointSquared(lineStart, lineEnd, point));
+}