@cornerstonejs/tools 2.0.0-beta.1 → 2.0.0-beta.11

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

@@ -1,17 +1,14 @@
 import type { Types } from '@cornerstonejs/core';
-import { vec3 } from 'gl-matrix';
+import { vec2, vec3 } from 'gl-matrix';
 
-type Line = [Types.Point3, Types.Point3];
+type Line2D = [Types.Point2, Types.Point2];
+type Line3D = [Types.Point3, Types.Point3];
+type Line = Line2D | Line3D;
 
 /**
- * It returns the angle between two lines in degrees.
- * The angle measured is that between the vectors
- * line1[1]->line1[0] AND line2[0]->line2[1].
- * @param line1 - Line = [p1, p2]
- * @param line2 - Line = [p3, p4]
- * @returns The angle between two lines in degrees.
+ * Calculates the angle between two 3D lines.
  */
-export default function angleBetweenLines(line1: Line, line2: Line): number {
+function angleBetween3DLines(line1: Line3D, line2: Line3D): number {
   const [p1, p2] = line1;
   const [p3, p4] = line2;
 
@@ -29,3 +26,36 @@ export default function angleBetweenLines(line1: Line, line2: Line): number {
 
   return (radian * 180) / Math.PI;
 }
+
+/**
+ * Calculates the angle between two 2D lines.
+ */
+function angleBetween2DLines(line1: Line2D, line2: Line2D): number {
+  const [p1, p2] = line1;
+  const [p3, p4] = line2;
+
+  const v1 = vec2.sub(vec2.create(), p2, p1);
+  const v2 = vec2.sub(vec2.create(), p3, p4);
+
+  const dot = vec2.dot(v1, v2);
+  const v1Length = vec2.length(v1);
+  const v2Length = vec2.length(v2);
+
+  const cos = dot / (v1Length * v2Length);
+  return Math.acos(cos) * (180 / Math.PI);
+}
+
+/**
+ * Returns the angle between two lines in degrees.
+ * The angle measured is that between the vectors
+ * line1[1]->line1[0] AND line2[0]->line2[1].
+ * @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 is3D = line1[0].length === 3;
+  return is3D
+    ? angleBetween3DLines(line1 as Line3D, line2 as Line3D)
+    : angleBetween2DLines(line1 as Line2D, line2 as Line2D);
+}

package/src/utilities/math/basic/BasicStatsCalculator.ts

@@ -0,0 +1,148 @@
+import { utilities } from '@cornerstonejs/core';
+import { NamedStatistics } from '../../../types';
+import Calculator from './Calculator';
+
+const { PointsManager } = utilities;
+
+export default class BasicStatsCalculator extends Calculator {
+  private static max = [-Infinity];
+  private static min = [Infinity];
+  private static sum = [0];
+  private static count = 0;
+
+  // private static sumSquares = [0];
+  // Values for Welford's algorithm
+  private static runMean = [0];
+  private static m2 = [0];
+
+  // Collect the points to be returned
+  private static pointsInShape = PointsManager.create3(1024);
+
+  public static statsInit(options: { noPointsCollection: boolean }) {
+    if (options.noPointsCollection) {
+      BasicStatsCalculator.pointsInShape = null;
+    }
+  }
+
+  /**
+   * This callback is used when we verify if the point is in the annotation drawn
+   * so we can get every point in the shape to calculate the statistics
+   */
+  static statsCallback = ({ value: newValue, pointLPS = null }): void => {
+    if (
+      Array.isArray(newValue) &&
+      newValue.length > 1 &&
+      this.max.length === 1
+    ) {
+      this.max.push(this.max[0], this.max[0]);
+      this.min.push(this.min[0], this.min[0]);
+      this.sum.push(this.sum[0], this.sum[0]);
+      this.runMean.push(0, 0);
+      // this.sumSquares.push(this.sumSquares[0], this.sumSquares[0]);
+      this.m2.push(this.m2[0], this.m2[0]);
+    }
+
+    this.pointsInShape?.push(pointLPS);
+    const newArray = Array.isArray(newValue) ? newValue : [newValue];
+
+    this.count += 1;
+    this.max.map((it, idx) => {
+      const value = newArray[idx];
+
+      const delta = value - this.runMean[idx];
+      this.sum[idx] += value;
+      this.runMean[idx] += delta / this.count;
+      const delta2 = value - this.runMean[idx];
+      this.m2[idx] += delta * delta2;
+      // this.sumSquares[idx] += value * value;
+
+      this.min[idx] = Math.min(this.min[idx], value);
+      this.max[idx] = Math.max(it, value);
+    });
+  };
+
+  /**
+   * Basic function that calculates statistics for a given array of points.
+   * @returns An object that contains :
+   * max : The maximum value of the array
+   * mean : mean of the array
+   * stdDev : standard deviation of the array
+   * array : An array of hte above values, in order.
+   */
+
+  static getStatistics = (options?: { unit: string }): NamedStatistics => {
+    const mean = this.sum.map((sum) => sum / this.count);
+    const stdDev = this.m2.map((squaredDiffSum) =>
+      Math.sqrt(squaredDiffSum / this.count)
+    );
+    // const stdDevWithSumSquare = this.sumSquares.map((it, idx) =>
+    //   Math.sqrt(this.sumSquares[idx] / this.count - mean[idx] ** 2)
+    // );
+
+    const unit = options?.unit || null;
+
+    const named: NamedStatistics = {
+      max: {
+        name: 'max',
+        label: 'Max Pixel',
+        value: singleArrayAsNumber(this.max),
+        unit,
+      },
+      min: {
+        name: 'min',
+        label: 'Min Pixel',
+        value: singleArrayAsNumber(this.min),
+        unit,
+      },
+      mean: {
+        name: 'mean',
+        label: 'Mean Pixel',
+        value: singleArrayAsNumber(mean),
+        unit,
+      },
+      stdDev: {
+        name: 'stdDev',
+        label: 'Standard Deviation',
+        value: singleArrayAsNumber(stdDev),
+        unit,
+      },
+      // stdDevWithSumSquare: {
+      //   name: 'stdDevWithSumSquare',
+      //   value: singleArrayAsNumber(stdDevWithSumSquare),
+      //   unit,
+      // },
+      count: {
+        name: 'count',
+        label: 'Pixel Count',
+        value: this.count,
+        unit: null,
+      },
+      pointsInShape: this.pointsInShape,
+      array: [],
+    };
+    named.array.push(
+      named.max,
+      named.mean,
+      named.stdDev,
+      // Use the stdDev twice to preserve old ordering - this is updated to be
+      // correct value with Welford's algorithm now.
+      named.stdDev,
+      named.count
+    );
+
+    this.max = [-Infinity];
+    this.min = [Infinity];
+    this.sum = [0];
+    // this.sumSquares = [0];
+    this.m2 = [0];
+    this.runMean = [0];
+    this.count = 0;
+    this.pointsInShape = PointsManager.create3(1024);
+
+    return named;
+  };
+}
+
+function singleArrayAsNumber(val: number[]) {
+  return val.length === 1 ? val[0] : val;
+}

package/src/utilities/math/basic/Calculator.ts

@@ -0,0 +1,11 @@
+import { NamedStatistics } from '../../../types';
+
+abstract class Calculator {
+  static run: ({ value }) => void;
+  /**
+   * Gets the statistics as both an array of values, as well as the named values.
+   */
+  static getStatistics: () => NamedStatistics;
+}
+
+export default Calculator;

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

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

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

@@ -1,6 +1,6 @@
 import type { Types } from '@cornerstonejs/core';
 
-type canvasCoordinates = [
+export type CanvasCoordinates = [
   Types.Point2, // bottom
   Types.Point2, // top
   Types.Point2, // left
@@ -15,7 +15,7 @@ type canvasCoordinates = [
  * @returns An array of two points.
  */
 export default function getCanvasEllipseCorners(
-  ellipseCanvasPoints: canvasCoordinates
+  ellipseCanvasPoints: CanvasCoordinates
 ): Array<Types.Point2> {
   const [bottom, top, left, right] = ellipseCanvasPoints;
 

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

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

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

@@ -1,38 +1,94 @@
 import type { Types } from '@cornerstonejs/core';
-
-type Ellipse = {
-  center: Types.Point3;
-  xRadius: number;
-  yRadius: number;
-  zRadius: number;
-};
+interface Inverts {
+  invXRadiusSq?: number;
+  invYRadiusSq?: number;
+  invZRadiusSq?: number;
+  fast?: boolean;
+  /**
+   * If you call the pointInEllipse.precalculateInverts first, then you
+   * can call precalculated directly instead of having the extra time for
+   * the if conditions.
+   */
+  precalculated?: (pointLPS: Types.Point3) => boolean;
+}
 
 /**
  * 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.
+ * @param inverts - An object to cache the inverted radius squared values, if you
+ * are testing multiple points against the same ellipse then it is recommended to
+ * pass in the same object to cache the values. However, there is a simpler way
+ * to do this by passing in the fast flag as true, then on the first iteration
+ * the values will be cached and on subsequent iterations the cached values will
+ * be used.
+ *
  * @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);
+  ellipse,
+  pointLPS,
+  inverts: Inverts = {}
+) {
+  if (!inverts.precalculated) {
+    precalculatePointInEllipse(ellipse, inverts);
   }
+  return inverts.precalculated(pointLPS);
+}
 
-  if (yRadius !== 0) {
-    inside += ((y - y0) * (y - y0)) / (yRadius * yRadius);
-  }
+/**
+ * This will perform some precalculations to make things faster.
+ * Ideally, use the 'precalculated' function inside inverts to call the
+ * test function.  This minimizes re-reading of variables and only needs the
+ * LPS passed each time.
+ * That is:
+ *
+ * ```
+ *    const inverts = precalculatePointInEllipse(ellipse);
+ *    if( inverts.precalculated(pointLPS) ) ...
+ * ```
+ */
+const precalculatePointInEllipse = (ellipse, inverts: Inverts = {}) => {
+  const { xRadius, yRadius, zRadius } = ellipse;
 
-  if (zRadius !== 0) {
-    inside += ((z - z0) * (z - z0)) / (zRadius * zRadius);
+  // This will run only once since we are caching the values in the same
+  // object that is passed in.
+  if (
+    inverts.invXRadiusSq === undefined ||
+    inverts.invYRadiusSq === undefined ||
+    inverts.invZRadiusSq === undefined
+  ) {
+    inverts.invXRadiusSq = xRadius !== 0 ? 1 / xRadius ** 2 : 0;
+    inverts.invYRadiusSq = yRadius !== 0 ? 1 / yRadius ** 2 : 0;
+    inverts.invZRadiusSq = zRadius !== 0 ? 1 / zRadius ** 2 : 0;
   }
 
-  return inside <= 1;
-}
+  const { invXRadiusSq, invYRadiusSq, invZRadiusSq } = inverts;
+  const { center } = ellipse;
+  const [centerL, centerP, centerS] = center;
+
+  inverts.precalculated = (pointLPS) => {
+    // Calculate the sum of normalized squared distances
+    const dx = pointLPS[0] - centerL;
+    let inside = dx * dx * invXRadiusSq;
+    if (inside > 1) {
+      return false;
+    }
+
+    const dy = pointLPS[1] - centerP;
+    inside += dy * dy * invYRadiusSq;
+    if (inside > 1) {
+      return false;
+    }
+
+    const dz = pointLPS[2] - centerS;
+    inside += dz * dz * invZRadiusSq;
+
+    // Check if the point is inside the ellipse
+    return inside <= 1;
+  };
+
+  return inverts;
+};
+
+export { precalculatePointInEllipse };

package/src/utilities/math/index.ts

@@ -1,8 +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 polyline from './polyline';
+import * as rectangle from './rectangle';
+import * as vec2 from './vec2';
 
-export { vec2, ellipse, lineSegment, rectangle, polyline, point };
+export {
+  aabb,
+  BasicStatsCalculator,
+  ellipse,
+  lineSegment,
+  point,
+  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,55 @@
+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 equal to the lineEnd which means the closest point
+  // is any of these two points
+  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,13 @@
 import distanceToPoint from './distanceToPoint';
 import distanceToPointSquared from './distanceToPointSquared';
+import distanceToPointSquaredInfo from './distanceToPointSquaredInfo';
 import intersectLine from './intersectLine';
+import isPointOnLineSegment from './isPointOnLineSegment';
 
-export { distanceToPoint, distanceToPointSquared, intersectLine };
+export {
+  distanceToPoint,
+  distanceToPointSquared,
+  distanceToPointSquaredInfo,
+  intersectLine,
+  isPointOnLineSegment,
+};

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

@@ -0,0 +1,44 @@
+import type { Types } from '@cornerstonejs/core';
+
+const ORIENTATION_TOLERANCE = 1e-2;
+
+/**
+ * Test if a point is on a line segment
+ * @param lineStart - Line segment start point
+ * @param lineEnd - Line segment end point
+ * @param point - Point to test
+ * @returns True if the point lies on the line segment or false otherwise
+ */
+export default function isPointOnLineSegment(
+  lineStart: Types.Point2,
+  lineEnd: Types.Point2,
+  point: Types.Point2
+): boolean {
+  // The code below runs ~4x faster than calling `line.distanceToPointSquared()` (155 vs 598 ms)
+
+  // No Math.min/max call for better performance when testing thousands of points
+  const minX = lineStart[0] <= lineEnd[0] ? lineStart[0] : lineEnd[0];
+  const maxX = lineStart[0] >= lineEnd[0] ? lineStart[0] : lineEnd[0];
+  const minY = lineStart[1] <= lineEnd[1] ? lineStart[1] : lineEnd[1];
+  const maxY = lineStart[1] >= lineEnd[1] ? lineStart[1] : lineEnd[1];
+
+  // Checks if the point lies inside the AABB
+  const aabbContainsPoint =
+    point[0] >= minX - ORIENTATION_TOLERANCE &&
+    point[0] <= maxX + ORIENTATION_TOLERANCE &&
+    point[1] >= minY - ORIENTATION_TOLERANCE &&
+    point[1] <= maxY + ORIENTATION_TOLERANCE;
+
+  if (!aabbContainsPoint) {
+    return false;
+  }
+
+  // Now that we know the point is inside the AABB we check if it lies on the line segment
+  const orientation =
+    (lineEnd[1] - lineStart[1]) * (point[0] - lineEnd[0]) -
+    (lineEnd[0] - lineStart[0]) * (point[1] - lineEnd[1]);
+  const absOrientation = orientation >= 0 ? orientation : -orientation;
+
+  // The orientation must be zero for points that lies on the same line
+  return absOrientation <= ORIENTATION_TOLERANCE;
+}

package/src/utilities/math/midPoint.ts

@@ -12,7 +12,9 @@ const midPoint = (
   for (const arg of args) {
     ret[0] += arg[0] / len;
     ret[1] += arg[1] / len;
-    if (ret.length === 3) ret[2] += arg[2] / len;
+    if (ret.length === 3) {
+      ret[2] += arg[2] / len;
+    }
   }
   return ret;
 };

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

@@ -1,22 +1,15 @@
 import type { Types } from '@cornerstonejs/core';
+import distanceToPointSquared from './distanceToPointSquared';
+
+type Point = Types.Point2 | Types.Point3;
 
 /**
  * Calculates the distance of a point to another point
  *
- * @param p1 - x,y of the point
- * @param p2 - x,y of the 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 distanceToPoint(
-  p1: Types.Point2,
-  p2: Types.Point2
-): number {
-  if (p1?.length !== 2 || p2?.length !== 2) {
-    throw Error('points should have 2 elements of [x, y]');
-  }
-
-  const [x1, y1] = p1;
-  const [x2, y2] = p2;
-
-  return Math.sqrt(Math.pow(x1 - x2, 2) + Math.pow(y1 - y2, 2));
+export default function distanceToPoint(p1: Point, p2: Point): number {
+  return Math.sqrt(distanceToPointSquared(p1, p2));
 }

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

@@ -0,0 +1,26 @@
+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;
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+  const dz = z2 - z1;
+
+  // Time to square 10M numbers:
+  //   (n * n) = 161ms | (n ** 2) = 199ms | Math.pow(n, 2) = 29529ms
+  return dx * dx + dy * dy + dz * dz;
+}

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';

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

@@ -0,0 +1,21 @@
+import { Types } from '@cornerstonejs/core';
+
+/**
+ * Get a mirrored point along the line created by two points where one of them
+ * is the static ("anchor") point and the other one is the point to be mirroed.
+ * @param mirrorPoint - 2D Point to be mirroed
+ * @param staticPoint - Static 2D point
+ * @returns Mirroed 2D point
+ */
+export default function mirror(
+  mirrorPoint: Types.Point2,
+  staticPoint: Types.Point2
+): Types.Point2 {
+  const [x1, y1] = mirrorPoint;
+  const [x2, y2] = staticPoint;
+
+  const newX = 2 * x2 - x1;
+  const newY = 2 * y2 - y1;
+
+  return [newX, newY];
+}

package/src/utilities/math/polyline/addCanvasPointsToArray.ts

@@ -16,11 +16,16 @@ const addCanvasPointsToArray = (
   const enabledElement = getEnabledElement(element);
   const { viewport } = enabledElement;
 
+  if (!canvasPoints.length) {
+    canvasPoints.push(newCanvasPoint);
+    console.log('>>>>> !canvasPoints. :: RETURN');
+    return 1;
+  }
+
   const lastWorldPos = viewport.canvasToWorld(
     canvasPoints[canvasPoints.length - 1]
   );
   const newWorldPos = viewport.canvasToWorld(newCanvasPoint);
-
   const worldPosDiff = vec3.create();
 
   vec3.subtract(worldPosDiff, newWorldPos, lastWorldPos);