@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/math/ImprovedNoise.js

@@ -1,5 +1,3 @@
-// https://cs.nyu.edu/~perlin/noise/
-
 const _p = [ 151, 160, 137, 91, 90, 15, 131, 13, 201, 95, 96, 53, 194, 233, 7, 225, 140, 36, 103, 30, 69, 142, 8, 99, 37, 240, 21, 10,
 	 23, 190, 6, 148, 247, 120, 234, 75, 0, 26, 197, 62, 94, 252, 219, 203, 117, 35, 11, 32, 57, 177, 33, 88, 237, 149, 56, 87,
 	 174, 20, 125, 136, 171, 168, 68, 175, 74, 165, 71, 134, 139, 48, 27, 166, 77, 146, 158, 231, 83, 111, 229, 122, 60, 211,
@@ -37,8 +35,22 @@ function grad( hash, x, y, z ) {
 
 }
 
+/**
+ * A utility class providing a 3D noise function.
+ *
+ * The code is based on [IMPROVED NOISE]{@link https://cs.nyu.edu/~perlin/noise/}
+ * by Ken Perlin, 2002.
+ */
 class ImprovedNoise {
 
+	/**
+	 * Returns a noise value for the given parameters.
+	 *
+	 * @param {number} x - The x coordinate.
+	 * @param {number} y - The y coordinate.
+	 * @param {number} z - The z coordinate.
+	 * @return {number} The noise value.
+	 */
 	noise( x, y, z ) {
 
 		const floorX = Math.floor( x ), floorY = Math.floor( y ), floorZ = Math.floor( z );

package/examples/jsm/math/Lut.js

@@ -4,22 +4,83 @@ import {
 	MathUtils
 } from 'three';
 
+/**
+ * Represents a lookup table for colormaps. It is used to determine the color
+ * values from a range of data values.
+ *
+ * ```js
+ * const lut = new Lut( 'rainbow', 512 );
+ * const color = lut.getColor( 0.5 );
+ * ```
+ */
 class Lut {
 
+	/**
+	 * Constructs a new Lut.
+	 *
+	 * @param {('rainbow'|'cooltowarm'|'blackbody'|'grayscale')} [colormap='rainbow'] - Sets a colormap from predefined list of colormaps.
+	 * @param {number} [count=32] - Sets the number of colors used to represent the data array.
+	 */
  	constructor( colormap, count = 32 ) {
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLut = true;
 
+
+		/**
+		 * The lookup table for the selected color map
+		 *
+		 * @type {Array<Color>}
+		 */
 		this.lut = [];
+
+		/**
+		 * The currently selected color map.
+		 *
+		 * @type {Array}
+		 */
 		this.map = [];
+
+		/**
+		 * The number of colors of the current selected color map.
+		 *
+		 * @type {number}
+		 * @default 32
+		 */
 		this.n = 0;
+
+		/**
+		 * The minimum value to be represented with the lookup table.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.minV = 0;
+
+		/**
+		 * The maximum value to be represented with the lookup table.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.maxV = 1;
 
 		this.setColorMap( colormap, count );
 
 	}
 
+	/**
+	 * Sets the given LUT.
+	 *
+	 * @param {Lut} value - The LUT to set.
+	 * @return {Lut} A reference to this LUT.
+	 */
 	set( value ) {
 
 		if ( value.isLut === true ) {
@@ -32,6 +93,12 @@ class Lut {
 
 	}
 
+	/**
+	 * Sets the minimum value to be represented with this LUT.
+	 *
+	 * @param {number} min - The minimum value to be represented with the lookup table.
+	 * @return {Lut} A reference to this LUT.
+	 */
 	setMin( min ) {
 
 		this.minV = min;
@@ -40,6 +107,12 @@ class Lut {
 
 	}
 
+	/**
+	 * Sets the maximum value to be represented with this LUT.
+	 *
+	 * @param {number} max - The maximum value to be represented with the lookup table.
+	 * @return {Lut} A reference to this LUT.
+	 */
 	setMax( max ) {
 
 		this.maxV = max;
@@ -48,6 +121,13 @@ class Lut {
 
 	}
 
+	/**
+	 * Configure the lookup table for the given color map and number of colors.
+	 *
+	 * @param {string} colormap - The name of the color map.
+	 * @param {number} [count=32] - The number of colors.
+	 * @return {Lut} A reference to this LUT.
+	 */
 	setColorMap( colormap, count = 32 ) {
 
 		this.map = ColorMapKeywords[ colormap ] || ColorMapKeywords.rainbow;
@@ -97,6 +177,12 @@ class Lut {
 
 	}
 
+	/**
+	 * Copies the given lut.
+	 *
+	 * @param {Lut} lut - The LUT to copy.
+	 * @return {Lut} A reference to this LUT.
+	 */
 	copy( lut ) {
 
 		this.lut = lut.lut;
@@ -109,6 +195,12 @@ class Lut {
 
 	}
 
+	/**
+	 * Returns an instance of Color for the given data value.
+	 *
+	 * @param {number} alpha - The value to lookup.
+	 * @return {Color} The color from the LUT.
+	 */
 	getColor( alpha ) {
 
 		alpha = MathUtils.clamp( alpha, this.minV, this.maxV );
@@ -121,6 +213,14 @@ class Lut {
 
 	}
 
+	/**
+	 * Adds a color map to this Lut instance.
+	 *
+	 * @param {string} name - The name of the color map.
+	 * @param {Array} arrayOfColors - An array of color values. Each value is an array
+	 * holding a threshold and the actual color value as a hexadecimal number.
+	 * @return {Lut} A reference to this LUT.
+	 */
 	addColorMap( name, arrayOfColors ) {
 
 		ColorMapKeywords[ name ] = arrayOfColors;
@@ -129,6 +229,11 @@ class Lut {
 
 	}
 
+	/**
+	 * Creates a canvas in order to visualize the lookup table as a texture.
+	 *
+	 * @return {HTMLCanvasElement} The created canvas.
+	 */
 	createCanvas() {
 
 		const canvas = document.createElement( 'canvas' );
@@ -141,6 +246,12 @@ class Lut {
 
 	}
 
+	/**
+	 * Updates the given canvas with the Lut's data.
+	 *
+	 * @param {HTMLCanvasElement} canvas - The canvas to update.
+	 * @return {HTMLCanvasElement} The updated canvas.
+	 */
 	updateCanvas( canvas ) {
 
 		const ctx = canvas.getContext( '2d', { alpha: false } );

package/examples/jsm/math/MeshSurfaceSampler.js

@@ -4,6 +4,10 @@ import {
 	Vector3
 } from 'three';
 
+const _face = new Triangle();
+const _color = new Vector3();
+const _uva = new Vector2(), _uvb = new Vector2(), _uvc = new Vector2();
+
 /**
  * Utility class for sampling weighted random points on the surface of a mesh.
  *
@@ -11,16 +15,39 @@ import {
  * random samples may be selected in O(logn) time. Memory usage is O(n).
  *
  * References:
- * - http://www.joesfer.com/?p=84
- * - https://stackoverflow.com/a/4322940/1314762
+ * - {@link http://www.joesfer.com/?p=84}
+ * - {@link https://stackoverflow.com/a/4322940/1314762}
+ *
+ * ```js
+ * const sampler = new MeshSurfaceSampler( surfaceMesh )
+ * 	.setWeightAttribute( 'color' )
+ * 	.build();
+ *
+ * const mesh = new THREE.InstancedMesh( sampleGeometry, sampleMaterial, 100 );
+ *
+ * const position = new THREE.Vector3();
+ * const matrix = new THREE.Matrix4();
+ *
+ * // Sample randomly from the surface, creating an instance of the sample geometry at each sample point.
+ *
+ * for ( let i = 0; i < 100; i ++ ) {
+ *
+ * 	sampler.sample( position );
+ * 	matrix.makeTranslation( position.x, position.y, position.z );
+ * 	mesh.setMatrixAt( i, matrix );
+ *
+ * }
+ *
+ * scene.add( mesh );
+ * ```
  */
-
-const _face = new Triangle();
-const _color = new Vector3();
-const _uva = new Vector2(), _uvb = new Vector2(), _uvc = new Vector2();
-
 class MeshSurfaceSampler {
 
+	/**
+	 * Constructs a mesh surface sampler.
+	 *
+	 * @param {Mesh} mesh - Surface mesh from which to sample.
+	 */
 	constructor( mesh ) {
 
 		this.geometry = mesh.geometry;
@@ -37,6 +64,16 @@ class MeshSurfaceSampler {
 
 	}
 
+	/**
+	 * Specifies a vertex attribute to be used as a weight when sampling from the surface.
+	 * Faces with higher weights are more likely to be sampled, and those with weights of
+	 * zero will not be sampled at all. For vector attributes, only .x is used in sampling.
+	 *
+	 * If no weight attribute is selected, sampling is randomly distributed by area.
+	 *
+	 * @param {string} name - The attribute name.
+	 * @return {MeshSurfaceSampler} A reference to this sampler.
+	 */
 	setWeightAttribute( name ) {
 
 		this.weightAttribute = name ? this.geometry.getAttribute( name ) : null;
@@ -45,6 +82,13 @@ class MeshSurfaceSampler {
 
 	}
 
+	/**
+	 * Processes the input geometry and prepares to return samples. Any configuration of the
+	 * geometry or sampler must occur before this method is called. Time complexity is O(n)
+	 * for a surface with n faces.
+	 *
+	 * @return {MeshSurfaceSampler} A reference to this sampler.
+	 */
 	build() {
 
 		const indexAttribute = this.indexAttribute;
@@ -107,6 +151,12 @@ class MeshSurfaceSampler {
 
 	}
 
+	/**
+	 * Allows to set a custom random number generator. Default is `Math.random()`.
+	 *
+	 * @param {Function} randomFunction - A random number generator.
+	 * @return {MeshSurfaceSampler} A reference to this sampler.
+	 */
 	setRandomGenerator( randomFunction ) {
 
 		this.randomFunction = randomFunction;
@@ -114,21 +164,34 @@ class MeshSurfaceSampler {
 
 	}
 
+	/**
+	 * Selects a random point on the surface of the input geometry, returning the
+	 * position and optionally the normal vector, color and UV Coordinate at that point.
+	 * Time complexity is O(log n) for a surface with n faces.
+	 *
+	 * @param {Vector3} targetPosition - The target object holding the sampled position.
+	 * @param {Vector3} targetNormal - The target object holding the sampled normal.
+	 * @param {Color} targetColor - The target object holding the sampled color.
+	 * @param {Vector2} targetUV -  The target object holding the sampled uv coordinates.
+	 * @return {MeshSurfaceSampler} A reference to this sampler.
+	 */
 	sample( targetPosition, targetNormal, targetColor, targetUV ) {
 
-		const faceIndex = this.sampleFaceIndex();
-		return this.sampleFace( faceIndex, targetPosition, targetNormal, targetColor, targetUV );
+		const faceIndex = this._sampleFaceIndex();
+		return this._sampleFace( faceIndex, targetPosition, targetNormal, targetColor, targetUV );
 
 	}
 
-	sampleFaceIndex() {
+	// private
+
+	_sampleFaceIndex() {
 
 		const cumulativeTotal = this.distribution[ this.distribution.length - 1 ];
-		return this.binarySearch( this.randomFunction() * cumulativeTotal );
+		return this._binarySearch( this.randomFunction() * cumulativeTotal );
 
 	}
 
-	binarySearch( x ) {
+	_binarySearch( x ) {
 
 		const dist = this.distribution;
 		let start = 0;
@@ -162,7 +225,7 @@ class MeshSurfaceSampler {
 
 	}
 
-	sampleFace( faceIndex, targetPosition, targetNormal, targetColor, targetUV ) {
+	_sampleFace( faceIndex, targetPosition, targetNormal, targetColor, targetUV ) {
 
 		let u = this.randomFunction();
 		let v = this.randomFunction();

package/examples/jsm/math/OBB.js

@@ -37,18 +37,51 @@ const matrix = new Matrix4();
 const inverse = new Matrix4();
 const localRay = new Ray();
 
-// OBB
-
+/**
+ * Represents an oriented bounding box (OBB) in 3D space.
+ */
 class OBB {
 
+	/**
+	 * Constructs a new OBB.
+	 *
+	 * @param {Vector3} [center] - The center of the OBB.
+	 * @param {Vector3} [halfSize] - Positive halfwidth extents of the OBB along each axis.
+	 * @param {Matrix3} [rotation] - The rotation of the OBB.
+	 */
 	constructor( center = new Vector3(), halfSize = new Vector3(), rotation = new Matrix3() ) {
 
+		/**
+		 * The center of the OBB.
+		 *
+		 * @type {Vector3}
+		 */
 		this.center = center;
+
+		/**
+		 * Positive halfwidth extents of the OBB along each axis.
+		 *
+		 * @type {Vector3}
+		 */
 		this.halfSize = halfSize;
+
+		/**
+		 * The rotation of the OBB.
+		 *
+		 * @type {Matrix3}
+		 */
 		this.rotation = rotation;
 
 	}
 
+	/**
+	 * Sets the OBBs components to the given values.
+	 *
+	 * @param {Vector3} [center] - The center of the OBB.
+	 * @param {Vector3} [halfSize] - Positive halfwidth extents of the OBB along each axis.
+	 * @param {Matrix3} [rotation] - The rotation of the OBB.
+	 * @return {OBB} A reference to this OBB.
+	 */
 	set( center, halfSize, rotation ) {
 
 		this.center = center;
@@ -59,6 +92,12 @@ class OBB {
 
 	}
 
+	/**
+	 * Copies the values of the given OBB to this instance.
+	 *
+	 * @param {OBB} obb - The OBB to copy.
+	 * @return {OBB} A reference to this OBB.
+	 */
 	copy( obb ) {
 
 		this.center.copy( obb.center );
@@ -69,27 +108,40 @@ class OBB {
 
 	}
 
+	/**
+	 * Returns a new OBB with copied values from this instance.
+	 *
+	 * @return {OBB} A clone of this instance.
+	 */
 	clone() {
 
 		return new this.constructor().copy( this );
 
 	}
 
-	getSize( result ) {
+	/**
+	 * Returns the size of this OBB.
+	 *
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {Vector3} The size.
+	 */
+	getSize( target ) {
 
-		return result.copy( this.halfSize ).multiplyScalar( 2 );
+		return target.copy( this.halfSize ).multiplyScalar( 2 );
 
 	}
 
 	/**
-	* Reference: Closest Point on OBB to Point in Real-Time Collision Detection
-	* by Christer Ericson (chapter 5.1.4)
-	*
-	* @param {Vector3} point
-	* @param {Vector3} result
-	* @returns {Vector3}
-	*/
-	clampPoint( point, result ) {
+	 * Clamps the given point within the bounds of this OBB.
+	 *
+	 * @param {Vector3} point - The point that should be clamped within the bounds of this OBB.
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @returns {Vector3} - The clamped point.
+	 */
+	clampPoint( point, target ) {
+
+		// Reference: Closest Point on OBB to Point in Real-Time Collision Detection
+		// by Christer Ericson (chapter 5.1.4)
 
 		const halfSize = this.halfSize;
 
@@ -98,23 +150,29 @@ class OBB {
 
 		// start at the center position of the OBB
 
-		result.copy( this.center );
+		target.copy( this.center );
 
 		// project the target onto the OBB axes and walk towards that point
 
 		const x = MathUtils.clamp( v1.dot( xAxis ), - halfSize.x, halfSize.x );
-		result.add( xAxis.multiplyScalar( x ) );
+		target.add( xAxis.multiplyScalar( x ) );
 
 		const y = MathUtils.clamp( v1.dot( yAxis ), - halfSize.y, halfSize.y );
-		result.add( yAxis.multiplyScalar( y ) );
+		target.add( yAxis.multiplyScalar( y ) );
 
 		const z = MathUtils.clamp( v1.dot( zAxis ), - halfSize.z, halfSize.z );
-		result.add( zAxis.multiplyScalar( z ) );
+		target.add( zAxis.multiplyScalar( z ) );
 
-		return result;
+		return target;
 
 	}
 
+	/**
+	 * Returns `true` if the given point lies within this OBB.
+	 *
+	 * @param {Vector3} point - The point to test.
+	 * @returns {boolean} - Whether the given point lies within this OBB or not.
+	 */
 	containsPoint( point ) {
 
 		v1.subVectors( point, this.center );
@@ -128,12 +186,24 @@ class OBB {
 
 	}
 
+	/**
+	 * Returns `true` if the given AABB intersects this OBB.
+	 *
+	 * @param {Box3} box3 - The AABB to test.
+	 * @returns {boolean} - Whether the given AABB intersects this OBB or not.
+	 */
 	intersectsBox3( box3 ) {
 
 		return this.intersectsOBB( obb.fromBox3( box3 ) );
 
 	}
 
+	/**
+	 * Returns `true` if the given bounding sphere intersects this OBB.
+	 *
+	 * @param {Sphere} sphere - The bounding sphere to test.
+	 * @returns {boolean} - Whether the given bounding sphere intersects this OBB or not.
+	 */
 	intersectsSphere( sphere ) {
 
 		// find the point on the OBB closest to the sphere center
@@ -147,15 +217,17 @@ class OBB {
 	}
 
 	/**
-	* Reference: OBB-OBB Intersection in Real-Time Collision Detection
-	* by Christer Ericson (chapter 4.4.1)
-	*
-	* @param {OBB} obb
-	* @param {number} [epsilon=Number.EPSILON] - A small value to prevent arithmetic errors
-	* @returns {boolean}
-	*/
+	 * Returns `true` if the given OBB intersects this OBB.
+	 *
+	 * @param {OBB} obb - The OBB to test.
+	 * @param {number} [epsilon=Number.EPSILON] - A small value to prevent arithmetic errors.
+	 * @returns {boolean} - Whether the given OBB intersects this OBB or not.
+	 */
 	intersectsOBB( obb, epsilon = Number.EPSILON ) {
 
+		// Reference: OBB-OBB Intersection in Real-Time Collision Detection
+		// by Christer Ericson (chapter 4.4.1)
+
 		// prepare data structures (the code uses the same nomenclature like the reference)
 
 		a.c = this.center;
@@ -290,14 +362,16 @@ class OBB {
 	}
 
 	/**
-	* Reference: Testing Box Against Plane in Real-Time Collision Detection
-	* by Christer Ericson (chapter 5.2.3)
-	*
-	* @param {Plane} plane
-	* @returns {boolean}
-	*/
+	 * Returns `true` if the given plane intersects this OBB.
+	 *
+	 * @param {Plane} plane - The plane to test.
+	 * @returns {boolean} Whether the given plane intersects this OBB or not.
+	 */
 	intersectsPlane( plane ) {
 
+		// Reference: Testing Box Against Plane in Real-Time Collision Detection
+		// by Christer Ericson (chapter 5.2.3)
+
 		this.rotation.extractBasis( xAxis, yAxis, zAxis );
 
 		// compute the projection interval radius of this OBB onto L(t) = this->center + t * p.normal;
@@ -317,14 +391,14 @@ class OBB {
 	}
 
 	/**
-	* Performs a ray/OBB intersection test and stores the intersection point
-	* to the given 3D vector. If no intersection is detected, *null* is returned.
-	*
-	* @param {Ray} ray
-	* @param {Vector3} result
-	* @return {?Vector3}
-	*/
-	intersectRay( ray, result ) {
+	 * Performs a ray/OBB intersection test and stores the intersection point
+	 * in the given 3D vector.
+	 *
+	 * @param {Ray} ray - The ray to test.
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {?Vector3} The intersection point. If no intersection is detected, `null` is returned.
+	 */
+	intersectRay( ray, target ) {
 
 		// the idea is to perform the intersection test in the local space
 		// of the OBB.
@@ -344,11 +418,11 @@ class OBB {
 
 		// perform ray <-> AABB intersection test
 
-		if ( localRay.intersectBox( aabb, result ) ) {
+		if ( localRay.intersectBox( aabb, target ) ) {
 
 			// transform the intersection point back to world space
 
-			return result.applyMatrix4( matrix );
+			return target.applyMatrix4( matrix );
 
 		} else {
 
@@ -359,18 +433,23 @@ class OBB {
 	}
 
 	/**
-	* Performs a ray/OBB intersection test. Returns either true or false if
-	* there is a intersection or not.
-	*
-	* @param {Ray} ray
-	* @returns {boolean}
-	*/
+	 * Returns `true` if the given ray intersects this OBB.
+	 *
+	 * @param {Ray} ray - The ray to test.
+	 * @returns {boolean} Whether the given ray intersects this OBB or not.
+	 */
 	intersectsRay( ray ) {
 
 		return this.intersectRay( ray, v1 ) !== null;
 
 	}
 
+	/**
+	 * Defines an OBB based on the given AABB.
+	 *
+	 * @param {Box3} box3 - The AABB to setup the OBB from.
+	 * @return {OBB} A reference of this OBB.
+	 */
 	fromBox3( box3 ) {
 
 		box3.getCenter( this.center );
@@ -383,6 +462,12 @@ class OBB {
 
 	}
 
+	/**
+	 * Returns `true` if the given OBB is equal to this OBB.
+	 *
+	 * @param {OBB} obb - The OBB to test.
+	 * @returns {boolean} Whether the given OBB is equal to this OBB or not.
+	 */
 	equals( obb ) {
 
 		return obb.center.equals( this.center ) &&
@@ -391,6 +476,14 @@ class OBB {
 
 	}
 
+	/**
+	 * Applies the given transformation matrix to this OBB. This method can be
+	 * used to transform the bounding volume with the world matrix of a 3D object
+	 * in order to keep both entities in sync.
+	 *
+	 * @param {Matrix4} matrix - The matrix to apply.
+	 * @return {OBB} A reference of this OBB.
+	 */
 	applyMatrix4( matrix ) {
 
 		const e = matrix.elements;