@plastic-software/three 0.174.0 → 0.175.1

package/examples/jsm/loaders/MaterialXLoader.js

@@ -145,14 +145,41 @@ const MXElements = [
 const MtlXLibrary = {};
 MXElements.forEach( element => MtlXLibrary[ element.name ] = element );
 
+/**
+ * A loader for the MaterialX format.
+ *
+ * The node materials loaded with this loader can only be used with {@link WebGPURenderer}.
+ *
+ * ```js
+ * const loader = new MaterialXLoader().setPath( SAMPLE_PATH );
+ * const materials = await loader.loadAsync( 'standard_surface_brass_tiled.mtlx' );
+ * ```
+ *
+ * @augments Loader
+ */
 class MaterialXLoader extends Loader {
 
+	/**
+	 * Constructs a new MaterialX loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded MaterialX 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(Object<string,NodeMaterial>)} 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.
+	 * @return {MaterialXLoader} A reference to this loader.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const _onError = function ( e ) {
@@ -189,6 +216,12 @@ class MaterialXLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given MaterialX data and returns the resulting materials.
+	 *
+	 * @param {string} text - The raw MaterialX data as a string.
+	 * @return {Object<string,NodeMaterial>} A dictionary holding the parse node materials.
+	 */
 	parse( text ) {
 
 		return new MaterialX( this.manager, this.path ).parse( text );

package/examples/jsm/loaders/NRRDLoader.js

@@ -7,14 +7,38 @@ import {
 import * as fflate from '../libs/fflate.module.js';
 import { Volume } from '../misc/Volume.js';
 
+/**
+ * A loader for the NRRD format.
+ *
+ * ```js
+ * const loader = new NRRDLoader();
+ * const volume = await loader.loadAsync( 'models/nrrd/I.nrrd' );
+ * ```
+ *
+ * @augments Loader
+ */
 class NRRDLoader extends Loader {
 
+	/**
+	 * Constructs a new NRRD loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded NRRD 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(Volume)} 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;
@@ -51,15 +75,22 @@ class NRRDLoader extends Loader {
 	}
 
 	/**
+	 * Toggles the segmentation mode.
 	 *
-	 * @param {boolean} segmentation is a option for user to choose
-   	 */
+	 * @param {boolean} segmentation - Whether to use segmentation mode or not.
+	 */
 	setSegmentation( segmentation ) {
 
-	    this.segmentation = segmentation;
+		this.segmentation = segmentation;
 
 	}
 
+	/**
+	 * Parses the given NRRD data and returns the resulting volume data.
+	 *
+	 * @param {ArrayBuffer} data - The raw NRRD data as an array buffer.
+	 * @return {Volume} The parsed volume.
+	 */
 	parse( data ) {
 
 		// this parser is largely inspired from the XTK NRRD parser : https://github.com/xtk/X
@@ -307,7 +338,7 @@ class NRRDLoader extends Loader {
 
 				// we found two line breaks in a row
 				// now we know what the header is
-				_header = this.parseChars( _bytes, 0, i - 2 );
+				_header = this._parseChars( _bytes, 0, i - 2 );
 				// this is were the data starts
 				_data_start = i + 1;
 				break;
@@ -485,7 +516,7 @@ class NRRDLoader extends Loader {
 
 	}
 
-	parseChars( array, start, end ) {
+	_parseChars( array, start, end ) {
 
 		// without borders, use the whole array
 		if ( start === undefined ) {

package/examples/jsm/loaders/OBJLoader.js

@@ -432,18 +432,53 @@ function ParserState() {
 
 }
 
-//
 
+/**
+ * A loader for the OBJ format.
+ *
+ * The [OBJ format]{@link https://en.wikipedia.org/wiki/Wavefront_.obj_file} is a simple data-format that
+ * represents 3D geometry in a human readable format as the position of each vertex, the UV position of
+ * each texture coordinate vertex, vertex normals, and the faces that make each polygon defined as a list
+ * of vertices, and texture vertices.
+ *
+ * ```js
+ * const loader = new OBJLoader();
+ * const object = await loader.loadAsync( 'models/monster.obj' );
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
+ */
 class OBJLoader extends Loader {
 
+	/**
+	 * Constructs a new OBJ loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * A reference to a material creator.
+		 *
+		 * @type {?MaterialCreator}
+		 * @default null
+		 */
 		this.materials = null;
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded OBJ 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(Group)} 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;
@@ -478,6 +513,12 @@ class OBJLoader extends Loader {
 
 	}
 
+	/**
+	 * Sets the material creator for this OBJ. This object is loaded via {@link MTLLoader}.
+	 *
+	 * @param {MaterialCreator} materials - An object that creates the materials for this OBJ.
+	 * @return {OBJLoader} A reference to this loader.
+	 */
 	setMaterials( materials ) {
 
 		this.materials = materials;
@@ -486,6 +527,12 @@ class OBJLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given OBJ data and returns the resulting group.
+	 *
+	 * @param {string} text - The raw OBJ data as a string.
+	 * @return {Group} The parsed OBJ.
+	 */
 	parse( text ) {
 
 		const state = new ParserState();

package/examples/jsm/loaders/PCDLoader.js

@@ -10,16 +10,57 @@ import {
 	SRGBColorSpace
 } from 'three';
 
+/**
+ * A loader for the Point Cloud Data (PCD) format.
+ *
+ * PCDLoader supports ASCII and (compressed) binary files as well as the following PCD fields:
+ * - x y z
+ * - rgb
+ * - normal_x normal_y normal_z
+ * - intensity
+ * - label
+ *
+ * ```js
+ * const loader = new PCDLoader();
+ *
+ * const points = await loader.loadAsync( './models/pcd/binary/Zaghetto.pcd' );
+ * points.geometry.center(); // optional
+ * points.geometry.rotateX( Math.PI ); // optional
+ * scene.add( points );
+ * ```
+ *
+ * @augments Loader
+ */
 class PCDLoader extends Loader {
 
+	/**
+	 * Constructs a new PCD loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * Whether to use little Endian or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.littleEndian = true;
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded PCD 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(Points)} 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;
@@ -55,6 +96,12 @@ class PCDLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given PCD data and returns a point cloud.
+	 *
+	 * @param {ArrayBuffer} data - The raw PCD data as an array buffer.
+	 * @return {Points} The parsed point cloud.
+	 */
 	parse( data ) {
 
 		// from https://gitlab.com/taketwo/three-pcd-loader/blob/master/decompress-lzf.js

package/examples/jsm/loaders/PDBLoader.js

@@ -7,14 +7,45 @@ import {
 	SRGBColorSpace
 } from 'three';
 
+/**
+ * A loader for the PDB format.
+ *
+ * The [Protein Data Bank]{@link https://en.wikipedia.org/wiki/Protein_Data_Bank_(file_format)}
+ * file format is a textual file describing the three-dimensional structures of molecules.
+ *
+ * ```js
+ * const loader = new PDBLoader();
+ * const pdb = await loader.loadAsync( 'models/pdb/ethanol.pdb' );
+ *
+ * const geometryAtoms = pdb.geometryAtoms;
+ * const geometryBonds = pdb.geometryBonds;
+ * const json = pdb.json;
+ * ```
+ *
+ * @augments Loader
+ */
 class PDBLoader extends Loader {
 
+	/**
+	 * Constructs a new PDB loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded PDB 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(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,10 +80,17 @@ class PDBLoader extends Loader {
 
 	}
 
-	// Based on CanvasMol PDB parser
-
+	/**
+	 * Parses the given PDB data and returns an object holding the atoms and
+	 * bond geometries as well as the raw atom data as JSON.
+	 *
+	 * @param {string} text - The raw PDB data as a string.
+	 * @return {Object} The result object.
+	 */
 	parse( text ) {
 
+		// Based on CanvasMol PDB parser
+
 		function trim( text ) {
 
 			return text.replace( /^\s\s*/, '' ).replace( /\s\s*$/, '' );

package/examples/jsm/loaders/PLYLoader.js

@@ -7,55 +7,50 @@ import {
 	SRGBColorSpace
 } from 'three';
 
+const _color = new Color();
+
 /**
- * Description: A THREE loader for PLY ASCII files (known as the Polygon
+ * A loader for PLY the PLY format (known as the Polygon
  * File Format or the Stanford Triangle Format).
  *
- * Limitations: ASCII decoding assumes file is UTF-8.
- *
- * Usage:
- *	const loader = new PLYLoader();
- *	loader.load('./models/ply/ascii/dolphins.ply', function (geometry) {
- *
- *		scene.add( new THREE.Mesh( geometry ) );
- *
- *	} );
- *
- * If the PLY file uses non standard property names, they can be mapped while
- * loading. For example, the following maps the properties
- * “diffuse_(red|green|blue)” in the file to standard color names.
+ * Limitations:
+ *  - ASCII decoding assumes file is UTF-8.
  *
- * loader.setPropertyNameMapping( {
- *	diffuse_red: 'red',
- *	diffuse_green: 'green',
- *	diffuse_blue: 'blue'
- * } );
- *
- * Custom properties outside of the defaults for position, uv, normal
- * and color attributes can be added using the setCustomPropertyNameMapping method.
- * For example, the following maps the element properties “custom_property_a”
- * and “custom_property_b” to an attribute “customAttribute” with an item size of 2.
- * Attribute item sizes are set from the number of element properties in the property array.
- *
- * loader.setCustomPropertyNameMapping( {
- *	customAttribute: ['custom_property_a', 'custom_property_b'],
- * } );
+ * ```js
+ * const loader = new PLYLoader();
+ * const geometry = await loader.loadAsync( './models/ply/ascii/dolphins.ply' );
+ * scene.add( new THREE.Mesh( geometry ) );
+ * ```
  *
+ * @augments Loader
  */
-
-const _color = new Color();
-
 class PLYLoader extends Loader {
 
+	/**
+	 * Constructs a new PLY loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		// internals
+
 		this.propertyNameMapping = {};
 		this.customPropertyMapping = {};
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded PLY 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;
@@ -91,18 +86,53 @@ class PLYLoader extends Loader {
 
 	}
 
+	/**
+	 * Sets a property name mapping that maps default property names
+	 * to custom ones. For example, the following maps the properties
+	 * “diffuse_(red|green|blue)” in the file to standard color names.
+	 *
+	 * ```js
+	 * loader.setPropertyNameMapping( {
+	 * 	diffuse_red: 'red',
+	 * 	diffuse_green: 'green',
+	 * 	diffuse_blue: 'blue'
+	 * } );
+	 * ```
+	 *
+	 * @param {Object} mapping - The mapping dictionary.
+	 */
 	setPropertyNameMapping( mapping ) {
 
 		this.propertyNameMapping = mapping;
 
 	}
 
+	/**
+	 * Custom properties outside of the defaults for position, uv, normal
+	 * and color attributes can be added using the setCustomPropertyNameMapping method.
+	 * For example, the following maps the element properties “custom_property_a”
+	 * and “custom_property_b” to an attribute “customAttribute” with an item size of 2.
+	 * Attribute item sizes are set from the number of element properties in the property array.
+	 *
+	 * ```js
+	 * loader.setCustomPropertyNameMapping( {
+	 *	customAttribute: ['custom_property_a', 'custom_property_b'],
+	 * } );
+	 * ```
+	 * @param {Object} mapping - The mapping dictionary.
+	 */
 	setCustomPropertyNameMapping( mapping ) {
 
 		this.customPropertyMapping = mapping;
 
 	}
 
+	/**
+	 * Parses the given PLY data and returns the resulting geometry.
+	 *
+	 * @param {ArrayBuffer} data - The raw PLY data as an array buffer.
+	 * @return {BufferGeometry} The parsed geometry.
+	 */
 	parse( data ) {
 
 		function parseHeader( data, headerLength = 0 ) {

package/examples/jsm/loaders/PVRLoader.js

@@ -6,20 +6,38 @@ import {
 	RGB_PVRTC_4BPPV1_Format
 } from 'three';
 
-/*
- *	 PVR v2 (legacy) parser
- *   TODO : Add Support for PVR v3 format
- *   TODO : implement loadMipmaps option
+/**
+ * A loader for the PVRTC texture compression format.
+ *
+ * ```js
+ * const loader = new PVRLoader();
+ *
+ * const map = loader.load( 'textures/compressed/disturb_4bpp_rgb.pvr' );
+ * map.colorSpace = THREE.SRGBColorSpace; // only for color textures
+ * ```
+ *
+ * @augments CompressedTextureLoader
  */
-
 class PVRLoader extends CompressedTextureLoader {
 
+	/**
+	 * Constructs a new PVR loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Parses the given PVRTC texture data.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw texture data.
+	 * @param {boolean} loadMipmaps - Whether to load mipmaps or not. This option is not yet supported by the loader.
+	 * @return {CompressedTextureLoader~TexData} An object representing the parsed texture data.
+	 */
 	parse( buffer, loadMipmaps ) {
 
 		const headerLengthInt = 13;

package/examples/jsm/loaders/RGBELoader.js

@@ -7,23 +7,50 @@ import {
 	LinearSRGBColorSpace
 } from 'three';
 
-// https://github.com/mrdoob/three.js/issues/5552
-// http://en.wikipedia.org/wiki/RGBE_image_format
-
+/**
+ * A loader for the RGBE HDR texture format.
+ *
+ * ```js
+ * const loader = new RGBELoader();
+ * const envMap = await loader.loadAsync( 'textures/equirectangular/blouberg_sunrise_2_1k.hdr' );
+ * envMap.mapping = THREE.EquirectangularReflectionMapping;
+ *
+ * scene.environment = envMap;
+ * ```
+ *
+ * @augments DataTextureLoader
+ */
 class RGBELoader extends DataTextureLoader {
 
+	/**
+	 * Constructs a new RGBE loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * The texture type.
+		 *
+		 * @type {(HalfFloatType|FloatType)}
+		 * @default HalfFloatType
+		 */
 		this.type = HalfFloatType;
 
 	}
 
-	// adapted from http://www.graphics.cornell.edu/~bjw/rgbe.html
-
+	/**
+	 * Parses the given RGBE texture data.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw texture data.
+	 * @return {DataTextureLoader~TexData} An object representing the parsed texture data.
+	 */
 	parse( buffer ) {
 
+		// adapted from http://www.graphics.cornell.edu/~bjw/rgbe.html
+
 		const
 			/* default error routine.  change this to change error handling */
 			rgbe_read_error = 1,
@@ -411,6 +438,12 @@ class RGBELoader extends DataTextureLoader {
 
 	}
 
+	/**
+	 * Sets the texture type.
+	 *
+	 * @param {(HalfFloatType|FloatType)} value - The texture type to set.
+	 * @return {RGBELoader} A reference to this loader.
+	 */
 	setDataType( value ) {
 
 		this.type = value;