super-three 0.173.5 → 0.175.0

package/src/helpers/ArrowHelper.js

@@ -11,10 +11,37 @@ import { Vector3 } from '../math/Vector3.js';
 const _axis = /*@__PURE__*/ new Vector3();
 let _lineGeometry, _coneGeometry;
 
+/**
+ * An 3D arrow object for visualizing directions.
+ *
+ * ```js
+ * const dir = new THREE.Vector3( 1, 2, 0 );
+ *
+ * //normalize the direction vector (convert to vector of length 1)
+ * dir.normalize();
+ *
+ * const origin = new THREE.Vector3( 0, 0, 0 );
+ * const length = 1;
+ * const hex = 0xffff00;
+ *
+ * const arrowHelper = new THREE.ArrowHelper( dir, origin, length, hex );
+ * scene.add( arrowHelper );
+ * ```
+ *
+ * @augments Object3D
+ */
 class ArrowHelper extends Object3D {
 
-	// dir is assumed to be normalized
-
+	/**
+	 * Constructs a new arrow helper.
+	 *
+	 * @param {Vector3} [dir=(0, 0, 1)] - The (normalized) direction vector.
+	 * @param {Vector3} [origin=(0, 0, 0)] - Point at which the arrow starts.
+	 * @param {number} [length=1] - Length of the arrow in world units.
+	 * @param {(number|Color|string)} [color=0xffff00] - Color of the arrow.
+	 * @param {number} [headLength=length*0.2] - The length of the head of the arrow.
+	 * @param {number} [headWidth=headLength*0.2] - The width of the head of the arrow.
+	 */
 	constructor( dir = new Vector3( 0, 0, 1 ), origin = new Vector3( 0, 0, 0 ), length = 1, color = 0xffff00, headLength = length * 0.2, headWidth = headLength * 0.2 ) {
 
 		super();
@@ -33,10 +60,20 @@ class ArrowHelper extends Object3D {
 
 		this.position.copy( origin );
 
+		/**
+		 * The line part of the arrow helper.
+		 *
+		 * @type {Line}
+		 */
 		this.line = new Line( _lineGeometry, new LineBasicMaterial( { color: color, toneMapped: false } ) );
 		this.line.matrixAutoUpdate = false;
 		this.add( this.line );
 
+		/**
+		 * The cone part of the arrow helper.
+		 *
+		 * @type {Mesh}
+		 */
 		this.cone = new Mesh( _coneGeometry, new MeshBasicMaterial( { color: color, toneMapped: false } ) );
 		this.cone.matrixAutoUpdate = false;
 		this.add( this.cone );
@@ -46,6 +83,11 @@ class ArrowHelper extends Object3D {
 
 	}
 
+	/**
+	 * Sets the direction of the helper.
+	 *
+	 * @param {Vector3} dir - The normalized direction vector.
+	 */
 	setDirection( dir ) {
 
 		// dir is assumed to be normalized
@@ -70,6 +112,13 @@ class ArrowHelper extends Object3D {
 
 	}
 
+	/**
+	 * Sets the length of the helper.
+	 *
+	 * @param {number} length - Length of the arrow in world units.
+	 * @param {number} [headLength=length*0.2] - The length of the head of the arrow.
+	 * @param {number} [headWidth=headLength*0.2] - The width of the head of the arrow.
+	 */
 	setLength( length, headLength = length * 0.2, headWidth = headLength * 0.2 ) {
 
 		this.line.scale.set( 1, Math.max( 0.0001, length - headLength ), 1 ); // see #17458
@@ -81,6 +130,11 @@ class ArrowHelper extends Object3D {
 
 	}
 
+	/**
+	 * Sets the color of the helper.
+	 *
+	 * @param {number|Color|string} color - The color to set.
+	 */
 	setColor( color ) {
 
 		this.line.material.color.set( color );
@@ -99,6 +153,10 @@ class ArrowHelper extends Object3D {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.line.geometry.dispose();
@@ -110,5 +168,4 @@ class ArrowHelper extends Object3D {
 
 }
 
-
 export { ArrowHelper };

package/src/helpers/AxesHelper.js

@@ -4,8 +4,24 @@ import { Float32BufferAttribute } from '../core/BufferAttribute.js';
 import { BufferGeometry } from '../core/BufferGeometry.js';
 import { Color } from '../math/Color.js';
 
+/**
+ * An axis object to visualize the 3 axes in a simple way.
+ * The X axis is red. The Y axis is green. The Z axis is blue.
+ *
+ * ```js
+ * const axesHelper = new THREE.AxesHelper( 5 );
+ * scene.add( axesHelper );
+ * ```
+ *
+ * @augments LineSegments
+ */
 class AxesHelper extends LineSegments {
 
+	/**
+	 * Constructs a new axes helper.
+	 *
+	 * @param {number} [size=1] - Size of the lines representing the axes.
+	 */
 	constructor( size = 1 ) {
 
 		const vertices = [
@@ -32,6 +48,14 @@ class AxesHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Defines the colors of the axes helper.
+	 *
+	 * @param {number|Color|string} xAxisColor - The color for the x axis.
+	 * @param {number|Color|string} yAxisColor - The color for the y axis.
+	 * @param {number|Color|string} zAxisColor - The color for the z axis.
+	 * @return {AxesHelper} A reference to this axes helper.
+	 */
 	setColors( xAxisColor, yAxisColor, zAxisColor ) {
 
 		const color = new Color();
@@ -55,6 +79,10 @@ class AxesHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.geometry.dispose();

package/src/helpers/Box3Helper.js

@@ -3,8 +3,27 @@ import { LineBasicMaterial } from '../materials/LineBasicMaterial.js';
 import { BufferAttribute, Float32BufferAttribute } from '../core/BufferAttribute.js';
 import { BufferGeometry } from '../core/BufferGeometry.js';
 
+/**
+ * A helper object to visualize an instance of {@link Box3}.
+ *
+ * ```js
+ * const box = new THREE.Box3();
+ * box.setFromCenterAndSize( new THREE.Vector3( 1, 1, 1 ), new THREE.Vector3( 2, 1, 3 ) );
+ *
+ * const helper = new THREE.Box3Helper( box, 0xffff00 );
+ * scene.add( helper )
+ * ```
+ *
+ * @augments LineSegments
+ */
 class Box3Helper extends LineSegments {
 
+	/**
+	 * Constructs a new box3 helper.
+	 *
+	 * @param {Box3} box - The box to visualize.
+	 * @param {number|Color|string} [color=0xffff00] - The box's color.
+	 */
 	constructor( box, color = 0xffff00 ) {
 
 		const indices = new Uint16Array( [ 0, 1, 1, 2, 2, 3, 3, 0, 4, 5, 5, 6, 6, 7, 7, 4, 0, 4, 1, 5, 2, 6, 3, 7 ] );
@@ -19,6 +38,11 @@ class Box3Helper extends LineSegments {
 
 		super( geometry, new LineBasicMaterial( { color: color, toneMapped: false } ) );
 
+		/**
+		 * The box being visualized.
+		 *
+		 * @type {Box3}
+		 */
 		this.box = box;
 
 		this.type = 'Box3Helper';
@@ -43,6 +67,10 @@ class Box3Helper extends LineSegments {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.geometry.dispose();

package/src/helpers/BoxHelper.js

@@ -6,8 +6,31 @@ import { BufferGeometry } from '../core/BufferGeometry.js';
 
 const _box = /*@__PURE__*/ new Box3();
 
+/**
+ * Helper object to graphically show the world-axis-aligned bounding box
+ * around an object. The actual bounding box is handled with {@link Box3},
+ * this is just a visual helper for debugging. It can be automatically
+ * resized with {@link BoxHelper#update} when the object it's created from
+ * is transformed. Note that the object must have a geometry for this to work,
+ * so it won't work with sprites.
+ *
+ * ```js
+ * const sphere = new THREE.SphereGeometry();
+ * const object = new THREE.Mesh( sphere, new THREE.MeshBasicMaterial( 0xff0000 ) );
+ * const box = new THREE.BoxHelper( object, 0xffff00 );
+ * scene.add( box );
+ * ```
+ *
+ * @augments LineSegments
+ */
 class BoxHelper extends LineSegments {
 
+	/**
+	 * Constructs a new box helper.
+	 *
+	 * @param {Object3D} [object] - The 3D object to show the world-axis-aligned bounding box.
+	 * @param {number|Color|string} [color=0xffff00] - The box's color.
+	 */
 	constructor( object, color = 0xffff00 ) {
 
 		const indices = new Uint16Array( [ 0, 1, 1, 2, 2, 3, 3, 0, 4, 5, 5, 6, 6, 7, 7, 4, 0, 4, 1, 5, 2, 6, 3, 7 ] );
@@ -19,6 +42,11 @@ class BoxHelper extends LineSegments {
 
 		super( geometry, new LineBasicMaterial( { color: color, toneMapped: false } ) );
 
+		/**
+		 * The 3D object being visualized.
+		 *
+		 * @type {Object3D}
+		 */
 		this.object = object;
 		this.type = 'BoxHelper';
 
@@ -28,13 +56,11 @@ class BoxHelper extends LineSegments {
 
 	}
 
-	update( object ) {
-
-		if ( object !== undefined ) {
-
-			console.warn( 'THREE.BoxHelper: .update() has no longer arguments.' );
-
-		}
+	/**
+	 * Updates the helper's geometry to match the dimensions of the object,
+	 * including any children.
+	 */
+	update() {
 
 		if ( this.object !== undefined ) {
 
@@ -81,6 +107,12 @@ class BoxHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Updates the wireframe box for the passed object.
+	 *
+	 * @param {Object3D} object - The 3D object to create the helper for.
+	 * @return {BoxHelper} A reference to this instance.
+	 */
 	setFromObject( object ) {
 
 		this.object = object;
@@ -100,6 +132,10 @@ class BoxHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.geometry.dispose();

package/src/helpers/CameraHelper.js

@@ -11,14 +11,28 @@ const _vector = /*@__PURE__*/ new Vector3();
 const _camera = /*@__PURE__*/ new Camera();
 
 /**
- *	- shows frustum, line of sight and up of the camera
- *	- suitable for fast updates
- * 	- based on frustum visualization in lightgl.js shadowmap example
- *		https://github.com/evanw/lightgl.js/blob/master/tests/shadowmap.html
+ * This helps with visualizing what a camera contains in its frustum. It
+ * visualizes the frustum of a camera using a line segments.
+ *
+ * Based on frustum visualization in [lightgl.js shadowmap example]{@link https://github.com/evanw/lightgl.js/blob/master/tests/shadowmap.html}.
+ *
+ * `CameraHelper` must be a child of the scene.
+ *
+ * ```js
+ * const camera = new THREE.PerspectiveCamera( 75, window.innerWidth / window.innerHeight, 0.1, 1000 );
+ * const helper = new THREE.CameraHelper( camera );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments LineSegments
  */
-
 class CameraHelper extends LineSegments {
 
+	/**
+	 * Constructs a new arrow helper.
+	 *
+	 * @param {Camera} camera - The camera to visualize.
+	 */
 	constructor( camera ) {
 
 		const geometry = new BufferGeometry();
@@ -105,12 +119,22 @@ class CameraHelper extends LineSegments {
 
 		this.type = 'CameraHelper';
 
+		/**
+		 * The camera being visualized.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = camera;
 		if ( this.camera.updateProjectionMatrix ) this.camera.updateProjectionMatrix();
 
 		this.matrix = camera.matrixWorld;
 		this.matrixAutoUpdate = false;
 
+		/**
+		 * This contains the points used to visualize the camera.
+		 *
+		 * @type {Object<string,Array<number>>}
+		 */
 		this.pointMap = pointMap;
 
 		this.update();
@@ -127,6 +151,15 @@ class CameraHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Defines the colors of the helper.
+	 *
+	 * @param {Color} frustum - The frustum line color.
+	 * @param {Color} cone - The cone line color.
+	 * @param {Color} up - The up line color.
+	 * @param {Color} target - The target line color.
+	 * @param {Color} cross - The cross line color.
+	 */
 	setColors( frustum, cone, up, target, cross ) {
 
 		const geometry = this.geometry;
@@ -184,6 +217,9 @@ class CameraHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Updates the helper based on the projection matrix of the camera.
+	 */
 	update() {
 
 		const geometry = this.geometry;
@@ -239,6 +275,10 @@ class CameraHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.geometry.dispose();

package/src/helpers/DirectionalLightHelper.js

@@ -9,17 +9,51 @@ const _v1 = /*@__PURE__*/ new Vector3();
 const _v2 = /*@__PURE__*/ new Vector3();
 const _v3 = /*@__PURE__*/ new Vector3();
 
+/**
+ * Helper object to assist with visualizing a {@link DirectionalLight}'s
+ * effect on the scene. This consists of plane and a line representing the
+ * light's position and direction.
+ *
+ * ```js
+ * const light = new THREE.DirectionalLight( 0xFFFFFF );
+ * scene.add( light );
+ *
+ * const helper = new THREE.DirectionalLightHelper( light, 5 );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments Object3D
+ */
 class DirectionalLightHelper extends Object3D {
 
+	/**
+	 * Constructs a new directional light helper.
+	 *
+	 * @param {DirectionalLight} light - The light to be visualized.
+	 * @param {number} [size=1] - The dimensions of the plane.
+	 * @param {number|Color|string} [color] - The helper's color. If not set, the helper will take
+	 * the color of the light.
+	 */
 	constructor( light, size, color ) {
 
 		super();
 
+		/**
+		 * The light being visualized.
+		 *
+		 * @type {DirectionalLight}
+		 */
 		this.light = light;
 
 		this.matrix = light.matrixWorld;
 		this.matrixAutoUpdate = false;
 
+		/**
+		 * The color parameter passed in the constructor.
+		 * If not set, the helper will take the color of the light.
+		 *
+		 * @type {number|Color|string}
+		 */
 		this.color = color;
 
 		this.type = 'DirectionalLightHelper';
@@ -37,12 +71,22 @@ class DirectionalLightHelper extends Object3D {
 
 		const material = new LineBasicMaterial( { fog: false, toneMapped: false } );
 
+		/**
+		 * Contains the line showing the location of the directional light.
+		 *
+		 * @type {Line}
+		 */
 		this.lightPlane = new Line( geometry, material );
 		this.add( this.lightPlane );
 
 		geometry = new BufferGeometry();
 		geometry.setAttribute( 'position', new Float32BufferAttribute( [ 0, 0, 0, 0, 0, 1 ], 3 ) );
 
+		/**
+		 * Represents the target line of the directional light.
+		 *
+		 * @type {Line}
+		 */
 		this.targetLine = new Line( geometry, material );
 		this.add( this.targetLine );
 
@@ -50,6 +94,10 @@ class DirectionalLightHelper extends Object3D {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.lightPlane.geometry.dispose();
@@ -59,6 +107,10 @@ class DirectionalLightHelper extends Object3D {
 
 	}
 
+	/**
+	 * Updates the helper to match the position and direction of the
+	 * light being visualized.
+	 */
 	update() {
 
 		this.light.updateWorldMatrix( true, false );

package/src/helpers/GridHelper.js

@@ -4,8 +4,30 @@ import { Float32BufferAttribute } from '../core/BufferAttribute.js';
 import { BufferGeometry } from '../core/BufferGeometry.js';
 import { Color } from '../math/Color.js';
 
+/**
+ * The helper is an object to define grids. Grids are two-dimensional
+ * arrays of lines.
+ *
+ * ```js
+ * const size = 10;
+ * const divisions = 10;
+ *
+ * const gridHelper = new THREE.GridHelper( size, divisions );
+ * scene.add( gridHelper );
+ * ```
+ *
+ * @augments LineSegments
+ */
 class GridHelper extends LineSegments {
 
+	/**
+	 * Constructs a new grid helper.
+	 *
+	 * @param {number} [size=10] - The size of the grid.
+	 * @param {number} [divisions=10] - The number of divisions across the grid.
+	 * @param {number|Color|string} [color1=0x444444] - The color of the center line.
+	 * @param {number|Color|string} [color2=0x888888] - The color of the lines of the grid.
+	 */
 	constructor( size = 10, divisions = 10, color1 = 0x444444, color2 = 0x888888 ) {
 
 		color1 = new Color( color1 );
@@ -43,6 +65,10 @@ class GridHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.geometry.dispose();

package/src/helpers/HemisphereLightHelper.js

@@ -10,17 +10,48 @@ const _vector = /*@__PURE__*/ new Vector3();
 const _color1 = /*@__PURE__*/ new Color();
 const _color2 = /*@__PURE__*/ new Color();
 
+/**
+ * Creates a visual aid consisting of a spherical mesh for a
+ * given {@link HemisphereLight}.
+ *
+ * ```js
+ * const light = new THREE.HemisphereLight( 0xffffbb, 0x080820, 1 );
+ * const helper = new THREE.HemisphereLightHelper( light, 5 );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments Object3D
+ */
 class HemisphereLightHelper extends Object3D {
 
+	/**
+	 * Constructs a new hemisphere light helper.
+	 *
+	 * @param {HemisphereLight} light - The light to be visualized.
+	 * @param {number} [size=1] - The size of the mesh used to visualize the light.
+	 * @param {number|Color|string} [color] - The helper's color. If not set, the helper will take
+	 * the color of the light.
+	 */
 	constructor( light, size, color ) {
 
 		super();
 
+		/**
+		 * The light being visualized.
+		 *
+		 * @type {HemisphereLight}
+		 */
 		this.light = light;
 
 		this.matrix = light.matrixWorld;
 		this.matrixAutoUpdate = false;
 
+		/**
+		 * The color parameter passed in the constructor.
+		 * If not set, the helper will take the color of the light.
+		 *
+		 * @type {number|Color|string}
+		 */
 		this.color = color;
 
 		this.type = 'HemisphereLightHelper';
@@ -42,6 +73,10 @@ class HemisphereLightHelper extends Object3D {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this.children[ 0 ].geometry.dispose();
@@ -49,6 +84,10 @@ class HemisphereLightHelper extends Object3D {
 
 	}
 
+	/**
+	 * Updates the helper to match the position and direction of the
+	 * light being visualized.
+	 */
 	update() {
 
 		const mesh = this.children[ 0 ];

package/src/helpers/PlaneHelper.js

@@ -5,8 +5,26 @@ import { MeshBasicMaterial } from '../materials/MeshBasicMaterial.js';
 import { Float32BufferAttribute } from '../core/BufferAttribute.js';
 import { BufferGeometry } from '../core/BufferGeometry.js';
 
+/**
+ * A helper object to visualize an instance of {@link Plane}.
+ *
+ * ```js
+ * const plane = new THREE.Plane( new THREE.Vector3( 1, 1, 0.2 ), 3 );
+ * const helper = new THREE.PlaneHelper( plane, 1, 0xffff00 );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments Line
+ */
 class PlaneHelper extends Line {
 
+	/**
+	 * Constructs a new plane helper.
+	 *
+	 * @param {Plane} plane - The plane to be visualized.
+	 * @param {number} [size=1] - The side length of plane helper.
+	 * @param {number|Color|string} [hex=0xffff00] - The helper's color.
+	 */
 	constructor( plane, size = 1, hex = 0xffff00 ) {
 
 		const color = hex;
@@ -21,8 +39,19 @@ class PlaneHelper extends Line {
 
 		this.type = 'PlaneHelper';
 
+		/**
+		 * The plane being visualized.
+		 *
+		 * @type {Plane}
+		 */
 		this.plane = plane;
 
+		/**
+		 * The side length of plane helper.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.size = size;
 
 		const positions2 = [ 1, 1, 0, - 1, 1, 0, - 1, - 1, 0, 1, 1, 0, - 1, - 1, 0, 1, - 1, 0 ];
@@ -49,6 +78,10 @@ class PlaneHelper extends Line {
 
 	}
 
+	/**
+	 * Updates the helper to match the position and direction of the
+	 * light being visualized.
+	 */
 	dispose() {
 
 		this.geometry.dispose();