@immugio/three-math-extensions 0.0.13 → 0.0.15

package/src/Line3D.ts

@@ -444,6 +444,64 @@ export class Line3D extends Line3 {
         return this;
     }
 
+    /**
+     * Calculates the intersection between this and `other` line. The lines are assumed to be infinite.
+     * In a lot of cases an actual intersection cannot be calculated due to rounding errors.
+     * Therefore, the intersection calculated by this method comes in a form of the shorted possible line segment connecting the two lines.
+     * Sources:
+     * http://paulbourke.net/geometry/pointlineplane/
+     * https://stackoverflow.com/questions/2316490/the-algorithm-to-find-the-point-of-intersection-of-two-3d-line-segment/2316934#2316934
+     * @param other
+     */
+    public intersect(other: Line3D): Line3D {
+        const p1: Vec3 = this.start.clone();
+        const p2: Vec3 = this.end.clone();
+
+        const p3: Vec3 = other.start.clone();
+        const p4: Vec3 = other.end.clone();
+
+        const p13: Vec3 = p1.clone().sub(p3);
+        const p43: Vec3 = p4.clone().sub(p3);
+
+        if (p43.lengthSq() <= Number.EPSILON) {
+            return null;
+        }
+
+        const p21 = p2.clone().sub(p1);
+        if (p21.lengthSq() <= Number.EPSILON) {
+            return null;
+        }
+
+        const d1343: number = p13.x * p43.x + p13.y * p43.y + p13.z * p43.z;
+        const d4321: number = p43.x * p21.x + p43.y * p21.y + p43.z * p21.z;
+        const d1321: number = p13.x * p21.x + p13.y * p21.y + p13.z * p21.z;
+        const d4343: number = p43.x * p43.x + p43.y * p43.y + p43.z * p43.z;
+        const d2121: number = p21.x * p21.x + p21.y * p21.y + p21.z * p21.z;
+
+        const denominator: number = d2121 * d4343 - d4321 * d4321;
+        if (Math.abs(denominator) <= Number.EPSILON) {
+            return null;
+        }
+        const numerator: number = d1343 * d4321 - d1321 * d4343;
+
+        const mua: number = numerator / denominator;
+        const mub: number = (d1343 + d4321 * (mua)) / d4343;
+
+        const resultSegmentPoint1 = new Vec3(
+            (p1.x + mua * p21.x),
+            (p1.y + mua * p21.y),
+            (p1.z + mua * p21.z)
+        );
+
+        const resultSegmentPoint2 = new Vec3(
+            (p3.x + mub * p43.x),
+            (p3.y + mub * p43.y),
+            (p3.z + mub * p43.z)
+        );
+
+        return new Line3D(resultSegmentPoint1, resultSegmentPoint2);
+    }
+
     /**
      * Project the line to 2D space, Y value is dropped
      */

package/src/Vec2.ts

@@ -3,7 +3,7 @@ import { Vec3 } from "./Vec3";
 import { Point2 } from "./Point2";
 
 /**
- * Vec2 represents a 2D vector. It extends `Vector2` from the `three` library.
+ * Vec2 represents a 2D vector. It extends `Vector2` from the `threejs` library.
  */
 export class Vec2 extends Vector2 {
 
@@ -44,12 +44,12 @@ export class Vec2 extends Vector2 {
     }
 
     /**
-     * Projects this Vec2 instance to a Vec3 instance in 3D space.
-     * @param z - The z value of the new Vec3 instance.
+     * Projects this Vec2 instance to a Vec3 instance in 3D space. Vec2.y becomes Vec3.z. and Vec3.y is provided as an argument.
+     * @param y - The y value of the new Vec3 instance.
      * @returns A new Vec3 instance.
      */
-    public in3DSpace(z: number = 0): Vec3 {
-        return new Vec3(this.x, z, this.y);
+    public in3DSpace(y: number = 0): Vec3 {
+        return new Vec3(this.x, y, this.y);
     }
 
     /**

package/src/Vec3.ts

@@ -2,14 +2,28 @@ import { Vector3 } from "three";
 import { Vec2 } from "./Vec2";
 import { Point3 } from "./Point3";
 
+/**
+ * Vec3 represents a 2D vector. It extends `Vector3` from the `threejs` library.
+ */
 export class Vec3 extends Vector3 {
 
     #target: Vector3;
 
+    /**
+     * Creates a new Vec3 instance from an {x, y, z} object.
+     * @param point - The {x, y, z} instance.
+     * @returns A new Vec3 instance.
+     */
     public static fromPoint(point: Point3): Vec3 {
         return new Vec3(point.x, point.y, point.z);
     }
 
+    /**
+     * Moves this Vec3 instance towards the target Vec3 by the given amount.
+     * @param target - The target Vec3.
+     * @param amount - The distance to move.
+     * @returns This Vec3 instance.
+     */
     public moveTowards(target: Vector3, amount: number): Vec3 {
         if (this.#target === undefined) {
             this.#target = new Vector3();
@@ -21,7 +35,12 @@ export class Vec3 extends Vector3 {
         return this;
     }
 
-    public centerTowards(target: Vector3): Vec3 {
+    /**
+     * Moves this Vec3 instance halfway towards the target Vec3 by the given amount.
+     * @param target - The target Vec3.
+     * @returns This Vec3 instance.
+     */
+    public moveHalfWayTowards(target: Vector3): Vec3 {
         if (this.#target === undefined) {
             this.#target = new Vector3();
         }
@@ -29,41 +48,61 @@ export class Vec3 extends Vector3 {
         return this.moveTowards(target, this.distanceTo(target) / 2);
     }
 
+
+    /**
+     * Adds y amount to this Vec3 instance and return this
+     * @param y
+     */
     public addY(y: number): Vec3 {
         this.y += y;
         return this;
     }
 
+    /**
+     * Adds x amount to this Vec3 instance and return this
+     * @param x
+     */
     public addX(x: number): Vec3 {
         this.x += x;
         return this;
     }
 
-    public scale(p: Vector3): Vec3 {
-        this.x *= p.x;
-        this.y *= p.y;
-        this.z *= p.z;
-        return this;
-    }
-
+    /**
+     * Returns a clone of the point closest to this from the given points.
+     * @param points
+     */
     public closest(...points: Vector3[]): Vec3 {
         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);
     }
 
+    /**
+     * Returns a clone of this Vec3 instance with y and z swapped.
+     */
     public toPointWithFlippedYZ(): Vec3 {
         return new Vec3(this.x, this.z, this.y);
     }
 
+    /**
+     * Projects this Vec3 instance onto 2d plan. Vec3.z becomes Vec2.y and Vec3.y is ignored.
+     */
     public onPlan(): Vec2 {
         return new Vec2(this.x, this.z);
     }
 
+    /**
+     * Get distance to another vector while ignoring the y-axis.
+     * @param point
+     */
     public horizontalDistanceTo(point: Vector3): number {
         return new Vector3(this.x, 0, this.z).distanceTo(new Vector3(point.x, 0, point.z));
     }
 
+    /**
+     * Determines if this Vec2 instance is near the target Vec2.
+     * maxDistance is the maximum distance between the two vectors within which they are considered `near`.
+     */
     public isNear(v: Vector3, maxDistance: number = undefined): boolean {
         if (maxDistance === undefined) {
             return this.equals(v);

package/types/Line2D.d.ts

@@ -213,10 +213,10 @@ export declare class Line2D {
      * @param expectedAngleInRads number
      */
     hasIntersectionWithAngle(other: Line2D, expectedAngleInRads: number): Vec2;
+    equals(other: Line2D): boolean;
     /**
      * Deep clone of this line
      */
     clone(): Line2D;
     toString(): string;
-    equals(other: Line2D): boolean;
 }

package/types/Line3D.d.ts

@@ -135,6 +135,16 @@ export declare class Line3D extends Line3 {
      * @param p
      */
     translate(p: Vector3): this;
+    /**
+     * Calculates the intersection between this and `other` line. The lines are assumed to be infinite.
+     * In a lot of cases an actual intersection cannot be calculated due to rounding errors.
+     * Therefore, the intersection calculated by this method comes in a form of the shorted possible line segment connecting the two lines.
+     * Sources:
+     * http://paulbourke.net/geometry/pointlineplane/
+     * https://stackoverflow.com/questions/2316490/the-algorithm-to-find-the-point-of-intersection-of-two-3d-line-segment/2316934#2316934
+     * @param other
+     */
+    intersect(other: Line3D): Line3D;
     /**
      * Project the line to 2D space, Y value is dropped
      */

package/types/Vec2.d.ts

@@ -2,7 +2,7 @@ import { Vector2 } from "three";
 import { Vec3 } from "./Vec3";
 import { Point2 } from "./Point2";
 /**
- * Vec2 represents a 2D vector. It extends `Vector2` from the `three` library.
+ * Vec2 represents a 2D vector. It extends `Vector2` from the `threejs` library.
  */
 export declare class Vec2 extends Vector2 {
     /**
@@ -25,11 +25,11 @@ export declare class Vec2 extends Vector2 {
      */
     roundIfCloseToInteger(max?: number): this;
     /**
-     * Projects this Vec2 instance to a Vec3 instance in 3D space.
-     * @param z - The z value of the new Vec3 instance.
+     * Projects this Vec2 instance to a Vec3 instance in 3D space. Vec2.y becomes Vec3.z. and Vec3.y is provided as an argument.
+     * @param y - The y value of the new Vec3 instance.
      * @returns A new Vec3 instance.
      */
-    in3DSpace(z?: number): Vec3;
+    in3DSpace(y?: number): Vec3;
     /**
      * Determines if this Vec2 instance is near the target Vec2.
      * maxDistance is the maximum distance between the two vectors within which they are considered `near`.

package/types/Vec3.d.ts

@@ -1,18 +1,62 @@
 import { Vector3 } from "three";
 import { Vec2 } from "./Vec2";
 import { Point3 } from "./Point3";
+/**
+ * Vec3 represents a 2D vector. It extends `Vector3` from the `threejs` library.
+ */
 export declare class Vec3 extends Vector3 {
     #private;
+    /**
+     * Creates a new Vec3 instance from an {x, y, z} object.
+     * @param point - The {x, y, z} instance.
+     * @returns A new Vec3 instance.
+     */
     static fromPoint(point: Point3): Vec3;
+    /**
+     * Moves this Vec3 instance towards the target Vec3 by the given amount.
+     * @param target - The target Vec3.
+     * @param amount - The distance to move.
+     * @returns This Vec3 instance.
+     */
     moveTowards(target: Vector3, amount: number): Vec3;
-    centerTowards(target: Vector3): Vec3;
+    /**
+     * Moves this Vec3 instance halfway towards the target Vec3 by the given amount.
+     * @param target - The target Vec3.
+     * @returns This Vec3 instance.
+     */
+    moveHalfWayTowards(target: Vector3): Vec3;
+    /**
+     * Adds y amount to this Vec3 instance and return this
+     * @param y
+     */
     addY(y: number): Vec3;
+    /**
+     * Adds x amount to this Vec3 instance and return this
+     * @param x
+     */
     addX(x: number): Vec3;
-    scale(p: Vector3): Vec3;
+    /**
+     * Returns a clone of the point closest to this from the given points.
+     * @param points
+     */
     closest(...points: Vector3[]): Vec3;
+    /**
+     * Returns a clone of this Vec3 instance with y and z swapped.
+     */
     toPointWithFlippedYZ(): Vec3;
+    /**
+     * Projects this Vec3 instance onto 2d plan. Vec3.z becomes Vec2.y and Vec3.y is ignored.
+     */
     onPlan(): Vec2;
+    /**
+     * Get distance to another vector while ignoring the y-axis.
+     * @param point
+     */
     horizontalDistanceTo(point: Vector3): number;
+    /**
+     * Determines if this Vec2 instance is near the target Vec2.
+     * maxDistance is the maximum distance between the two vectors within which they are considered `near`.
+     */
     isNear(v: Vector3, maxDistance?: number): boolean;
     clone(): this;
 }