super-three 0.173.4 → 0.175.0

package/examples/jsm/loaders/3DMLoader.js

@@ -30,12 +30,38 @@ import { EXRLoader } from '../loaders/EXRLoader.js';
 
 const _taskCache = new WeakMap();
 
+/**
+ * A loader for Rhinoceros 3D files and objects.
+ *
+ * Rhinoceros is a 3D modeler used to create, edit, analyze, document, render,
+ * animate, and translate NURBS curves, surfaces, breps, extrusions, point clouds,
+ * as well as polygon meshes and SubD objects. `rhino3dm.js` is compiled to WebAssembly
+ * from the open source geometry library `openNURBS`. The loader currently uses
+ * `rhino3dm.js 8.4.0`.
+ *
+ * ```js
+ * const loader = new Rhino3dmLoader();
+ * loader.setLibraryPath( 'https://cdn.jsdelivr.net/npm/rhino3dm@8.0.1' );
+ *
+ * const object = await loader.loadAsync( 'models/3dm/Rhino_Logo.3dm' );
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
+ */
 class Rhino3dmLoader extends Loader {
 
+	/**
+	 * Constructs a new Rhino 3DM loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		// internals
+
 		this.libraryPath = '';
 		this.libraryPending = null;
 		this.libraryBinary = null;
@@ -54,6 +80,12 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Path to a folder containing the JS and WASM libraries.
+	 *
+	 * @param {string} path - The library path to set.
+	 * @return {Rhino3dmLoader} A reference to this loader.
+	 */
 	setLibraryPath( path ) {
 
 		this.libraryPath = path;
@@ -62,6 +94,14 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Sets the maximum number of Web Workers to be used during decoding.
+	 * A lower limit may be preferable if workers are also for other
+	 * tasks in the application.
+	 *
+	 * @param {number} workerLimit - The worker limit.
+	 * @return {Rhino3dmLoader} A reference to this loader.
+	 */
 	setWorkerLimit( workerLimit ) {
 
 		this.workerLimit = workerLimit;
@@ -70,6 +110,15 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded 3DM 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(Object3D)} 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 loader = new FileLoader( this.manager );
@@ -105,12 +154,22 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Prints debug messages to the browser console.
+	 */
 	debug() {
 
 		console.log( 'Task load: ', this.workerPool.map( ( worker ) => worker._taskLoad ) );
 
 	}
 
+	/**
+	 * Decodes the 3DM asset data with a Web Worker.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw 3DM asset data as an array buffer.
+	 * @param {string} url - The asset URL.
+	 * @return {Promise<Object3D>} A Promise that resolved with the decoded 3D object.
+	 */
 	decodeObjects( buffer, url ) {
 
 		let worker;
@@ -170,6 +229,14 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given 3DM data and passes the loaded 3DM asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {ArrayBuffer} data - The raw 3DM asset data as an array buffer.
+	 * @param {function(Object3D)} onLoad - Executed when the loading process has been finished.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	parse( data, onLoad, onError ) {
 
 		this.decodeObjects( data, '' )
@@ -962,6 +1029,10 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the loader is no longer required.
+	 */
 	dispose() {
 
 		for ( let i = 0; i < this.workerPool.length; ++ i ) {
@@ -972,8 +1043,6 @@ class Rhino3dmLoader extends Loader {
 
 		this.workerPool.length = 0;
 
-		return this;
-
 	}
 
 }

package/examples/jsm/loaders/3MFLoader.js

@@ -24,8 +24,7 @@ import * as fflate from '../libs/fflate.module.js';
 const COLOR_SPACE_3MF = SRGBColorSpace;
 
 /**
- *
- * 3D Manufacturing Format (3MF) specification: https://3mf.io/specification/
+ * A loader for the [3D Manufacturing Format (3MF)]{@link https://3mf.io/specification/} format.
  *
  * The following features from the core specification are supported:
  *
@@ -39,18 +38,46 @@ const COLOR_SPACE_3MF = SRGBColorSpace;
  * - Texture 2D Groups
  * - Color Groups (Vertex Colors)
  * - Metallic Display Properties (PBR)
+ *
+ * ```js
+ * const loader = new ThreeMFLoader();
+ *
+ * const object = await loader.loadAsync( './models/3mf/truck.3mf' );
+ * object.rotation.set( - Math.PI / 2, 0, 0 ); // z-up conversion
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
  */
-
 class ThreeMFLoader extends Loader {
 
+	/**
+	 * Constructs a new 3MF loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * An array of available extensions.
+		 *
+		 * @type {Array<Object>}
+		 */
 		this.availableExtensions = [];
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded 3MF 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;
@@ -85,6 +112,12 @@ class ThreeMFLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given 3MF data and returns the resulting group.
+	 *
+	 * @param {ArrayBuffer} data - The raw 3MF asset data as an array buffer.
+	 * @return {Group} A group representing the parsed asset.
+	 */
 	parse( data ) {
 
 		const scope = this;
@@ -122,6 +155,8 @@ class ThreeMFLoader extends Loader {
 
 			}
 
+			let rootModelFile = null;
+
 			for ( file in zip ) {
 
 				if ( file.match( /\_rels\/.rels$/ ) ) {
@@ -132,9 +167,13 @@ class ThreeMFLoader extends Loader {
 
 					modelRelsName = file;
 
-				} else if ( file.match( /^3D\/.*\.model$/ ) ) {
+				} else if ( file.match( /^3D\/[^\/]*\.model$/ ) ) {
+
+					rootModelFile = file;
 
-					modelPartNames.push( file );
+				} else if ( file.match( /^3D\/.*\/.*\.model$/ ) ) {
+
+					modelPartNames.push( file ); // sub models
 
 				} else if ( file.match( /^3D\/Textures?\/.*/ ) ) {
 
@@ -144,6 +183,8 @@ class ThreeMFLoader extends Loader {
 
 			}
 
+			modelPartNames.push( rootModelFile ); // push root model at the end so it is processed after the sub models
+
 			if ( relsName === undefined ) throw new Error( 'THREE.ThreeMFLoader: Cannot find relationship file `rels` in 3MF archive.' );
 
 			//
@@ -1563,6 +1604,11 @@ class ThreeMFLoader extends Loader {
 
 	}
 
+	/**
+	 * Adds a 3MF extension.
+	 *
+	 * @param {Object} extension - The extension to add.
+	 */
 	addExtension( extension ) {
 
 		this.availableExtensions.push( extension );

package/examples/jsm/loaders/AMFLoader.js

@@ -11,29 +11,42 @@ import {
 import * as fflate from '../libs/fflate.module.js';
 
 /**
- * Description: Early release of an AMF Loader following the pattern of the
- * example loaders in the three.js project.
+ * A loader for the AMF format.
  *
- * Usage:
- *	const loader = new AMFLoader();
- *	loader.load('/path/to/project.amf', function(objecttree) {
- *		scene.add(objecttree);
- *	});
+ * The loader supports materials, color and ZIP compressed files.
+ * No constellation support (yet).
  *
- * Materials now supported, material colors supported
- * Zip support, requires fflate
- * No constellation support (yet)!
+ * ```js
+ * const loader = new AMFLoader();
  *
+ * const object = await loader.loadAsync( './models/amf/rook.amf' );
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
  */
-
 class AMFLoader extends Loader {
 
+	/**
+	 * Constructs a new AMF loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded AMF 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;
@@ -69,6 +82,12 @@ class AMFLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given AMF data and returns the resulting group.
+	 *
+	 * @param {ArrayBuffer} data - The raw AMF asset data as an array buffer.
+	 * @return {Group} A group representing the parsed asset.
+	 */
 	parse( data ) {
 
 		function loadDocument( data ) {
@@ -236,7 +255,7 @@ class AMFLoader extends Loader {
 
 		function loadMeshVolume( node ) {
 
-			const volume = { name: '', triangles: [], materialid: null };
+			const volume = { name: '', triangles: [], materialId: null };
 
 			let currVolumeNode = node.firstElementChild;
 

package/examples/jsm/loaders/BVHLoader.js

@@ -11,23 +11,65 @@ import {
 } from 'three';
 
 /**
- * Description: reads BVH files and outputs a single Skeleton and an AnimationClip
+ * A loader for the BVH format.
  *
- * Currently only supports bvh files containing a single root.
+ * Imports BVH files and outputs a single {@link Skeleton} and {@link AnimationClip}.
+ * The loader only supports BVH files containing a single root right now.
  *
+ * ```js
+ * const loader = new BVHLoader();
+ * const result = await loader.loadAsync( 'models/bvh/pirouette.bvh' );
+ *
+ * // visualize skeleton
+ * const skeletonHelper = new THREE.SkeletonHelper( result.skeleton.bones[ 0 ] );
+ * scene.add( result.skeleton.bones[ 0 ] );
+ * scene.add( skeletonHelper );
+ *
+ * // play animation clip
+ * mixer = new THREE.AnimationMixer( result.skeleton.bones[ 0 ] );
+ * mixer.clipAction( result.clip ).play();
+ * ```
+ *
+ * @augments Loader
  */
-
 class BVHLoader extends Loader {
 
+	/**
+	 * Constructs a new BVH loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * Whether to animate bone positions or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.animateBonePositions = true;
+
+		/**
+		 * Whether to animate bone rotations or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.animateBoneRotations = true;
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded BVH 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({skeleton:Skeleton,clip:AnimationClip})} 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;
@@ -62,15 +104,19 @@ class BVHLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given BVH data and returns the resulting data.
+	 *
+	 * @param {string} text - The raw BVH data as a string.
+	 * @return {{skeleton:Skeleton,clip:AnimationClip}} An object representing the parsed asset.
+	 */
 	parse( text ) {
 
-		/*
-			reads a string array (lines) from a BVH file
-			and outputs a skeleton structure including motion data
+		// reads a string array (lines) from a BVH file
+		// and outputs a skeleton structure including motion data
 
-			returns thee root node:
-			{ name: '', channels: [], children: [] }
-		*/
+		// returns thee root node:
+		// { name: '', channels: [], children: [] }
 		function readBvh( lines ) {
 
 			// read model structure
@@ -338,11 +384,11 @@ class BVHLoader extends Loader {
 		}
 
 		/*
-			builds a AnimationClip from the keyframe data saved in each bone.
+			builds an AnimationClip from the keyframe data saved in each bone.
 
 			bone: bvh root node
 
-			returns: a AnimationClip containing position and quaternion tracks
+			returns: an AnimationClip containing position and quaternion tracks
 		*/
 		function toTHREEAnimation( bones ) {
 

package/examples/jsm/loaders/ColladaLoader.js

@@ -41,8 +41,35 @@ import {
 } from 'three';
 import { TGALoader } from '../loaders/TGALoader.js';
 
+/**
+ * A loader for the Collada format.
+ *
+ * The Collada format is very complex so this loader only supports a subset of what
+ * is defined in the [official specification]{@link https://www.khronos.org/files/collada_spec_1_5.pdf}.
+ *
+ * Assets with a Z-UP coordinate system are transformed it into Y-UP by a simple rotation.
+ * The vertex data are not converted.
+ *
+ * ```js
+ * const loader = new ColladaLoader();
+ *
+ * const result = await loader.loadAsync( './models/collada/elf/elf.dae' );
+ * scene.add( result.scene );
+ * ```
+ *
+ * @augments Loader
+ */
 class ColladaLoader extends Loader {
 
+	/**
+	 * Starts loading from the given URL and passes the loaded Collada 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:Group,animations:Array<AnimationClip>,kinematics: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;
@@ -79,6 +106,14 @@ class ColladaLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given Collada data and returns a result oject holding the parsed scene,
+	 * an array of animation clips and kinematics.
+	 *
+	 * @param {string} text - The raw Collada data as a string.
+	 * @param {string} path - The asset path.
+	 * @return {{scene:Group,animations:Array<AnimationClip>,kinematics:Object}} An object representing the parsed asset.
+	 */
 	parse( text, path ) {
 
 		function getElementsByTagName( xml, name ) {
@@ -3971,7 +4006,7 @@ class ColladaLoader extends Loader {
 				} else {
 
 					result += '\n';
-					stack.push.apply( stack, node.childNodes );
+					stack.push( ...node.childNodes );
 
 				}
 

package/examples/jsm/loaders/DDSLoader.js

@@ -9,14 +9,38 @@ import {
 	RGB_BPTC_UNSIGNED_Format
 } from 'three';
 
+/**
+ * A loader for the S3TC texture compression format.
+ *
+ * ```js
+ * const loader = new DDSLoader();
+ *
+ * const map = loader.load( 'textures/compressed/disturb_dxt1_nomip.dds' );
+ * map.colorSpace = THREE.SRGBColorSpace; // only for color textures
+ * ```
+ *
+ * @augments CompressedTextureLoader
+ */
 class DDSLoader extends CompressedTextureLoader {
 
+	/**
+	 * Constructs a new DDS loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Parses the given S3TC texture data.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw texture data.
+	 * @param {boolean} loadMipmaps - Whether to load mipmaps or not.
+	 * @return {CompressedTextureLoader~TexData} An object representing the parsed texture data.
+	 */
 	parse( buffer, loadMipmaps ) {
 
 		const dds = { mipmaps: [], width: 0, height: 0, format: null, mipmapCount: 1 };
@@ -126,7 +150,7 @@ class DDSLoader extends CompressedTextureLoader {
 					byteArray[ dst ] = r; dst ++;	//r
 					byteArray[ dst ] = g; dst ++;	//g
 					byteArray[ dst ] = b; dst ++;	//b
-                    			byteArray[ dst ] = 1.0; dst ++; //a
+					byteArray[ dst ] = 255; dst ++; //a
 
 				}
 

package/examples/jsm/loaders/DRACOLoader.js

@@ -11,8 +11,44 @@ import {
 
 const _taskCache = new WeakMap();
 
+/**
+ * A loader for the Draco format.
+ *
+ * [Draco]{@link https://google.github.io/draco/} is an open source library for compressing
+ * and decompressing 3D meshes and point clouds. Compressed geometry can be significantly smaller,
+ * at the cost of additional decoding time on the client device.
+ *
+ * Standalone Draco files have a `.drc` extension, and contain vertex positions, normals, colors,
+ * and other attributes. Draco files do not contain materials, textures, animation, or node hierarchies –
+ * to use these features, embed Draco geometry inside of a glTF file. A normal glTF file can be converted
+ * to a Draco-compressed glTF file using [glTF-Pipeline]{@link https://github.com/CesiumGS/gltf-pipeline}.
+ * When using Draco with glTF, an instance of `DRACOLoader` will be used internally by {@link GLTFLoader}.
+ *
+ * It is recommended to create one DRACOLoader instance and reuse it to avoid loading and creating
+ * multiple decoder instances.
+ *
+ * `DRACOLoader` will automatically use either the JS or the WASM decoding library, based on
+ * browser capabilities.
+ *
+ * ```js
+ * const loader = new DRACOLoader();
+ * loader.setDecoderPath( '/examples/jsm/libs/draco/' );
+ *
+ * const geometry = await dracoLoader.loadAsync( 'models/draco/bunny.drc' );
+ * geometry.computeVertexNormals(); // optional
+ *
+ * dracoLoader.dispose();
+ * ```
+ *
+ * @augments Loader
+ */
 class DRACOLoader extends Loader {
 
+	/**
+	 * Constructs a new Draco loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
@@ -42,6 +78,12 @@ class DRACOLoader extends Loader {
 
 	}
 
+	/**
+	 * Provides configuration for the decoder libraries. Configuration cannot be changed after decoding begins.
+	 *
+	 * @param {string} path - The decoder path.
+	 * @return {DRACOLoader} A reference to this loader.
+	 */
 	setDecoderPath( path ) {
 
 		this.decoderPath = path;
@@ -50,6 +92,12 @@ class DRACOLoader extends Loader {
 
 	}
 
+	/**
+	 * Provides configuration for the decoder libraries. Configuration cannot be changed after decoding begins.
+	 *
+	 * @param {{type:('js'|'wasm')}} config - The decoder config.
+	 * @return {DRACOLoader} A reference to this loader.
+	 */
 	setDecoderConfig( config ) {
 
 		this.decoderConfig = config;
@@ -58,6 +106,13 @@ class DRACOLoader extends Loader {
 
 	}
 
+	/**
+	 * Sets the maximum number of Web Workers to be used during decoding.
+	 * A lower limit may be preferable if workers are also for other tasks in the application.
+	 *
+	 * @param {number} workerLimit - The worker limit.
+	 * @return {DRACOLoader} A reference to this loader.
+	 */
 	setWorkerLimit( workerLimit ) {
 
 		this.workerLimit = workerLimit;
@@ -66,6 +121,15 @@ class DRACOLoader extends Loader {
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded Draco 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 loader = new FileLoader( this.manager );
@@ -83,13 +147,21 @@ class DRACOLoader extends Loader {
 
 	}
 
-
+	/**
+	 * Parses the given Draco data.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw Draco data as an array buffer.
+	 * @param {function(BufferGeometry)} onLoad - Executed when the loading/parsing process has been finished.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	parse( buffer, onLoad, onError = ()=>{} ) {
 
 		this.decodeDracoFile( buffer, onLoad, null, null, SRGBColorSpace, onError ).catch( onError );
 
 	}
 
+	//
+
 	decodeDracoFile( buffer, callback, attributeIDs, attributeTypes, vertexColorSpace = LinearSRGBColorSpace, onError = () => {} ) {
 
 		const taskConfig = {