@cornerstonejs/tools 1.33.0 → 1.35.0

package/src/tools/index.ts

@@ -26,6 +26,7 @@ import DragProbeTool from './annotation/DragProbeTool';
 import RectangleROITool from './annotation/RectangleROITool';
 import EllipticalROITool from './annotation/EllipticalROITool';
 import CircleROITool from './annotation/CircleROITool';
+import SplineROITool from './annotation/SplineROITool';
 import PlanarFreehandROITool from './annotation/PlanarFreehandROITool';
 import ArrowAnnotateTool from './annotation/ArrowAnnotateTool';
 import AngleTool from './annotation/AngleTool';
@@ -73,6 +74,7 @@ export {
   RectangleROITool,
   EllipticalROITool,
   CircleROITool,
+  SplineROITool,
   PlanarFreehandROITool,
   ArrowAnnotateTool,
   AngleTool,

package/src/types/CardinalSplineProps.ts

@@ -0,0 +1,11 @@
+import { SplineProps } from './SplineProps';
+
+/**
+ * Cardinal spline properties
+ */
+export type CardinalSplineProps = SplineProps & {
+  /** Scale that must be in 0-1 range */
+  scale?: number;
+  /** Fixed scale used by children classes (Catmull-Rom and Linear splines) */
+  fixedScale?: boolean;
+};

package/src/types/ClosestControlPoint.ts

@@ -0,0 +1,6 @@
+import type { ClosestPoint } from './ClosestPoint';
+
+export type ClosestControlPoint = ClosestPoint & {
+  /** Control point index */
+  index: number;
+};

package/src/types/ClosestPoint.ts

@@ -0,0 +1,8 @@
+import { Types } from '@cornerstonejs/core';
+
+export type ClosestPoint = {
+  /** 2D coordinate */
+  point: Types.Point2;
+  /** Distance to the reference point */
+  distance: number;
+};

package/src/types/ClosestSplinePoint.ts

@@ -0,0 +1,6 @@
+import type { ClosestPoint } from './ClosestPoint';
+
+export type ClosestSplinePoint = ClosestPoint & {
+  /** `u` value in Parameter Space (curve segment index + `t` value from 0-1) */
+  uValue: number;
+};

package/src/types/ControlPointInfo.ts

@@ -0,0 +1,8 @@
+import { Types } from '@cornerstonejs/core';
+
+export type ControlPointInfo = {
+  /** Control point index */
+  index: number;
+  /** 2D coordinate */
+  point: Types.Point2;
+};

package/src/types/ISpline.ts

@@ -0,0 +1,164 @@
+import { Types } from '@cornerstonejs/core';
+import type {
+  ClosestPoint,
+  ClosestControlPoint,
+  ClosestSplinePoint,
+  ControlPointInfo,
+} from './';
+
+/**
+ * Spline curve interface
+ */
+export interface ISpline {
+  /** Number of control points */
+  get numControlPoints(): number;
+
+  /** Resolution of the spline curve (greater than or equal to 0) */
+  get resolution(): number;
+
+  /** Set the resolution of the spline curve */
+  set resolution(resolution: number);
+
+  /** Flag that is set to true when the curve is already closed */
+  get closed(): boolean;
+
+  /** Set the curve as closed which connects the last to the first point */
+  set closed(closed: boolean);
+
+  /** Axis-aligned bounding box (minX, minY, maxX, maxY) */
+  get aabb(): Types.AABB2;
+
+  /** Length of the spline curve in pixels */
+  get length(): number;
+
+  /**
+   * Flag that is set to true when the spline needs to be updated. The update
+   * runs automaticaly when needed (eg: getPolylinePoints).
+   */
+  get invalidated(): boolean;
+
+  /**
+   * Bézier curves have tangent points connected to control points
+   * @returns True if the spline has tangent point or false otherwise
+   */
+  hasTangentPoints(): boolean;
+
+  /**
+   * Add a control point to the end of the array
+   * @param point - Control point (2D)
+   */
+  addControlPoint(point: Types.Point2): void;
+
+  /**
+   * Add a list of control poits to the end of the array
+   * @param points - Control points to be added
+   */
+  addControlPoints(points: Types.Point2[]): void;
+
+  /**
+   * Add a control point specifying its `u` value in Parameter Space which is a number from 0 to N
+   * where N is the number of curve segments. The integer part is the curve segment index and the
+   * decimal part is the `t` value on that curve segment.
+   * @param u - `u` value in Parameter Space
+   */
+  addControlPointAtU(u: number): ControlPointInfo;
+
+  /**
+   * Delete a control point given its index
+   * @param index - Control point index to be removed
+   * @returns True if the control point is removed or false otherwise
+   */
+  deleteControlPointByIndex(index: number): boolean;
+
+  /**
+   * Remove all control points
+   */
+  clearControlPoints(): void;
+
+  /**
+   * Replace all control points by some new ones
+   * @param points - Control points to be added to the array
+   */
+  setControlPoints(points: Types.Point2[]): void;
+
+  /**
+   * Update the coordinate of a control point given its index
+   * @param index - Control point index
+   * @param newControlPoint - New control point
+   */
+  updateControlPoint(index: number, newControlPoint: Types.Point2): void;
+
+  /**
+   * Get a list with all control points. The control points are cloned to prevent
+   * any caller from changing them resulting in unexpected behaviors
+   * @returns - List of all control points
+   */
+  getControlPoints(): Types.Point2[];
+
+  /**
+   * Finds the closest control point given a 2D point
+   * @param point - Reference point
+   * @returns Closest control point
+   */
+  getClosestControlPoint(point: Types.Point2): ClosestControlPoint;
+
+  /**
+   * Finds the closest control point given a 2D point and a maximum distance
+   * @param point - Reference 2D point
+   * @param maxDist - Maximum distance
+   * @returns Closest control point that is within the given range or undefined otherwise
+   */
+  getClosestControlPointWithinDistance(
+    point: Types.Point2,
+    range: number
+  ): ClosestControlPoint;
+
+  /**
+   * Finds the closest point on the spline curve given 2D point
+   * @param point - Reference 2D point
+   * @returns Closest point on the spline curve
+   */
+  getClosestPoint(point: Types.Point2): ClosestSplinePoint;
+
+  /**
+   * Finds the closest point on the straight line that connects all control points given a 2D point
+   * @param point - Reference point
+   * @returns Closest point on the straight line that connects all control points
+   */
+  getClosestPointOnControlPointLines(point: Types.Point2): ClosestPoint;
+
+  /**
+   * Get all points necessary to draw a spline curve
+   * @returns Array with all points necessary to draw a spline curve
+   */
+  getPolylinePoints(): Types.Point2[];
+
+  /**
+   * Get all points necessary to draw the preview curve for a new possible control point
+   * @returns Array with all points necessary to draw the preview curve
+   */
+  getPreviewPolylinePoints(
+    controlPointPreview: Types.Point2,
+    closeDistance: number
+  ): Types.Point2[];
+
+  /**
+   * Checks if a point is near to the spline curve
+   * @param point - Reference point
+   * @param maxDist - Maximum allowed distance
+   * @returns True if the point is close to the spline curve or false otherwise
+   */
+  isPointNearCurve(point: Types.Point2, maxDist: number): boolean;
+
+  /**
+   * Checks if a 2D point is inside the spline curve.
+   *
+   * A point is inside a curve/polygon if the number of intersections between the horizontal
+   * ray emanating from the given point and to the right and the line segments is odd.
+   * https://www.eecs.umich.edu/courses/eecs380/HANDOUTS/PROJ2/InsidePoly.html
+   *
+   * @param point - 2D Point
+   * @returns True is the point is inside the spline curve or false otherwise
+   */
+  containsPoint(point: Types.Point2): boolean;
+}

package/src/types/SplineCurveSegment.ts

@@ -0,0 +1,28 @@
+import { Types } from '@cornerstonejs/core';
+import type { SplineLineSegment } from './SplineLineSegment';
+
+/**
+ * Spline curve segment the is part of a spline path
+ */
+export type SplineCurveSegment = {
+  /**
+   * Control Points that influences the spline curve segment.
+   *
+   * For cubic splines the curve goes from P1 and P2 but it is also influenced by the
+   * previous point (P0) and the next point (P3)
+   */
+  controlPoints: {
+    p0: Types.Point2;
+    p1: Types.Point2;
+    p2: Types.Point2;
+    p3: Types.Point2;
+  };
+  /** Axis-aligned bounding (minX, minY, maxX, maxY) */
+  aabb: Types.AABB2;
+  /** Length of the curve segment */
+  length: number;
+  /** Total length of all previous curve segments */
+  previousCurveSegmentsLength: number;
+  /** Line segments that makes the curve segment */
+  lineSegments: SplineLineSegment[];
+};

package/src/types/SplineLineSegment.ts

@@ -0,0 +1,20 @@
+import { Types } from '@cornerstonejs/core';
+
+/**
+ * Line segment the is part of a curve segment based on its resolution.
+ * Each curve segment shall have 20 line segments when spline resolution
+ * is set to 20.
+ */
+export type SplineLineSegment = {
+  /** Start and end points for the line segment */
+  points: {
+    start: Types.Point2;
+    end: Types.Point2;
+  };
+  /** Axis-aligned bounding (minX, minY, maxX, maxY) */
+  aabb: Types.AABB2;
+  /** Length of the line segment */
+  length: number;
+  /** Total length of all previous line segments for a given curve segment */
+  previousLineSegmentsLength: number;
+};

package/src/types/SplineProps.ts

@@ -0,0 +1,15 @@
+export type SplineProps = {
+  /**
+   * Resolution of the spline curve
+   *
+   * The number assigned to the resolution is the number of intermediate points on each
+   * curve segment that makes the spline path. For example, if the resolution is set to 0
+   * that means that each curve segment will have no intermediate points but only a straight
+   * line similar to Linear Spline. For a resolution equal to 20 that means the curve shall
+   * have 20 intermediate points or 21 line segments total making it look more like a curve.
+   */
+  resolution?: number;
+
+  /** Flag that is set to true when the curve is closed */
+  closed?: boolean;
+};

package/src/types/ToolSpecificAnnotationTypes.ts

@@ -1,5 +1,6 @@
 import type { Types } from '@cornerstonejs/core';
 import { Annotation } from './AnnotationTypes';
+import { ISpline } from './';
 
 interface ROICachedStats {
   [targetId: string]: {
@@ -117,6 +118,40 @@ export interface CircleROIAnnotation extends Annotation {
   };
 }
 
+export interface SplineROIAnnotation extends Annotation {
+  data: {
+    label?: string;
+    handles: {
+      points: Types.Point3[];
+      activeHandleIndex: number | null;
+      textBox?: {
+        hasMoved: boolean;
+        worldPosition: Types.Point3;
+        worldBoundingBox: {
+          topLeft: Types.Point3;
+          topRight: Types.Point3;
+          bottomLeft: Types.Point3;
+          bottomRight: Types.Point3;
+        };
+      };
+    };
+    spline: {
+      type: string;
+      instance: ISpline;
+      resolution: number;
+      polyline: Types.Point3[];
+      closed: boolean;
+    };
+    cachedStats?: {
+      [targetId: string]: {
+        Modality: string;
+        area: number;
+        areaUnit: string;
+      };
+    };
+  };
+}
+
 export interface EllipticalROIAnnotation extends Annotation {
   data: {
     handles: {

package/src/types/index.ts

@@ -64,6 +64,17 @@ import {
   LabelmapToolOperationDataVolume,
 } from './LabelmapToolOperationData';
 
+// Splines
+import type { CardinalSplineProps } from './CardinalSplineProps';
+import type { ClosestControlPoint } from './ClosestControlPoint';
+import type { ClosestPoint } from './ClosestPoint';
+import type { ClosestSplinePoint } from './ClosestSplinePoint';
+import type { ControlPointInfo } from './ControlPointInfo';
+import type { ISpline } from './ISpline';
+import type { SplineCurveSegment } from './SplineCurveSegment';
+import type { SplineLineSegment } from './SplineLineSegment';
+import type { SplineProps } from './SplineProps';
+
 export type {
   // AnnotationState
   Annotation,
@@ -132,4 +143,14 @@ export type {
   LabelmapToolOperationData,
   LabelmapToolOperationDataStack,
   LabelmapToolOperationDataVolume,
+  // Splines
+  CardinalSplineProps,
+  ClosestControlPoint,
+  ClosestPoint,
+  ClosestSplinePoint,
+  ControlPointInfo,
+  ISpline,
+  SplineCurveSegment,
+  SplineLineSegment,
+  SplineProps,
 };

package/src/utilities/index.ts

@@ -9,8 +9,11 @@ import throttle from './throttle';
 import isObject from './isObject';
 import clip from './clip';
 import calibrateImageSpacing from './calibrateImageSpacing';
-import getCalibratedLengthUnits from './getCalibratedUnits';
-import { getCalibratedScale } from './getCalibratedUnits';
+import {
+  getCalibratedLengthUnits,
+  getCalibratedAreaUnits,
+  getCalibratedScale,
+} from './getCalibratedUnits';
 import triggerAnnotationRenderForViewportIds from './triggerAnnotationRenderForViewportIds';
 import triggerAnnotationRender from './triggerAnnotationRender';
 import jumpToSlice from './viewport/jumpToSlice';
@@ -57,6 +60,7 @@ export {
   triggerEvent,
   calibrateImageSpacing,
   getCalibratedLengthUnits,
+  getCalibratedAreaUnits,
   getCalibratedScale,
   segmentation,
   triggerAnnotationRenderForViewportIds,

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

@@ -0,0 +1,20 @@
+import { Types } from '@cornerstonejs/core';
+import distanceToPointSquared from './distanceToPointSquared';
+
+/**
+ * Calculates the squared distance of a point to an AABB using
+ * 2D Box SDF (Signed Distance Field)
+ *
+ * The SDF of a Box
+ * https://www.youtube.com/watch?v=62-pRVZuS5c
+ *
+ * @param aabb - Axis-aligned bound box (minX, minY, maxX and maxY)
+ * @param point - 2D point
+ * @returns The squared distance between the 2D point and the AABB
+ */
+export default function distanceToPoint(
+  aabb: Types.AABB2,
+  point: Types.Point2
+): number {
+  return Math.sqrt(distanceToPointSquared(aabb, point));
+}

package/src/utilities/math/aabb/distanceToPointSquared.ts

@@ -0,0 +1,47 @@
+import { Types } from '@cornerstonejs/core';
+
+/**
+ * Calculates the distance of a point to an AABB using 2D Box SDF (Signed Distance Field)
+ *
+ * The SDF of a Box
+ * https://www.youtube.com/watch?v=62-pRVZuS5c
+ *
+ * @param aabb - Axis-aligned bound box
+ * @param point - 2D point
+ * @returns The closest distance between the 2D point and the AABB
+ */
+export default function distanceToPointSquared(
+  aabb: Types.AABB2,
+  point: Types.Point2
+): number {
+  const aabbWidth = aabb.maxX - aabb.minX;
+  const aabbHeight = aabb.maxY - aabb.minY;
+  const aabbSize = [aabbWidth, aabbHeight];
+  const aabbCenter: Types.Point2 = [
+    aabb.minX + aabbWidth / 2,
+    aabb.minY + aabbHeight / 2,
+  ];
+
+  // Translates the point as the center of the AABB is the new origin.
+  // THe point is also mirroed to the first quadrant to simplify the math.
+  const translatedPoint = [
+    Math.abs(point[0] - aabbCenter[0]),
+    Math.abs(point[1] - aabbCenter[1]),
+  ];
+
+  // Calculate the distance from the point to the vertical and horizontal AABB borders
+  const dx = translatedPoint[0] - aabbSize[0] * 0.5;
+  const dy = translatedPoint[1] - aabbSize[1] * 0.5;
+
+  // dx >  0 && dy >  0: diagonal line connecting the point to AABB's corner
+  // dx >  0 && dy <= 0: a line parallel to x-axis connecting the point to AABB's right side
+  // dx <= 0 && dy >  0: a line parallel to y-axis connecting the point to AABB's top side
+  // dx <= 0 && dy <= 0: the point is inside the AABB
+  if (dx > 0 && dy > 0) {
+    return dx * dx + dy * dy;
+  }
+
+  const dist = Math.max(dx, 0) + Math.max(dy, 0);
+
+  return dist * dist;
+}

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

@@ -0,0 +1,2 @@
+export { default as distanceToPoint } from './distanceToPoint';
+export { default as distanceToPointSquared } from './distanceToPointSquared';

package/src/utilities/math/index.ts

@@ -1,17 +1,19 @@
-import * as vec2 from './vec2';
+import * as aabb from './aabb';
+import * as BasicStatsCalculator from './basic';
 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';
-import * as BasicStatsCalculator from './basic';
+import * as polyline from './polyline';
+import * as rectangle from './rectangle';
+import * as vec2 from './vec2';
 
 export {
-  vec2,
+  aabb,
+  BasicStatsCalculator,
   ellipse,
   lineSegment,
-  rectangle,
-  polyline,
   point,
-  BasicStatsCalculator,
+  polyline,
+  rectangle,
+  vec2,
 };

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

@@ -1,11 +1,8 @@
 import { Types } from '@cornerstonejs/core';
-
-function dist2(p1: Types.Point2, p2: Types.Point2): number {
-  return (p1[0] - p2[0]) * (p1[0] - p2[0]) + (p1[1] - p2[1]) * (p1[1] - p2[1]);
-}
+import distanceToPointSquaredInfo from './distanceToPointSquaredInfo';
 
 /**
- * Calculates the distance-squared of a point to a line
+ * Calculates the distance-squared of a point to a line segment
  *
  * @param lineStart - x,y coordinates of the start of the line
  * @param lineEnd - x,y coordinates of the end of the line
@@ -17,28 +14,5 @@ export default function distanceToPointSquared(
   lineEnd: Types.Point2,
   point: Types.Point2
 ): number {
-  const d2 = dist2(lineStart, lineEnd);
-
-  if (d2 === 0) {
-    return dist2(point, lineStart);
-  }
-
-  const t =
-    ((point[0] - lineStart[0]) * (lineEnd[0] - lineStart[0]) +
-      (point[1] - lineStart[1]) * (lineEnd[1] - lineStart[1])) /
-    d2;
-
-  if (t < 0) {
-    return dist2(point, lineStart);
-  }
-  if (t > 1) {
-    return dist2(point, lineEnd);
-  }
-
-  const pt: Types.Point2 = [
-    lineStart[0] + t * (lineEnd[0] - lineStart[0]),
-    lineStart[1] + t * (lineEnd[1] - lineStart[1]),
-  ];
-
-  return dist2(point, pt);
+  return distanceToPointSquaredInfo(lineStart, lineEnd, point).distanceSquared;
 }

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

@@ -0,0 +1,54 @@
+import type { Types } from '@cornerstonejs/core';
+import * as math from '../';
+
+/**
+ * Calculate the closest point and the squared distance between a reference point and a line segment.
+ *
+ * It projects the reference point onto the line segment but it shall be bounded by the
+ * start/end points since this is a line segment and not a line which could be extended.
+ *
+ * @param lineStart - Start point of the line segment
+ * @param lineEnd - End point of the line segment
+ * @param point - Reference point
+ * @returns Closest point and the squared distance between a `point` and a line
+ *   segment defined by `lineStart` and `lineEnd` points
+ */
+export default function distanceToPointSquaredInfo(
+  lineStart: Types.Point2,
+  lineEnd: Types.Point2,
+  point: Types.Point2
+): {
+  point: Types.Point2;
+  distanceSquared: number;
+} {
+  let closestPoint: Types.Point2;
+  const distanceSquared = math.point.distanceToPointSquared(lineStart, lineEnd);
+
+  // Check if lineStart is the same as lineEnd which means
+  if (lineStart[0] === lineEnd[0] && lineStart[1] === lineEnd[1]) {
+    closestPoint = lineStart;
+  }
+
+  if (!closestPoint) {
+    const dotProduct =
+      ((point[0] - lineStart[0]) * (lineEnd[0] - lineStart[0]) +
+        (point[1] - lineStart[1]) * (lineEnd[1] - lineStart[1])) /
+      distanceSquared;
+
+    if (dotProduct < 0) {
+      closestPoint = lineStart;
+    } else if (dotProduct > 1) {
+      closestPoint = lineEnd;
+    } else {
+      closestPoint = [
+        lineStart[0] + dotProduct * (lineEnd[0] - lineStart[0]),
+        lineStart[1] + dotProduct * (lineEnd[1] - lineStart[1]),
+      ];
+    }
+  }
+
+  return {
+    point: [...closestPoint],
+    distanceSquared: math.point.distanceToPointSquared(point, closestPoint),
+  };
+}

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

@@ -1,5 +1,11 @@
 import distanceToPoint from './distanceToPoint';
 import distanceToPointSquared from './distanceToPointSquared';
+import distanceToPointSquaredInfo from './distanceToPointSquaredInfo';
 import intersectLine from './intersectLine';
 
-export { distanceToPoint, distanceToPointSquared, intersectLine };
+export {
+  distanceToPoint,
+  distanceToPointSquared,
+  distanceToPointSquaredInfo,
+  intersectLine,
+};

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

@@ -1,4 +1,5 @@
 import type { Types } from '@cornerstonejs/core';
+import distanceToPointSquared from './distanceToPointSquared';
 
 type Point = Types.Point2 | Types.Point3;
 
@@ -10,14 +11,5 @@ type Point = Types.Point2 | Types.Point3;
  * @returns distance
  */
 export default function distanceToPoint(p1: Point, p2: Point): number {
-  if (p1.length !== p2.length) {
-    throw Error('Both points should have the same dimensionality');
-  }
-
-  const [x1, y1, z1 = 0] = p1;
-  const [x2, y2, z2 = 0] = p2;
-
-  return Math.sqrt(
-    Math.pow(x1 - x2, 2) + Math.pow(y1 - y2, 2) + Math.pow(z1 - z2, 2)
-  );
+  return Math.sqrt(distanceToPointSquared(p1, p2));
 }

package/src/utilities/math/point/distanceToPointSquared.ts

@@ -0,0 +1,21 @@
+import type { Types } from '@cornerstonejs/core';
+
+type Point = Types.Point2 | Types.Point3;
+
+/**
+ * Calculates the distance squared of a point to another point
+ *
+ * @param p1 - x,y or x,y,z of the point
+ * @param p2 - x,y or x,y,z of the point
+ * @returns distance
+ */
+export default function distanceToPointSquared(p1: Point, p2: Point): number {
+  if (p1.length !== p2.length) {
+    throw Error('Both points should have the same dimensionality');
+  }
+
+  const [x1, y1, z1 = 0] = p1;
+  const [x2, y2, z2 = 0] = p2;
+
+  return Math.pow(x1 - x2, 2) + Math.pow(y1 - y2, 2) + Math.pow(z1 - z2, 2);
+}

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

@@ -1,3 +1,3 @@
-import distanceToPoint from './distanceToPoint';
-
-export { distanceToPoint };
+export { default as distanceToPoint } from './distanceToPoint';
+export { default as distanceToPointSquared } from './distanceToPointSquared';
+export { default as mirror } from './mirror';