@woosh/meep-engine 2.121.8 → 2.121.11

package/src/core/geom/Vector3.js

@@ -17,7 +17,7 @@ import { v3_slerp } from "./vec3/v3_slerp.js";
  * @author Alex Goldring
  * @copyright Alex Goldring 2015-2024
  */
-class Vector3 {
+export class Vector3 {
     /**
      *
      * @param {number} [x=0]
@@ -36,21 +36,21 @@ class Vector3 {
         assert.notNaN(z, 'x');
 
         /**
-         * NOTE: do not assign directly, please use {@link set} method instead
+         * Do not assign directly, use {@link set} method instead
          * @readonly
          * @type {number}
          */
         this.x = x;
 
         /**
-         * NOTE: do not assign directly, please use {@link set} method instead
+         * Do not assign directly, use {@link set} method instead
          * @readonly
          * @type {number}
          */
         this.y = y;
 
         /**
-         * NOTE: do not assign directly, please use {@link set} method instead
+         * Do not assign directly, use {@link set} method instead
          * @readonly
          * @type {number}
          */
@@ -91,10 +91,10 @@ class Vector3 {
 
     /**
      *
-     * @param {Number} x
-     * @param {Number} y
-     * @param {Number} z
-     * @returns {Vector3}
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {this}
      */
     set(x, y, z) {
         assert.isNumber(x, "x");
@@ -128,15 +128,16 @@ class Vector3 {
     /**
      *
      * @param {number} v
+     * @returns {this}
      */
     setScalar(v) {
-        this.set(v, v, v);
+        return this.set(v, v, v);
     }
 
     /**
      *
      * @param {number} v
-     * @returns {Vector3}
+     * @returns {this}
      */
     setX(v) {
         return this.set(v, this.y, this.z);
@@ -145,7 +146,7 @@ class Vector3 {
     /**
      *
      * @param {number} v
-     * @returns {Vector3}
+     * @returns {this}
      */
     setY(v) {
         return this.set(this.x, v, this.z);
@@ -154,7 +155,7 @@ class Vector3 {
     /**
      *
      * @param {number} v
-     * @returns {Vector3}
+     * @returns {this}
      */
     setZ(v) {
         return this.set(this.x, this.y, v);
@@ -164,7 +165,7 @@ class Vector3 {
      *
      * @param {number} x
      * @param {number} y
-     * @returns {Vector3}
+     * @returns {this}
      */
     setXY(x, y) {
         return this.set(x, y, this.z);
@@ -174,7 +175,7 @@ class Vector3 {
      *
      * @param {number} x
      * @param {number} z
-     * @returns {Vector3}
+     * @returns {this}
      */
     setXZ(x, z) {
         return this.set(x, this.y, z);
@@ -184,7 +185,7 @@ class Vector3 {
      *
      * @param {number} y
      * @param {number} z
-     * @returns {Vector3}
+     * @returns {this}
      */
     setYZ(y, z) {
         return this.set(this.x, y, z);
@@ -194,19 +195,20 @@ class Vector3 {
      *
      * @param {Vector3} a
      * @param {Vector3} b
+     * @returns {this}
      */
     addVectors(a, b) {
         const x = a.x + b.x;
         const y = a.y + b.y;
         const z = a.z + b.z;
 
-        this.set(x, y, z);
+        return this.set(x, y, z);
     }
 
     /**
      *
      * @param {Vector3} other
-     * @returns {Vector3}
+     * @returns {this}
      */
     add(other) {
         return this._add(other.x, other.y, other.z);
@@ -214,10 +216,10 @@ class Vector3 {
 
     /**
      *
-     * @param {Number} x
-     * @param {Number} y
-     * @param {Number} z
-     * @returns {Vector3}
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {this}
      */
     _add(x, y, z) {
         return this.set(this.x + x, this.y + y, this.z + z);
@@ -228,19 +230,20 @@ class Vector3 {
      *
      * @param {Vector3} a
      * @param {Vector3} b
+     * @returns {this}
      */
     subVectors(a, b) {
         const x = a.x - b.x;
         const y = a.y - b.y;
         const z = a.z - b.z;
 
-        this.set(x, y, z);
+        return this.set(x, y, z);
     }
 
     /**
      *
      * @param {Vector3} other
-     * @returns {Vector3}
+     * @returns {this}
      */
     sub(other) {
         return this._sub(other.x, other.y, other.z);
@@ -248,10 +251,10 @@ class Vector3 {
 
     /**
      *
-     * @param {Number} x
-     * @param {Number} y
-     * @param {Number} z
-     * @returns {Vector3}
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {this}
      */
     _sub(x, y, z) {
         const _x = this.x - x;
@@ -263,10 +266,10 @@ class Vector3 {
 
     /**
      *
-     * @param {Number} x
-     * @param {Number} y
-     * @param {Number} z
-     * @returns {Vector3}
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @returns {this}
      */
     _multiply(x, y, z) {
         return this.set(this.x * x, this.y * y, this.z * z);
@@ -275,7 +278,7 @@ class Vector3 {
     /**
      *
      * @param {Vector3} other
-     * @returns {Vector3}
+     * @returns {this}
      */
     multiply(other) {
         return this._multiply(other.x, other.y, other.z);
@@ -285,9 +288,10 @@ class Vector3 {
      *
      * @param {Vector3} a
      * @param {Vector3} b
+     * @returns {this}
      */
     multiplyVectors(a, b) {
-        this.set(
+        return this.set(
             a.x * b.x,
             a.y * b.y,
             a.z * b.z
@@ -299,7 +303,7 @@ class Vector3 {
      * @param {number} x
      * @param {number} y
      * @param {number} z
-     * @returns {Vector3}
+     * @returns {this}
      */
     _divide(x, y, z) {
         return this.set(
@@ -312,7 +316,7 @@ class Vector3 {
     /**
      *
      * @param {Vector3} other
-     * @returns {Vector3}
+     * @returns {this}
      */
     divide(other) {
         return this._divide(other.x, other.y, other.z);
@@ -321,7 +325,7 @@ class Vector3 {
     /**
      * Subtract scalar value from each component of the vector
      * @param {number} val
-     * @returns {Vector3}
+     * @returns {this}
      */
     subScalar(val) {
         return this.set(this.x - val, this.y - val, this.z - val);
@@ -330,7 +334,7 @@ class Vector3 {
     /**
      * Add a scalar value to each component of the vector
      * @param {number} val
-     * @returns {Vector3}
+     * @returns {this}
      */
     addScalar(val) {
         return this.set(this.x + val, this.y + val, this.z + val);
@@ -347,7 +351,7 @@ class Vector3 {
     /**
      *
      * @param {number} val
-     * @returns {Vector3}
+     * @returns {this}
      */
     multiplyScalar(val) {
         assert.isNumber(val, "val");
@@ -361,30 +365,32 @@ class Vector3 {
      * @returns {boolean}
      */
     isZero() {
-        return this.x === 0 && this.y === 0 && this.z === 0;
+        return this.x === 0
+            && this.y === 0
+            && this.z === 0
+            ;
     }
 
     /**
      * Compute cross-product of two vectors. Result is written to this vector.
      * @param {Vector3} other
-     * @returns {Vector3}
+     * @returns {this}
      */
     cross(other) {
-        this.crossVectors(this, other);
-
-        return this;
+        return this.crossVectors(this, other);
     }
 
     /**
      *
      * @param {Vector3} first
      * @param {Vector3} second
+     * @returns {this}
      */
     crossVectors(first, second) {
         const ax = first.x, ay = first.y, az = first.z;
         const bx = second.x, by = second.y, bz = second.z;
 
-        this._crossVectors(
+        return this._crossVectors(
             ax, ay, az,
             bx, by, bz
         );
@@ -399,18 +405,19 @@ class Vector3 {
      * @param {number} bx
      * @param {number} by
      * @param {number} bz
+     * @returns {this}
      */
     _crossVectors(ax, ay, az, bx, by, bz) {
         const x = ay * bz - az * by;
         const y = az * bx - ax * bz;
         const z = ax * by - ay * bx;
 
-        this.set(x, y, z);
+        return this.set(x, y, z);
     }
 
     /**
      * Sets all components of the vector to absolute value (positive)
-     * @returns {Vector3}
+     * @returns {this}
      */
     abs() {
         return this.set(
@@ -448,13 +455,14 @@ class Vector3 {
 
     /**
      * Normalizes the vector, preserving its direction, but making magnitude equal to 1
+     * @returns {this}
      */
     normalize() {
         const l = this.length();
 
         if (l === 0) {
             //special case, can't normalize 0 length vector
-            return;
+            return this;
         }
 
         const m = 1 / l;
@@ -475,7 +483,7 @@ class Vector3 {
     /**
      *
      * @param {Vector3|{x:number,y:number,z:number}} other
-     * @returns {Vector3}
+     * @returns {this}
      */
     copy(other) {
         return this.set(other.x, other.y, other.z);
@@ -484,10 +492,14 @@ class Vector3 {
 
     /**
      * Negates every component of the vector making it {-x, -y, -z}
-     * @returns {Vector3}
+     * @returns {this}
      */
     negate() {
-        return this.set(-this.x, -this.y, -this.z);
+        return this.set(
+            -this.x,
+            -this.y,
+            -this.z
+        );
     }
 
     /**
@@ -507,16 +519,25 @@ class Vector3 {
      * @return {number}
      */
     _distanceTo(x, y, z) {
-        return v3_distance(this.x, this.y, this.z, x, y, z);
+        return v3_distance(
+            this.x, this.y, this.z,
+            x, y, z
+        );
     }
 
     /**
      * Squared distance between this vector and another. It is faster than computing real distance because no SQRT operation is needed.
      * @param {Vector3} other
-     * returns {number}
+     * @returns {number}
      */
     distanceSqrTo(other) {
-        return v3_length_sqr(this.x - other.x, this.y - other.y, this.z - other.z);
+        assert.defined(other, "other");
+
+        const dx = this.x - other.x;
+        const dy = this.y - other.y;
+        const dz = this.z - other.z;
+
+        return v3_length_sqr(dx, dy, dz);
     }
 
     /**
@@ -536,19 +557,28 @@ class Vector3 {
      * @returns {number}
      */
     angleTo(other) {
-        return v3_angle_between(this.x, this.y, this.z, other.x, other.y, other.z);
+        return v3_angle_between(
+            this.x, this.y, this.z,
+            other.x, other.y, other.z
+        );
     }
 
     /**
      *
      * @param {Quaternion} q
-     * @returns {Vector3}
+     * @returns {this}
      */
     applyQuaternion(q) {
         //transform point into quaternion
 
-        const x = this.x, y = this.y, z = this.z;
-        const qx = q.x, qy = q.y, qz = q.z, qw = q.w;
+        const x = this.x;
+        const y = this.y;
+        const z = this.z;
+
+        const qx = q.x;
+        const qy = q.y;
+        const qz = q.z;
+        const qw = q.w;
 
         // calculate quat * vector
 
@@ -569,7 +599,7 @@ class Vector3 {
     /**
      * Set components X,Y,Z to values 1,0 or -1 based on the sign of their original value.
      * @example new Vector(5,0,-10).sign().equals(new Vector(1,0,-1)); //true
-     * @returns {Vector3}
+     * @returns {this}
      */
     sign() {
         return this.set(
@@ -582,8 +612,8 @@ class Vector3 {
     /**
      * Linear interpolation
      * @param {Vector3} other
-     * @param {Number} fraction between 0 and 1
-     * @returns {Vector3}
+     * @param {number} fraction between 0 and 1
+     * @returns {this}
      */
     lerp(other, fraction) {
         return this.lerpVectors(this, other, fraction);
@@ -628,6 +658,7 @@ class Vector3 {
     /**
      *
      * @param {ArrayLike<number>|number[]|Float32Array} m4
+     * @returns {this}
      */
     applyMatrix4(m4) {
         const x = this.x;
@@ -640,12 +671,13 @@ class Vector3 {
         const _y = (m4[1] * x + m4[5] * y + m4[9] * z + m4[13]) * w;
         const _z = (m4[2] * x + m4[6] * y + m4[10] * z + m4[14]) * w;
 
-        this.set(_x, _y, _z);
+       return this.set(_x, _y, _z);
     }
 
     /**
      * Assume current vector holds a direction, transform using a matrix to produce a new directional unit vector
      * @param {ArrayLike<number>|number[]|Float32Array} m4
+     * @returns {this}
      */
     applyDirectionMatrix4(m4) {
         const x = this.x;
@@ -660,7 +692,7 @@ class Vector3 {
         // normalize the result
         const _l = 1 / v3_length(_x, _y, _z);
 
-        this.set(
+        return this.set(
             _x * _l,
             _y * _l,
             _z * _l
@@ -670,6 +702,7 @@ class Vector3 {
     /**
      *
      * @param {number[]|Float32Array} mat
+     * @returns {this}
      */
     applyMatrix3(mat) {
         const x = this.x;
@@ -680,13 +713,14 @@ class Vector3 {
         const _y = mat[1] * x + mat[4] * y + mat[7] * z;
         const _z = mat[2] * x + mat[5] * y + mat[8] * z;
 
-        this.set(_x, _y, _z);
+        return this.set(_x, _y, _z);
     }
 
 
     /**
      *
      * @param {ArrayLike<number>|number[]|Float32Array} matrix4 4x4 transform matrix
+     * @returns {this}
      */
     setFromMatrixPosition(matrix4) {
 
@@ -694,7 +728,7 @@ class Vector3 {
         const _y = matrix4[13];
         const _z = matrix4[14];
 
-        this.set(_x, _y, _z);
+       return this.set(_x, _y, _z);
     }
 
     /**
@@ -741,17 +775,21 @@ class Vector3 {
             && epsilonEquals(this.z, z, tolerance);
     }
 
+    /**
+     * @returns {this}
+     */
     floor() {
         const x = this.x | 0;
         const y = this.y | 0;
         const z = this.z | 0;
 
-        this.set(x, y, z);
+        return this.set(x, y, z);
     }
 
     /**
      * Project this vector onto another
      * @param {Vector3} other
+     * @returns {this}
      */
     projectOntoVector3(other) {
         const x0 = this.x;
@@ -762,7 +800,7 @@ class Vector3 {
         const y1 = other.y;
         const z1 = other.z;
 
-        this._projectVectors(x0, y0, z0, x1, y1, z1);
+        return this._projectVectors(x0, y0, z0, x1, y1, z1);
     }
 
     /**
@@ -773,6 +811,7 @@ class Vector3 {
      * @param {number} x1
      * @param {number} y1
      * @param {number} z1
+     * @returns {this}
      */
     _projectVectors(
         x0, y0, z0,
@@ -789,7 +828,7 @@ class Vector3 {
         const y = y1 * m;
         const z = z1 * m;
 
-        this.set(x, y, z);
+        return this.set(x, y, z);
     }
 
     /**
@@ -797,6 +836,7 @@ class Vector3 {
      * @param {number} radius
      * @param {number} phi Also known as Azimuth
      * @param {number} theta Also known as Elevation
+     * @returns {this}
      */
     setFromSphericalCoords(radius, phi, theta) {
         assert.isNumber(radius, 'radius');
@@ -818,7 +858,7 @@ class Vector3 {
         const _y = radius * cos_phi;
         const _z = radius * sin_phi * cos_theta;
 
-        this.set(_x, _y, _z);
+       return this.set(_x, _y, _z);
     }
 
     /**