@cornerstonejs/tools 2.0.0-beta.6 → 2.0.0-beta.8

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

@@ -0,0 +1,118 @@
+import type { Types } from '@cornerstonejs/core';
+
+// ATTENTION: this is an internal function and it should not be added to "polyline"
+// namespace.
+//
+// TODO: there is a similar function in math.lineSegment.intersectLine but we
+// need to investigate why it is 6x slower than this one when thousands of
+// intersections are calculated. Also that one may return [NaN, NaN] for
+// collinear points.
+
+/**
+ * Checks whether the line (`p1`,`q1`) intersects the line (`p2`,`q2`) via an
+ * orientation algorithm.
+ *
+ * Credit and details: geeksforgeeks.org/check-if-two-given-line-segments-intersect/
+ *
+ * @param p1 - Start point of line segment 1
+ * @param q1 - End point of line segment 1
+ * @param p2 - Start point of line segment 2
+ * @param q2 - End point of line segment 2
+ * @returns True if the line segments intersect or false otherwise
+ */
+export default function areLineSegmentsIntersecting(
+  p1: Types.Point2,
+  q1: Types.Point2,
+  p2: Types.Point2,
+  q2: Types.Point2
+): boolean {
+  let result = false;
+
+  // Line 1 AABB
+  const line1MinX = p1[0] < q1[0] ? p1[0] : q1[0];
+  const line1MinY = p1[1] < q1[1] ? p1[1] : q1[1];
+  const line1MaxX = p1[0] > q1[0] ? p1[0] : q1[0];
+  const line1MaxY = p1[1] > q1[1] ? p1[1] : q1[1];
+
+  // Line 2 AABB
+  const line2MinX = p2[0] < q2[0] ? p2[0] : q2[0];
+  const line2MinY = p2[1] < q2[1] ? p2[1] : q2[1];
+  const line2MaxX = p2[0] > q2[0] ? p2[0] : q2[0];
+  const line2MaxY = p2[1] > q2[1] ? p2[1] : q2[1];
+
+  // If AABBs do not intersect it is impossible for the lines to intersect.
+  // Checking AABB before doing any math makes it run ~12% faster.
+  if (
+    line1MinX > line2MaxX ||
+    line1MaxX < line2MinX ||
+    line1MinY > line2MaxY ||
+    line1MaxY < line2MinY
+  ) {
+    return false;
+  }
+
+  const orient = [
+    orientation(p1, q1, p2),
+    orientation(p1, q1, q2),
+    orientation(p2, q2, p1),
+    orientation(p2, q2, q1),
+  ];
+
+  // General Case
+  if (orient[0] !== orient[1] && orient[2] !== orient[3]) {
+    return true;
+  }
+
+  // Special Cases
+  if (orient[0] === 0 && onSegment(p1, p2, q1)) {
+    // If p1, q1 and p2 are colinear and p2 lies on segment p1q1
+    result = true;
+  } else if (orient[1] === 0 && onSegment(p1, q2, q1)) {
+    // If p1, q1 and p2 are colinear and q2 lies on segment p1q1
+    result = true;
+  } else if (orient[2] === 0 && onSegment(p2, p1, q2)) {
+    // If p2, q2 and p1 are colinear and p1 lies on segment p2q2
+    result = true;
+  } else if (orient[3] === 0 && onSegment(p2, q1, q2)) {
+    // If p2, q2 and q1 are colinear and q1 lies on segment p2q2
+    result = true;
+  }
+
+  return result;
+}
+
+/**
+ * Checks the orientation of 3 points, returns a 0, 1 or 2 based on
+ * the orientation of the points.
+ */
+function orientation(
+  p: Types.Point2,
+  q: Types.Point2,
+  r: Types.Point2
+): number {
+  // Take the cross product between vectors PQ and QR
+  const orientationValue =
+    (q[1] - p[1]) * (r[0] - q[0]) - (q[0] - p[0]) * (r[1] - q[1]);
+
+  if (orientationValue === 0) {
+    return 0; // Colinear
+  }
+
+  return orientationValue > 0 ? 1 : 2;
+}
+
+/**
+ * Checks if point `q` lies on the segment (`p`,`r`).
+ */
+function onSegment(p: Types.Point2, q: Types.Point2, r: Types.Point2): boolean {
+  if (
+    q[0] <= Math.max(p[0], r[0]) &&
+    q[0] >= Math.min(p[0], r[0]) &&
+    q[1] <= Math.max(p[1], r[1]) &&
+    q[1] >= Math.min(p[1], r[1])
+  ) {
+    return true;
+  }
+
+  return false;
+}

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

@@ -0,0 +1,348 @@
+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 getLinesIntersection from './getLinesIntersection';
+
+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 isFirstPointInside = containsPoint(sourcePolyline, targetPolyline[0]);
+
+  let intersectionPointDirection = isFirstPointInside
+    ? 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 the midpoint of the four points
+      // when the lines are parallel or co-incident.  Otherwise it will return
+      // an extension of the line.
+      const intersectionCoordinate = getLinesIntersection(
+        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,80 @@
+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
+ *
+ * Note that a point on the polyline is considered inside.
+ *
+ * @param polyline - Polyline points (2D)
+ * @param point - 2D Point
+ * @returns True if the point is inside the polyline or false otherwise
+ */
+export default function containsPoint(
+  polyline: Types.Point2[],
+  point: Types.Point2,
+  options: {
+    closed?: boolean;
+    holes?: Types.Point2[][];
+  } = {
+    closed: undefined,
+  }
+): boolean {
+  if (polyline.length < 3) {
+    return false;
+  }
+
+  const numPolylinePoints = polyline.length;
+  let numIntersections = 0;
+
+  const { closed, holes } = options;
+
+  if (holes?.length) {
+    for (const hole of holes) {
+      if (containsPoint(hole, point)) {
+        return false;
+      }
+    }
+  }
+
+  // Test intersection against [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/containsPoints.ts

@@ -0,0 +1,22 @@
+import type { Types } from '@cornerstonejs/core';
+import containsPoint from './containsPoint';
+
+/**
+ * Checks if a polyline contains a set of points.
+ *
+ * @param polyline - Polyline points (2D)
+ * @param points - 2D points to verify
+ * @returns True if all points are inside the polyline or false otherwise
+ */
+export default function containsPoints(
+  polyline: Types.Point2[],
+  points: Types.Point2[]
+): boolean {
+  for (let i = 0, numPoint = points.length; i < numPoint; i++) {
+    if (!containsPoint(polyline, points[i])) {
+      return false;
+    }
+  }
+
+  return true;
+}

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

@@ -0,0 +1,105 @@
+import type { Types } from '@cornerstonejs/core';
+import * as mathLine from '../line';
+
+const DEFAULT_EPSILON = 0.1;
+
+/**
+ * Ramer–Douglas–Peucker algorithm implementation to decimate a polyline
+ * to a similar polyline with fewer points
+ *
+ * https://en.wikipedia.org/wiki/Ramer%E2%80%93Douglas%E2%80%93Peucker_algorithm
+ * https://rosettacode.org/wiki/Ramer-Douglas-Peucker_line_simplification
+ * https://karthaus.nl/rdp/
+ *
+ * @param polyline - Polyline to decimate
+ * @param epsilon - A maximum given distance 'epsilon' to decide if a point
+ * should or shouldn't be added the decimated polyline version. In each
+ * iteration the polyline is split into two polylines and the distance of each
+ * point from those new polylines are checked against the line that connects
+ * the first and last points.
+ * @returns Decimated polyline
+ */
+export default function decimate(
+  polyline: Types.Point2[],
+  epsilon = DEFAULT_EPSILON
+) {
+  const numPoints = polyline.length;
+
+  // The polyline must have at least a start and end points
+  if (numPoints < 3) {
+    return polyline;
+  }
+
+  const epsilonSquared = epsilon * epsilon;
+  const partitionQueue = [[0, numPoints - 1]];
+
+  // Used a boolean array to set each point that will be in the decimated polyline
+  // because pre-allocated arrays are 3-4x faster than thousands of push() calls
+  // to add all points to a new array.
+  const polylinePointFlags = new Array(numPoints).fill(false);
+
+  // Start and end points are always added to the decimated polyline
+  let numDecimatedPoints = 2;
+
+  // Add start and end points to the decimated polyline
+  polylinePointFlags[0] = true;
+  polylinePointFlags[numPoints - 1] = true;
+
+  // Iterative approach using a queue instead of recursion to reduce the number
+  // of function calls (performance)
+  while (partitionQueue.length) {
+    const [startIndex, endIndex] = partitionQueue.pop();
+
+    // Return if there is no point between the start and end points
+    if (endIndex - startIndex === 1) {
+      continue;
+    }
+
+    const startPoint = polyline[startIndex];
+    const endPoint = polyline[endIndex];
+    let maxDistSquared = -Infinity;
+    let maxDistIndex = -1;
+
+    // Search for the furthest point
+    for (let i = startIndex + 1; i < endIndex; i++) {
+      const currentPoint = polyline[i];
+      const distSquared = mathLine.distanceToPointSquared(
+        startPoint,
+        endPoint,
+        currentPoint
+      );
+
+      if (distSquared > maxDistSquared) {
+        maxDistSquared = distSquared;
+        maxDistIndex = i;
+      }
+    }
+
+    // Do not add any of the points because the fursthest one is very close to
+    // the line based on the epsilon value
+    if (maxDistSquared < epsilonSquared) {
+      continue;
+    }
+
+    // Update the flag for the furthest point because it will be added to the
+    // decimated polyline
+    polylinePointFlags[maxDistIndex] = true;
+    numDecimatedPoints++;
+
+    // Partition the points into two parts using maxDistIndex as the pivot point
+    // and process both sides
+    partitionQueue.push([maxDistIndex, endIndex]);
+    partitionQueue.push([startIndex, maxDistIndex]);
+  }
+
+  // A pre-allocated array is 3-4x faster then multiple push() calls
+  const decimatedPolyline: Types.Point2[] = new Array(numDecimatedPoints);
+
+  for (let srcIndex = 0, dstIndex = 0; srcIndex < numPoints; srcIndex++) {
+    if (polylinePointFlags[srcIndex]) {
+      decimatedPolyline[dstIndex++] = polyline[srcIndex];
+    }
+  }
+
+  return decimatedPolyline;
+}