@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/loaders/VOXLoader.js

@@ -13,8 +13,35 @@ import {
 	SRGBColorSpace
 } from 'three';
 
+/**
+ * A loader for the VOX format.
+ *
+ * ```js
+ * const loader = new VOXLoader();
+ * const chunks = await loader.loadAsync( 'models/vox/monu10.vox' );
+ *
+ * for ( let i = 0; i < chunks.length; i ++ ) {
+ *
+ * 	const chunk = chunks[ i ];
+ * 	const mesh = new VOXMesh( chunk );
+ * 	mesh.scale.setScalar( 0.0015 );
+ * 	scene.add( mesh );
+ *
+ * }
+ * ```
+ * @augments Loader
+ */
 class VOXLoader extends Loader {
 
+	/**
+	 * Starts loading from the given URL and passes the loaded VOX asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function(Array<Object>)} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -49,6 +76,12 @@ class VOXLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given VOX data and returns the resulting chunks.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw VOX data as an array buffer.
+	 * @return {Array<Object>} The parsed chunks.
+	 */
 	parse( buffer ) {
 
 		const data = new DataView( buffer );
@@ -173,8 +206,20 @@ class VOXLoader extends Loader {
 
 }
 
+/**
+ * A VOX mesh.
+ *
+ * Instances of this class are created from the loaded chunks of {@link VOXLoader}.
+ *
+ * @augments Mesh
+ */
 class VOXMesh extends Mesh {
 
+	/**
+	 * Constructs a new VOX mesh.
+	 *
+	 * @param {Object} chunk - A VOX chunk loaded via {@link VOXLoader}.
+	 */
 	constructor( chunk ) {
 
 		const data = chunk.data;
@@ -279,8 +324,20 @@ class VOXMesh extends Mesh {
 
 }
 
+/**
+ * A VOX 3D texture.
+ *
+ * Instances of this class are created from the loaded chunks of {@link VOXLoader}.
+ *
+ * @augments Data3DTexture
+ */
 class VOXData3DTexture extends Data3DTexture {
 
+	/**
+	 * Constructs a new VOX 3D texture.
+	 *
+	 * @param {Object} chunk - A VOX chunk loaded via {@link VOXLoader}.
+	 */
 	constructor( chunk ) {
 
 		const data = chunk.data;

package/examples/jsm/loaders/VRMLLoader.js

@@ -36,15 +36,39 @@ import {
 } from 'three';
 import chevrotain from '../libs/chevrotain.module.min.js';
 
-
+/**
+ * A loader for the VRML format.
+ *
+ * ```js
+ * const loader = new VRMLLoader();
+ * const object = await loader.loadAsync( 'models/vrml/house.wrl' );
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
+ */
 class VRMLLoader extends Loader {
 
+	/**
+	 * Constructs a new VRML loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded VRML asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function(Scene)} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -81,6 +105,13 @@ class VRMLLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given VRML data and returns the resulting scene.
+	 *
+	 * @param {string} data - The raw VRML data as a string.
+	 * @param {string} path - The URL base path.
+	 * @return {Scene} The parsed scene.
+	 */
 	parse( data, path ) {
 
 		const nodeMap = {};

package/examples/jsm/loaders/VTKLoader.js

@@ -9,14 +9,46 @@ import {
 } from 'three';
 import * as fflate from '../libs/fflate.module.js';
 
+/**
+ * A loader for the VTK format.
+ *
+ * This loader only supports the `POLYDATA` dataset format so far. Other formats
+ * (structured points, structured grid, rectilinear grid, unstructured grid, appended)
+ * are not supported.
+ *
+ * ```js
+ * const loader = new VTKLoader();
+ * const geometry = await loader.loadAsync( 'models/vtk/liver.vtk' );
+ * geometry.computeVertexNormals();
+ *
+ * const mesh = new THREE.Mesh( geometry, new THREE.MeshLambertMaterial() );
+ * scene.add( mesh );
+ * ```
+ *
+ * @augments Loader
+ */
 class VTKLoader extends Loader {
 
+	/**
+	 * Constructs a new VTK loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded VRML asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function(BufferGeometry)} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -52,6 +84,12 @@ class VTKLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given VTK data and returns the resulting geometry.
+	 *
+	 * @param {ArrayBuffer} data - The raw VTK data as an array buffer
+	 * @return {BufferGeometry} The parsed geometry.
+	 */
 	parse( data ) {
 
 		function parseASCII( data ) {

package/examples/jsm/loaders/XYZLoader.js

@@ -7,8 +7,37 @@ import {
 	SRGBColorSpace
 } from 'three';
 
+/**
+ * A loader for the XYZ format.
+ *
+ * XYZ is a very simple format for storing point clouds. The layouts
+ * `XYZ` (points) and `XYZRGB` (points + colors) are supported.
+ *
+ * ```js
+ * const loader = new XYZLoader();
+ * const geometry = await loader.loadAsync( 'models/xyz/helix_201.xyz' );
+ * geometry.center();
+ *
+ * const vertexColors = ( geometry.hasAttribute( 'color' ) === true );
+ * const material = new THREE.PointsMaterial( { size: 0.1, vertexColors: vertexColors } );
+ *
+ * const points = new THREE.Points( geometry, material );
+ * scene.add( points );
+ * ```
+ *
+ * @augments Loader
+ */
 class XYZLoader extends Loader {
 
+	/**
+	 * Starts loading from the given URL and passes the loaded XYZ asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function(BufferGeometry)} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -43,6 +72,12 @@ class XYZLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given XYZ data and returns the resulting geometry.
+	 *
+	 * @param {string} text - The raw XYZ data as a string.
+	 * @return {BufferGeometry} The geometry representing the point cloud.
+	 */
 	parse( text ) {
 
 		const lines = text.split( '\n' );

package/examples/jsm/materials/LDrawConditionalLineMaterial.js

@@ -5,6 +5,14 @@ import {
 	UniformsUtils,
 } from 'three';
 
+/**
+ * A special line material for meshes loaded via {@link LDrawLoader}.
+ *
+ * This module can only be used with {@link WebGLRenderer}. When using {@link WebGPURenderer},
+ * import the class from `LDrawConditionalLineNodeMaterial.js`.
+ *
+ * @augments ShaderMaterial
+ */
 class LDrawConditionalLineMaterial extends ShaderMaterial {
 
 	static get type() {
@@ -13,6 +21,15 @@ class LDrawConditionalLineMaterial extends ShaderMaterial {
 
 	}
 
+	/**
+	 * Constructs a new conditional line material.
+	 *
+	 * @param {Object} [parameters] - An object with one or more properties
+	 * defining the material's appearance. Any property of the material
+	 * (including any property from inherited materials) can be passed
+	 * in here. Color values can be passed any type of value accepted
+	 * by {@link Color#set}.
+	 */
 	constructor( parameters ) {
 
 		super( {
@@ -109,6 +126,13 @@ class LDrawConditionalLineMaterial extends ShaderMaterial {
 
 		Object.defineProperties( this, {
 
+			/**
+			 * The material's opacity.
+			 *
+			 * @name LDrawConditionalLineMaterial#opacity
+			 * @type {number}
+			 * @default 1
+			 */
 			opacity: {
 				get: function () {
 
@@ -123,6 +147,13 @@ class LDrawConditionalLineMaterial extends ShaderMaterial {
 				}
 			},
 
+			/**
+			 * The material's color.
+			 *
+			 * @name LDrawConditionalLineMaterial#color
+			 * @type {Color}
+			 * @default (1,1,1)
+			 */
 			color: {
 				get: function () {
 
@@ -134,6 +165,14 @@ class LDrawConditionalLineMaterial extends ShaderMaterial {
 		} );
 
 		this.setValues( parameters );
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLDrawConditionalLineMaterial = true;
 
 	}

package/examples/jsm/materials/LDrawConditionalLineNodeMaterial.js

@@ -1,6 +1,14 @@
 import { Color } from 'three';
 import { attribute, cameraProjectionMatrix, dot, float, Fn, modelViewMatrix, modelViewProjection, NodeMaterial, normalize, positionGeometry, sign, uniform, varyingProperty, vec2, vec4 } from 'three/tsl';
 
+/**
+ * A special line material for meshes loaded via {@link LDrawLoader}.
+ *
+ * This module can only be used with {@link WebGPURenderer}. When using {@link WebGLRenderer},
+ * import the class from `LDrawConditionalLineMaterial.js`.
+ *
+ * @augments NodeMaterial
+ */
 class LDrawConditionalLineMaterial extends NodeMaterial {
 
 	static get type() {
@@ -9,6 +17,15 @@ class LDrawConditionalLineMaterial extends NodeMaterial {
 
 	}
 
+	/**
+	 * Constructs a new conditional line material.
+	 *
+	 * @param {Object} [parameters] - An object with one or more properties
+	 * defining the material's appearance. Any property of the material
+	 * (including any property from inherited materials) can be passed
+	 * in here. Color values can be passed any type of value accepted
+	 * by {@link Color#set}.
+	 */
 	constructor( parameters ) {
 
 		super();
@@ -74,6 +91,13 @@ class LDrawConditionalLineMaterial extends NodeMaterial {
 
 		Object.defineProperties( this, {
 
+			/**
+			 * The material's opacity.
+			 *
+			 * @name LDrawConditionalLineMaterial#opacity
+			 * @type {number}
+			 * @default 1
+			 */
 			opacity: {
 				get: function () {
 
@@ -88,6 +112,13 @@ class LDrawConditionalLineMaterial extends NodeMaterial {
 				}
 			},
 
+			/**
+			 * The material's color.
+			 *
+			 * @name LDrawConditionalLineMaterial#color
+			 * @type {Color}
+			 * @default (1,1,1)
+			 */
 			color: {
 				get: function () {
 
@@ -105,6 +136,14 @@ class LDrawConditionalLineMaterial extends NodeMaterial {
 		} );
 
 		this.setValues( parameters );
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLDrawConditionalLineMaterial = true;
 
 	}

package/examples/jsm/materials/MeshPostProcessingMaterial.js

@@ -21,10 +21,20 @@ import { MeshPhysicalMaterial } from 'three';
  *
  * Further extension work might be to use the output of an SSR pass or an HBIL pass from a previous frame.
  * This would then create the possibility of SSR and IR depending on material properties such as `roughness`, `metalness` and `reflectivity`.
-**/
-
+ *
+ * @augments MeshPhysicalMaterial
+ */
 class MeshPostProcessingMaterial extends MeshPhysicalMaterial {
 
+	/**
+	 * Constructs a new conditional line material.
+	 *
+	 * @param {Object} [parameters] - An object with one or more properties
+	 * defining the material's appearance. Any property of the material
+	 * (including any property from inherited materials) can be passed
+	 * in here. Color values can be passed any type of value accepted
+	 * by {@link Color#set}.
+	 */
 	constructor( parameters ) {
 
 		const aoPassMap = parameters.aoPassMap;
@@ -37,11 +47,23 @@ class MeshPostProcessingMaterial extends MeshPhysicalMaterial {
 		this.onBeforeCompile = this._onBeforeCompile;
 		this.customProgramCacheKey = this._customProgramCacheKey;
 		this._aoPassMap = aoPassMap;
+
+		/**
+		 * The scale of the AO pass.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.aoPassMapScale = aoPassMapScale;
 		this._shader = null;
 
 	}
 
+	/**
+	 * A texture representing the AO pass.
+	 *
+	 * @type {Texture}
+	 */
 	get aoPassMap() {
 
 		return this._aoPassMap;

package/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 {Capsule} A reference to this capsule.
+	 */
 	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 };

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