@immugio/three-math-extensions 0.0.3 → 0.0.5

package/src/__tests__/Line3D.spec.ts

@@ -10,6 +10,35 @@ describe("Line3d", () => {
         expect(line.end).toEqual(new Vec3(4, 5, 6));
     });
 
+    it("should create a single line polygon from a 2 points polygon", () => {
+        const start = new Vec3(1, 2, 20);
+        const end = new Vec3(3, 4, 20);
+        const lines = Line3D.fromPolygon([start, end]);
+        expect(lines.length).toEqual(1);
+        expect(lines[0]).toEqual(new Line3D(start, end));
+    });
+
+    it("should create a 2 lines polygon from a 3 points polygon", () => {
+        const p1 = new Vec3(1, 2, 20);
+        const p2 = new Vec3(3, 4, 20);
+        const p3 = new Vec3(5, 2, 20);
+        const lines = Line3D.fromPolygon([p1, p2, p3]);
+        expect(lines.length).toEqual(2);
+        expect(lines[0]).toEqual(new Line3D(p1, p2));
+        expect(lines[1]).toEqual(new Line3D(p2, p3));
+    });
+
+    it("should create a closed 3 lines polygon from a 3 points polygon", () => {
+        const p1 = new Vec3(1, 2, 20);
+        const p2 = new Vec3(3, 4, 20);
+        const p3 = new Vec3(5, 2, 20);
+        const lines = Line3D.fromPolygon([p1, p2, p3], true);
+        expect(lines.length).toEqual(3);
+        expect(lines[0]).toEqual(new Line3D(p1, p2));
+        expect(lines[1]).toEqual(new Line3D(p2, p3));
+        expect(lines[2]).toEqual(new Line3D(p3, p1));
+    });
+
     it("should return the expected center", () => {
         const line = defaultLine();
         expect(line.center).toEqual(new Vec3(0, 0, 0));

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;
+}

package/types/Line3D.d.ts

@@ -0,0 +1,151 @@
+import { Line3, Vector3 } from "three";
+import { Vec3 } from "./Vec3";
+import { Point3 } from "./Point3";
+import { Line2D } from "./Line2D";
+export declare class Line3D extends Line3 {
+    #private;
+    start: Vec3;
+    end: Vec3;
+    constructor(start: Vec3, end: Vec3);
+    static fromPoints(start: Point3, end: Point3): Line3D;
+    /**
+     * 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: Point3[], forceClosedPolygon?: boolean): Line3D[];
+    /**
+     * 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: Line3D, parallelTolerance?: number): Line3D[];
+    /**
+     * 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: Line3D[], distanceTolerance?: number, parallelTolerance?: number): Line3D[];
+    /**
+     * 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: Line3D, distanceTolerance?: number, parallelTolerance?: number): Line3D;
+    /**
+     * Joins provided lines into several joined lines.
+     * Lines must be parallel for joining.
+     * @param lines
+     * @param distanceTolerance
+     * @param parallelTolerance
+     */
+    static joinLines(lines: Line3D[], distanceTolerance?: number, parallelTolerance?: number): Line3D[];
+    /**
+     * Returns true if this line section completely overlaps the @other line section.
+     * @param other
+     * @param tolerance
+     */
+    covers(other: Line3D, tolerance?: number): boolean;
+    /**
+     * Returns true if there is any overlap between this line and the @other line section.
+     * @param other
+     * @param distanceTolerance
+     * @param parallelTolerance
+     */
+    overlaps(other: Line3D, distanceTolerance?: number, parallelTolerance?: number): boolean;
+    /**
+     * Returns this line's length.
+     */
+    get length(): number;
+    /**
+     * Set the length of this line. Center and direction remain unchanged.
+     * @param length
+     */
+    setLength(length: number): this;
+    /**
+     * Returns the direction of this line.
+     */
+    get direction(): Vec3;
+    /**
+     * Returns the center of this line
+     */
+    get center(): Vec3;
+    /**
+     * Set the center of the line to the provided point. Length and direction remain unchanged.
+     * @param value
+     */
+    setCenter(value: Vector3): this;
+    /** Returns the start and end points of the line as an array. */
+    get endpoints(): Vec3[];
+    /**
+     * Check that this line section contains provided point.
+     * @param p
+     * @param tolerance
+     */
+    containsPoint(p: Vector3, tolerance?: number): boolean;
+    /**
+     * Distance from this line to provided point.
+     * @param p
+     * @param clampToLine
+     */
+    distanceToPoint(p: Vector3, clampToLine?: boolean): number;
+    /**
+     * 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: Line3D, tolerance?: number): Line3D;
+    /**
+     * Check if @other is parallel to this line.
+     * @param other
+     * @param tolerance
+     */
+    isParallelTo(other: Line3D, tolerance?: number): boolean;
+    resize(amount: number): this;
+    moveStartPoint(amount: number): Line3D;
+    moveEndPoint(amount: number): Line3D;
+    /**
+     * 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: Line3D, clampToLine: boolean): Line3D;
+    /**
+     * Divides the Line3D into a number of segments of the given length.
+     * @param maxSegmentLength number
+     */
+    chunk(maxSegmentLength: number): Line3D[];
+    /**
+     * 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
+     */
+    private movePointOnThisLine;
+    /**
+     * Move this line by the given vector.
+     * @param p
+     */
+    translate(p: Vector3): this;
+    /**
+     * Project the line to 2D space, Y value is dropped
+     */
+    onPlan(): Line2D;
+    /**
+     * Equals with tolerance
+     */
+    equals(other: Line3D, tolerance?: number): boolean;
+    /**
+     * Deep clone of this line
+     */
+    clone(): this;
+    toString(): string;
+}

package/types/Point2.d.ts

@@ -0,0 +1,4 @@
+export interface Point2 {
+    x: number;
+    y: number;
+}

package/types/Point3.d.ts

@@ -0,0 +1,5 @@
+export interface Point3 {
+    x: number;
+    y: number;
+    z: number;
+}

package/types/Vec2.d.ts

@@ -0,0 +1,8 @@
+import { Vector2 } from "three";
+import { Vec3 } from "./Vec3";
+import { Point2 } from "./Point2";
+export declare class Vec2 extends Vector2 {
+    static fromPoint(point: Point2): Vec2;
+    roundIfCloseToInteger(max?: number): this;
+    in3DSpace(z?: number): Vec3;
+}

package/types/Vec3.d.ts

@@ -0,0 +1,17 @@
+import { Vector3 } from "three";
+import { Vec2 } from "./Vec2";
+import { Point3 } from "./Point3";
+export declare class Vec3 extends Vector3 {
+    #private;
+    static fromPoint(point: Point3): Vec3;
+    moveTowards(target: Vector3, amount: number): Vec3;
+    centerTowards(target: Vector3): Vec3;
+    addY(y: number): Vec3;
+    addX(x: number): Vec3;
+    scale(p: Vector3): Vec3;
+    closest(...points: Vector3[]): Vec3;
+    toPointWithFlippedYZ(): Vec3;
+    onPlan(): Vec2;
+    horizontalDistanceTo(point: Vector3): number;
+    clone(): this;
+}

package/types/index.d.ts

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