@immugio/three-math-extensions 0.0.13 → 0.0.14

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