@plastic-software/three 0.167.3 → 0.174.0

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

@@ -5,19 +5,34 @@ import { Color } from '../math/Color.js';
 import { LineBasicMaterial } from '../materials/LineBasicMaterial.js';
 import { BufferGeometry } from '../core/BufferGeometry.js';
 import { Float32BufferAttribute } from '../core/BufferAttribute.js';
+import { WebGLCoordinateSystem } from '../constants.js';
 
 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();
@@ -104,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();
@@ -126,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;
@@ -183,6 +217,9 @@ class CameraHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Updates the helper based on the projection matrix of the camera.
+	 */
 	update() {
 
 		const geometry = this.geometry;
@@ -195,17 +232,19 @@ class CameraHelper extends LineSegments {
 
 		_camera.projectionMatrixInverse.copy( this.camera.projectionMatrixInverse );
 
-		// center / target
+		// Adjust z values based on coordinate system
+		const nearZ = this.camera.coordinateSystem === WebGLCoordinateSystem ? - 1 : 0;
 
-		setPoint( 'c', pointMap, geometry, _camera, 0, 0, - 1 );
+		// center / target
+		setPoint( 'c', pointMap, geometry, _camera, 0, 0, nearZ );
 		setPoint( 't', pointMap, geometry, _camera, 0, 0, 1 );
 
 		// near
 
-		setPoint( 'n1', pointMap, geometry, _camera, - w, - h, - 1 );
-		setPoint( 'n2', pointMap, geometry, _camera, w, - h, - 1 );
-		setPoint( 'n3', pointMap, geometry, _camera, - w, h, - 1 );
-		setPoint( 'n4', pointMap, geometry, _camera, w, h, - 1 );
+		setPoint( 'n1', pointMap, geometry, _camera, - w, - h, nearZ );
+		setPoint( 'n2', pointMap, geometry, _camera, w, - h, nearZ );
+		setPoint( 'n3', pointMap, geometry, _camera, - w, h, nearZ );
+		setPoint( 'n4', pointMap, geometry, _camera, w, h, nearZ );
 
 		// far
 
@@ -216,9 +255,9 @@ class CameraHelper extends LineSegments {
 
 		// up
 
-		setPoint( 'u1', pointMap, geometry, _camera, w * 0.7, h * 1.1, - 1 );
-		setPoint( 'u2', pointMap, geometry, _camera, - w * 0.7, h * 1.1, - 1 );
-		setPoint( 'u3', pointMap, geometry, _camera, 0, h * 2, - 1 );
+		setPoint( 'u1', pointMap, geometry, _camera, w * 0.7, h * 1.1, nearZ );
+		setPoint( 'u2', pointMap, geometry, _camera, - w * 0.7, h * 1.1, nearZ );
+		setPoint( 'u3', pointMap, geometry, _camera, 0, h * 2, nearZ );
 
 		// cross
 
@@ -227,15 +266,19 @@ class CameraHelper extends LineSegments {
 		setPoint( 'cf3', pointMap, geometry, _camera, 0, - h, 1 );
 		setPoint( 'cf4', pointMap, geometry, _camera, 0, h, 1 );
 
-		setPoint( 'cn1', pointMap, geometry, _camera, - w, 0, - 1 );
-		setPoint( 'cn2', pointMap, geometry, _camera, w, 0, - 1 );
-		setPoint( 'cn3', pointMap, geometry, _camera, 0, - h, - 1 );
-		setPoint( 'cn4', pointMap, geometry, _camera, 0, h, - 1 );
+		setPoint( 'cn1', pointMap, geometry, _camera, - w, 0, nearZ );
+		setPoint( 'cn2', pointMap, geometry, _camera, w, 0, nearZ );
+		setPoint( 'cn3', pointMap, geometry, _camera, 0, - h, nearZ );
+		setPoint( 'cn4', pointMap, geometry, _camera, 0, h, nearZ );
 
 		geometry.getAttribute( 'position' ).needsUpdate = true;
 
 	}
 
+	/**
+	 * 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();

package/src/helpers/PointLightHelper.js

@@ -2,8 +2,32 @@ import { Mesh } from '../objects/Mesh.js';
 import { MeshBasicMaterial } from '../materials/MeshBasicMaterial.js';
 import { SphereGeometry } from '../geometries/SphereGeometry.js';
 
+/**
+ * This displays a helper object consisting of a spherical mesh for
+ * visualizing an instance of {@link PointLight}.
+ *
+ * ```js
+ * const pointLight = new THREE.PointLight( 0xff0000, 1, 100 );
+ * pointLight.position.set( 10, 10, 10 );
+ * scene.add( pointLight );
+ *
+ * const sphereSize = 1;
+ * const pointLightHelper = new THREE.PointLightHelper( pointLight, sphereSize );
+ * scene.add( pointLightHelper );
+ * ```
+ *
+ * @augments Mesh
+ */
 class PointLightHelper extends Mesh {
 
+	/**
+	 * Constructs a new point light helper.
+	 *
+	 * @param {PointLight} light - The light to be visualized.
+	 * @param {number} [sphereSize=1] - The size of the sphere helper.
+	 * @param {number|Color|string} [color] - The helper's color. If not set, the helper will take
+	 * the color of the light.
+	 */
 	constructor( light, sphereSize, color ) {
 
 		const geometry = new SphereGeometry( sphereSize, 4, 2 );
@@ -11,8 +35,19 @@ class PointLightHelper extends Mesh {
 
 		super( geometry, material );
 
+		/**
+		 * The light being visualized.
+		 *
+		 * @type {HemisphereLight}
+		 */
 		this.light = light;
 
+		/**
+		 * 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 = 'PointLightHelper';
@@ -48,6 +83,10 @@ class PointLightHelper extends Mesh {
 
 	}
 
+	/**
+	 * 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();
@@ -55,6 +94,10 @@ class PointLightHelper extends Mesh {
 
 	}
 
+	/**
+	 * Updates the helper to match the position of the
+	 * light being visualized.
+	 */
 	update() {
 
 		this.light.updateWorldMatrix( true, false );

package/src/helpers/PolarGridHelper.js

@@ -4,8 +4,34 @@ import { Float32BufferAttribute } from '../core/BufferAttribute.js';
 import { BufferGeometry } from '../core/BufferGeometry.js';
 import { Color } from '../math/Color.js';
 
+/**
+ * This helper is an object to define polar grids. Grids are
+ * two-dimensional arrays of lines.
+ *
+ * ```js
+ * const radius = 10;
+ * const sectors = 16;
+ * const rings = 8;
+ * const divisions = 64;
+ *
+ * const helper = new THREE.PolarGridHelper( radius, sectors, rings, divisions );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments LineSegments
+ */
 class PolarGridHelper extends LineSegments {
 
+	/**
+	 * Constructs a new polar grid helper.
+	 *
+	 * @param {number} [radius=10] - The radius of the polar grid. This can be any positive number.
+	 * @param {number} [sectors=16] - The number of sectors the grid will be divided into. This can be any positive integer.
+	 * @param {number} [rings=16] - The number of rings. This can be any positive integer.
+	 * @param {number} [divisions=64] - The number of line segments used for each circle. This can be any positive integer.
+	 * @param {number|Color|string} [color1=0x444444] - The first color used for grid elements.
+	 * @param {number|Color|string} [color2=0x888888] -  The second color used for grid elements.
+	 */
 	constructor( radius = 10, sectors = 16, rings = 8, divisions = 64, color1 = 0x444444, color2 = 0x888888 ) {
 
 		color1 = new Color( color1 );
@@ -83,6 +109,10 @@ class PolarGridHelper 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/SkeletonHelper.js

@@ -10,9 +10,24 @@ const _vector = /*@__PURE__*/ new Vector3();
 const _boneMatrix = /*@__PURE__*/ new Matrix4();
 const _matrixWorldInv = /*@__PURE__*/ new Matrix4();
 
-
+/**
+ * A helper object to assist with visualizing a {@link Skeleton}.
+ *
+ * ```js
+ * const helper = new THREE.SkeletonHelper( skinnedMesh );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments LineSegments
+ */
 class SkeletonHelper extends LineSegments {
 
+	/**
+	 * Constructs a new hemisphere light helper.
+	 *
+	 * @param {Object3D} object -  Usually an instance of {@link SkinnedMesh}. However, any 3D object
+	 * can be used if it represents a hierarchy of bones (see {@link Bone}).
+	 */
 	constructor( object ) {
 
 		const bones = getBoneList( object );
@@ -47,11 +62,29 @@ class SkeletonHelper extends LineSegments {
 
 		super( geometry, material );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSkeletonHelper = true;
 
 		this.type = 'SkeletonHelper';
 
+		/**
+		 * The object being visualized.
+		 *
+		 * @type {Object3D}
+		 */
 		this.root = object;
+
+		/**
+		 * he list of bones that the helper visualizes.
+		 *
+		 * @type {Array<Bone>}
+		 */
 		this.bones = bones;
 
 		this.matrix = object.matrixWorld;
@@ -94,6 +127,10 @@ class SkeletonHelper 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();
@@ -116,7 +153,7 @@ function getBoneList( object ) {
 
 	for ( let i = 0; i < object.children.length; i ++ ) {
 
-		boneList.push.apply( boneList, getBoneList( object.children[ i ] ) );
+		boneList.push( ...getBoneList( object.children[ i ] ) );
 
 	}