@cornerstonejs/tools 1.50.3 → 1.51.0

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

@@ -0,0 +1,350 @@
+import { Types } from '@cornerstonejs/core';
+import * as mathPoint from '../point';
+import getLineSegmentIntersectionsIndexes from './getLineSegmentIntersectionsIndexes';
+import containsPoint from './containsPoint';
+import getNormal2 from './getNormal2';
+import { glMatrix, vec3 } from 'gl-matrix';
+import getLineSegmentsIntersection from './getLineSegmentsIntersection';
+
+enum PolylinePointType {
+  Vertex,
+  Intersection,
+}
+
+// Position of the point related to the intersection region
+enum PolylinePointPosition {
+  Outside = -1,
+  Edge = 0,
+  Inside = 1,
+}
+
+// Direction from last point to the intersection point to know if it is entering
+// or exiting the intersection region
+enum PolylinePointDirection {
+  Exiting = -1,
+  Unknown = 0,
+  Entering = 1,
+}
+
+type PolylinePoint = {
+  type: PolylinePointType;
+  coordinates: Types.Point2;
+  position?: PolylinePointPosition;
+  visited: boolean;
+  next: PolylinePoint;
+};
+
+type PolylineIntersectionPoint = PolylinePoint & {
+  direction: PolylinePointDirection;
+  cloned?: boolean;
+};
+
+/**
+ * Ensure all polyline point objects are pointing to the next object in case
+ * it is still not point to anyone.
+ * @param polylinePoints - Array that contains all polyline points (vertices and intersections)
+ */
+function ensuresNextPointers(polylinePoints: PolylinePoint[]) {
+  // Make sure all nodes point to a valid node
+  for (let i = 0, len = polylinePoints.length; i < len; i++) {
+    const currentPoint = polylinePoints[i];
+
+    if (!currentPoint.next) {
+      currentPoint.next = polylinePoints[i === len - 1 ? 0 : i + 1];
+    }
+  }
+}
+
+/**
+ * Creates one linked list per polyline that contains all vertices and intersections
+ * found while walking along the edges.
+ *
+ * @param targetPolyline - Target polyline
+ * @param sourcePolyline - Source polyline
+ * @returns Two linked lists with all vertices and intersections.
+ */
+function getSourceAndTargetPointsList(
+  targetPolyline: Types.Point2[],
+  sourcePolyline: Types.Point2[]
+) {
+  const targetPolylinePoints: PolylinePoint[] = [];
+  const sourcePolylinePoints: PolylinePoint[] = [];
+  const sourceIntersectionsCache = new Map<
+    number,
+    PolylineIntersectionPoint[]
+  >();
+
+  const isFisrtPointInside = containsPoint(sourcePolyline, targetPolyline[0]);
+
+  let intersectionPointDirection = isFisrtPointInside
+    ? PolylinePointDirection.Exiting
+    : PolylinePointDirection.Entering;
+
+  // Store all vertices and intersection for target contour
+  for (let i = 0, len = targetPolyline.length; i < len; i++) {
+    const p1 = targetPolyline[i];
+    const pointInside = containsPoint(sourcePolyline, p1);
+    const vertexPoint: PolylinePoint = {
+      type: PolylinePointType.Vertex,
+      coordinates: p1,
+      position: pointInside
+        ? PolylinePointPosition.Inside
+        : PolylinePointPosition.Outside,
+      visited: false,
+      next: null,
+    };
+
+    targetPolylinePoints.push(vertexPoint);
+
+    const q1 = targetPolyline[i === len - 1 ? 0 : i + 1];
+    const intersectionsInfo = getLineSegmentIntersectionsIndexes(
+      sourcePolyline,
+      p1,
+      q1
+    ).map((intersectedLineSegment) => {
+      const sourceLineSegmentId: number = intersectedLineSegment[0];
+      const p2 = sourcePolyline[intersectedLineSegment[0]];
+      const q2 = sourcePolyline[intersectedLineSegment[1]];
+
+      // lineSegment.intersectLine returns `undefined` when the intersection
+      // is at one of the line vertices.
+      // Examples:
+      //   - [(0, 0), (1, 1)] x [(1, 1), (1, 2)]
+      //   - [(0, 1), (2, 1)] x [(1, 1), (1, 2)]
+      const intersectionCoordinate = getLineSegmentsIntersection(
+        p1,
+        q1,
+        p2,
+        q2
+      ) as Types.Point2;
+
+      const targetStartPointDistSquared = mathPoint.distanceToPointSquared(
+        p1,
+        intersectionCoordinate
+      );
+
+      return {
+        sourceLineSegmentId,
+        coordinate: intersectionCoordinate,
+        targetStartPointDistSquared,
+      };
+    });
+
+    intersectionsInfo.sort(
+      (left, right) =>
+        left.targetStartPointDistSquared - right.targetStartPointDistSquared
+    );
+
+    intersectionsInfo.forEach((intersectionInfo) => {
+      const { sourceLineSegmentId, coordinate: intersectionCoordinate } =
+        intersectionInfo;
+
+      // Intersection point to be added to the target polyline list
+      const targetEdgePoint: PolylineIntersectionPoint = {
+        type: PolylinePointType.Intersection,
+        coordinates: intersectionCoordinate,
+        position: PolylinePointPosition.Edge,
+        direction: intersectionPointDirection,
+        visited: false,
+        next: null,
+      };
+
+      // Intersection point to be added to the source polyline list.
+      // At this point there is no way to know if the point is entering or
+      // exiting the intersection region but that is not going to be used
+      // hence it is set to "unknown".
+      const sourceEdgePoint: PolylineIntersectionPoint = {
+        ...targetEdgePoint,
+        direction: PolylinePointDirection.Unknown,
+        cloned: true,
+      };
+
+      if (intersectionPointDirection === PolylinePointDirection.Entering) {
+        targetEdgePoint.next = sourceEdgePoint;
+      } else {
+        sourceEdgePoint.next = targetEdgePoint;
+      }
+
+      let sourceIntersectionPoints =
+        sourceIntersectionsCache.get(sourceLineSegmentId);
+
+      if (!sourceIntersectionPoints) {
+        sourceIntersectionPoints = [];
+        sourceIntersectionsCache.set(
+          sourceLineSegmentId,
+          sourceIntersectionPoints
+        );
+      }
+
+      targetPolylinePoints.push(targetEdgePoint);
+      sourceIntersectionPoints.push(sourceEdgePoint);
+
+      // Switches from "exiting" to "entering" and vice-versa
+      intersectionPointDirection *= -1;
+    });
+  }
+
+  // Store all vertices and intersections for source contour
+  for (let i = 0, len = sourcePolyline.length; i < len; i++) {
+    const lineSegmentId: number = i;
+    const p1 = sourcePolyline[i];
+    const vertexPoint: PolylinePoint = {
+      type: PolylinePointType.Vertex,
+      coordinates: p1,
+      visited: false,
+      next: null,
+    };
+
+    sourcePolylinePoints.push(vertexPoint);
+
+    const sourceIntersectionPoints =
+      sourceIntersectionsCache.get(lineSegmentId);
+
+    if (!sourceIntersectionPoints?.length) {
+      continue;
+    }
+
+    // Calculate the distance between each intersection point to the start point
+    // of the line segment, sort them by distance and return a sorted array that
+    // contains all intersection points.
+    sourceIntersectionPoints
+      .map((intersectionPoint) => ({
+        intersectionPoint,
+        lineSegStartDistSquared: mathPoint.distanceToPointSquared(
+          p1,
+          intersectionPoint.coordinates
+        ),
+      }))
+      .sort(
+        (left, right) =>
+          left.lineSegStartDistSquared - right.lineSegStartDistSquared
+      )
+      .map(({ intersectionPoint }) => intersectionPoint)
+      .forEach((intersectionPoint) =>
+        sourcePolylinePoints.push(intersectionPoint)
+      );
+  }
+
+  ensuresNextPointers(targetPolylinePoints);
+  ensuresNextPointers(sourcePolylinePoints);
+
+  return { targetPolylinePoints, sourcePolylinePoints };
+}
+
+/**
+ * Get the next unvisited polyline points that is outside the intersection region.
+ * @param polylinePoints - All polyline points (vertices and intersections)
+ * @returns Any unvisited point that is outside the intersection region if it
+ * exists or `undefined` otherwise
+ */
+function getUnvisitedOutsidePoint(polylinePoints: PolylinePoint[]) {
+  for (let i = 0, len = polylinePoints.length; i < len; i++) {
+    const point = polylinePoints[i];
+
+    if (!point.visited && point.position === PolylinePointPosition.Outside) {
+      return point;
+    }
+  }
+}
+
+/**
+ * Merge two planar polylines (2D)
+ */
+function mergePolylines(
+  targetPolyline: Types.Point2[],
+  sourcePolyline: Types.Point2[]
+) {
+  const targetNormal = getNormal2(targetPolyline);
+  const sourceNormal = getNormal2(sourcePolyline);
+  const dotNormals = vec3.dot(sourceNormal, targetNormal);
+
+  // Both polylines need to be CW or CCW to be merged and one of them needs to
+  // be reversed if theirs orientation are not the same
+  if (!glMatrix.equals(1, dotNormals)) {
+    sourcePolyline = sourcePolyline.slice().reverse();
+  }
+
+  const { targetPolylinePoints } = getSourceAndTargetPointsList(
+    targetPolyline,
+    sourcePolyline
+  );
+  const startPoint: PolylinePoint =
+    getUnvisitedOutsidePoint(targetPolylinePoints);
+
+  // Source polyline contains target polyline
+  if (!startPoint) {
+    return targetPolyline.slice();
+  }
+
+  const mergedPolyline = [startPoint.coordinates];
+  let currentPoint = startPoint.next;
+
+  while (currentPoint !== startPoint) {
+    if (
+      currentPoint.type === PolylinePointType.Intersection &&
+      (<PolylineIntersectionPoint>currentPoint).cloned
+    ) {
+      currentPoint = currentPoint.next;
+      continue;
+    }
+
+    mergedPolyline.push(currentPoint.coordinates);
+    currentPoint = currentPoint.next;
+  }
+
+  return mergedPolyline;
+}
+
+/**
+ * Subtract two planar polylines (2D)
+ */
+function subtractPolylines(
+  targetPolyline: Types.Point2[],
+  sourcePolyline: Types.Point2[]
+): Types.Point2[][] {
+  const targetNormal = getNormal2(targetPolyline);
+  const sourceNormal = getNormal2(sourcePolyline);
+  const dotNormals = vec3.dot(sourceNormal, targetNormal);
+
+  // The polylines need to have different orientation (CW+CCW or CCW+CW) to be
+  // subtracted and one of them needs to be reversed if theirs orientation are
+  // the same
+  if (!glMatrix.equals(-1, dotNormals)) {
+    sourcePolyline = sourcePolyline.slice().reverse();
+  }
+
+  const { targetPolylinePoints } = getSourceAndTargetPointsList(
+    targetPolyline,
+    sourcePolyline
+  );
+  let startPoint: PolylinePoint = null;
+  const subtractedPolylines = [];
+
+  while ((startPoint = getUnvisitedOutsidePoint(targetPolylinePoints))) {
+    const subtractedPolyline = [startPoint.coordinates];
+    let currentPoint = startPoint.next;
+
+    startPoint.visited = true;
+
+    while (currentPoint !== startPoint) {
+      currentPoint.visited = true;
+
+      if (
+        currentPoint.type === PolylinePointType.Intersection &&
+        (<PolylineIntersectionPoint>currentPoint).cloned
+      ) {
+        currentPoint = currentPoint.next;
+        continue;
+      }
+
+      subtractedPolyline.push(currentPoint.coordinates);
+      currentPoint = currentPoint.next;
+    }
+
+    subtractedPolylines.push(subtractedPolyline);
+  }
+
+  return subtractedPolylines;
+}
+
+export { mergePolylines, subtractPolylines };

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

@@ -0,0 +1,63 @@
+import type { Types } from '@cornerstonejs/core';
+import isClosed from './isClosed';
+
+/**
+ * Checks if a 2D point is inside the polyline.
+ *
+ * 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 polyline - Polyline points (2D)
+ * @param point - 2D Point
+ * @returns True is the point is inside the polyline or false otherwise
+ */
+export default function containsPoint(
+  polyline: Types.Point2[],
+  point: Types.Point2,
+  closed?: boolean
+): boolean {
+  if (polyline.length < 3) {
+    return false;
+  }
+
+  const numPolylinePoints = polyline.length;
+  let numIntersections = 0;
+
+  // Test intersection agains [end, start] line segment if it should be closed
+  const shouldClose = !(closed === undefined ? isClosed(polyline) : closed);
+  const maxSegmentIndex = polyline.length - (shouldClose ? 1 : 2);
+
+  for (let i = 0; i <= maxSegmentIndex; i++) {
+    const p1 = polyline[i];
+
+    // Calculating the next point index without using % (mod) operator like in
+    // `(i + 1) % numPolylinePoints` to make it 20% faster
+    const p2Index = i === numPolylinePoints - 1 ? 0 : i + 1;
+    const p2 = polyline[p2Index];
+
+    // Calculating min/max without using Math.min/max to make it ~3% faster
+    const maxX = p1[0] >= p2[0] ? p1[0] : p2[0];
+    const maxY = p1[1] >= p2[1] ? p1[1] : p2[1];
+    const minY = p1[1] <= p2[1] ? p1[1] : p2[1];
+
+    const mayIntersectLineSegment =
+      point[0] <= maxX && point[1] >= minY && point[1] < maxY;
+
+    if (mayIntersectLineSegment) {
+      const isVerticalLine = p1[0] === p2[0];
+      let intersects = isVerticalLine;
+
+      if (!intersects) {
+        const xIntersection =
+          ((point[1] - p1[1]) * (p2[0] - p1[0])) / (p2[1] - p1[1]) + p1[0];
+
+        intersects = point[0] <= xIntersection;
+      }
+
+      numIntersections += intersects ? 1 : 0;
+    }
+  }
+
+  return !!(numIntersections % 2);
+}

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

@@ -0,0 +1,20 @@
+import { Types } from '@cornerstonejs/core';
+
+export default function getAABB(polyline: Types.Point2[]): Types.AABB2 {
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+
+  for (let i = 0, len = polyline.length; i < len; i++) {
+    const [x, y] = polyline[i];
+
+    // No Math.min/max calls for better performance
+    minX = minX < x ? minX : x;
+    minY = minY < y ? minY : y;
+    maxX = maxX > x ? maxX : x;
+    maxY = maxY > y ? maxY : y;
+  }
+
+  return { minX, maxX, minY, maxY };
+}

package/src/utilities/math/polyline/{calculateAreaOfPoints.ts → getArea.ts}

@@ -7,7 +7,7 @@ import type { Types } from '@cornerstonejs/core';
  * the points are in canvas, then the result is in canvas pixels ^2; If they are
  * in mm, then the result is in mm^2; etc.
  */
-export default function calculateAreaOfPoints(points: Types.Point2[]): number {
+export default function getArea(points: Types.Point2[]): number {
   // Shoelace algorithm.
   const n = points.length;
   let area = 0.0;

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

@@ -0,0 +1,72 @@
+import { vec2 } from 'gl-matrix';
+import type { Types } from '@cornerstonejs/core';
+import areLineSegmentsIntersecting from './areLineSegmentsIntersecting';
+
+/**
+ * Checks whether the line (`p1`,`q1`) intersects any of the other lines in the
+ * `points`, and returns the closest value.
+ * @param points - Polyline points
+ * @param p1 - Start point of the line segment
+ * @param q1 - End point of the line segment
+ * @param closed - Test the intersection against the line that connects the first to the last when closed
+ * @returns The closest line segment from polyline that intersects the line segment [p1, q1]
+ */
+export default function getClosestLineSegmentIntersection(
+  points: Types.Point2[],
+  p1: Types.Point2,
+  q1: Types.Point2,
+  closed = true
+): { segment: Types.Point2; distance: number } | undefined {
+  let initialQ2Index;
+  let p2Index;
+
+  if (closed) {
+    p2Index = points.length - 1;
+    initialQ2Index = 0;
+  } else {
+    p2Index = 0;
+    initialQ2Index = 1;
+  }
+
+  const intersections = [];
+
+  for (let q2Index = initialQ2Index; q2Index < points.length; q2Index++) {
+    const p2 = points[p2Index];
+    const q2 = points[q2Index];
+
+    if (areLineSegmentsIntersecting(p1, q1, p2, q2)) {
+      intersections.push([p2Index, q2Index]);
+    }
+
+    p2Index = q2Index;
+  }
+
+  if (intersections.length === 0) {
+    return;
+  }
+
+  // Find intersection closest to the start point
+  const distances = [];
+
+  intersections.forEach((intersection) => {
+    const intersectionPoints = [
+      points[intersection[0]],
+      points[intersection[1]],
+    ];
+
+    const midpoint = [
+      (intersectionPoints[0][0] + intersectionPoints[1][0]) / 2,
+      (intersectionPoints[0][1] + intersectionPoints[1][1]) / 2,
+    ];
+
+    distances.push(vec2.distance(<vec2>midpoint, p1));
+  });
+
+  const minDistance = Math.min(...distances);
+  const indexOfMinDistance = distances.indexOf(minDistance);
+
+  return {
+    segment: intersections[indexOfMinDistance],
+    distance: minDistance,
+  };
+}

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

@@ -0,0 +1,42 @@
+import type { Types } from '@cornerstonejs/core';
+import areLineSegmentsIntersecting from './areLineSegmentsIntersecting';
+
+/**
+ * Checks whether the line (`p1`,`q1`) intersects any of the other lines in the
+ * `points`, and returns the first value.
+ *
+ * @param points - Polyline points
+ * @param p1 - First point of the line segment that is being tested
+ * @param q1 - Second point of the line segment that is being tested
+ * @param closed - Test the intersection with the line segment that connects
+ *   the last and first points of the polyline
+ * @returns Indexes of the line segment points from the polyline that intersects [p1, q1]
+ */
+export default function getFirstLineSegmentIntersectionIndexes(
+  points: Types.Point2[],
+  p1: Types.Point2,
+  q1: Types.Point2,
+  closed = true
+): Types.Point2 | undefined {
+  let initialI;
+  let j;
+
+  if (closed) {
+    j = points.length - 1;
+    initialI = 0;
+  } else {
+    j = 0;
+    initialI = 1;
+  }
+
+  for (let i = initialI; i < points.length; i++) {
+    const p2 = points[j];
+    const q2 = points[i];
+
+    if (areLineSegmentsIntersecting(p1, q1, p2, q2)) {
+      return [j, i];
+    }
+
+    j = i;
+  }
+}

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

@@ -0,0 +1,30 @@
+import type { Types } from '@cornerstonejs/core';
+import getLineSegmentIntersectionsIndexes from './getLineSegmentIntersectionsIndexes';
+import getLineSegmentsIntersection from './getLineSegmentsIntersection';
+
+/**
+ * Returns all intersections points between a line segment and a polyline
+ */
+export default function getLineSegmentIntersectionsCoordinates(
+  points: Types.Point2[],
+  p1: Types.Point2,
+  q1: Types.Point2,
+  closed = true
+): Types.Point2[] {
+  const result = [];
+  const polylineIndexes = getLineSegmentIntersectionsIndexes(
+    points,
+    p1,
+    q1,
+    closed
+  );
+
+  for (let i = 0; i < polylineIndexes.length; i++) {
+    const p2 = points[polylineIndexes[i][0]];
+    const q2 = points[polylineIndexes[i][1]];
+    const intersection = getLineSegmentsIntersection(p1, q1, p2, q2);
+    result.push(intersection);
+  }
+
+  return result;
+}

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

@@ -0,0 +1,35 @@
+import type { Types } from '@cornerstonejs/core';
+import areLineSegmentsIntersecting from './areLineSegmentsIntersecting';
+
+/**
+ * Get all intersections between a polyline and a line segment.
+ * @param polyline - Polyline points
+ * @param p1 - Start point of line segment
+ * @param q1 - End point of line segment
+ * @param closed - Test the intersection against the line segment that connects
+ * the last to the first point when set to true
+ * @returns Start/end point indexes of all line segments that intersect (p1, q1)
+ */
+export default function getLineSegmentIntersectionsIndexes(
+  polyline: Types.Point2[],
+  p1: Types.Point2,
+  q1: Types.Point2,
+  closed = true
+): Types.Point2[] {
+  const intersections: Types.Point2[] = [];
+  const numPoints = polyline.length;
+  const maxI = numPoints - (closed ? 1 : 2);
+
+  for (let i = 0; i <= maxI; i++) {
+    const p2 = polyline[i];
+    // Do not use % operator for better performance
+    const j = i === numPoints - 1 ? 0 : i + 1;
+    const q2 = polyline[j];
+
+    if (areLineSegmentsIntersecting(p1, q1, p2, q2)) {
+      intersections.push([i, j]);
+    }
+  }
+
+  return intersections;
+}

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

@@ -0,0 +1,47 @@
+import { Types } from '@cornerstonejs/core';
+
+// ATTENTION: this is an internal function and it should not be added to "polyline"
+// namespace because there is another one from lineSegment.intersectLine that also
+// finds an intersection between two line segments. This one should be removed but
+// it is faster and able to find intersections when the intersection is one of the
+// two points of a line segment.
+//
+// Example:
+//   Line 1: (0, 0), (1, 1) x Line 2 (1, 1), (1, 2)
+//   Line 1: (0, 1), (2, 1) x Line 2 (1, 1), (1, 2)
+//
+// This function must replace `lineSegment.intersectLine` but it requires some
+// tests first
+
+/**
+ * Gets the intersection between the line segments (`p1`,`q1`) and (`p2`,`q2`)
+ *
+ * http://jsfiddle.net/justin_c_rounds/Gd2S2/light/
+ * https://en.wikipedia.org/wiki/Line%E2%80%93line_intersection#Given_two_points_on_each_line
+ */
+export default function getLineSegmentsIntersection(
+  p1: Types.Point2,
+  q1: Types.Point2,
+  p2: Types.Point2,
+  q2: Types.Point2
+): Types.Point2 {
+  const diffQ1P1 = [q1[0] - p1[0], q1[1] - p1[1]];
+  const diffQ2P2 = [q2[0] - p2[0], q2[1] - p2[1]];
+  const denominator = diffQ2P2[1] * diffQ1P1[0] - diffQ2P2[0] * diffQ1P1[1];
+
+  if (denominator == 0) {
+    return;
+  }
+
+  let a = p1[1] - p2[1];
+  let b = p1[0] - p2[0];
+  const numerator1 = diffQ2P2[0] * a - diffQ2P2[1] * b;
+  const numerator2 = diffQ1P1[0] * a - diffQ1P1[1] * b;
+  a = numerator1 / denominator;
+  b = numerator2 / denominator;
+
+  const resultX = p1[0] + a * diffQ1P1[0];
+  const resultY = p1[1] + a * diffQ1P1[1];
+
+  return [resultX, resultY];
+}

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

@@ -0,0 +1,17 @@
+import { Types } from '@cornerstonejs/core';
+import getSignedArea from './getSignedArea';
+
+/**
+ * Calculate the normal of a 2D polyline
+ * https://www.youtube.com/watch?v=GpsKrAipXm8&t=1982s
+ *
+ * @param polyline - Planar polyline in 2D space
+ * @returns Normal of the 2D planar polyline
+ */
+export default function getNormal2(polyline: Types.Point2[]): Types.Point3 {
+  const area = getSignedArea(polyline);
+
+  // The normal of a 2D polyline is (0, 0, 1) or (0, 0, -1) depending if it
+  // is CW or CCW polyline
+  return [0, 0, area / Math.abs(area)] as Types.Point3;
+}