@needle-tools/three 0.169.20-experimental.0 → 0.183.2-canary.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,37 @@ 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, WebGPUCoordinateSystem } 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](https://github.com/evanw/lightgl.js/blob/master/tests/shadowmap.html).
+ *
+ * `CameraHelper` must be a child of the scene.
+ *
+ * When the camera is transformed or its projection matrix is changed, it's necessary
+ * to call the `update()` method of the respective helper.
+ *
+ * ```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 +122,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 +154,16 @@ 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.
+	 * @return {CameraHelper} A reference to this helper.
+	 */
 	setColors( frustum, cone, up, target, cross ) {
 
 		const geometry = this.geometry;
@@ -181,8 +219,13 @@ class CameraHelper extends LineSegments {
 
 		colorAttribute.needsUpdate = true;
 
+		return this;
+
 	}
 
+	/**
+	 * Updates the helper based on the projection matrix of the camera.
+	 */
 	update() {
 
 		const geometry = this.geometry;
@@ -190,52 +233,85 @@ class CameraHelper extends LineSegments {
 
 		const w = 1, h = 1;
 
+		let nearZ, farZ;
+
 		// we need just camera projection matrix inverse
 		// world matrix must be identity
 
 		_camera.projectionMatrixInverse.copy( this.camera.projectionMatrixInverse );
 
-		// center / target
+		// Adjust z values based on coordinate system
+
+		if ( this.camera.reversedDepth === true ) {
+
+			nearZ = 1;
+			farZ = 0;
+
+		} else {
+
+			if ( this.camera.coordinateSystem === WebGLCoordinateSystem ) {
+
+				nearZ = - 1;
+				farZ = 1;
+
+			} else if ( this.camera.coordinateSystem === WebGPUCoordinateSystem ) {
 
-		setPoint( 'c', pointMap, geometry, _camera, 0, 0, - 1 );
-		setPoint( 't', pointMap, geometry, _camera, 0, 0, 1 );
+				nearZ = 0;
+				farZ = 1;
+
+			} else {
+
+				throw new Error( 'THREE.CameraHelper.update(): Invalid coordinate system: ' + this.camera.coordinateSystem );
+
+			}
+
+		}
+
+
+		// center / target
+		setPoint( 'c', pointMap, geometry, _camera, 0, 0, nearZ );
+		setPoint( 't', pointMap, geometry, _camera, 0, 0, farZ );
 
 		// 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
 
-		setPoint( 'f1', pointMap, geometry, _camera, - w, - h, 1 );
-		setPoint( 'f2', pointMap, geometry, _camera, w, - h, 1 );
-		setPoint( 'f3', pointMap, geometry, _camera, - w, h, 1 );
-		setPoint( 'f4', pointMap, geometry, _camera, w, h, 1 );
+		setPoint( 'f1', pointMap, geometry, _camera, - w, - h, farZ );
+		setPoint( 'f2', pointMap, geometry, _camera, w, - h, farZ );
+		setPoint( 'f3', pointMap, geometry, _camera, - w, h, farZ );
+		setPoint( 'f4', pointMap, geometry, _camera, w, h, farZ );
 
 		// 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
 
-		setPoint( 'cf1', pointMap, geometry, _camera, - w, 0, 1 );
-		setPoint( 'cf2', pointMap, geometry, _camera, w, 0, 1 );
-		setPoint( 'cf3', pointMap, geometry, _camera, 0, - h, 1 );
-		setPoint( 'cf4', pointMap, geometry, _camera, 0, h, 1 );
+		setPoint( 'cf1', pointMap, geometry, _camera, - w, 0, farZ );
+		setPoint( 'cf2', pointMap, geometry, _camera, w, 0, farZ );
+		setPoint( 'cf3', pointMap, geometry, _camera, 0, - h, farZ );
+		setPoint( 'cf4', pointMap, geometry, _camera, 0, h, farZ );
 
-		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,54 @@ 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 a plane and a line representing the
+ * light's position and direction.
+ *
+ * When the directional light or its target are transformed or light properties
+ * are changed, it's necessary to call the `update()` method of the respective helper.
+ *
+ * ```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 +74,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 +97,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 +110,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,51 @@ 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}.
+ *
+ * When the hemisphere light is transformed or its light properties are changed,
+ * it's necessary to call the `update()` method of the respective helper.
+ *
+ * ```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 +76,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 +87,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 {PointLight}
+		 */
 		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';
@@ -22,32 +57,12 @@ class PointLightHelper extends Mesh {
 
 		this.update();
 
-
-		/*
-	// TODO: delete this comment?
-	const distanceGeometry = new THREE.IcosahedronGeometry( 1, 2 );
-	const distanceMaterial = new THREE.MeshBasicMaterial( { color: hexColor, fog: false, wireframe: true, opacity: 0.1, transparent: true } );
-
-	this.lightSphere = new THREE.Mesh( bulbGeometry, bulbMaterial );
-	this.lightDistance = new THREE.Mesh( distanceGeometry, distanceMaterial );
-
-	const d = light.distance;
-
-	if ( d === 0.0 ) {
-
-		this.lightDistance.visible = false;
-
-	} else {
-
-		this.lightDistance.scale.set( d, d, d );
-
-	}
-
-	this.add( this.lightDistance );
-	*/
-
 	}
 
+	/**
+	 * 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 +70,10 @@ class PointLightHelper extends Mesh {
 
 	}
 
+	/**
+	 * Updates the helper to match the position of the
+	 * light being visualized.
+	 */
 	update() {
 
 		this.light.updateWorldMatrix( true, false );