@immugio/three-math-extensions 0.0.13 → 0.0.15

package/CHANGELOG.md

@@ -7,7 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-## [0.0.13](https://github.com/Immugio/three-math-extensions/compare/0.0.12...0.0.13)
+## [0.0.15](https://github.com/Immugio/three-math-extensions/compare/0.0.14...0.0.15)
+
+### Commits
+
+- Add intersect method to Line3D [`6fe47de`](https://github.com/Immugio/three-math-extensions/commit/6fe47de7caaa1807b47a4363e551510c463757d7)
+
+## [0.0.14](https://github.com/Immugio/three-math-extensions/compare/0.0.13...0.0.14) - 2022-12-26
+
+### Commits
+
+- Generate documentation using TSDoc [`304c3a8`](https://github.com/Immugio/three-math-extensions/commit/304c3a84b5dcc49183db57083f550d134ae641b2)
+- Improve documentation for Vec2 and Vec3 [`6a2373d`](https://github.com/Immugio/three-math-extensions/commit/6a2373d8b6754a87720dcaea5d98336bfa7bc5b5)
+- Clean up documentation [`70c8d5e`](https://github.com/Immugio/three-math-extensions/commit/70c8d5efe8b7095d7a03af637df3af5d46615293)
+- Documentation improvements [`160db8b`](https://github.com/Immugio/three-math-extensions/commit/160db8ba6d6e5eb63a4e91ed9c40efd6fa70181a)
+- Documentation improvements [`2f3e676`](https://github.com/Immugio/three-math-extensions/commit/2f3e6768b3b0139b60688fc151a4084f15566f8d)
+- Revert npm ignore [`590b26a`](https://github.com/Immugio/three-math-extensions/commit/590b26a9e57fc41466b51e711f3f5c648e2d56ed)
+
+## [0.0.13](https://github.com/Immugio/three-math-extensions/compare/0.0.12...0.0.13) - 2022-12-21
 
 ### Commits
 

package/HowToRelease.txt

@@ -0,0 +1,13 @@
+Update documentation:
+npx typedoc --plugin typedoc-plugin-markdown --out docs src/index.ts --excludeExternals --excludeProtected --excludePrivate --githubPages false
+
+Before release
+- Ensure clean working directory
+- Ensure that the last release commit has a tag that matches the latest release number in the format "0.0.11". This step should have been completed in the previous release. It's only mentioned here in case it's for any reason missing.
+- Run "prerelease" script to verify that the code builds and the tests pass
+
+Release:
+- Bump up version in package.json e.g. "0.0.11" -> "0.0.12"
+- Run "version" script, it should add the new commits since the last release into `CHANGELOG.md`
+- Commit and push the changes in `package.json` and `CHANGELOG.md`, ideally, call the commit as the new release e.g. "`0.0.12`". This is not necessary but makes it easier to find
+- **Tag the commit**  the new version number. In this example "`0.0.12`" and push. This is required for CI to build and publish to npm.

package/README.md

@@ -2,10 +2,7 @@
 
 [![Build](https://github.com/Immugio/three-math-extensions/actions/workflows/build.yml/badge.svg)](https://github.com/Immugio/three-math-extensions/actions/workflows/build.yml)
 
-### How to release:
-- Commit and push all changes for this release.
-- Make sure that the last release commit has a tag that matches the latest release number in the format "0.0.11". This step should have been completed in the previous release. It's only mentioned here in case it's for any reason missing.
-- Bump up version in package.json e.g. "0.0.11" -> "0.0.12"
-- Run "version" script, it should add the new commits since the last release into `CHANGELOG.md`
-- Commit and push the changes in `package.json` and `CHANGELOG.md`, ideally, call the commit as the new release e.g. "`0.0.12`". This is not necessary but makes it easier to find
-- NOW THE CRITICAL PART - **tag the commit** with the new version number. In this example "`0.0.12`" and push. This is required for CI to build and release and publish to npm.
+- [Line2D](docs/classes/Line2D.md)
+- [Line3D](docs/classes/Line3D.md)
+- [Vec2](docs/classes/Vec2.md)
+- [Vec3](docs/classes/Vec3.md)

package/cjs/Line2D.js

@@ -550,6 +550,9 @@ class Line2D {
         }
         return null;
     }
+    equals(other) {
+        return !!other && this.start.equals(other.start) && this.end.equals(other.end);
+    }
     /**
      * Deep clone of this line
      */
@@ -559,8 +562,5 @@ class Line2D {
     toString() {
         return `Line(${this.start.x}, ${this.start.y}, ${this.end.x}, ${this.end.y})`;
     }
-    equals(other) {
-        return !!other && this.start.equals(other.start) && this.end.equals(other.end);
-    }
 }
 exports.Line2D = Line2D;

package/cjs/Line3D.js

@@ -367,6 +367,45 @@ class Line3D extends three_1.Line3 {
         this.end.add(p);
         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
+     */
+    intersect(other) {
+        const p1 = this.start.clone();
+        const p2 = this.end.clone();
+        const p3 = other.start.clone();
+        const p4 = other.end.clone();
+        const p13 = p1.clone().sub(p3);
+        const p43 = 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 = p13.x * p43.x + p13.y * p43.y + p13.z * p43.z;
+        const d4321 = p43.x * p21.x + p43.y * p21.y + p43.z * p21.z;
+        const d1321 = p13.x * p21.x + p13.y * p21.y + p13.z * p21.z;
+        const d4343 = p43.x * p43.x + p43.y * p43.y + p43.z * p43.z;
+        const d2121 = p21.x * p21.x + p21.y * p21.y + p21.z * p21.z;
+        const denominator = d2121 * d4343 - d4321 * d4321;
+        if (Math.abs(denominator) <= Number.EPSILON) {
+            return null;
+        }
+        const numerator = d1343 * d4321 - d1321 * d4343;
+        const mua = numerator / denominator;
+        const mub = (d1343 + d4321 * (mua)) / d4343;
+        const resultSegmentPoint1 = new Vec3_1.Vec3((p1.x + mua * p21.x), (p1.y + mua * p21.y), (p1.z + mua * p21.z));
+        const resultSegmentPoint2 = new Vec3_1.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/cjs/Vec2.js

@@ -4,7 +4,7 @@ exports.Vec2 = void 0;
 const three_1 = require("three");
 const Vec3_1 = require("./Vec3");
 /**
- * Vec2 represents a 2D vector. It extends `Vector2` from the `three` library.
+ * Vec2 represents a 2D vector. It extends `Vector2` from the `threejs` library.
  */
 class Vec2 extends three_1.Vector2 {
     /**
@@ -41,12 +41,12 @@ class Vec2 extends three_1.Vector2 {
         return 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 = 0) {
-        return new Vec3_1.Vec3(this.x, z, this.y);
+    in3DSpace(y = 0) {
+        return new Vec3_1.Vec3(this.x, y, this.y);
     }
     /**
      * Determines if this Vec2 instance is near the target Vec2.

package/cjs/Vec3.js

@@ -3,11 +3,25 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Vec3 = void 0;
 const three_1 = require("three");
 const Vec2_1 = require("./Vec2");
+/**
+ * Vec3 represents a 2D vector. It extends `Vector3` from the `threejs` library.
+ */
 class Vec3 extends three_1.Vector3 {
     #target;
+    /**
+     * 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) {
         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.
+     */
     moveTowards(target, amount) {
         if (this.#target === undefined) {
             this.#target = new three_1.Vector3();
@@ -16,40 +30,65 @@ class Vec3 extends three_1.Vector3 {
         this.add(this.#target.sub(this).normalize().multiplyScalar(amount));
         return this;
     }
-    centerTowards(target) {
+    /**
+     * Moves this Vec3 instance halfway towards the target Vec3 by the given amount.
+     * @param target - The target Vec3.
+     * @returns This Vec3 instance.
+     */
+    moveHalfWayTowards(target) {
         if (this.#target === undefined) {
             this.#target = new three_1.Vector3();
         }
         return this.moveTowards(target, this.distanceTo(target) / 2);
     }
+    /**
+     * Adds y amount to this Vec3 instance and return this
+     * @param y
+     */
     addY(y) {
         this.y += y;
         return this;
     }
+    /**
+     * Adds x amount to this Vec3 instance and return this
+     * @param x
+     */
     addX(x) {
         this.x += x;
         return this;
     }
-    scale(p) {
-        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
+     */
     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);
     }
+    /**
+     * Returns a clone of this Vec3 instance with y and z swapped.
+     */
     toPointWithFlippedYZ() {
         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.
+     */
     onPlan() {
         return new Vec2_1.Vec2(this.x, this.z);
     }
+    /**
+     * Get distance to another vector while ignoring the y-axis.
+     * @param point
+     */
     horizontalDistanceTo(point) {
         return new three_1.Vector3(this.x, 0, this.z).distanceTo(new three_1.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`.
+     */
     isNear(v, maxDistance = undefined) {
         if (maxDistance === undefined) {
             return this.equals(v);

package/docs/README.md

@@ -0,0 +1,5 @@
+@immugio/three-math-extensions / [Exports](modules.md)
+
+# Set of utilities for 2d and 3d line math built on top of three.js
+
+[![Build](https://github.com/Immugio/three-math-extensions/actions/workflows/build.yml/badge.svg)](https://github.com/Immugio/three-math-extensions/actions/workflows/build.yml)