@immugio/three-math-extensions 0.0.4 → 0.0.5

package/esm/Line3D.js

@@ -0,0 +1,388 @@
+import { Line3 } from "three";
+import { Vec3 } from "./Vec3";
+import { Line2D } from "./Line2D";
+export class Line3D extends Line3 {
+    #target;
+    constructor(start, end) {
+        super(start, end);
+        this.#target = new Vec3();
+    }
+    static fromPoints(start, end) {
+        return new Line3D(new Vec3(start.x, start.y, start.z), new Vec3(end.x, end.y, end.z));
+    }
+    /**
+     * Creates a polygon formed by an array of lines from points provided.
+     * The polygon will only be closed if either
+     * 1) the first and last points are the same or 2) `forceClosedPolygon` is true.
+     */
+    static fromPolygon(polygon, forceClosedPolygon = false) {
+        if (!polygon || polygon.length < 2) {
+            return [];
+        }
+        if (forceClosedPolygon && (polygon[0].x !== polygon.at(-1).x || polygon[0].y !== polygon.at(-1).y || polygon[0].z !== polygon.at(-1).z)) {
+            polygon = [...polygon, polygon[0]];
+        }
+        const lines = [];
+        for (let i = 0; i < polygon.length - 1; i++) {
+            lines.push(Line3D.fromPoints(polygon[i], polygon[i + 1]));
+        }
+        return lines;
+    }
+    /**
+     * Returns lines that are the result of clipping this line by the @other line.
+     * Clips must be parallel to this line.
+     * Clones the line, does not modify this.
+     * @param other
+     * @param parallelTolerance
+     */
+    clipLine(other, parallelTolerance = Number.EPSILON) {
+        other = this.getParallelLineInTheSameDirection(other, parallelTolerance);
+        // 1) Lines aren't parallel
+        if (!other) {
+            return [this.clone()];
+        }
+        const left = this.clone();
+        left.end.copy(other.start);
+        const right = this.clone();
+        right.start.copy(other.end);
+        return [left, right].filter(x => x.direction.manhattanDistanceTo(this.direction) <= parallelTolerance);
+    }
+    /**
+     * Returns lines that are the result of clipping this line by the @clips.
+     * Clips must be parallel to this line.
+     * Clones the line, does not modify this.
+     * @param clips
+     * @param distanceTolerance
+     * @param parallelTolerance
+     */
+    clipLines(clips, distanceTolerance = 0, parallelTolerance = Number.EPSILON) {
+        const free = [];
+        const sources = [this.clone()];
+        while (sources.length > 0) {
+            let isFree = true;
+            const tested = sources.pop();
+            for (const clip of clips) {
+                if (tested.overlaps(clip, distanceTolerance, parallelTolerance)) {
+                    isFree = false;
+                    const subtracted = tested.clipLine(clip, parallelTolerance);
+                    sources.push(...subtracted);
+                    break;
+                }
+            }
+            if (isFree)
+                free.push(tested);
+        }
+        return free;
+    }
+    /**
+     * Joins a copy of this line with the @other line.
+     * Other must be parallel to this line.
+     * Returns null if there is no overlap
+     * Clones the line, does not modify this.
+     * @param other
+     * @param distanceTolerance
+     * @param parallelTolerance
+     */
+    joinLine(other, distanceTolerance = 0, parallelTolerance = Number.EPSILON) {
+        // 6 possible cases:
+        const otherParallel = this.getParallelLineInTheSameDirection(other, parallelTolerance);
+        // 1) Lines aren't parallel
+        if (!otherParallel) {
+            return null;
+        }
+        const thisContainsOtherStartPoint = this.containsPoint(otherParallel.start, distanceTolerance);
+        const thisContainsOtherEndPoint = this.containsPoint(otherParallel.end, distanceTolerance);
+        const otherContainsThisStartPoint = otherParallel.containsPoint(this.start, distanceTolerance);
+        const otherContainsThisEndPoint = otherParallel.containsPoint(this.end, distanceTolerance);
+        // 2) Lines don't overlap at all
+        if (!thisContainsOtherStartPoint &&
+            !thisContainsOtherEndPoint &&
+            !otherContainsThisStartPoint &&
+            !otherContainsThisEndPoint) {
+            return null;
+        }
+        // 3) This line entirely covers the other line
+        if (thisContainsOtherStartPoint && thisContainsOtherEndPoint) {
+            return this.clone();
+        }
+        // 4) The other line entirely covers this line
+        if (otherContainsThisStartPoint && otherContainsThisEndPoint) {
+            return otherParallel.clone();
+        }
+        // 5) This line is overlapped by the start of the other line
+        if (thisContainsOtherStartPoint && !thisContainsOtherEndPoint) {
+            return new Line3D(this.start, otherParallel.end);
+        }
+        // 6) This line is overlapped by the end of the other line
+        if (thisContainsOtherEndPoint && !thisContainsOtherStartPoint) {
+            return new Line3D(otherParallel.start, this.end);
+        }
+        return null;
+    }
+    /**
+     * Joins provided lines into several joined lines.
+     * Lines must be parallel for joining.
+     * @param lines
+     * @param distanceTolerance
+     * @param parallelTolerance
+     */
+    static joinLines(lines, distanceTolerance = 0, parallelTolerance = Number.EPSILON) {
+        if (lines.length < 2) {
+            return lines.map(x => x.clone());
+        }
+        const toProcess = lines.slice();
+        const result = [];
+        while (toProcess.length > 0) {
+            const current = toProcess.pop();
+            let joinedLine;
+            for (let i = 0; i < result.length; i++) {
+                const other = result[i];
+                joinedLine = current.joinLine(other, distanceTolerance, parallelTolerance);
+                if (joinedLine) {
+                    result.splice(i, 1);
+                    toProcess.push(joinedLine);
+                    break;
+                }
+            }
+            if (!joinedLine) {
+                result.push(current.clone());
+            }
+        }
+        return result;
+    }
+    /**
+     * Returns true if this line section completely overlaps the @other line section.
+     * @param other
+     * @param tolerance
+     */
+    covers(other, tolerance = 0) {
+        return this.containsPoint(other.start, tolerance) && this.containsPoint(other.end, tolerance);
+    }
+    /**
+     * Returns true if there is any overlap between this line and the @other line section.
+     * @param other
+     * @param distanceTolerance
+     * @param parallelTolerance
+     */
+    overlaps(other, distanceTolerance = 0, parallelTolerance = Number.EPSILON) {
+        // Special case
+        if (this.equals(other, distanceTolerance)) {
+            return true;
+        }
+        // Always have to be parallel
+        if (this.isParallelTo(other, parallelTolerance)) {
+            // To pass as overlapping, at least one point has to be within the other line, but they mush not be equal - "touching" is not considered overlapping
+            const otherStartEqualsToAnyOfThisPoint = other.start.distanceTo(this.start) <= distanceTolerance || other.start.distanceTo(this.end) <= distanceTolerance;
+            if (this.containsPoint(other.start, distanceTolerance) && !otherStartEqualsToAnyOfThisPoint) {
+                return true;
+            }
+            const otherEndEqualsToAnyOfThisPoint = other.end.distanceTo(this.start) <= distanceTolerance || other.end.distanceTo(this.end) <= distanceTolerance;
+            if (this.containsPoint(other.end, distanceTolerance) && !otherEndEqualsToAnyOfThisPoint) {
+                return true;
+            }
+            const thisStartEqualsToAnyOfOtherPoint = this.start.distanceTo(other.start) <= distanceTolerance || this.start.distanceTo(other.end) <= distanceTolerance;
+            if (other.containsPoint(this.start, distanceTolerance) && !thisStartEqualsToAnyOfOtherPoint) {
+                return true;
+            }
+            const thisEndEqualsToAnyOfOtherPoint = this.end.distanceTo(other.start) <= distanceTolerance || this.end.distanceTo(other.end) <= distanceTolerance;
+            if (other.containsPoint(this.end, distanceTolerance) && !thisEndEqualsToAnyOfOtherPoint) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Returns this line's length.
+     */
+    get length() {
+        return this.start.distanceTo(this.end);
+    }
+    /**
+     * Set the length of this line. Center and direction remain unchanged.
+     * @param length
+     */
+    setLength(length) {
+        const diff = length - this.length;
+        return this.resize(diff);
+    }
+    /**
+     * Returns the direction of this line.
+     */
+    get direction() {
+        return this.end.clone().sub(this.start).normalize();
+    }
+    /**
+     * Returns the center of this line
+     */
+    get center() {
+        return this.getCenter(new Vec3());
+    }
+    /**
+     * Set the center of the line to the provided point. Length and direction remain unchanged.
+     * @param value
+     */
+    setCenter(value) {
+        const current = this.center;
+        const diffX = current.x - value.x;
+        const diffY = current.y - value.y;
+        const diffZ = current.z - value.z;
+        this.start.x -= diffX;
+        this.start.y -= diffY;
+        this.start.z -= diffZ;
+        this.end.x -= diffX;
+        this.end.y -= diffY;
+        this.end.z -= diffZ;
+        return this;
+    }
+    /** Returns the start and end points of the line as an array. */
+    get endpoints() {
+        return [this.start, this.end];
+    }
+    /**
+     * Check that this line section contains provided point.
+     * @param p
+     * @param tolerance
+     */
+    containsPoint(p, tolerance = 0) {
+        const closestPointToPoint = this.closestPointToPoint(p, true, this.#target);
+        return closestPointToPoint.distanceTo(p) <= tolerance;
+    }
+    /**
+     * Distance from this line to provided point.
+     * @param p
+     * @param clampToLine
+     */
+    distanceToPoint(p, clampToLine = true) {
+        const closestPointToPoint = this.closestPointToPoint(p, clampToLine, this.#target);
+        return closestPointToPoint.distanceTo(p);
+    }
+    /**
+     * Returns a copy of @other line, the direction of @other is reversed if needed.
+     * Returns null if lines are not parallel.
+     * @param other
+     * @param tolerance
+     */
+    getParallelLineInTheSameDirection(other, tolerance = Number.EPSILON) {
+        const direction = this.direction;
+        const areTheSameDirection = direction.manhattanDistanceTo(other.direction) < tolerance;
+        if (areTheSameDirection) {
+            return other.clone();
+        }
+        const otherLineOppositeDirection = new Line3D(other.end, other.start);
+        if (otherLineOppositeDirection.direction.manhattanDistanceTo(direction) < tolerance) {
+            return otherLineOppositeDirection;
+        }
+        return null;
+    }
+    /**
+     * Check if @other is parallel to this line.
+     * @param other
+     * @param tolerance
+     */
+    isParallelTo(other, tolerance = Number.EPSILON) {
+        const direction = this.direction;
+        const otherDirection = other.direction;
+        const areTheSameDirection = direction.manhattanDistanceTo(otherDirection) <= tolerance;
+        if (areTheSameDirection) {
+            return true;
+        }
+        return direction.negate().manhattanDistanceTo(otherDirection) < tolerance;
+    }
+    /*
+    * Extends or reduces the line to the given length while keeping the center of the line constant.
+    */
+    resize(amount) {
+        this.moveStartPoint(amount / 2);
+        this.moveEndPoint(amount / 2);
+        return this;
+    }
+    /*
+    * Moves start on the line by the given amount. Plus values move the point further away from the center.
+    */
+    moveStartPoint(amount) {
+        const start = this.movePointOnThisLine(this.start, amount);
+        this.start.x = start.x;
+        this.start.y = start.y;
+        this.start.z = start.z;
+        return this;
+    }
+    /*
+    * Moves end on the line by the given amount in the current direction. Plus values move the point further away from the center.
+    */
+    moveEndPoint(amount) {
+        const end = this.movePointOnThisLine(this.end, amount);
+        this.end.x = end.x;
+        this.end.y = end.y;
+        this.end.z = end.z;
+        return this;
+    }
+    /**
+     * Returns a new line that is the projection of this line onto @other. Uses `closestPointToPoint` to find the projection.
+     * @param other
+     * @param clampToLine
+     */
+    projectOn(other, clampToLine) {
+        const p1 = other.closestPointToPoint(this.start, clampToLine, new Vec3());
+        const p2 = other.closestPointToPoint(this.end, clampToLine, new Vec3());
+        return p1.distanceTo(this.start) < p2.distanceTo(this.start) ? new Line3D(p1, p2) : new Line3D(p2, p1);
+    }
+    /**
+     * Divides the Line3D into a number of segments of the given length.
+     * @param maxSegmentLength number
+     */
+    chunk(maxSegmentLength) {
+        const source = this.clone();
+        const result = [];
+        while (source.length > maxSegmentLength) {
+            const chunk = source.clone();
+            chunk.moveEndPoint(-(chunk.length - maxSegmentLength));
+            result.push(chunk);
+            source.start.copy(chunk.end);
+        }
+        if (source.length > 0) {
+            result.push(source);
+        }
+        return result;
+    }
+    /**
+     * Note that this works well for moving the endpoints as it's currently used
+     * If it were to be made public, it would need to handle the situation where the point to move is in the center of the line which would require a different approach
+     */
+    movePointOnThisLine(point, amount) {
+        const center = this.getCenter(this.#target);
+        const vec = new Vec3(center.x - point.x, center.y - point.y, center.z - point.z);
+        const length = vec.length();
+        vec.normalize().multiplyScalar(length + amount);
+        return new Vec3(center.x - vec.x, center.y - vec.y, center.z - vec.z);
+    }
+    /**
+     * Move this line by the given vector.
+     * @param p
+     */
+    translate(p) {
+        this.start.add(p);
+        this.end.add(p);
+        return this;
+    }
+    /**
+     * Project the line to 2D space, Y value is dropped
+     */
+    onPlan() {
+        return new Line2D(this.start.onPlan(), this.end.onPlan());
+    }
+    /**
+     * Equals with tolerance
+     */
+    equals(other, tolerance = 0) {
+        return !!other && this.start.distanceTo(other.start) <= tolerance && this.end.distanceTo(other.end) <= tolerance;
+    }
+    /**
+     * Deep clone of this line
+     */
+    clone() {
+        return new Line3D(this.start.clone(), this.end.clone());
+    }
+    toString() {
+        return `Line3D { start: ${this.start.x}, ${this.start.y}, ${this.start.z}, end: ${this.end.x}, ${this.end.y}, ${this.end.z}}`;
+    }
+}

package/esm/Point2.js

@@ -0,0 +1 @@
+export {};

package/esm/Point3.js

@@ -0,0 +1 @@
+export {};

package/esm/Vec2.js

@@ -0,0 +1,19 @@
+import { Vector2 } from "three";
+import { Vec3 } from "./Vec3";
+export class Vec2 extends Vector2 {
+    static fromPoint(point) {
+        return new Vec2(point.x, point.y);
+    }
+    roundIfCloseToInteger(max = 0.000000000001) {
+        if (Math.abs(this.x - Math.round(this.x)) < max) {
+            this.x = Math.round(this.x);
+        }
+        if (Math.abs(this.y - Math.round(this.y)) < max) {
+            this.y = Math.round(this.y);
+        }
+        return this;
+    }
+    in3DSpace(z = 0) {
+        return new Vec3(this.x, z, this.y);
+    }
+}

package/esm/Vec3.js

@@ -0,0 +1,53 @@
+import { Vector3 } from "three";
+import { Vec2 } from "./Vec2";
+export class Vec3 extends Vector3 {
+    #target;
+    static fromPoint(point) {
+        return new Vec3(point.x, point.y, point.z);
+    }
+    moveTowards(target, amount) {
+        if (this.#target === undefined) {
+            this.#target = new Vector3();
+        }
+        this.#target.copy(target);
+        this.add(this.#target.sub(this).normalize().multiplyScalar(amount));
+        return this;
+    }
+    centerTowards(target) {
+        if (this.#target === undefined) {
+            this.#target = new Vector3();
+        }
+        return this.moveTowards(target, this.distanceTo(target) / 2);
+    }
+    addY(y) {
+        this.y += y;
+        return this;
+    }
+    addX(x) {
+        this.x += x;
+        return this;
+    }
+    scale(p) {
+        this.x *= p.x;
+        this.y *= p.y;
+        this.z *= p.z;
+        return this;
+    }
+    closest(...points) {
+        const withDistances = points.map(p => ({ point: p, distance: this.distanceTo(p) }));
+        const closest = withDistances.reduce((a, b) => a.distance < b.distance ? a : b);
+        return Vec3.fromPoint(closest.point);
+    }
+    toPointWithFlippedYZ() {
+        return new Vec3(this.x, this.z, this.y);
+    }
+    onPlan() {
+        return new Vec2(this.x, this.z);
+    }
+    horizontalDistanceTo(point) {
+        return new Vector3(this.x, 0, this.z).distanceTo(new Vector3(point.x, 0, point.z));
+    }
+    clone() {
+        return super.clone();
+    }
+}

package/esm/index.js

@@ -0,0 +1,4 @@
+export { Vec2 } from "./Vec2";
+export { Vec3 } from "./Vec3";
+export { Line2D } from "./Line2D";
+export { Line3D } from "./Line3D";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immugio/three-math-extensions",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Set of utilities for 2d and 3d line math built on top of three.js",
   "author": "Jan Mikeska <janmikeska@gmail.com>",
   "license": "ISC",

package/types/Line2D.d.ts

@@ -0,0 +1,215 @@
+import { Point2 } from "./Point2";
+import { Vector2 } from "three";
+import { Vec2 } from "./Vec2";
+export declare class Line2D {
+    start: Vec2;
+    end: Vec2;
+    index: number;
+    constructor(start: Vec2, end: Vec2, index?: number);
+    static fromCoordinates(x1: number, y1: number, x2: number, y2: number, index?: number): Line2D;
+    static fromPoints(p1: Point2, p2: Point2, index?: number): Line2D;
+    /**
+     * Creates a polygon formed by an array of lines from points provided.
+     * The polygon will only be closed if either
+     * 1) the first and last points are the same or 2) `forceClosedPolygon` is true.
+     */
+    static fromPolygon(polygon: Point2[], forceClosedPolygon?: boolean): Line2D[];
+    static fromLength(length: number): Line2D;
+    get center(): Vec2;
+    /**
+     * Set the center of the line to the provided point. Length and direction remain unchanged.
+     * Modifies this line.
+     * @param value
+     */
+    set center(value: Point2);
+    /**
+     * Set the center of the line to the provided point. Length and direction remain unchanged.
+     * Modifies this line.
+     * @param value
+     */
+    setCenter(value: Point2): Line2D;
+    resize(amount: number): Line2D;
+    moveStartPoint(amount: number): Line2D;
+    /**
+     * Moves end point on the line by the given amount. Plus values move the point further away from the center.
+     * Modifies this line.
+     */
+    moveEndPoint(amount: number): Line2D;
+    private movePointOnThisLine;
+    /**
+     * Set the length of this line. Center and direction remain unchanged.
+     * Modifies this line.
+     * @param l
+     */
+    set length(l: number);
+    get length(): number;
+    /**
+     * Set the length of this line. Center and direction remain unchanged.
+     * @param length
+     */
+    setLength(length: number): this;
+    /**
+     * Returns the start and end points of the line as an array.
+     * Endpoints are not cloned.
+     */
+    get endpoints(): Vec2[];
+    /**
+     * Returns the direction of this line.
+     */
+    get direction(): Vec2;
+    /**
+     * Inverts the direction of the line.
+     * Modifies this line.
+     */
+    flip(): Line2D;
+    /**
+     * Rotates the line around the center by the given angle in radians.
+     * Modifies this line.
+     * @param radians Positive values rotate counter-clockwise.
+     * @param center
+     */
+    rotate(radians: number, center?: Vec2): Line2D;
+    /**
+     * Move the line by the given vector.
+     * Modifies this line.
+     */
+    translate(value: Point2): Line2D;
+    /**
+     * Move the line to its left by the given amount.
+     * Modifies this line.
+     */
+    translateLeft(amount: number): Line2D;
+    /**
+     * Move the line to its right by the given amount.
+     * Modifies this line.
+     */
+    translateRight(amount: number): Line2D;
+    /**
+     * Returns true when the point is actually inside the (finite) line segment.
+     * https://jsfiddle.net/c06zdxtL/2/
+     * https://stackoverflow.com/questions/6865832/detecting-if-a-point-is-of-a-line-segment/6877674
+     * @param point: Point2
+     */
+    isPointOnLineSection(point: Point2): boolean;
+    /**
+     * Returns true when the point is beside the line **segment** and within the maxDistance.
+     * @param point
+     * @param maxDistance
+     */
+    isPointCloseToAndBesideLineSection(point: Point2, maxDistance: number): boolean;
+    /**
+     * Returns true when the point is beside the line **segment**
+     * @param point
+     */
+    isPointBesideLineSection(point: Point2): boolean;
+    /**
+     * Returns true when the point is on the **infinite** line.
+     * @param point
+     */
+    isPointOnInfiniteLine(point: Point2): boolean;
+    /**
+     * Returns true if other line is collinear and overlaps or at least touching this line.
+     * @param other
+     */
+    isCollinearWithTouchOrOverlap(other: Line2D): boolean;
+    /**
+     * Returns true if there is any overlap between this line and the @other line section.
+     */
+    overlaps(other: Line2D): boolean;
+    /**
+     * Logical AND of this and the other line section.
+     * @param other
+     */
+    getOverlap(other: Line2D): Line2D;
+    /**
+     * Joins a copy of @line with the @other line.
+     * Other must be parallel to this line.
+     * Returns null if there is no overlap
+     * Clones the line, does not modify.
+     * @param line
+     * @param other
+     */
+    static joinLine(line: Line2D, other: Line2D): Line2D;
+    /**
+     * Joins provided lines into several joined lines.
+     * Lines must be parallel for joining.
+     * Clone the lines, does not modify.
+     * @param lines
+     */
+    static joinLines(lines: Line2D[]): Line2D[];
+    /**
+     * Divides the Line3D into a number of segments of the given length.
+     * Clone the line, does not modify.
+     * @param maxSegmentLength number
+     */
+    chunk(maxSegmentLength: number): Line2D[];
+    /**
+     * Returns the closest point parameter on the **infinite** line to the given point.
+     * @param point
+     */
+    closestPointToPointParameterOnInfiniteLine(point: Vector2): number;
+    /**
+     * Returns the closest point on the **infinite** line to the given point.
+     * @param point
+     */
+    closestPointOnInfiniteLine(point: Vector2): Vec2;
+    /**
+     * Returns the closest point on the line **section** to the given point.
+     * @param point
+     */
+    closestPointOnLine(point: Vector2): Vec2;
+    /**
+     * Returns the distance between the **infinite** line and the point.
+     * @param point
+     */
+    distanceToPointOnInfiniteLine(point: Point2): number;
+    /**
+     * Returns lines that are the result of clipping @source line by the @clips.
+     * Clips must be parallel to this line.
+     * Clones the line, does not modify this.
+     * @param source
+     * @param clips
+     */
+    static clipLines(source: Line2D, clips: Line2D[]): Line2D[];
+    /**
+     * Returns the original line section split into two parts, if the line **sections** overlap, otherwise null
+     */
+    splitAtIntersection(other: Line2D, tolerance?: number): Line2D[];
+    /**
+     * If lines **sections** overlap, returns the original line section split into two parts, sorted by length
+     * Else, if the **infinite** lines intersect, returns a new line extended to the intersection point
+     * Otherwise, null if the lines are parallel and do not intersect
+     */
+    splitAtOrExtendToIntersection(other: Line2D): Line2D[];
+    private static order;
+    private static subtractSingle;
+    /**
+     * If other line is not contained within this line, the excess is trimmed.
+     * Does not create a copy. Provided line is modified.
+     * @param lineToTrim
+     */
+    trimExcess(lineToTrim: Line2D): void;
+    /**
+     * If other line is shorter than this, endpoints are moved to extend other
+     * Does not create a copy. Provided line is modified.
+     * @param lineToExtend
+     * @param tolerance
+     */
+    extendToEnds(lineToExtend: Line2D, tolerance: number): void;
+    /**
+     * Returns the intersection point of two lines. The lines are assumed to be infinite.
+     */
+    intersect(other: Line2D): Vec2;
+    /**
+     * Check that the infinite lines intersect and that they are in the specified angle to each other
+     * @param other Line
+     * @param expectedAngleInRads number
+     */
+    hasIntersectionWithAngle(other: Line2D, expectedAngleInRads: number): Vec2;
+    /**
+     * Deep clone of this line
+     */
+    clone(): Line2D;
+    toString(): string;
+    equals(other: Line2D): boolean;
+}