@immugio/three-math-extensions 0.0.13 → 0.0.15

package/docs/classes/Vec2.md

@@ -0,0 +1,167 @@
+[@immugio/three-math-extensions](../README.md) / [Exports](../modules.md) / Vec2
+
+# Class: Vec2
+
+Vec2 represents a 2D vector. It extends `Vector2` from the `threejs` library.
+
+## Hierarchy
+
+- `Vector2`
+
+  ↳ **`Vec2`**
+
+## Table of contents
+
+### Constructors
+
+- [constructor](Vec2.md#constructor)
+
+### Methods
+
+- [in3DSpace](Vec2.md#in3dspace)
+- [isNear](Vec2.md#isnear)
+- [moveTowards](Vec2.md#movetowards)
+- [roundIfCloseToInteger](Vec2.md#roundifclosetointeger)
+- [fromPoint](Vec2.md#frompoint)
+
+## Constructors
+
+### constructor
+
+• **new Vec2**(`x?`, `y?`)
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `x?` | `number` |
+| `y?` | `number` |
+
+#### Inherited from
+
+Vector2.constructor
+
+#### Defined in
+
+node_modules/@types/three/src/math/Vector2.d.ts:140
+
+## Methods
+
+### in3DSpace
+
+▸ **in3DSpace**(`y?`): [`Vec3`](Vec3.md)
+
+Projects this Vec2 instance to a Vec3 instance in 3D space. Vec2.y becomes Vec3.z. and Vec3.y is provided as an argument.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `y` | `number` | `0` | The y value of the new Vec3 instance. |
+
+#### Returns
+
+[`Vec3`](Vec3.md)
+
+A new Vec3 instance.
+
+#### Defined in
+
+[src/Vec2.ts:51](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec2.ts#L51)
+
+___
+
+### isNear
+
+▸ **isNear**(`v`, `maxDistance?`): `boolean`
+
+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`.
+
+#### Parameters
+
+| Name | Type | Default value |
+| :------ | :------ | :------ |
+| `v` | `Vector2` | `undefined` |
+| `maxDistance` | `number` | `undefined` |
+
+#### Returns
+
+`boolean`
+
+#### Defined in
+
+[src/Vec2.ts:59](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec2.ts#L59)
+
+___
+
+### moveTowards
+
+▸ **moveTowards**(`target`, `amount`): [`Vec2`](Vec2.md)
+
+Moves this Vec2 instance towards the target Vec2 by the given amount.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `target` | `Vector2` | The target Vec2. |
+| `amount` | `number` | The distance to move. |
+
+#### Returns
+
+[`Vec2`](Vec2.md)
+
+This Vec2 instance.
+
+#### Defined in
+
+[src/Vec2.ts:25](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec2.ts#L25)
+
+___
+
+### roundIfCloseToInteger
+
+▸ **roundIfCloseToInteger**(`max?`): [`Vec2`](Vec2.md)
+
+Rounds the x and y values of this Vec2 instance if they are close to an integer value.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `max` | `number` | `0.000000000001` | The maximum difference between the value and the nearest integer. |
+
+#### Returns
+
+[`Vec2`](Vec2.md)
+
+This Vec2 instance.
+
+#### Defined in
+
+[src/Vec2.ts:36](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec2.ts#L36)
+
+___
+
+### fromPoint
+
+▸ `Static` **fromPoint**(`point`): [`Vec2`](Vec2.md)
+
+Creates a new Vec2 instance from an {x, y} object.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `point` | `Point2` | The {x, y} instance. |
+
+#### Returns
+
+[`Vec2`](Vec2.md)
+
+A new Vec2 instance.
+
+#### Defined in
+
+[src/Vec2.ts:15](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec2.ts#L15)

package/docs/classes/Vec3.md

@@ -0,0 +1,288 @@
+[@immugio/three-math-extensions](../README.md) / [Exports](../modules.md) / Vec3
+
+# Class: Vec3
+
+Vec3 represents a 2D vector. It extends `Vector3` from the `threejs` library.
+
+## Hierarchy
+
+- `Vector3`
+
+  ↳ **`Vec3`**
+
+## Table of contents
+
+### Constructors
+
+- [constructor](Vec3.md#constructor)
+
+### Methods
+
+- [addX](Vec3.md#addx)
+- [addY](Vec3.md#addy)
+- [clone](Vec3.md#clone)
+- [closest](Vec3.md#closest)
+- [horizontalDistanceTo](Vec3.md#horizontaldistanceto)
+- [isNear](Vec3.md#isnear)
+- [moveHalfWayTowards](Vec3.md#movehalfwaytowards)
+- [moveTowards](Vec3.md#movetowards)
+- [onPlan](Vec3.md#onplan)
+- [toPointWithFlippedYZ](Vec3.md#topointwithflippedyz)
+- [fromPoint](Vec3.md#frompoint)
+
+## Constructors
+
+### constructor
+
+• **new Vec3**(`x?`, `y?`, `z?`)
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `x?` | `number` |
+| `y?` | `number` |
+| `z?` | `number` |
+
+#### Inherited from
+
+Vector3.constructor
+
+#### Defined in
+
+node_modules/@types/three/src/math/Vector3.d.ts:26
+
+## Methods
+
+### addX
+
+▸ **addX**(`x`): [`Vec3`](Vec3.md)
+
+Adds x amount to this Vec3 instance and return this
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `x` | `number` |
+
+#### Returns
+
+[`Vec3`](Vec3.md)
+
+#### Defined in
+
+[src/Vec3.ts:65](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec3.ts#L65)
+
+___
+
+### addY
+
+▸ **addY**(`y`): [`Vec3`](Vec3.md)
+
+Adds y amount to this Vec3 instance and return this
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `y` | `number` |
+
+#### Returns
+
+[`Vec3`](Vec3.md)
+
+#### Defined in
+
+[src/Vec3.ts:56](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec3.ts#L56)
+
+___
+
+### clone
+
+▸ **clone**(): [`Vec3`](Vec3.md)
+
+#### Returns
+
+[`Vec3`](Vec3.md)
+
+#### Overrides
+
+Vector3.clone
+
+#### Defined in
+
+[src/Vec3.ts:114](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec3.ts#L114)
+
+___
+
+### closest
+
+▸ **closest**(`...points`): [`Vec3`](Vec3.md)
+
+Returns a clone of the point closest to this from the given points.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `...points` | `Vector3`[] |
+
+#### Returns
+
+[`Vec3`](Vec3.md)
+
+#### Defined in
+
+[src/Vec3.ts:74](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec3.ts#L74)
+
+___
+
+### horizontalDistanceTo
+
+▸ **horizontalDistanceTo**(`point`): `number`
+
+Get distance to another vector while ignoring the y-axis.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `point` | `Vector3` |
+
+#### Returns
+
+`number`
+
+#### Defined in
+
+[src/Vec3.ts:98](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec3.ts#L98)
+
+___
+
+### isNear
+
+▸ **isNear**(`v`, `maxDistance?`): `boolean`
+
+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`.
+
+#### Parameters
+
+| Name | Type | Default value |
+| :------ | :------ | :------ |
+| `v` | `Vector3` | `undefined` |
+| `maxDistance` | `number` | `undefined` |
+
+#### Returns
+
+`boolean`
+
+#### Defined in
+
+[src/Vec3.ts:106](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec3.ts#L106)
+
+___
+
+### moveHalfWayTowards
+
+▸ **moveHalfWayTowards**(`target`): [`Vec3`](Vec3.md)
+
+Moves this Vec3 instance halfway towards the target Vec3 by the given amount.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `target` | `Vector3` | The target Vec3. |
+
+#### Returns
+
+[`Vec3`](Vec3.md)
+
+This Vec3 instance.
+
+#### Defined in
+
+[src/Vec3.ts:43](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec3.ts#L43)
+
+___
+
+### moveTowards
+
+▸ **moveTowards**(`target`, `amount`): [`Vec3`](Vec3.md)
+
+Moves this Vec3 instance towards the target Vec3 by the given amount.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `target` | `Vector3` | The target Vec3. |
+| `amount` | `number` | The distance to move. |
+
+#### Returns
+
+[`Vec3`](Vec3.md)
+
+This Vec3 instance.
+
+#### Defined in
+
+[src/Vec3.ts:27](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec3.ts#L27)
+
+___
+
+### onPlan
+
+▸ **onPlan**(): [`Vec2`](Vec2.md)
+
+Projects this Vec3 instance onto 2d plan. Vec3.z becomes Vec2.y and Vec3.y is ignored.
+
+#### Returns
+
+[`Vec2`](Vec2.md)
+
+#### Defined in
+
+[src/Vec3.ts:90](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec3.ts#L90)
+
+___
+
+### toPointWithFlippedYZ
+
+▸ **toPointWithFlippedYZ**(): [`Vec3`](Vec3.md)
+
+Returns a clone of this Vec3 instance with y and z swapped.
+
+#### Returns
+
+[`Vec3`](Vec3.md)
+
+#### Defined in
+
+[src/Vec3.ts:83](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec3.ts#L83)
+
+___
+
+### fromPoint
+
+▸ `Static` **fromPoint**(`point`): [`Vec3`](Vec3.md)
+
+Creates a new Vec3 instance from an {x, y, z} object.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `point` | `Point3` | The {x, y, z} instance. |
+
+#### Returns
+
+[`Vec3`](Vec3.md)
+
+A new Vec3 instance.
+
+#### Defined in
+
+[src/Vec3.ts:17](https://github.com/Immugio/three-math-extensions/blob/70c8d5e/src/Vec3.ts#L17)

package/docs/modules.md

@@ -0,0 +1,12 @@
+[@immugio/three-math-extensions](README.md) / Exports
+
+# @immugio/three-math-extensions
+
+## Table of contents
+
+### Classes
+
+- [Line2D](classes/Line2D.md)
+- [Line3D](classes/Line3D.md)
+- [Vec2](classes/Vec2.md)
+- [Vec3](classes/Vec3.md)

package/esm/Line2D.js

@@ -547,6 +547,9 @@ export class Line2D {
         }
         return null;
     }
+    equals(other) {
+        return !!other && this.start.equals(other.start) && this.end.equals(other.end);
+    }
     /**
      * Deep clone of this line
      */
@@ -556,7 +559,4 @@ export 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);
-    }
 }

package/esm/Line3D.js

@@ -364,6 +364,45 @@ export class Line3D extends 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((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/esm/Vec2.js

@@ -1,7 +1,7 @@
 import { Vector2 } from "three";
 import { Vec3 } from "./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.
  */
 export class Vec2 extends Vector2 {
     /**
@@ -38,12 +38,12 @@ export class Vec2 extends 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(this.x, z, this.y);
+    in3DSpace(y = 0) {
+        return new Vec3(this.x, y, this.y);
     }
     /**
      * Determines if this Vec2 instance is near the target Vec2.

package/esm/Vec3.js

@@ -1,10 +1,24 @@
 import { Vector3 } from "three";
 import { Vec2 } from "./Vec2";
+/**
+ * Vec3 represents a 2D vector. It extends `Vector3` from the `threejs` library.
+ */
 export class Vec3 extends 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 Vector3();
@@ -13,40 +27,65 @@ export class Vec3 extends 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 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(this.x, this.z);
     }
+    /**
+     * Get distance to another vector while ignoring the y-axis.
+     * @param point
+     */
     horizontalDistanceTo(point) {
         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`.
+     */
     isNear(v, maxDistance = undefined) {
         if (maxDistance === undefined) {
             return this.equals(v);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immugio/three-math-extensions",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Set of utilities for 2d and 3d line math built on top of three.js",
   "author": "Jan Mikeska <janmikeska@gmail.com>",
   "license": "ISC",
@@ -40,6 +40,8 @@
     "jest": "^29.2.2",
     "rimraf": "^3.0.2",
     "ts-jest": "^29.0.0",
+    "typedoc": "^0.23.23",
+    "typedoc-plugin-markdown": "^3.14.0",
     "typescript": "4.7.4"
   },
   "peerDependencies": {

package/src/Line2D.ts

@@ -644,6 +644,10 @@ export class Line2D {
         return null;
     }
 
+    public equals(other: Line2D): boolean {
+        return !!other && this.start.equals(other.start) && this.end.equals(other.end);
+    }
+
     /**
      * Deep clone of this line
      */
@@ -654,8 +658,4 @@ export class Line2D {
     public toString(): string {
         return `Line(${this.start.x}, ${this.start.y}, ${this.end.x}, ${this.end.y})`;
     }
-
-    public equals(other: Line2D): boolean {
-        return !!other && this.start.equals(other.start) && this.end.equals(other.end);
-    }
 }