@plastic-software/three 0.167.4 → 0.174.0

package/src/math/SphericalHarmonics3.js

@@ -1,21 +1,33 @@
 import { Vector3 } from './Vector3.js';
 
 /**
- * Primary reference:
- *   https://graphics.stanford.edu/papers/envmap/envmap.pdf
+ * Represents a third-order spherical harmonics (SH). Light probes use this class
+ * to encode lighting information.
  *
- * Secondary reference:
- *   https://www.ppsloan.org/publications/StupidSH36.pdf
+ * - Primary reference: {@link https://graphics.stanford.edu/papers/envmap/envmap.pdf}
+ * - Secondary reference: {@link https://www.ppsloan.org/publications/StupidSH36.pdf}
  */
-
-// 3-band SH defined by 9 coefficients
-
 class SphericalHarmonics3 {
 
+	/**
+	 * Constructs a new spherical harmonics.
+	 */
 	constructor() {
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSphericalHarmonics3 = true;
 
+		/**
+		 * An array holding the (9) SH coefficients.
+		 *
+		 * @type {Array<Vector3>}
+		 */
 		this.coefficients = [];
 
 		for ( let i = 0; i < 9; i ++ ) {
@@ -26,6 +38,13 @@ class SphericalHarmonics3 {
 
 	}
 
+	/**
+	 * Sets the given SH coefficients to this instance by copying
+	 * the values.
+	 *
+	 * @param {Array<Vector3>} coefficients - The SH coefficients.
+	 * @return {SphericalHarmonics3} A reference to this spherical harmonics.
+	 */
 	set( coefficients ) {
 
 		for ( let i = 0; i < 9; i ++ ) {
@@ -38,6 +57,11 @@ class SphericalHarmonics3 {
 
 	}
 
+	/**
+	 * Sets all SH coefficients to `0`.
+	 *
+	 * @return {SphericalHarmonics3} A reference to this spherical harmonics.
+	 */
 	zero() {
 
 		for ( let i = 0; i < 9; i ++ ) {
@@ -50,8 +74,13 @@ class SphericalHarmonics3 {
 
 	}
 
-	// get the radiance in the direction of the normal
-	// target is a Vector3
+	/**
+	 * Returns the radiance in the direction of the given normal.
+	 *
+	 * @param {Vector3} normal - The normal vector (assumed to be unit length)
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {Vector3} The radiance.
+	 */
 	getAt( normal, target ) {
 
 		// normal is assumed to be unit length
@@ -79,9 +108,14 @@ class SphericalHarmonics3 {
 
 	}
 
-	// get the irradiance (radiance convolved with cosine lobe) in the direction of the normal
-	// target is a Vector3
-	// https://graphics.stanford.edu/papers/envmap/envmap.pdf
+	/**
+	 * Returns the irradiance (radiance convolved with cosine lobe) in the
+	 * direction of the given normal.
+	 *
+	 * @param {Vector3} normal - The normal vector (assumed to be unit length)
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {Vector3} The irradiance.
+	 */
 	getIrradianceAt( normal, target ) {
 
 		// normal is assumed to be unit length
@@ -109,6 +143,12 @@ class SphericalHarmonics3 {
 
 	}
 
+	/**
+	 * Adds the given SH to this instance.
+	 *
+	 * @param {SphericalHarmonics3} sh - The SH to add.
+	 * @return {SphericalHarmonics3} A reference to this spherical harmonics.
+	 */
 	add( sh ) {
 
 		for ( let i = 0; i < 9; i ++ ) {
@@ -121,6 +161,14 @@ class SphericalHarmonics3 {
 
 	}
 
+	/**
+	 * A convenience method for performing {@link SphericalHarmonics3#add} and
+	 * {@link SphericalHarmonics3#scale} at once.
+	 *
+	 * @param {SphericalHarmonics3} sh - The SH to add.
+	 * @param {number} s - The scale factor.
+	 * @return {SphericalHarmonics3} A reference to this spherical harmonics.
+	 */
 	addScaledSH( sh, s ) {
 
 		for ( let i = 0; i < 9; i ++ ) {
@@ -133,6 +181,12 @@ class SphericalHarmonics3 {
 
 	}
 
+	/**
+	 * Scales this SH by the given scale factor.
+	 *
+	 * @param {number} s - The scale factor.
+	 * @return {SphericalHarmonics3} A reference to this spherical harmonics.
+	 */
 	scale( s ) {
 
 		for ( let i = 0; i < 9; i ++ ) {
@@ -145,6 +199,14 @@ class SphericalHarmonics3 {
 
 	}
 
+	/**
+	 * Linear interpolates between the given SH and this instance by the given
+	 * alpha factor.
+	 *
+	 * @param {SphericalHarmonics3} sh - The SH to interpolate with.
+	 * @param {number} alpha - The alpha factor.
+	 * @return {SphericalHarmonics3} A reference to this spherical harmonics.
+	 */
 	lerp( sh, alpha ) {
 
 		for ( let i = 0; i < 9; i ++ ) {
@@ -157,6 +219,12 @@ class SphericalHarmonics3 {
 
 	}
 
+	/**
+	 * Returns `true` if this spherical harmonics is equal with the given one.
+	 *
+	 * @param {SphericalHarmonics3} sh - The spherical harmonics to test for equality.
+	 * @return {boolean} Whether this spherical harmonics is equal with the given one.
+	 */
 	equals( sh ) {
 
 		for ( let i = 0; i < 9; i ++ ) {
@@ -173,18 +241,36 @@ class SphericalHarmonics3 {
 
 	}
 
+	/**
+	 * Copies the values of the given spherical harmonics to this instance.
+	 *
+	 * @param {SphericalHarmonics3} sh - The spherical harmonics to copy.
+	 * @return {SphericalHarmonics3} A reference to this spherical harmonics.
+	 */
 	copy( sh ) {
 
 		return this.set( sh.coefficients );
 
 	}
 
+	/**
+	 * Returns a new spherical harmonics with copied values from this instance.
+	 *
+	 * @return {SphericalHarmonics3} A clone of this instance.
+	 */
 	clone() {
 
 		return new this.constructor().copy( this );
 
 	}
 
+	/**
+	 * Sets the SH coefficients of this instance from the given array.
+	 *
+	 * @param {Array<number>} array - An array holding the SH coefficients.
+	 * @param {number} [offset=0] - The array offset where to start copying.
+	 * @return {SphericalHarmonics3} A clone of this instance.
+	 */
 	fromArray( array, offset = 0 ) {
 
 		const coefficients = this.coefficients;
@@ -199,6 +285,14 @@ class SphericalHarmonics3 {
 
 	}
 
+	/**
+	 * Returns an array with the SH coefficients, or copies them into the provided
+	 * array. The coefficients are represented as numbers.
+	 *
+	 * @param {Array<number>} [array=[]] - The target array.
+	 * @param {number} [offset=0] - The array offset where to start copying.
+	 * @return {Array<number>} An array with flat SH coefficients.
+	 */
 	toArray( array = [], offset = 0 ) {
 
 		const coefficients = this.coefficients;
@@ -213,8 +307,12 @@ class SphericalHarmonics3 {
 
 	}
 
-	// evaluate the basis functions
-	// shBasis is an Array[ 9 ]
+	/**
+	 * Computes the SH basis for the given normal vector.
+	 *
+	 * @param {Vector3} normal - The normal.
+	 * @param {Array<number>} shBasis - The target array holding the SH basis.
+	 */
 	static getBasisAt( normal, shBasis ) {
 
 		// normal is assumed to be unit length

package/src/math/Triangle.js

@@ -1,4 +1,5 @@
 import { Vector3 } from './Vector3.js';
+import { Vector4 } from './Vector4.js';
 
 const _v0 = /*@__PURE__*/ new Vector3();
 const _v1 = /*@__PURE__*/ new Vector3();
@@ -12,16 +13,56 @@ const _vap = /*@__PURE__*/ new Vector3();
 const _vbp = /*@__PURE__*/ new Vector3();
 const _vcp = /*@__PURE__*/ new Vector3();
 
+const _v40 = /*@__PURE__*/ new Vector4();
+const _v41 = /*@__PURE__*/ new Vector4();
+const _v42 = /*@__PURE__*/ new Vector4();
+
+/**
+ * A geometric triangle as defined by three vectors representing its three corners.
+ */
 class Triangle {
 
+	/**
+	 * Constructs a new triangle.
+	 *
+	 * @param {Vector3} [a=(0,0,0)] - The first corner of the triangle.
+	 * @param {Vector3} [b=(0,0,0)] - The second corner of the triangle.
+	 * @param {Vector3} [c=(0,0,0)] - The third corner of the triangle.
+	 */
 	constructor( a = new Vector3(), b = new Vector3(), c = new Vector3() ) {
 
+		/**
+		 * The first corner of the triangle.
+		 *
+		 * @type {Vector3}
+		 */
 		this.a = a;
+
+		/**
+		 * The second corner of the triangle.
+		 *
+		 * @type {Vector3}
+		 */
 		this.b = b;
+
+		/**
+		 * The third corner of the triangle.
+		 *
+		 * @type {Vector3}
+		 */
 		this.c = c;
 
 	}
 
+	/**
+	 * Computes the normal vector of a triangle.
+	 *
+	 * @param {Vector3} a - The first corner of the triangle.
+	 * @param {Vector3} b - The second corner of the triangle.
+	 * @param {Vector3} c - The third corner of the triangle.
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {Vector3} The triangle's normal.
+	 */
 	static getNormal( a, b, c, target ) {
 
 		target.subVectors( c, b );
@@ -39,10 +80,21 @@ class Triangle {
 
 	}
 
-	// static/instance method to calculate barycentric coordinates
-	// based on: http://www.blackpawn.com/texts/pointinpoly/default.html
+	/**
+	 * Computes a barycentric coordinates from the given vector.
+	 * Returns `null` if the triangle is degenerate.
+	 *
+	 * @param {Vector3} point - A point in 3D space.
+	 * @param {Vector3} a - The first corner of the triangle.
+	 * @param {Vector3} b - The second corner of the triangle.
+	 * @param {Vector3} c - The third corner of the triangle.
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {?Vector3} The barycentric coordinates for the given point
+	 */
 	static getBarycoord( point, a, b, c, target ) {
 
+		// based on: http://www.blackpawn.com/texts/pointinpoly/default.html
+
 		_v0.subVectors( c, a );
 		_v1.subVectors( b, a );
 		_v2.subVectors( point, a );
@@ -72,6 +124,17 @@ class Triangle {
 
 	}
 
+	/**
+	 * Returns `true` if the given point, when projected onto the plane of the
+	 * triangle, lies within the triangle.
+	 *
+	 * @param {Vector3} point - The point in 3D space to test.
+	 * @param {Vector3} a - The first corner of the triangle.
+	 * @param {Vector3} b - The second corner of the triangle.
+	 * @param {Vector3} c - The third corner of the triangle.
+	 * @return {boolean} Whether the given point, when projected onto the plane of the
+	 * triangle, lies within the triangle or not.
+	 */
 	static containsPoint( point, a, b, c ) {
 
 		// if the triangle is degenerate then we can't contain a point
@@ -85,6 +148,20 @@ class Triangle {
 
 	}
 
+	/**
+	 * Computes the value barycentrically interpolated for the given point on the
+	 * triangle. Returns `null` if the triangle is degenerate.
+	 *
+	 * @param {Vector3} point - Position of interpolated point.
+	 * @param {Vector3} p1 - The first corner of the triangle.
+	 * @param {Vector3} p2 - The second corner of the triangle.
+	 * @param {Vector3} p3 - The third corner of the triangle.
+	 * @param {Vector3} v1 - Value to interpolate of first vertex.
+	 * @param {Vector3} v2 - Value to interpolate of second vertex.
+	 * @param {Vector3} v3 - Value to interpolate of third vertex.
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {?Vector3} The interpolated value.
+	 */
 	static getInterpolation( point, p1, p2, p3, v1, v2, v3, target ) {
 
 		if ( this.getBarycoord( point, p1, p2, p3, _v3 ) === null ) {
@@ -106,6 +183,45 @@ class Triangle {
 
 	}
 
+	/**
+	 * Computes the value barycentrically interpolated for the given attribute and indices.
+	 *
+	 * @param {BufferAttribute} attr - The attribute to interpolate.
+	 * @param {number} i1 - Index of first vertex.
+	 * @param {number} i2 - Index of second vertex.
+	 * @param {number} i3 - Index of third vertex.
+	 * @param {Vector3} barycoord - The barycoordinate value to use to interpolate.
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {Vector3} The interpolated attribute value.
+	 */
+	static getInterpolatedAttribute( attr, i1, i2, i3, barycoord, target ) {
+
+		_v40.setScalar( 0 );
+		_v41.setScalar( 0 );
+		_v42.setScalar( 0 );
+
+		_v40.fromBufferAttribute( attr, i1 );
+		_v41.fromBufferAttribute( attr, i2 );
+		_v42.fromBufferAttribute( attr, i3 );
+
+		target.setScalar( 0 );
+		target.addScaledVector( _v40, barycoord.x );
+		target.addScaledVector( _v41, barycoord.y );
+		target.addScaledVector( _v42, barycoord.z );
+
+		return target;
+
+	}
+
+	/**
+	 * Returns `true` if the triangle is oriented towards the given direction.
+	 *
+	 * @param {Vector3} a - The first corner of the triangle.
+	 * @param {Vector3} b - The second corner of the triangle.
+	 * @param {Vector3} c - The third corner of the triangle.
+	 * @param {Vector3} direction - The (normalized) direction vector.
+	 * @return {boolean} Whether the triangle is oriented towards the given direction or not.
+	 */
 	static isFrontFacing( a, b, c, direction ) {
 
 		_v0.subVectors( c, b );
@@ -116,6 +232,14 @@ class Triangle {
 
 	}
 
+	/**
+	 * Sets the triangle's vertices by copying the given values.
+	 *
+	 * @param {Vector3} a - The first corner of the triangle.
+	 * @param {Vector3} b - The second corner of the triangle.
+	 * @param {Vector3} c - The third corner of the triangle.
+	 * @return {Triangle} A reference to this triangle.
+	 */
 	set( a, b, c ) {
 
 		this.a.copy( a );
@@ -126,6 +250,15 @@ class Triangle {
 
 	}
 
+	/**
+	 * Sets the triangle's vertices by copying the given array values.
+	 *
+	 * @param {Array<Vector3>} points - An array with 3D points.
+	 * @param {number} i0 - The array index representing the first corner of the triangle.
+	 * @param {number} i1 - The array index representing the second corner of the triangle.
+	 * @param {number} i2 - The array index representing the third corner of the triangle.
+	 * @return {Triangle} A reference to this triangle.
+	 */
 	setFromPointsAndIndices( points, i0, i1, i2 ) {
 
 		this.a.copy( points[ i0 ] );
@@ -136,6 +269,15 @@ class Triangle {
 
 	}
 
+	/**
+	 * Sets the triangle's vertices by copying the given attribute values.
+	 *
+	 * @param {BufferAttribute} attribute - A buffer attribute with 3D points data.
+	 * @param {number} i0 - The attribute index representing the first corner of the triangle.
+	 * @param {number} i1 - The attribute index representing the second corner of the triangle.
+	 * @param {number} i2 - The attribute index representing the third corner of the triangle.
+	 * @return {Triangle} A reference to this triangle.
+	 */
 	setFromAttributeAndIndices( attribute, i0, i1, i2 ) {
 
 		this.a.fromBufferAttribute( attribute, i0 );
@@ -146,12 +288,23 @@ class Triangle {
 
 	}
 
+	/**
+	 * Returns a new triangle with copied values from this instance.
+	 *
+	 * @return {Triangle} A clone of this instance.
+	 */
 	clone() {
 
 		return new this.constructor().copy( this );
 
 	}
 
+	/**
+	 * Copies the values of the given triangle to this instance.
+	 *
+	 * @param {Triangle} triangle - The triangle to copy.
+	 * @return {Triangle} A reference to this triangle.
+	 */
 	copy( triangle ) {
 
 		this.a.copy( triangle.a );
@@ -162,6 +315,11 @@ class Triangle {
 
 	}
 
+	/**
+	 * Computes the area of the triangle.
+	 *
+	 * @return {number} The triangle's area.
+	 */
 	getArea() {
 
 		_v0.subVectors( this.c, this.b );
@@ -171,54 +329,118 @@ class Triangle {
 
 	}
 
+	/**
+	 * Computes the midpoint of the triangle.
+	 *
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {Vector3} The triangle's midpoint.
+	 */
 	getMidpoint( target ) {
 
 		return target.addVectors( this.a, this.b ).add( this.c ).multiplyScalar( 1 / 3 );
 
 	}
 
+	/**
+	 * Computes the normal of the triangle.
+	 *
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {Vector3} The triangle's normal.
+	 */
 	getNormal( target ) {
 
 		return Triangle.getNormal( this.a, this.b, this.c, target );
 
 	}
 
+	/**
+	 * Computes a plane the triangle lies within.
+	 *
+	 * @param {Plane} target - The target vector that is used to store the method's result.
+	 * @return {Plane} The plane the triangle lies within.
+	 */
 	getPlane( target ) {
 
 		return target.setFromCoplanarPoints( this.a, this.b, this.c );
 
 	}
 
+	/**
+	 * Computes a barycentric coordinates from the given vector.
+	 * Returns `null` if the triangle is degenerate.
+	 *
+	 * @param {Vector3} point - A point in 3D space.
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {?Vector3} The barycentric coordinates for the given point
+	 */
 	getBarycoord( point, target ) {
 
 		return Triangle.getBarycoord( point, this.a, this.b, this.c, target );
 
 	}
 
+	/**
+	 * Computes the value barycentrically interpolated for the given point on the
+	 * triangle. Returns `null` if the triangle is degenerate.
+	 *
+	 * @param {Vector3} point - Position of interpolated point.
+	 * @param {Vector3} v1 - Value to interpolate of first vertex.
+	 * @param {Vector3} v2 - Value to interpolate of second vertex.
+	 * @param {Vector3} v3 - Value to interpolate of third vertex.
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {?Vector3} The interpolated value.
+	 */
 	getInterpolation( point, v1, v2, v3, target ) {
 
 		return Triangle.getInterpolation( point, this.a, this.b, this.c, v1, v2, v3, target );
 
 	}
 
+	/**
+	 * Returns `true` if the given point, when projected onto the plane of the
+	 * triangle, lies within the triangle.
+	 *
+	 * @param {Vector3} point - The point in 3D space to test.
+	 * @return {boolean} Whether the given point, when projected onto the plane of the
+	 * triangle, lies within the triangle or not.
+	 */
 	containsPoint( point ) {
 
 		return Triangle.containsPoint( point, this.a, this.b, this.c );
 
 	}
 
+	/**
+	 * Returns `true` if the triangle is oriented towards the given direction.
+	 *
+	 * @param {Vector3} direction - The (normalized) direction vector.
+	 * @return {boolean} Whether the triangle is oriented towards the given direction or not.
+	 */
 	isFrontFacing( direction ) {
 
 		return Triangle.isFrontFacing( this.a, this.b, this.c, direction );
 
 	}
 
+	/**
+	 * Returns `true` if this triangle intersects with the given box.
+	 *
+	 * @param {Box3} box - The box to intersect.
+	 * @return {boolean} Whether this triangle intersects with the given box or not.
+	 */
 	intersectsBox( box ) {
 
 		return box.intersectsTriangle( this );
 
 	}
 
+	/**
+	 * Returns the closest point on the triangle to the given point.
+	 *
+	 * @param {Vector3} p - The point to compute the closest point for.
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {Vector3} The closest point on the triangle.
+	 */
 	closestPointToPoint( p, target ) {
 
 		const a = this.a, b = this.b, c = this.c;
@@ -300,6 +522,12 @@ class Triangle {
 
 	}
 
+	/**
+	 * Returns `true` if this triangle is equal with the given one.
+	 *
+	 * @param {Triangle} triangle - The triangle to test for equality.
+	 * @return {boolean} Whether this triangle is equal with the given one.
+	 */
 	equals( triangle ) {
 
 		return triangle.a.equals( this.a ) && triangle.b.equals( this.b ) && triangle.c.equals( this.c );