@immugio/three-math-extensions 0.3.4 → 0.3.6

package/src/isContinuousClosedShape.ts

@@ -1,25 +1,25 @@
-// The point type P must implement an isNear method that accepts the same point type and an optional tolerance.
-type Point<P extends { isNear(other: P, tolerance?: number): boolean }> = { isNear(other: P, tolerance?: number): boolean };
-
-// This matches the signatures on Vec2 and Vec3 (for example, isNear(v: Vector2, maxDistance?: number)).
-export function isContinuousClosedShape<P extends Point<P>>(lines: { start: P; end: P }[], tolerance: number = 0): boolean {
-    if (lines.length < 3) {
-        return false; // A shape needs at least 3 lines to be closed
-    }
-
-    // Starting from the first line, check if the end of the current line is the start of the next line
-    for (let i = 0; i < lines.length - 1; i++) {
-        const endCurrent = lines[i].end;
-        const startNext = lines[i + 1].start;
-
-        if (!endCurrent.isNear(startNext, tolerance)) {
-            return false; // If the end of the current line and start of the next line are not close, return false
-        }
-    }
-
-    // Lastly, we should check the end of the last line with the start of the first line
-    const endLast = lines[lines.length - 1].end;
-    const startFirst = lines[0].start;
-
-    return endLast.isNear(startFirst, tolerance);
+// The point type P must implement an isNear method that accepts the same point type and an optional tolerance.
+type Point<P extends { isNear(other: P, tolerance?: number): boolean }> = { isNear(other: P, tolerance?: number): boolean };
+
+// This matches the signatures on Vec2 and Vec3 (for example, isNear(v: Vector2, maxDistance?: number)).
+export function isContinuousClosedShape<P extends Point<P>>(lines: { start: P; end: P }[], tolerance: number = 0): boolean {
+    if (lines.length < 3) {
+        return false; // A shape needs at least 3 lines to be closed
+    }
+
+    // Starting from the first line, check if the end of the current line is the start of the next line
+    for (let i = 0; i < lines.length - 1; i++) {
+        const endCurrent = lines[i].end;
+        const startNext = lines[i + 1].start;
+
+        if (!endCurrent.isNear(startNext, tolerance)) {
+            return false; // If the end of the current line and start of the next line are not close, return false
+        }
+    }
+
+    // Lastly, we should check the end of the last line with the start of the first line
+    const endLast = lines[lines.length - 1].end;
+    const startFirst = lines[0].start;
+
+    return endLast.isNear(startFirst, tolerance);
 }

package/src/isPointInPolygon.ts

@@ -1,24 +1,24 @@
-import { Point2 } from "./Point2";
-
-/**
- * Check if a point is inside a polygon
- * Warning: The function returns unreliable results for points on the polygon boundary.
- * Obsolete, use containsPoint instead.
- * @param p
- * @param point
- */
-export function isPointInPolygon(p: Point2[], point: Point2): boolean {
-    const x = point.x, y = point.y;
-
-    let i: number, j: number, c = false;
-
-    for (i = 0, j = p.length - 1; i < p.length; j = i++) {
-        if ((((p[i].y <= y) && (y < p[j].y)) ||
-                ((p[j].y <= y) && (y < p[i].y))) &&
-            (x < (p[j].x - p[i].x) * (y - p[i].y) / (p[j].y - p[i].y) + p[i].x)) {
-            c = !c;
-        }
-    }
-
-    return c;
+import { Point2 } from "./Point2";
+
+/**
+ * Check if a point is inside a polygon
+ * Warning: The function returns unreliable results for points on the polygon boundary.
+ * Obsolete, use containsPoint instead.
+ * @param p
+ * @param point
+ */
+export function isPointInPolygon(p: Point2[], point: Point2): boolean {
+    const x = point.x, y = point.y;
+
+    let i: number, j: number, c = false;
+
+    for (i = 0, j = p.length - 1; i < p.length; j = i++) {
+        if ((((p[i].y <= y) && (y < p[j].y)) ||
+                ((p[j].y <= y) && (y < p[i].y))) &&
+            (x < (p[j].x - p[i].x) * (y - p[i].y) / (p[j].y - p[i].y) + p[i].x)) {
+            c = !c;
+        }
+    }
+
+    return c;
 }

package/src/isPolygonClockwise.ts

@@ -1,16 +1,16 @@
-import { Point2 } from "./Point2";
-
-/*
-* Determines if a polygon is clockwise or counter-clockwise.
-* X increases to the right, Y increases downwards.
-* Based on this answer https://stackoverflow.com/a/18472899/1837173 - the result is inverted, they assume the inverse y-axis
-*/
-export function isPolygonClockwise(vertices: Point2[]): boolean {
-    let sum = 0.0;
-    for (let i = 0; i < vertices.length; i++) {
-        const v1 = vertices[i];
-        const v2 = vertices[(i + 1) % vertices.length];
-        sum += (v2.x - v1.x) * (v2.y + v1.y);
-    }
-    return sum < 0.0;
+import { Point2 } from "./Point2";
+
+/*
+* Determines if a polygon is clockwise or counter-clockwise.
+* X increases to the right, Y increases downwards.
+* Based on this answer https://stackoverflow.com/a/18472899/1837173 - the result is inverted, they assume the inverse y-axis
+*/
+export function isPolygonClockwise(vertices: Point2[]): boolean {
+    let sum = 0.0;
+    for (let i = 0; i < vertices.length; i++) {
+        const v1 = vertices[i];
+        const v2 = vertices[(i + 1) % vertices.length];
+        sum += (v2.x - v1.x) * (v2.y + v1.y);
+    }
+    return sum < 0.0;
 }

package/src/normalizeAngleDegrees.ts

@@ -1,7 +1,7 @@
-/**
- * Normalizes an angle in degrees to the range [0, 360].
- * @param angle in degrees
- */
-export function normalizeAngleDegrees(angle: number): number {
-    return ((angle % 360) + 360) % 360;
+/**
+ * Normalizes an angle in degrees to the range [0, 360].
+ * @param angle in degrees
+ */
+export function normalizeAngleDegrees(angle: number): number {
+    return ((angle % 360) + 360) % 360;
 }

package/src/normalizeAngleRadians.ts

@@ -1,15 +1,15 @@
-import { TwoPI } from "./MathConstants";
-
-/**
- * Normalize an angle in radians to the range of 0 to 2π.
- * @param angle in radians
- */
-export function normalizeAngleRadians(angle: number): number {
-    angle = angle % TwoPI;  // Use modulus to get the angle within the range of 0 to 2π
-
-    if (angle < 0) {        // Add 2π if the angle is negative
-        angle = angle + TwoPI;
-    }
-
-    return angle;
+import { TwoPI } from "./MathConstants";
+
+/**
+ * Normalize an angle in radians to the range of 0 to 2π.
+ * @param angle in radians
+ */
+export function normalizeAngleRadians(angle: number): number {
+    angle = angle % TwoPI;  // Use modulus to get the angle within the range of 0 to 2π
+
+    if (angle < 0) {        // Add 2π if the angle is negative
+        angle = angle + TwoPI;
+    }
+
+    return angle;
 }

package/src/offsetPolyline.ts

@@ -1,27 +1,27 @@
-import { Line2D } from "./Line2D";
-
-export function offsetPolyline(lines: Line2D[], offset: number, tolerance: number = 0): Line2D[] {
-    const isClosed = lines[0].start.isNear(lines.at(-1).end, tolerance);
-
-    for (let i = 0; i < lines.length; i++) {
-        const isFirst = i === 0;
-        const isLast = i === lines.length - 1;
-
-        const line = lines[i];
-        line.translateLeft(offset);
-
-        const next = lines[(i + 1) % lines.length];
-        if (!isLast || isClosed) {
-            line.extendToOrTrimAtIntersection(next);
-            next.extendToOrTrimAtIntersection(line);
-        }
-
-        const previous = lines[(i + lines.length - 1) % lines.length];
-        if (!isFirst || isClosed) {
-            line.extendToOrTrimAtIntersection(previous);
-            previous.extendToOrTrimAtIntersection(line);
-        }
-    }
-
-    return lines;
+import { Line2D } from "./Line2D";
+
+export function offsetPolyline(lines: Line2D[], offset: number, tolerance: number = 0): Line2D[] {
+    const isClosed = lines[0].start.isNear(lines.at(-1).end, tolerance);
+
+    for (let i = 0; i < lines.length; i++) {
+        const isFirst = i === 0;
+        const isLast = i === lines.length - 1;
+
+        const line = lines[i];
+        line.translateLeft(offset);
+
+        const next = lines[(i + 1) % lines.length];
+        if (!isLast || isClosed) {
+            line.extendToOrTrimAtIntersection(next);
+            next.extendToOrTrimAtIntersection(line);
+        }
+
+        const previous = lines[(i + lines.length - 1) % lines.length];
+        if (!isFirst || isClosed) {
+            line.extendToOrTrimAtIntersection(previous);
+            previous.extendToOrTrimAtIntersection(line);
+        }
+    }
+
+    return lines;
 }

package/src/polygonPerimeter.ts

@@ -1,14 +1,14 @@
-import { Vec2 } from "./Vec2";
-
-export function polygonPerimeter(polygon: Vec2[], forceClosedPolygon: boolean = false): number {
-    if (forceClosedPolygon && !polygon[0].equals(polygon.at(-1))) {
-        polygon = [...polygon];
-        polygon.push(polygon[0].clone());
-    }
-
-    let length = 0;
-    for (let i = 0; i < polygon.length - 1; i++) {
-        length += polygon[i].distanceTo(polygon[i + 1]);
-    }
-    return length;
+import { Vec2 } from "./Vec2";
+
+export function polygonPerimeter(polygon: Vec2[], forceClosedPolygon: boolean = false): number {
+    if (forceClosedPolygon && !polygon[0].equals(polygon.at(-1))) {
+        polygon = [...polygon];
+        polygon.push(polygon[0].clone());
+    }
+
+    let length = 0;
+    for (let i = 0; i < polygon.length - 1; i++) {
+        length += polygon[i].distanceTo(polygon[i + 1]);
+    }
+    return length;
 }

package/src/sortLinesByConnections.ts

@@ -1,46 +1,46 @@
-import { Line2D } from "./Line2D";
-
-/**
- * Sort connected lines by their connections.
- * When the polygon is open, the first line must be the line that has no connection at the start.
- * When the polygon is open, the last line must be the line that has no connection at the end.
- * If the lines form a closed polygon, any line can be the first line.
- */
-export function sortLinesByConnections(lines: Line2D[], tolerance: number = 0): Line2D[] {
-    const remainingLines = [...lines];
-    const startLineIndex = findStartLineIndex(remainingLines, tolerance);
-
-    const sortedLines: Line2D[] = [remainingLines.splice(startLineIndex, 1)[0]];
-
-    while (remainingLines.length > 0) {
-        const lastLine = sortedLines[sortedLines.length - 1];
-        const nextLineIndex = remainingLines.findIndex(line => lastLine.end.isNear(line.start, tolerance));
-
-        if (nextLineIndex === -1) {
-            console.log("Lines do not form a connected path");
-            return [...sortedLines, ...remainingLines];
-        }
-
-        sortedLines.push(remainingLines.splice(nextLineIndex, 1)[0]);
-    }
-
-    return sortedLines;
-}
-
-/**
- * Find the index of the starting line.
- * A starting line is defined as a line that has no other line connected to its start.
- * If such a line does not exist, it means that the lines form a closed polygon, return 0.
- * @param lines
- * @param tolerance
- */
-function findStartLineIndex(lines: Line2D[], tolerance: number): number {
-    for (let i = 0; i < lines.length; i++) {
-        const startLine = lines[i];
-        const isStartLine = !lines.some(line => line.end.isNear(startLine.start, tolerance));
-        if (isStartLine) {
-            return i;
-        }
-    }
-    return 0;
+import { Line2D } from "./Line2D";
+
+/**
+ * Sort connected lines by their connections.
+ * When the polygon is open, the first line must be the line that has no connection at the start.
+ * When the polygon is open, the last line must be the line that has no connection at the end.
+ * If the lines form a closed polygon, any line can be the first line.
+ */
+export function sortLinesByConnections(lines: Line2D[], tolerance: number = 0): Line2D[] {
+    const remainingLines = [...lines];
+    const startLineIndex = findStartLineIndex(remainingLines, tolerance);
+
+    const sortedLines: Line2D[] = [remainingLines.splice(startLineIndex, 1)[0]];
+
+    while (remainingLines.length > 0) {
+        const lastLine = sortedLines[sortedLines.length - 1];
+        const nextLineIndex = remainingLines.findIndex(line => lastLine.end.isNear(line.start, tolerance));
+
+        if (nextLineIndex === -1) {
+            console.log("Lines do not form a connected path");
+            return [...sortedLines, ...remainingLines];
+        }
+
+        sortedLines.push(remainingLines.splice(nextLineIndex, 1)[0]);
+    }
+
+    return sortedLines;
+}
+
+/**
+ * Find the index of the starting line.
+ * A starting line is defined as a line that has no other line connected to its start.
+ * If such a line does not exist, it means that the lines form a closed polygon, return 0.
+ * @param lines
+ * @param tolerance
+ */
+function findStartLineIndex(lines: Line2D[], tolerance: number): number {
+    for (let i = 0; i < lines.length; i++) {
+        const startLine = lines[i];
+        const isStartLine = !lines.some(line => line.end.isNear(startLine.start, tolerance));
+        if (isStartLine) {
+            return i;
+        }
+    }
+    return 0;
 }

package/types/Line2D.d.ts

@@ -130,9 +130,12 @@ export declare class Line2D {
     isPointOnInfiniteLine(point: Point2): boolean;
     /**
      * Returns true if other line is collinear and overlaps or at least touching this line.
+     * Uses tolerances to allow for small gaps and angle differences.
      * @param other
+     * @param distanceTolerance Maximum distance between lines or points to be considered touching/overlapping
+     * @param parallelTolerance Maximum angle difference in radians for lines to be considered parallel
      */
-    isCollinearWithTouchOrOverlap(other: Line2D): boolean;
+    isCollinearWithTouchOrOverlap(other: Line2D, distanceTolerance?: number, parallelTolerance?: number): boolean;
     /**
      * Returns true if there is any overlap between this line and the @other line section.
      */
@@ -144,20 +147,24 @@ export declare class Line2D {
     getOverlap(other: Line2D): Line2D;
     /**
      * Joins a copy of @line with the @other line.
-     * Other must be parallel to this line.
+     * Other must be parallel to this line (within tolerance).
      * Returns null if there is no overlap
      * Clones the line, does not modify.
      * @param line
      * @param other
+     * @param distanceTolerance Maximum distance between lines or points to be considered touching/overlapping
+     * @param parallelTolerance Maximum angle difference in radians for lines to be considered parallel
      */
-    static joinLine(line: Line2D, other: Line2D): Line2D;
+    static joinLine(line: Line2D, other: Line2D, distanceTolerance?: number, parallelTolerance?: number): Line2D;
     /**
      * Joins provided lines into several joined lines.
-     * Lines must be parallel for joining.
+     * Lines must be parallel for joining (within tolerance).
      * Clone the lines, does not modify.
      * @param lines
+     * @param distanceTolerance Maximum distance between lines or points to be considered touching/overlapping
+     * @param parallelTolerance Maximum angle difference in radians for lines to be considered parallel
      */
-    static joinLines(lines: Line2D[]): Line2D[];
+    static joinLines(lines: Line2D[], distanceTolerance?: number, parallelTolerance?: number): Line2D[];
     /**
      * Checks if the current line covers another line.
      * A line is considered to cover another line if they are parallel and both the start and end points of the other line are contained within the current line.