@immugio/three-math-extensions 0.2.4 → 0.2.6

package/docs/classes/Vec2.md

@@ -22,6 +22,7 @@ Vec2 represents a 2D vector. It extends `Vector2` from the `threejs` library.
 - [isNear](Vec2.md#isnear)
 - [moveTowards](Vec2.md#movetowards)
 - [roundIfCloseToInteger](Vec2.md#roundifclosetointeger)
+- [signedAngle](Vec2.md#signedangle)
 - [fromPoint](Vec2.md#frompoint)
 
 ## Constructors
@@ -67,7 +68,7 @@ A new Vec3 instance.
 
 #### Defined in
 
-[src/Vec2.ts:51](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec2.ts#L51)
+[src/Vec2.ts:52](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec2.ts#L52)
 
 ___
 
@@ -91,7 +92,7 @@ maxDistance is the maximum distance between the two vectors within which they ar
 
 #### Defined in
 
-[src/Vec2.ts:59](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec2.ts#L59)
+[src/Vec2.ts:60](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec2.ts#L60)
 
 ___
 
@@ -116,7 +117,7 @@ This Vec2 instance.
 
 #### Defined in
 
-[src/Vec2.ts:25](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec2.ts#L25)
+[src/Vec2.ts:26](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec2.ts#L26)
 
 ___
 
@@ -140,7 +141,23 @@ This Vec2 instance.
 
 #### Defined in
 
-[src/Vec2.ts:36](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec2.ts#L36)
+[src/Vec2.ts:37](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec2.ts#L37)
+
+___
+
+### signedAngle
+
+▸ **signedAngle**(): `number`
+
+Returns the angle between this vector and positive x-axis, the return value is between 0 and 2PI
+
+#### Returns
+
+`number`
+
+#### Defined in
+
+[src/Vec2.ts:71](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec2.ts#L71)
 
 ___
 
@@ -154,7 +171,7 @@ Creates a new Vec2 instance from an {x, y} object.
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `point` | `Point2` | The {x, y} instance. |
+| `point` | [`Point2`](../interfaces/Point2.md) | The {x, y} instance. |
 
 #### Returns
 
@@ -164,4 +181,4 @@ A new Vec2 instance.
 
 #### Defined in
 
-[src/Vec2.ts:15](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec2.ts#L15)
+[src/Vec2.ts:16](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec2.ts#L16)

package/docs/classes/Vec3.md

@@ -72,7 +72,7 @@ Adds x amount to this Vec3 instance and return this
 
 #### Defined in
 
-[src/Vec3.ts:65](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec3.ts#L65)
+[src/Vec3.ts:65](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec3.ts#L65)
 
 ___
 
@@ -94,7 +94,7 @@ Adds y amount to this Vec3 instance and return this
 
 #### Defined in
 
-[src/Vec3.ts:56](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec3.ts#L56)
+[src/Vec3.ts:56](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec3.ts#L56)
 
 ___
 
@@ -112,7 +112,7 @@ Vector3.clone
 
 #### Defined in
 
-[src/Vec3.ts:114](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec3.ts#L114)
+[src/Vec3.ts:114](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec3.ts#L114)
 
 ___
 
@@ -134,7 +134,7 @@ Returns a clone of the point closest to this from the given points.
 
 #### Defined in
 
-[src/Vec3.ts:74](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec3.ts#L74)
+[src/Vec3.ts:74](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec3.ts#L74)
 
 ___
 
@@ -156,7 +156,7 @@ Get distance to another vector while ignoring the y-axis.
 
 #### Defined in
 
-[src/Vec3.ts:98](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec3.ts#L98)
+[src/Vec3.ts:98](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec3.ts#L98)
 
 ___
 
@@ -180,7 +180,7 @@ maxDistance is the maximum distance between the two vectors within which they ar
 
 #### Defined in
 
-[src/Vec3.ts:106](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec3.ts#L106)
+[src/Vec3.ts:106](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec3.ts#L106)
 
 ___
 
@@ -204,7 +204,7 @@ This Vec3 instance.
 
 #### Defined in
 
-[src/Vec3.ts:43](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec3.ts#L43)
+[src/Vec3.ts:43](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec3.ts#L43)
 
 ___
 
@@ -229,7 +229,7 @@ This Vec3 instance.
 
 #### Defined in
 
-[src/Vec3.ts:27](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec3.ts#L27)
+[src/Vec3.ts:27](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec3.ts#L27)
 
 ___
 
@@ -245,7 +245,7 @@ Projects this Vec3 instance onto 2d plan. Vec3.z becomes Vec2.y and Vec3.y is ig
 
 #### Defined in
 
-[src/Vec3.ts:90](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec3.ts#L90)
+[src/Vec3.ts:90](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec3.ts#L90)
 
 ___
 
@@ -261,7 +261,7 @@ Returns a clone of this Vec3 instance with y and z swapped.
 
 #### Defined in
 
-[src/Vec3.ts:83](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec3.ts#L83)
+[src/Vec3.ts:83](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec3.ts#L83)
 
 ___
 
@@ -275,7 +275,7 @@ Creates a new Vec3 instance from an {x, y, z} object.
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `point` | `Point3` | The {x, y, z} instance. |
+| `point` | [`Point3`](../interfaces/Point3.md) | The {x, y, z} instance. |
 
 #### Returns
 
@@ -285,4 +285,4 @@ A new Vec3 instance.
 
 #### Defined in
 
-[src/Vec3.ts:17](https://github.com/Immugio/three-math-extensions/blob/c004965/src/Vec3.ts#L17)
+[src/Vec3.ts:17](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Vec3.ts#L17)

package/docs/interfaces/Point2.md

@@ -0,0 +1,30 @@
+[@immugio/three-math-extensions](../README.md) / [Exports](../modules.md) / Point2
+
+# Interface: Point2
+
+## Table of contents
+
+### Properties
+
+- [x](Point2.md#x)
+- [y](Point2.md#y)
+
+## Properties
+
+### x
+
+• **x**: `number`
+
+#### Defined in
+
+[src/Point2.ts:2](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Point2.ts#L2)
+
+___
+
+### y
+
+• **y**: `number`
+
+#### Defined in
+
+[src/Point2.ts:3](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Point2.ts#L3)

package/docs/interfaces/Point3.md

@@ -0,0 +1,41 @@
+[@immugio/three-math-extensions](../README.md) / [Exports](../modules.md) / Point3
+
+# Interface: Point3
+
+## Table of contents
+
+### Properties
+
+- [x](Point3.md#x)
+- [y](Point3.md#y)
+- [z](Point3.md#z)
+
+## Properties
+
+### x
+
+• **x**: `number`
+
+#### Defined in
+
+[src/Point3.ts:2](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Point3.ts#L2)
+
+___
+
+### y
+
+• **y**: `number`
+
+#### Defined in
+
+[src/Point3.ts:3](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Point3.ts#L3)
+
+___
+
+### z
+
+• **z**: `number`
+
+#### Defined in
+
+[src/Point3.ts:4](https://github.com/Immugio/three-math-extensions/blob/151f214/src/Point3.ts#L4)

package/docs/modules.md

@@ -14,3 +14,71 @@
 - [Size2](classes/Size2.md)
 - [Vec2](classes/Vec2.md)
 - [Vec3](classes/Vec3.md)
+
+### Interfaces
+
+- [Point2](interfaces/Point2.md)
+- [Point3](interfaces/Point3.md)
+
+### Variables
+
+- [TwoPI](modules.md#twopi)
+
+### Functions
+
+- [normalizeAngleDegrees](modules.md#normalizeangledegrees)
+- [normalizeAngleRadians](modules.md#normalizeangleradians)
+
+## Variables
+
+### TwoPI
+
+• `Const` **TwoPI**: `number`
+
+#### Defined in
+
+[src/MathConstants.ts:1](https://github.com/Immugio/three-math-extensions/blob/151f214/src/MathConstants.ts#L1)
+
+## Functions
+
+### normalizeAngleDegrees
+
+▸ **normalizeAngleDegrees**(`angle`): `number`
+
+Normalizes an angle in degrees to the range [0, 360].
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `angle` | `number` | in degrees |
+
+#### Returns
+
+`number`
+
+#### Defined in
+
+[src/normalizeAngleDegrees.ts:5](https://github.com/Immugio/three-math-extensions/blob/151f214/src/normalizeAngleDegrees.ts#L5)
+
+___
+
+### normalizeAngleRadians
+
+▸ **normalizeAngleRadians**(`angle`): `number`
+
+Normalize an angle in radians to the range of 0 to 2π.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `angle` | `number` | in radians |
+
+#### Returns
+
+`number`
+
+#### Defined in
+
+[src/normalizeAngleRadians.ts:7](https://github.com/Immugio/three-math-extensions/blob/151f214/src/normalizeAngleRadians.ts#L7)

package/esm/Line2D.js

@@ -1,5 +1,8 @@
 import { Vector2 } from "three";
 import { Vec2 } from "./Vec2";
+import { MathUtils } from "three";
+const _startP = /*@__PURE__*/ new Vec2();
+const _startEnd = /*@__PURE__*/ new Vec2();
 export class Line2D {
     start;
     end;
@@ -326,34 +329,28 @@ export class Line2D {
         return result;
     }
     /**
-     * Returns the closest point parameter on the **infinite** line to the given point.
+     * Returns the closest point on the line to the given point.
      * @param point
+     * @param clampToLine boolean (optional)
+     * @param target Vec2 (optional)
      */
-    closestPointToPointParameterOnInfiniteLine(point) {
-        const startP = new Vec2().subVectors(point, this.start);
-        const startEnd = new Vec2().subVectors(this.end, this.start);
-        const startEnd2 = startEnd.dot(startEnd);
-        const startEnd_startP = startEnd.dot(startP);
-        return startEnd_startP / startEnd2;
+    closestPointToPoint(point, clampToLine, target) {
+        const t = this.closestPointToPointParameter(point, clampToLine);
+        return this.delta(target || new Vec2()).multiplyScalar(t).add(this.start);
     }
-    /**
-     * Returns the closest point on the **infinite** line to the given point.
-     * @param point
-     */
-    closestPointOnInfiniteLine(point) {
-        const t = this.closestPointToPointParameterOnInfiniteLine(point);
-        return new Vec2().subVectors(this.end, this.start).multiplyScalar(t).add(this.start);
+    delta(target) {
+        return target.subVectors(this.end, this.start);
     }
-    /**
-     * Returns the closest point on the line **section** to the given point.
-     * @param point
-     */
-    closestPointOnLine(point) {
-        const closestPoint = this.closestPointOnInfiniteLine(point);
-        if (this.isPointOnLineSection(closestPoint)) {
-            return closestPoint;
+    closestPointToPointParameter(point, clampToLine) {
+        _startP.subVectors(point, this.start);
+        _startEnd.subVectors(this.end, this.start);
+        const startEnd2 = _startEnd.dot(_startEnd);
+        const startEnd_startP = _startEnd.dot(_startP);
+        let t = startEnd_startP / startEnd2;
+        if (clampToLine) {
+            t = MathUtils.clamp(t, 0, 1);
         }
-        return closestPoint.distanceTo(this.start) < closestPoint.distanceTo(this.end) ? this.start : this.end;
+        return t;
     }
     /**
      * Returns the distance between the **infinite** line and the point.
@@ -463,11 +460,11 @@ export class Line2D {
             return;
         }
         if (!this.isPointOnLineSection(lineToTrim.start)) {
-            const closest = this.closestPointOnLine(lineToTrim.start);
+            const closest = this.closestPointToPoint(lineToTrim.start, true);
             lineToTrim.start.copy(closest);
         }
         if (!this.isPointOnLineSection(lineToTrim.end)) {
-            const closest = this.closestPointOnLine(lineToTrim.end);
+            const closest = this.closestPointToPoint(lineToTrim.end, true);
             lineToTrim.end.copy(closest);
         }
     }

package/esm/MathConstants.js

@@ -0,0 +1 @@
+export const TwoPI = 2 * Math.PI;

package/esm/index.js

@@ -8,3 +8,4 @@ export { BoundingBox } from "./BoundingBox";
 export { Rectangle } from "./Rectangle";
 export { normalizeAngleDegrees } from "./normalizeAngleDegrees";
 export { normalizeAngleRadians } from "./normalizeAngleRadians";
+export { TwoPI } from "./MathConstants";

package/esm/normalizeAngleDegrees.js

@@ -1,3 +1,7 @@
+/**
+ * Normalizes an angle in degrees to the range [0, 360].
+ * @param angle in degrees
+ */
 export function normalizeAngleDegrees(angle) {
     return ((angle % 360) + 360) % 360;
 }

package/esm/normalizeAngleRadians.js

@@ -1,8 +1,12 @@
+import { TwoPI } from "./MathConstants";
+/**
+ * Normalize an angle in radians to the range of 0 to 2π.
+ * @param angle in radians
+ */
 export function normalizeAngleRadians(angle) {
-    const twoPi = 2 * Math.PI;
-    angle = angle % twoPi; // Use modulus to get the angle within the range of 0 to 2π
+    angle = angle % TwoPI; // Use modulus to get the angle within the range of 0 to 2π
     if (angle < 0) { // Add 2π if the angle is negative
-        angle = angle + twoPi;
+        angle = angle + TwoPI;
     }
     return angle;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immugio/three-math-extensions",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "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/src/Line2D.ts

@@ -1,6 +1,10 @@
 import { Point2 } from "./Point2";
 import { Vector2 } from "three";
 import { Vec2 } from "./Vec2";
+import { MathUtils } from "three";
+
+const _startP = /*@__PURE__*/ new Vec2();
+const _startEnd = /*@__PURE__*/ new Vec2();
 
 export class Line2D {
 
@@ -381,39 +385,34 @@ export class Line2D {
     }
 
     /**
-     * Returns the closest point parameter on the **infinite** line to the given point.
+     * Returns the closest point on the line to the given point.
      * @param point
+     * @param clampToLine boolean (optional)
+     * @param target Vec2 (optional)
      */
-    public closestPointToPointParameterOnInfiniteLine(point: Vector2): number {
-        const startP = new Vec2().subVectors(point, this.start);
-        const startEnd = new Vec2().subVectors(this.end, this.start);
-
-        const startEnd2 = startEnd.dot(startEnd);
-        const startEnd_startP = startEnd.dot(startP);
-
-        return startEnd_startP / startEnd2;
+    public closestPointToPoint(point: Vector2, clampToLine?: boolean, target?: Vec2): Vec2 {
+        const t = this.closestPointToPointParameter(point, clampToLine);
+        return this.delta(target || new Vec2()).multiplyScalar(t).add(this.start);
     }
 
-    /**
-     * Returns the closest point on the **infinite** line to the given point.
-     * @param point
-     */
-    public closestPointOnInfiniteLine(point: Vector2): Vec2 {
-        const t = this.closestPointToPointParameterOnInfiniteLine(point);
-        return new Vec2().subVectors(this.end, this.start).multiplyScalar(t).add(this.start);
+    public delta(target: Vec2): Vec2 {
+        return target.subVectors(this.end, this.start);
     }
 
-    /**
-     * Returns the closest point on the line **section** to the given point.
-     * @param point
-     */
-    public closestPointOnLine(point: Vector2): Vec2 {
-        const closestPoint = this.closestPointOnInfiniteLine(point);
-        if (this.isPointOnLineSection(closestPoint)) {
-            return closestPoint;
+    public closestPointToPointParameter(point, clampToLine): number {
+        _startP.subVectors(point, this.start);
+        _startEnd.subVectors(this.end, this.start);
+
+        const startEnd2 = _startEnd.dot(_startEnd);
+        const startEnd_startP = _startEnd.dot(_startP);
+
+        let t = startEnd_startP / startEnd2;
+
+        if (clampToLine) {
+            t = MathUtils.clamp(t, 0, 1);
         }
 
-        return closestPoint.distanceTo(this.start) < closestPoint.distanceTo(this.end) ? this.start : this.end;
+        return t;
     }
 
     /**
@@ -541,12 +540,12 @@ export class Line2D {
         }
 
         if (!this.isPointOnLineSection(lineToTrim.start)) {
-            const closest = this.closestPointOnLine(lineToTrim.start);
+            const closest = this.closestPointToPoint(lineToTrim.start, true);
             lineToTrim.start.copy(closest);
         }
 
         if (!this.isPointOnLineSection(lineToTrim.end)) {
-            const closest = this.closestPointOnLine(lineToTrim.end);
+            const closest = this.closestPointToPoint(lineToTrim.end, true);
             lineToTrim.end.copy(closest);
         }
     }

package/src/MathConstants.ts

@@ -0,0 +1 @@
+export const TwoPI = 2 * Math.PI;

package/src/index.ts

@@ -7,4 +7,7 @@ export { Polygon } from "./Polygon";
 export { BoundingBox } from "./BoundingBox";
 export { Rectangle } from "./Rectangle";
 export { normalizeAngleDegrees } from "./normalizeAngleDegrees";
-export { normalizeAngleRadians } from "./normalizeAngleRadians";
+export { normalizeAngleRadians } from "./normalizeAngleRadians";
+export { TwoPI } from "./MathConstants";
+export { Point2 } from "./Point2";
+export { Point3 } from "./Point3";

package/src/normalizeAngleDegrees.ts

@@ -1,3 +1,7 @@
+/**
+ * Normalizes an angle in degrees to the range [0, 360].
+ * @param angle in degrees
+ */
 export function normalizeAngleDegrees(angle: number): number {
     return ((angle % 360) + 360) % 360;
 }

package/src/normalizeAngleRadians.ts

@@ -1,9 +1,15 @@
+import { TwoPI } from "./MathConstants";
+
+/**
+ * Normalize an angle in radians to the range of 0 to 2π.
+ * @param angle in radians
+ */
 export function normalizeAngleRadians(angle: number): number {
-    const twoPi = 2 * Math.PI;
-    angle = angle % twoPi;  // Use modulus to get the angle within the range of 0 to 2π
+    angle = angle % TwoPI;  // Use modulus to get the angle within the range of 0 to 2π
+
     if (angle < 0) {        // Add 2π if the angle is negative
-        angle = angle + twoPi;
+        angle = angle + TwoPI;
     }
-    return angle;
-}
 
+    return angle;
+}

package/types/Line2D.d.ts

@@ -144,20 +144,14 @@ export declare class Line2D {
      */
     chunk(maxSegmentLength: number): Line2D[];
     /**
-     * Returns the closest point parameter on the **infinite** line to the given point.
+     * Returns the closest point on the line to the given point.
      * @param point
+     * @param clampToLine boolean (optional)
+     * @param target Vec2 (optional)
      */
-    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;
+    closestPointToPoint(point: Vector2, clampToLine?: boolean, target?: Vec2): Vec2;
+    delta(target: Vec2): Vec2;
+    closestPointToPointParameter(point: any, clampToLine: any): number;
     /**
      * Returns the distance between the **infinite** line and the point.
      * @param point

package/types/MathConstants.d.ts

@@ -0,0 +1 @@
+export declare const TwoPI: number;

package/types/index.d.ts

@@ -8,3 +8,6 @@ export { BoundingBox } from "./BoundingBox";
 export { Rectangle } from "./Rectangle";
 export { normalizeAngleDegrees } from "./normalizeAngleDegrees";
 export { normalizeAngleRadians } from "./normalizeAngleRadians";
+export { TwoPI } from "./MathConstants";
+export { Point2 } from "./Point2";
+export { Point3 } from "./Point3";

package/types/normalizeAngleDegrees.d.ts

@@ -1 +1,5 @@
+/**
+ * Normalizes an angle in degrees to the range [0, 360].
+ * @param angle in degrees
+ */
 export declare function normalizeAngleDegrees(angle: number): number;

package/types/normalizeAngleRadians.d.ts

@@ -1 +1,5 @@
+/**
+ * Normalize an angle in radians to the range of 0 to 2π.
+ * @param angle in radians
+ */
 export declare function normalizeAngleRadians(angle: number): number;

package/HowToRelease.txt

@@ -1,13 +0,0 @@
-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.