@cornerstonejs/tools 0.56.2 → 0.56.4

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

@@ -0,0 +1,82 @@
+import type { Types } from '@cornerstonejs/core';
+import * as lineSegment from '../line';
+
+type rectLineSegments = {
+  top: Types.Point2[];
+  right: Types.Point2[];
+  bottom: Types.Point2[];
+  left: Types.Point2[];
+};
+
+/**
+ * Given a rectangle left, top, width and height, return an object containing the
+ * line segments that make up the rectangle's four sides
+ * @param left - The x-coordinate of the left edge of the rectangle.
+ * @param top - The y-coordinate of the top edge of the rectangle.
+ * @param width - The width of the rectangle.
+ * @param height - The height of the rectangle.
+ * @returns An object with four keys, each of which contains an array of two
+ * points.
+ */
+function rectToLineSegments(
+  left: number,
+  top: number,
+  width: number,
+  height: number
+): rectLineSegments {
+  const topLineStart: Types.Point2 = [left, top];
+  const topLineEnd: Types.Point2 = [left + width, top];
+
+  const rightLineStart: Types.Point2 = [left + width, top];
+  const rightLineEnd: Types.Point2 = [left + width, top + height];
+
+  const bottomLineStart: Types.Point2 = [left + width, top + height];
+  const bottomLineEnd: Types.Point2 = [left, top + height];
+
+  const leftLineStart: Types.Point2 = [left, top + height];
+  const leftLineEnd: Types.Point2 = [left, top];
+
+  const lineSegments = {
+    top: [topLineStart, topLineEnd],
+    right: [rightLineStart, rightLineEnd],
+    bottom: [bottomLineStart, bottomLineEnd],
+    left: [leftLineStart, leftLineEnd],
+  };
+
+  return lineSegments;
+}
+
+/**
+ * Calculates distance of the point to the rectangle. It calculates the minimum
+ * distance between the point and each line segment of the rectangle.
+ *
+ * @param rect - coordinates of the rectangle [left, top, width, height]
+ * @param point - [x,y] coordinates of a point
+ * @returns
+ */
+export default function distanceToPoint(
+  rect: number[],
+  point: Types.Point2
+): number {
+  if (rect.length !== 4 || point.length !== 2) {
+    throw Error(
+      'rectangle:[left, top, width, height] or point: [x,y] not defined correctly'
+    );
+  }
+
+  const [left, top, width, height] = rect;
+
+  let minDistance = 655535;
+  const lineSegments = rectToLineSegments(left, top, width, height);
+
+  Object.keys(lineSegments).forEach((segment) => {
+    const [lineStart, lineEnd] = lineSegments[segment];
+    const distance = lineSegment.distanceToPoint(lineStart, lineEnd, point);
+
+    if (distance < minDistance) {
+      minDistance = distance;
+    }
+  });
+
+  return minDistance;
+}

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

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

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

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

package/src/utilities/math/sphere/pointInSphere.ts

@@ -0,0 +1,31 @@
+import type { Types } from '@cornerstonejs/core';
+import { vec3 } from 'gl-matrix';
+
+type Sphere = {
+  center: Types.Point3 | vec3;
+  radius: number;
+};
+
+/**
+ * Checks if a point is inside a sphere. Note: this is similar to the
+ * `pointInEllipse` function, but since we don't need checks for the
+ * ellipse's rotation in different views, we can use a simpler equation
+ * which would be faster (no if statements).
+ *
+ * @param sphere - Sphere object with center and radius
+ * @param pointLPS - the point to check in world coordinates
+ * @returns boolean
+ */
+export default function pointInSphere(
+  sphere: Sphere,
+  pointLPS: Types.Point3
+): boolean {
+  const { center, radius } = sphere;
+
+  return (
+    (pointLPS[0] - center[0]) ** 2 +
+      (pointLPS[1] - center[1]) ** 2 +
+      (pointLPS[2] - center[2]) ** 2 <=
+    radius ** 2
+  );
+}

package/src/utilities/math/vec2/findClosestPoint.ts

@@ -0,0 +1,40 @@
+import type { Types } from '@cornerstonejs/core';
+
+/**
+ * Find the closest point to the target point
+ *
+ * @param sourcePoints - The potential source points.
+ * @param targetPoint - The target point, used to find the closest source.
+ * @returns The closest point in the array of point sources
+ */
+export default function findClosestPoint(
+  sourcePoints: Array<Types.Point2>,
+  targetPoint: Types.Point2
+): Types.Point2 {
+  let minPoint = [0, 0];
+  let minDistance = Number.MAX_SAFE_INTEGER;
+
+  sourcePoints.forEach(function (sourcePoint) {
+    const distance = _distanceBetween(targetPoint, sourcePoint);
+
+    if (distance < minDistance) {
+      minDistance = distance;
+      minPoint = [...sourcePoint];
+    }
+  });
+
+  return minPoint as Types.Point2;
+}
+
+/**
+ *
+ * @private
+ * @param p1
+ * @param p2
+ */
+function _distanceBetween(p1: Types.Point2, p2: Types.Point2): number {
+  const [x1, y1] = p1;
+  const [x2, y2] = p2;
+
+  return Math.sqrt(Math.pow(x1 - x2, 2) + Math.pow(y1 - y2, 2));
+}

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

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

package/src/utilities/math/vec2/liangBarksyClip.ts

@@ -0,0 +1,84 @@
+// Pulled from source: https://github.com/w8r/liang-barsky
+// MIT Licensed.
+
+/**
+ * Fast, destructive implementation of Liang-Barsky line clipping algorithm.
+ * It clips a 2D segment by a rectangle.
+ * @author Alexander Milevski <info@w8r.name>
+ * @license MIT
+ */
+
+const EPSILON = 1e-6;
+const INSIDE = 1;
+const OUTSIDE = 0;
+
+function clipT(num, denom, c) {
+  const [tE, tL] = c;
+  if (Math.abs(denom) < EPSILON) return num < 0;
+  const t = num / denom;
+
+  if (denom > 0) {
+    if (t > tL) return 0;
+    if (t > tE) c[0] = t;
+  } else {
+    if (t < tE) return 0;
+    if (t < tL) c[1] = t;
+  }
+  return 1;
+}
+
+/**
+ * @param  {Point} a
+ * @param  {Point} b
+ * @param  {BoundingBox} box [xmin, ymin, xmax, ymax]
+ * @param  {Point?} [da]
+ * @param  {Point?} [db]
+ * @return {number}
+ */
+export default function clip(a, b, box, da?, db?) {
+  const [x1, y1] = a;
+  const [x2, y2] = b;
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+
+  if (da === undefined || db === undefined) {
+    da = a;
+    db = b;
+  } else {
+    da[0] = a[0];
+    da[1] = a[1];
+    db[0] = b[0];
+    db[1] = b[1];
+  }
+
+  if (
+    Math.abs(dx) < EPSILON &&
+    Math.abs(dy) < EPSILON &&
+    x1 >= box[0] &&
+    x1 <= box[2] &&
+    y1 >= box[1] &&
+    y1 <= box[3]
+  ) {
+    return INSIDE;
+  }
+
+  const c = [0, 1];
+  if (
+    clipT(box[0] - x1, dx, c) &&
+    clipT(x1 - box[2], -dx, c) &&
+    clipT(box[1] - y1, dy, c) &&
+    clipT(y1 - box[3], -dy, c)
+  ) {
+    const [tE, tL] = c;
+    if (tL < 1) {
+      db[0] = x1 + tL * dx;
+      db[1] = y1 + tL * dy;
+    }
+    if (tE > 0) {
+      da[0] += tE * dx;
+      da[1] += tE * dy;
+    }
+    return INSIDE;
+  }
+  return OUTSIDE;
+}

package/src/utilities/orientation/getOrientationStringLPS.ts

@@ -0,0 +1,52 @@
+import { Types } from '@cornerstonejs/core';
+
+/**
+ * Returns the orientation of the vector in the patient coordinate system.
+ * @public
+ *
+ * @param vector - Input array
+ * @returns The orientation in the patient coordinate system.
+ */
+export default function getOrientationStringLPS(vector: Types.Point3): string {
+  // Thanks to David Clunie
+  // https://sites.google.com/site/dicomnotes/
+
+  let orientation = '';
+  const orientationX = vector[0] < 0 ? 'R' : 'L';
+  const orientationY = vector[1] < 0 ? 'A' : 'P';
+  const orientationZ = vector[2] < 0 ? 'F' : 'H';
+
+  // Should probably make this a function vector3.abs
+  const abs = [Math.abs(vector[0]), Math.abs(vector[1]), Math.abs(vector[2])];
+
+  const MIN = 0.0001;
+
+  for (let i = 0; i < 3; i++) {
+    if (abs[0] > MIN && abs[0] > abs[1] && abs[0] > abs[2]) {
+      orientation += orientationX;
+      abs[0] = 0;
+    } else if (abs[1] > MIN && abs[1] > abs[0] && abs[1] > abs[2]) {
+      orientation += orientationY;
+      abs[1] = 0;
+    } else if (abs[2] > MIN && abs[2] > abs[0] && abs[2] > abs[1]) {
+      orientation += orientationZ;
+      abs[2] = 0;
+    } else if (abs[0] > MIN && abs[1] > MIN && abs[0] === abs[1]) {
+      orientation += orientationX + orientationY;
+      abs[0] = 0;
+      abs[1] = 0;
+    } else if (abs[0] > MIN && abs[2] > MIN && abs[0] === abs[2]) {
+      orientation += orientationX + orientationZ;
+      abs[0] = 0;
+      abs[2] = 0;
+    } else if (abs[1] > MIN && abs[2] > MIN && abs[1] === abs[2]) {
+      orientation += orientationY + orientationZ;
+      abs[1] = 0;
+      abs[2] = 0;
+    } else {
+      break;
+    }
+  }
+
+  return orientation;
+}

package/src/utilities/orientation/index.ts

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

package/src/utilities/orientation/invertOrientationStringLPS.ts

@@ -0,0 +1,21 @@
+/**
+ * Inverts an orientation string.
+ * @public
+ *
+ * @param orientationString - The orientation.
+ * @returns The inverted orientationString.
+ */
+export default function invertOrientationStringLPS(
+  orientationString: string
+): string {
+  let inverted = orientationString.replace('H', 'f');
+
+  inverted = inverted.replace('F', 'h');
+  inverted = inverted.replace('R', 'l');
+  inverted = inverted.replace('L', 'r');
+  inverted = inverted.replace('A', 'p');
+  inverted = inverted.replace('P', 'a');
+  inverted = inverted.toUpperCase();
+
+  return inverted;
+}

package/src/utilities/planar/filterAnnotationsForDisplay.ts

@@ -0,0 +1,68 @@
+import {
+  StackViewport,
+  VolumeViewport,
+  Types,
+  utilities as csUtils,
+} from '@cornerstonejs/core';
+
+import filterAnnotationsWithinSlice from './filterAnnotationsWithinSlice';
+import { Annotations } from '../../types';
+
+/**
+ * Given the viewport and the annotations, it filters the annotations array and only
+ * return those annotation that should be displayed on the viewport
+ * @param annotations - Annotations
+ * @returns A filtered version of the annotations.
+ */
+export default function filterAnnotationsForDisplay(
+  viewport: Types.IViewport,
+  annotations: Annotations
+): Annotations {
+  if (viewport instanceof StackViewport) {
+    // 1. Get the currently displayed imageId from the StackViewport
+    const imageId = viewport.getCurrentImageId();
+
+    // 2. remove the dataLoader scheme since it might be an annotation that was
+    // created on the volumeViewport initially and has the volumeLoader scheme
+    // but shares the same imageId
+    const colonIndex = imageId.indexOf(':');
+    const imageURI = imageId.substring(colonIndex + 1);
+
+    // 3. Filter annotation in the frame of reference by the referenced image ID property
+    // Note: With the current implementation drawing on the stack (PT stack) will not
+    // show the annotation on a volume that does not share the same imageURIs (CT Volume),
+    // and we don't have a proper way to check distance either since a stack can be
+    // composed of multiple unrelated images
+    return annotations.filter((annotation) => {
+      if (!annotation.isVisible) {
+        return false;
+      }
+
+      const imageId = annotation.metadata.referencedImageId;
+
+      if (imageId === undefined) {
+        // This annotation was not drawn on a non-coplanar reformat, and such does
+        // note have a referenced imageId.
+        return false;
+      }
+
+      const colonIndex = imageId.indexOf(':');
+      const referenceImageURI = imageId.substring(colonIndex + 1);
+      return referenceImageURI === imageURI;
+    });
+  } else if (viewport instanceof VolumeViewport) {
+    const camera = viewport.getCamera();
+
+    const { spacingInNormalDirection } =
+      csUtils.getTargetVolumeAndSpacingInNormalDir(viewport, camera);
+
+    // Get data with same normal and within the same slice
+    return filterAnnotationsWithinSlice(
+      annotations,
+      camera,
+      spacingInNormalDirection
+    );
+  } else {
+    throw new Error(`Viewport Type ${viewport.type} not supported`);
+  }
+}

package/src/utilities/planar/filterAnnotationsWithinSlice.ts

@@ -0,0 +1,85 @@
+import { vec3 } from 'gl-matrix';
+import { CONSTANTS } from '@cornerstonejs/core';
+import type { Types } from '@cornerstonejs/core';
+import { Annotations, Annotation } from '../../types';
+
+const { EPSILON } = CONSTANTS;
+
+const PARALLEL_THRESHOLD = 1 - EPSILON;
+
+/**
+ * given some `Annotations`, and the slice defined by the camera's normal
+ * direction and the spacing in the normal, filter the `Annotations` which
+ * is within the slice.
+ *
+ * @param annotations - Annotations
+ * @param camera - The camera
+ * @param spacingInNormalDirection - The spacing in the normal direction
+ * @returns The filtered `Annotations`.
+ */
+export default function filterAnnotationsWithinSlice(
+  annotations: Annotations,
+  camera: Types.ICamera,
+  spacingInNormalDirection: number
+): Annotations {
+  const { viewPlaneNormal } = camera;
+
+  // The reason we use parallel normals instead of actual orientation is that
+  // flipped action is done through camera API, so we can't rely on the
+  // orientation (viewplaneNormal and viewUp) since even the same image and
+  // same slice if flipped will have different orientation, but still rendering
+  // the same slice. Instead, we choose to use the parallel normals to filter
+  // the annotations and later we fine tune it with the annotation within slice
+  // logic down below.
+  const annotationsWithParallelNormals = annotations.filter(
+    (td: Annotation) => {
+      const annotationViewPlaneNormal = td.metadata.viewPlaneNormal;
+
+      const isParallel =
+        Math.abs(vec3.dot(viewPlaneNormal, annotationViewPlaneNormal)) >
+        PARALLEL_THRESHOLD;
+
+      return annotationViewPlaneNormal && isParallel;
+    }
+  );
+
+  // No in plane annotations.
+  if (!annotationsWithParallelNormals.length) {
+    return [];
+  }
+
+  // Annotation should be within the slice, which means that it should be between
+  // camera's focalPoint +/- spacingInNormalDirection.
+
+  const halfSpacingInNormalDirection = spacingInNormalDirection / 2;
+  const { focalPoint } = camera;
+
+  const annotationsWithinSlice = [];
+
+  for (const annotation of annotationsWithParallelNormals) {
+    const data = annotation.data;
+    const point = data.handles.points[0];
+
+    if (!annotation.isVisible) {
+      continue;
+    }
+    // A = point
+    // B = focal point
+    // P = normal
+
+    // B-A dot P  => Distance in the view direction.
+    // this should be less than half the slice distance.
+
+    const dir = vec3.create();
+
+    vec3.sub(dir, focalPoint, point);
+
+    const dot = vec3.dot(dir, viewPlaneNormal);
+
+    if (Math.abs(dot) < halfSpacingInNormalDirection) {
+      annotationsWithinSlice.push(annotation);
+    }
+  }
+
+  return annotationsWithinSlice;
+}

package/src/utilities/planar/getPointInLineOfSightWithCriteria.ts

@@ -0,0 +1,104 @@
+import vtkMath from '@kitware/vtk.js/Common/Core/Math';
+import { utilities as csUtils } from '@cornerstonejs/core';
+import type { Types } from '@cornerstonejs/core';
+/**
+ * Returns a point based on some criteria (e.g., minimum or maximum intensity) in
+ * the line of sight (on the line between the passed worldPosition and camera position).
+ * It iterated over the points with a step size on the line.
+ *
+ * @param viewport - Volume viewport
+ * @param worldPos - World coordinates of the clicked location
+ * @param targetVolumeId - target Volume ID in the viewport
+ * @param criteriaFunction - A function that returns the point if it passes a certain
+ * written logic, for instance, it can be a maxValue function that keeps the
+ * records of all intensity values, and only return the point if its intensity
+ * is greater than the maximum intensity of the points passed before.
+ * @param stepsSize - Percentage of the spacing in the normal direction, default value
+ * is 0.25 which means steps = 1/4 of the spacing in the normal direction.
+ * @returns the World pos of the point that passes the criteriaFunction
+ */
+export default function getPointInLineOfSightWithCriteria(
+  viewport: Types.IVolumeViewport,
+  worldPos: Types.Point3,
+  targetVolumeId: string,
+  criteriaFunction: (intensity: number, point: Types.Point3) => Types.Point3,
+  stepSize = 0.25
+): Types.Point3 {
+  // 1. Getting the camera from the event details
+  const camera = viewport.getCamera();
+  const { position: cameraPosition } = camera;
+
+  // 2. Calculating the spacing in the normal direction, this will get
+  // used as the step size for iterating over the points in the line of sight
+  const { spacingInNormalDirection } =
+    csUtils.getTargetVolumeAndSpacingInNormalDir(
+      viewport,
+      camera,
+      targetVolumeId
+    );
+  // 2.1 Making sure, we are not missing any point
+  const step = spacingInNormalDirection * stepSize;
+
+  // 3. Getting the bounds of the viewports. Search for brightest point is
+  // limited to the visible bound
+  // Todo: this might be a problem since bounds will change to spatial bounds.
+  const bounds = viewport.getBounds();
+  const xMin = bounds[0];
+  const xMax = bounds[1];
+
+  // 5. Calculating the line, we use a parametric line definition
+  const vector = <Types.Point3>[0, 0, 0];
+
+  // 5.1 Point coordinate on the line
+  let point = <Types.Point3>[0, 0, 0];
+
+  // 5.2 Calculating the line direction, and storing in vector
+  vtkMath.subtract(worldPos, cameraPosition, vector);
+
+  let pickedPoint;
+
+  // 6. Iterating over the line from the lower bound to the upper bound, with the
+  // specified step size
+  for (let pointT = xMin; pointT <= xMax; pointT = pointT + step) {
+    // 6.1 Calculating the point x location
+    point = [pointT, 0, 0];
+    // 6.2 Calculating the point y,z location based on the line equation
+    const t = (pointT - cameraPosition[0]) / vector[0];
+    point[1] = t * vector[1] + cameraPosition[1];
+    point[2] = t * vector[2] + cameraPosition[2];
+
+    // 6.3 Checking if the points is inside the bounds
+    if (_inBounds(point, bounds)) {
+      // 6.4 Getting the intensity of the point
+      const intensity = viewport.getIntensityFromWorld(point);
+      // 6.5 Passing the intensity to the maximum value functions which decides
+      // whether the current point is of interest based on some criteria
+      const pointToPick = criteriaFunction(intensity, point);
+      if (pointToPick) {
+        pickedPoint = pointToPick;
+      }
+    }
+  }
+
+  return pickedPoint;
+}
+
+/**
+ * Returns whether the point in the world is inside the bounds of the viewport
+ * @param point - coordinates in the world
+ * @returns boolean
+ */
+const _inBounds = function (
+  point: Types.Point3,
+  bounds: Array<number>
+): boolean {
+  const [xMin, xMax, yMin, yMax, zMin, zMax] = bounds;
+  return (
+    point[0] > xMin &&
+    point[0] < xMax &&
+    point[1] > yMin &&
+    point[1] < yMax &&
+    point[2] > zMin &&
+    point[2] < zMax
+  );
+};

package/src/utilities/planar/getWorldWidthAndHeightFromCorners.ts

@@ -0,0 +1,51 @@
+import { vec3 } from 'gl-matrix';
+import type { Types } from '@cornerstonejs/core';
+
+/**
+ * Given two world positions and an orthogonal view to an `imageVolume` defined
+ * by a `viewPlaneNormal` and a `viewUp`, get the width and height in world coordinates
+ * of the rectangle defined by the two points. The implementation works both with orthogonal
+ * non-orthogonal rectangles.
+ *
+ * @param viewPlaneNormal - The normal of the view.
+ * @param viewUp - The up direction of the view.
+ * @param imageVolume - The imageVolume to use to measure.
+ * @param topLeftWorld - The first world position.
+ * @param bottomRightWorld - The second world position.
+ *
+ * @returns The `worldWidth` and `worldHeight`.
+ */
+export default function getWorldWidthAndHeightFromCorners(
+  viewPlaneNormal: Types.Point3,
+  viewUp: Types.Point3,
+  topLeftWorld: Types.Point3,
+  bottomRightWorld: Types.Point3
+): { worldWidth: number; worldHeight: number } {
+  const viewRight = vec3.create();
+
+  vec3.cross(viewRight, <vec3>viewUp, <vec3>viewPlaneNormal);
+
+  const pos1 = vec3.fromValues(...topLeftWorld);
+  const pos2 = vec3.fromValues(...bottomRightWorld);
+
+  const diagonal = vec3.create();
+  vec3.subtract(diagonal, pos1, pos2);
+
+  const diagonalLength = vec3.length(diagonal);
+
+  // When the two points are very close to each other return width as 0
+  // to avoid NaN the cosTheta formula calculation
+  if (diagonalLength < 0.0001) {
+    return { worldWidth: 0, worldHeight: 0 };
+  }
+
+  const cosTheta =
+    vec3.dot(diagonal, viewRight) / (diagonalLength * vec3.length(viewRight));
+
+  const sinTheta = Math.sqrt(1 - cosTheta * cosTheta);
+
+  const worldWidth = sinTheta * diagonalLength;
+  const worldHeight = cosTheta * diagonalLength;
+
+  return { worldWidth, worldHeight };
+}