@needle-tools/three 0.169.20 → 0.183.2-canary.0

package/examples/jsm/math/ImprovedNoise.js

@@ -1,4 +1,6 @@
-// https://cs.nyu.edu/~perlin/noise/
+import { MathUtils } from 'three';
+
+const { lerp } = MathUtils;
 
 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,
@@ -23,12 +25,6 @@ function fade( t ) {
 
 }
 
-function lerp( t, a, b ) {
-
-	return a + t * ( b - a );
-
-}
-
 function grad( hash, x, y, z ) {
 
 	const h = hash & 15;
@@ -37,8 +33,24 @@ function grad( hash, x, y, z ) {
 
 }
 
+/**
+ * A utility class providing a 3D noise function.
+ *
+ * The code is based on [IMPROVED NOISE](https://cs.nyu.edu/~perlin/noise/)
+ * by Ken Perlin, 2002.
+ *
+ * @three_import import { ImprovedNoise } from 'three/addons/math/ImprovedNoise.js';
+ */
 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 );
@@ -55,14 +67,19 @@ class ImprovedNoise {
 
 		const A = _p[ X ] + Y, AA = _p[ A ] + Z, AB = _p[ A + 1 ] + Z, B = _p[ X + 1 ] + Y, BA = _p[ B ] + Z, BB = _p[ B + 1 ] + Z;
 
-		return lerp( w, lerp( v, lerp( u, grad( _p[ AA ], x, y, z ),
-			grad( _p[ BA ], xMinus1, y, z ) ),
-		lerp( u, grad( _p[ AB ], x, yMinus1, z ),
-			grad( _p[ BB ], xMinus1, yMinus1, z ) ) ),
-		lerp( v, lerp( u, grad( _p[ AA + 1 ], x, y, zMinus1 ),
-			grad( _p[ BA + 1 ], xMinus1, y, zMinus1 ) ),
-		lerp( u, grad( _p[ AB + 1 ], x, yMinus1, zMinus1 ),
-			grad( _p[ BB + 1 ], xMinus1, yMinus1, zMinus1 ) ) ) );
+		return lerp(
+			lerp(
+				lerp( grad( _p[ AA ], x, y, z ), grad( _p[ BA ], xMinus1, y, z ), u ),
+				lerp( grad( _p[ AB ], x, yMinus1, z ), grad( _p[ BB ], xMinus1, yMinus1, z ), u ),
+				v
+			),
+			lerp(
+				lerp( grad( _p[ AA + 1 ], x, y, zMinus1 ), grad( _p[ BA + 1 ], xMinus1, y, zMinus1 ), u ),
+				lerp( grad( _p[ AB + 1 ], x, yMinus1, zMinus1 ), grad( _p[ BB + 1 ], xMinus1, yMinus1, zMinus1 ), u ),
+				v
+			),
+			w
+		);
 
 	}
 

package/examples/jsm/math/Lut.js

@@ -4,22 +4,85 @@ 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 );
+ * ```
+ *
+ * @three_import import { Lut } from 'three/addons/math/Lut.js';
+ */
 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<Array<number>>}
+		 */
 		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 +95,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 +109,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 +123,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 +179,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 +197,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 +215,14 @@ class Lut {
 
 	}
 
+	/**
+	 * Adds a color map to this Lut instance.
+	 *
+	 * @param {string} name - The name of the color map.
+	 * @param {Array<Array<number>>} 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 +231,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 +248,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,41 @@ 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 );
+ * ```
+ *
+ * @three_import import { MeshSurfaceSampler } from 'three/addons/math/MeshSurfaceSampler.js';
  */
-
-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 +66,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 +84,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 +153,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 +166,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 +227,7 @@ class MeshSurfaceSampler {
 
 	}
 
-	sampleFace( faceIndex, targetPosition, targetNormal, targetColor, targetUV ) {
+	_sampleFace( faceIndex, targetPosition, targetNormal, targetColor, targetUV ) {
 
 		let u = this.randomFunction();
 		let v = this.randomFunction();