Docs: More JSDoc. (#30662)

examples/jsm/math/Capsule.js

@@ -2,74 +2,138 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * A capsule is essentially a cylinder with hemispherical caps at both ends.
+ * It can be thought of as a swept sphere, where a sphere is moved along a line segment.
+ *
+ * Capsules are often used as bounding volumes (next to AABBs and bounding spheres).
+ */
 class Capsule {
 
+	/**
+	 * Constructs a new capsule.
+	 *
+	 * @param {Vector3} [start] - The start vector.
+	 * @param {Vector3} [end] - The end vector.
+	 * @param {number} [radius=1] - The capsule's radius.
+	 */
 	constructor( start = new Vector3( 0, 0, 0 ), end = new Vector3( 0, 1, 0 ), radius = 1 ) {
 
+		/**
+		 * The start vector.
+		 *
+		 * @type {Vector3}
+		 */
 		this.start = start;
+
+		/**
+		 * The end vector.
+		 *
+		 * @type {Vector3}
+		 */
 		this.end = end;
+
+		/**
+		 * The capsule's radius.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.radius = radius;
 
 	}
 
+	/**
+	 * Returns a new capsule with copied values from this instance.
+	 *
+	 * @return {Capsule} A clone of this instance.
+	 */
 	clone() {
 
-		return new Capsule( this.start.clone(), this.end.clone(), this.radius );
+		return new this.constructor().copy( this );
 
 	}
 
+	/**
+	 * Sets the capsule components to the given values.
+	 * Please note that this method only copies the values from the given objects.
+	 *
+	 * @param {Vector3} start - The start vector.
+	 * @param {Vector3} end - The end vector
+	 * @param {number} radius - The capsule's radius.
+	 * @return {Box2} A reference to this bounding box.
+	 */
 	set( start, end, radius ) {
 
 		this.start.copy( start );
 		this.end.copy( end );
 		this.radius = radius;
 
+		return this;
+
 	}
 
+	/**
+	 * Copies the values of the given capsule to this instance.
+	 *
+	 * @param {Capsule} capsule - The capsule to copy.
+	 * @return {Capsule} A reference to this capsule.
+	 */
 	copy( capsule ) {
 
 		this.start.copy( capsule.start );
 		this.end.copy( capsule.end );
 		this.radius = capsule.radius;
 
+		return this;
+
 	}
 
+	/**
+	 * Returns the center point of this capsule.
+	 *
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {Vector3} The center point.
+	 */
 	getCenter( target ) {
 
 		return target.copy( this.end ).add( this.start ).multiplyScalar( 0.5 );
 
 	}
 
+	/**
+	 * Adds the given offset to this capsule, effectively moving it in 3D space.
+	 *
+	 * @param {Vector3} v - The offset that should be used to translate the capsule.
+	 * @return {Capsule} A reference to this capsule.
+	 */
 	translate( v ) {
 
 		this.start.add( v );
 		this.end.add( v );
 
-	}
-
-	checkAABBAxis( p1x, p1y, p2x, p2y, minx, maxx, miny, maxy, radius ) {
-
-		return (
-			( minx - p1x < radius || minx - p2x < radius ) &&
-			( p1x - maxx < radius || p2x - maxx < radius ) &&
-			( miny - p1y < radius || miny - p2y < radius ) &&
-			( p1y - maxy < radius || p2y - maxy < radius )
-		);
+		return this;
 
 	}
 
+	/**
+	 * Returns `true` if the given bounding box intersects with this capsule.
+	 *
+	 * @param {Box3} box - The bounding box to test.
+	 * @return {boolean} Whether the given bounding box intersects with this capsule.
+	 */
 	intersectsBox( box ) {
 
 		return (
-			this.checkAABBAxis(
+			checkAABBAxis(
 				this.start.x, this.start.y, this.end.x, this.end.y,
 				box.min.x, box.max.x, box.min.y, box.max.y,
 				this.radius ) &&
-			this.checkAABBAxis(
+			checkAABBAxis(
 				this.start.x, this.start.z, this.end.x, this.end.z,
 				box.min.x, box.max.x, box.min.z, box.max.z,
 				this.radius ) &&
-			this.checkAABBAxis(
+			checkAABBAxis(
 				this.start.y, this.start.z, this.end.y, this.end.z,
 				box.min.y, box.max.y, box.min.z, box.max.z,
 				this.radius )
@@ -79,4 +143,15 @@ class Capsule {
 
 }
 
+function checkAABBAxis( p1x, p1y, p2x, p2y, minx, maxx, miny, maxy, radius ) {
+
+	return (
+		( minx - p1x < radius || minx - p2x < radius ) &&
+		( p1x - maxx < radius || p2x - maxx < radius ) &&
+		( miny - p1y < radius || miny - p2y < radius ) &&
+		( p1y - maxy < radius || p2y - maxy < radius )
+	);
+
+}
+
 export { Capsule };

examples/jsm/math/ColorConverter.js

@@ -2,8 +2,22 @@ import { MathUtils } from 'three';
 
 const _hsl = {};
 
+/**
+ * A utility class with helper functions for color conversion.
+ *
+ * @hideconstructor
+ */
 class ColorConverter {
 
+	/**
+	 * Sets the given HSV color definition to the given color object.
+	 *
+	 * @param {Color} color - The color to set.
+	 * @param {number} h - The hue.
+	 * @param {number} s - The saturation.
+	 * @param {number} v - The value.
+	 * @return {Color} The update color.
+	 */
 	static setHSV( color, h, s, v ) {
 
 		// https://gist.github.com/xpansive/1337890#file-index-js
@@ -16,6 +30,13 @@ class ColorConverter {
 
 	}
 
+	/**
+	 * Returns a HSV color representation of the given color object.
+	 *
+	 * @param {Color} color - The color to get HSV values from.
+	 * @param {{h:number,s:number,v:number}} target - The target object that is used to store the method's result.
+	 * @return {{h:number,s:number,v:number}} The HSV color.
+	 */
 	static getHSV( color, target ) {
 
 		color.getHSL( _hsl );

examples/jsm/math/ColorSpaces.js

@@ -1,5 +1,7 @@
 import { LinearTransfer, Matrix3, SRGBTransfer } from 'three';
 
+/** @module ColorSpaces */
+
 // Reference: http://www.russellcottrell.com/photo/matrixCalculator.htm
 
 const P3_PRIMARIES = [ 0.680, 0.320, 0.265, 0.690, 0.150, 0.060 ];
@@ -24,9 +26,28 @@ const XYZ_TO_LINEAR_DISPLAY_P3 = /*@__PURE__*/ new Matrix3().set(
 	0.0358458, - 0.0761724, 0.9568845
 );
 
+/**
+ * Display-P3 color space.
+ *
+ * @type {string}
+ * @constant
+ */
 export const DisplayP3ColorSpace = 'display-p3';
+
+/**
+ * Display-P3-Linear color space.
+ *
+ * @type {string}
+ * @constant
+ */
 export const LinearDisplayP3ColorSpace = 'display-p3-linear';
 
+/**
+ * Implementation object for the Display-P3 color space.
+ *
+ * @type {module:ColorSpaces~ColorSpaceImpl}
+ * @constant
+ */
 export const DisplayP3ColorSpaceImpl = {
 	primaries: P3_PRIMARIES,
 	whitePoint: D65,
@@ -37,6 +58,12 @@ export const DisplayP3ColorSpaceImpl = {
 	outputColorSpaceConfig: { drawingBufferColorSpace: DisplayP3ColorSpace }
 };
 
+/**
+ * Implementation object for the Display-P3-Linear color space.
+ *
+ * @type {module:ColorSpaces~ColorSpaceImpl}
+ * @constant
+ */
 export const LinearDisplayP3ColorSpaceImpl = {
 	primaries: P3_PRIMARIES,
 	whitePoint: D65,
@@ -64,8 +91,20 @@ const XYZ_TO_LINEAR_REC2020 = /*@__PURE__*/ new Matrix3().set(
 	0.0176399, - 0.0427706, 0.9421031
 );
 
+/**
+ * Rec2020-Linear color space.
+ *
+ * @type {string}
+ * @constant
+ */
 export const LinearRec2020ColorSpace = 'rec2020-linear';
 
+/**
+ * Implementation object for the Rec2020-Linear color space.
+ *
+ * @type {module:ColorSpaces~ColorSpaceImpl}
+ * @constant
+ */
 export const LinearRec2020ColorSpaceImpl = {
 	primaries: REC2020_PRIMARIES,
 	whitePoint: D65,
@@ -74,3 +113,17 @@ export const LinearRec2020ColorSpaceImpl = {
 	fromXYZ: XYZ_TO_LINEAR_REC2020,
 	luminanceCoefficients: REC2020_LUMINANCE_COEFFICIENTS,
 };
+
+
+/**
+ * An object holding the color space implementation.
+ *
+ * @typedef {Object} module:ColorSpaces~ColorSpaceImpl
+ * @property {Array<number>} primaries - The primaries.
+ * @property {Array<number>} whitePoint - The white point.
+ * @property {Matrix3} toXYZ - A color space conversion matrix, converting to CIE XYZ.
+ * @property {Matrix3} fromXYZ - A color space conversion matrix, converting from CIE XYZ.
+ * @property {Array<number>} luminanceCoefficients - The luminance coefficients.
+ * @property {{unpackColorSpace:string}} [workingColorSpaceConfig] - The working color space config.
+ * @property {{drawingBufferColorSpace:string}} [outputColorSpaceConfig] - The drawing buffer color space config.
+ **/

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 );

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

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();

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;

examples/jsm/math/Octree.js

@@ -81,19 +81,67 @@ function lineToLineClosestPoints( line1, line2, target1 = null, target2 = null )
 
 }
 
+/**
+ * An octree is a hierarchical tree data structure used to partition a three-dimensional
+ * space by recursively subdividing it into eight octants.
+ *
+ * This particular implementation can have up to sixteen levels and stores up to eight triangles
+ * in leaf nodes.
+ *
+ * `Octree` can be used in games to compute collision between the game world and colliders from
+ * the player or other dynamic 3D objects.
+ *
+ *
+ * ```js
+ * const octree = new Octree().fromGraphNode( scene );
+ * const result = octree.capsuleIntersect( playerCollider ); // collision detection
+ * ```
+ */
 class Octree {
 
+	/**
+	 * Constructs a new Octree.
+	 *
+	 * @param {Box3} [box] - The base box with enclose the entire Octree.
+	 */
 	constructor( box ) {
 
+		/**
+		 * The base box with enclose the entire Octree.
+		 *
+		 * @type {Box3}
+		 */
 		this.box = box;
+
+		/**
+		 * The bounds of the Octree. Compared to {@link Octree#box}, no
+		 * margin is applied.
+		 *
+		 * @type {Box3}
+		 */
 		this.bounds = new Box3();
 
+		/**
+		 * Can by used for layers configuration for refine testing.
+		 *
+		 * @type {Layers}
+		 */
+		this.layers = new Layers();
+
+		// private
+
 		this.subTrees = [];
 		this.triangles = [];
-		this.layers = new Layers();
 
 	}
 
+	/**
+	 * Adds the given triangle to the Octree. The triangle vertices are clampled if they exceed
+	 * the bounds of the Octree.
+	 *
+	 * @param {Triangle} triangle - The triangle to add.
+	 * @return {Octree} A reference to this Octree.
+	 */
 	addTriangle( triangle ) {
 
 		this.bounds.min.x = Math.min( this.bounds.min.x, triangle.a.x, triangle.b.x, triangle.c.x );
@@ -109,6 +157,11 @@ class Octree {
 
 	}
 
+	/**
+	 * Prepares {@link Octree#box} for the build.
+	 *
+	 * @return {Octree} A reference to this Octree.
+	 */
 	calcBox() {
 
 		this.box = this.bounds.clone();
@@ -122,6 +175,13 @@ class Octree {
 
 	}
 
+	/**
+	 * Splits the Octree. This method is used recursively when
+	 * building the Octree.
+	 *
+	 * @param {number} level - The current level.
+	 * @return {Octree} A reference to this Octree.
+	 */
 	split( level ) {
 
 		if ( ! this.box ) return;
@@ -187,6 +247,11 @@ class Octree {
 
 	}
 
+	/**
+	 * Builds the Octree.
+	 *
+	 * @return {Octree} A reference to this Octree.
+	 */
 	build() {
 
 		this.calcBox();
@@ -196,6 +261,12 @@ class Octree {
 
 	}
 
+	/**
+	 * Computes the triangles that potentially intersect with the given ray.
+	 *
+	 * @param {Ray} ray - The ray to test.
+	 * @param {Array<Triangle>} triangles - The target array that holds the triangles.
+	 */
 	getRayTriangles( ray, triangles ) {
 
 		for ( let i = 0; i < this.subTrees.length; i ++ ) {
@@ -219,10 +290,16 @@ class Octree {
 
 		}
 
-		return triangles;
-
 	}
 
+	/**
+	 * Computes the intersection between the given capsule and triangle.
+	 *
+	 * @param {Capsule} capsule - The capsule to test.
+	 * @param {Triangle} triangle - The triangle to test.
+	 * @return {Object|false} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	triangleCapsuleIntersect( capsule, triangle ) {
 
 		triangle.getPlane( _plane );
@@ -277,6 +354,14 @@ class Octree {
 
 	}
 
+	/**
+	 * Computes the intersection between the given sphere and triangle.
+	 *
+	 * @param {Sphere} sphere - The sphere to test.
+	 * @param {Triangle} triangle - The triangle to test.
+	 * @return {Object|false} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	triangleSphereIntersect( sphere, triangle ) {
 
 		triangle.getPlane( _plane );
@@ -319,6 +404,12 @@ class Octree {
 
 	}
 
+	/**
+	 * Computes the triangles that potentially intersect with the given bounding sphere.
+	 *
+	 * @param {Sphere} sphere - The sphere to test.
+	 * @param {Array<Triangle>} triangles - The target array that holds the triangles.
+	 */
 	getSphereTriangles( sphere, triangles ) {
 
 		for ( let i = 0; i < this.subTrees.length; i ++ ) {
@@ -345,6 +436,12 @@ class Octree {
 
 	}
 
+	/**
+	 * Computes the triangles that potentially intersect with the given capsule.
+	 *
+	 * @param {Capsule} capsule - The capsule to test.
+	 * @param {Array<Triangle>} triangles - The target array that holds the triangles.
+	 */
 	getCapsuleTriangles( capsule, triangles ) {
 
 		for ( let i = 0; i < this.subTrees.length; i ++ ) {
@@ -371,6 +468,13 @@ class Octree {
 
 	}
 
+	/**
+	 * Performs a bounding sphere intersection test with this Octree.
+	 *
+	 * @param {Sphere} sphere - The bounding sphere to test.
+	 * @return {Object|boolean} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	sphereIntersect( sphere ) {
 
 		_sphere.copy( sphere );
@@ -405,6 +509,13 @@ class Octree {
 
 	}
 
+	/**
+	 * Performs a capsule intersection test with this Octree.
+	 *
+	 * @param {Capsule} capsule - The capsule to test.
+	 * @return {Object|boolean} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	capsuleIntersect( capsule ) {
 
 		_capsule.copy( capsule );
@@ -439,10 +550,15 @@ class Octree {
 
 	}
 
+	/**
+	 * Performs a ray intersection test with this Octree.
+	 *
+	 * @param {Ray} ray - The ray to test.
+	 * @return {Object|boolean} The nearest intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	rayIntersect( ray ) {
 
-		if ( ray.direction.length() === 0 ) return;
-
 		const triangles = [];
 		let triangle, position, distance = 1e100;
 
@@ -472,6 +588,12 @@ class Octree {
 
 	}
 
+	/**
+	 * Constructs the Octree from the given 3D object.
+	 *
+	 * @param {Object3D} group - The scene graph node.
+	 * @return {Octree} A reference to this Octree.
+	 */
 	fromGraphNode( group ) {
 
 		group.updateWorldMatrix( true, true );
@@ -529,6 +651,11 @@ class Octree {
 
 	}
 
+	/**
+	 * Clears the Octree by making it empty.
+	 *
+	 * @return {Octree} A reference to this Octree.
+	 */
 	clear() {
 
 		this.box = null;

examples/jsm/math/SimplexNoise.js

@@ -1,17 +1,17 @@
-// Ported from Stefan Gustavson's java implementation
-// http://staffwww.itn.liu.se/~stegu/simplexnoise/simplexnoise.pdf
-// Read Stefan's excellent paper for details on how this code works.
-//
-// Sean McCullough banksean@gmail.com
-//
-// Added 4D noise
-
 /**
- * You can pass in a random number generator object if you like.
- * It is assumed to have a random() method.
+ * A utility class providing noise functions.
+ *
+ * The code is based on [Simplex noise demystified]{@link https://web.archive.org/web/20210210162332/http://staffwww.itn.liu.se/~stegu/simplexnoise/simplexnoise.pdf}
+ * by Stefan Gustavson, 2005.
  */
 class SimplexNoise {
 
+	/**
+	 * Constructs a new simplex noise object.
+	 *
+	 * @param {Object} [r=Math] - A math utility class that holds a `random()` method. This makes it
+	 * possiblet o pass in custom random number generator.
+	 */
 	constructor( r = Math ) {
 
 		this.grad3 = [[ 1, 1, 0 ], [ - 1, 1, 0 ], [ 1, - 1, 0 ], [ - 1, - 1, 0 ],
@@ -58,24 +58,13 @@ class SimplexNoise {
 
 	}
 
-	dot( g, x, y ) {
-
-		return g[ 0 ] * x + g[ 1 ] * y;
-
-	}
-
-	dot3( g, x, y, z ) {
-
-		return g[ 0 ] * x + g[ 1 ] * y + g[ 2 ] * z;
-
-	}
-
-	dot4( g, x, y, z, w ) {
-
-		return g[ 0 ] * x + g[ 1 ] * y + g[ 2 ] * z + g[ 3 ] * w;
-
-	}
-
+	/**
+	 * A 2D simplex noise method.
+	 *
+	 * @param {number} xin - The x coordinate.
+	 * @param {number} yin - The y coordinate.
+	 * @return {number} The noise value.
+	 */
 	noise( xin, yin ) {
 
 		let n0; // Noise contributions from the three corners
@@ -129,7 +118,7 @@ class SimplexNoise {
 		else {
 
 			t0 *= t0;
-			n0 = t0 * t0 * this.dot( this.grad3[ gi0 ], x0, y0 ); // (x,y) of grad3 used for 2D gradient
+			n0 = t0 * t0 * this._dot( this.grad3[ gi0 ], x0, y0 ); // (x,y) of grad3 used for 2D gradient
 
 		}
 
@@ -138,7 +127,7 @@ class SimplexNoise {
 		else {
 
 			t1 *= t1;
-			n1 = t1 * t1 * this.dot( this.grad3[ gi1 ], x1, y1 );
+			n1 = t1 * t1 * this._dot( this.grad3[ gi1 ], x1, y1 );
 
 		}
 
@@ -147,7 +136,7 @@ class SimplexNoise {
 		else {
 
 			t2 *= t2;
-			n2 = t2 * t2 * this.dot( this.grad3[ gi2 ], x2, y2 );
+			n2 = t2 * t2 * this._dot( this.grad3[ gi2 ], x2, y2 );
 
 		}
 
@@ -157,7 +146,14 @@ class SimplexNoise {
 
 	}
 
-	// 3D simplex noise
+	/**
+	 * A 3D simplex noise method.
+	 *
+	 * @param {number} xin - The x coordinate.
+	 * @param {number} yin - The y coordinate.
+	 * @param {number} zin - The z coordinate.
+	 * @return {number} The noise value.
+	 */
 	noise3d( xin, yin, zin ) {
 
 		let n0; // Noise contributions from the four corners
@@ -257,7 +253,7 @@ class SimplexNoise {
 		else {
 
 			t0 *= t0;
-			n0 = t0 * t0 * this.dot3( this.grad3[ gi0 ], x0, y0, z0 );
+			n0 = t0 * t0 * this._dot3( this.grad3[ gi0 ], x0, y0, z0 );
 
 		}
 
@@ -266,7 +262,7 @@ class SimplexNoise {
 		else {
 
 			t1 *= t1;
-			n1 = t1 * t1 * this.dot3( this.grad3[ gi1 ], x1, y1, z1 );
+			n1 = t1 * t1 * this._dot3( this.grad3[ gi1 ], x1, y1, z1 );
 
 		}
 
@@ -275,7 +271,7 @@ class SimplexNoise {
 		else {
 
 			t2 *= t2;
-			n2 = t2 * t2 * this.dot3( this.grad3[ gi2 ], x2, y2, z2 );
+			n2 = t2 * t2 * this._dot3( this.grad3[ gi2 ], x2, y2, z2 );
 
 		}
 
@@ -284,7 +280,7 @@ class SimplexNoise {
 		else {
 
 			t3 *= t3;
-			n3 = t3 * t3 * this.dot3( this.grad3[ gi3 ], x3, y3, z3 );
+			n3 = t3 * t3 * this._dot3( this.grad3[ gi3 ], x3, y3, z3 );
 
 		}
 
@@ -294,7 +290,15 @@ class SimplexNoise {
 
 	}
 
-	// 4D simplex noise
+	/**
+	 * A 4D simplex noise method.
+	 *
+	 * @param {number} x - The x coordinate.
+	 * @param {number} y - The y coordinate.
+	 * @param {number} z - The z coordinate.
+	 * @param {number} w - The w coordinate.
+	 * @return {number} The noise value.
+	 */
 	noise4d( x, y, z, w ) {
 
 		// For faster and easier lookups
@@ -394,7 +398,7 @@ class SimplexNoise {
 		else {
 
 			t0 *= t0;
-			n0 = t0 * t0 * this.dot4( grad4[ gi0 ], x0, y0, z0, w0 );
+			n0 = t0 * t0 * this._dot4( grad4[ gi0 ], x0, y0, z0, w0 );
 
 		}
 
@@ -403,7 +407,7 @@ class SimplexNoise {
 		else {
 
 			t1 *= t1;
-			n1 = t1 * t1 * this.dot4( grad4[ gi1 ], x1, y1, z1, w1 );
+			n1 = t1 * t1 * this._dot4( grad4[ gi1 ], x1, y1, z1, w1 );
 
 		}
 
@@ -412,7 +416,7 @@ class SimplexNoise {
 		else {
 
 			t2 *= t2;
-			n2 = t2 * t2 * this.dot4( grad4[ gi2 ], x2, y2, z2, w2 );
+			n2 = t2 * t2 * this._dot4( grad4[ gi2 ], x2, y2, z2, w2 );
 
 		}
 
@@ -421,7 +425,7 @@ class SimplexNoise {
 		else {
 
 			t3 *= t3;
-			n3 = t3 * t3 * this.dot4( grad4[ gi3 ], x3, y3, z3, w3 );
+			n3 = t3 * t3 * this._dot4( grad4[ gi3 ], x3, y3, z3, w3 );
 
 		}
 
@@ -430,7 +434,7 @@ class SimplexNoise {
 		else {
 
 			t4 *= t4;
-			n4 = t4 * t4 * this.dot4( grad4[ gi4 ], x4, y4, z4, w4 );
+			n4 = t4 * t4 * this._dot4( grad4[ gi4 ], x4, y4, z4, w4 );
 
 		}
 
@@ -439,6 +443,26 @@ class SimplexNoise {
 
 	}
 
+	// private
+
+	_dot( g, x, y ) {
+
+		return g[ 0 ] * x + g[ 1 ] * y;
+
+	}
+
+	_dot3( g, x, y, z ) {
+
+		return g[ 0 ] * x + g[ 1 ] * y + g[ 2 ] * z;
+
+	}
+
+	_dot4( g, x, y, z, w ) {
+
+		return g[ 0 ] * x + g[ 1 ] * y + g[ 2 ] * z + g[ 3 ] * w;
+
+	}
+
 }
 
 export { SimplexNoise };

utils/docs/jsdoc.config.json

@@ -27,6 +27,7 @@
             "examples/jsm/lights",
             "examples/jsm/lines",
             "examples/jsm/materials",
+            "examples/jsm/math",
             "examples/jsm/modifiers",
             "examples/jsm/renderers",
             "examples/jsm/textures",