@plastic-software/three 0.174.0 → 0.175.1

package/examples/jsm/loaders/LUTCubeLoader.js

@@ -1,40 +1,70 @@
-// https://wwwimages2.adobe.com/content/dam/acom/en/products/speedgrade/cc/pdfs/cube-lut-specification-1.0.pdf
-
 import {
 	ClampToEdgeWrapping,
 	Data3DTexture,
 	FileLoader,
-	FloatType,
 	LinearFilter,
 	Loader,
 	UnsignedByteType,
 	Vector3,
 } from 'three';
 
+/**
+ * A loader for the Cube LUT format.
+ *
+ * References:
+ * - [Cube LUT Specification]{@link https://web.archive.org/web/20220220033515/https://wwwimages2.adobe.com/content/dam/acom/en/products/speedgrade/cc/pdfs/cube-lut-specification-1.0.pdf}
+ *
+ * ```js
+ * const loader = new LUTCubeLoader();
+ * const map = loader.loadAsync( 'luts/Bourbon 64.CUBE' );
+ * ```
+ *
+ * @augments Loader
+ */
 export class LUTCubeLoader extends Loader {
 
+	/**
+	 * Constructs a new Cube LUT loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * The texture type.
+		 *
+		 * @type {(UnsignedByteType|FloatType)}
+		 * @default UnsignedByteType
+		 */
 		this.type = UnsignedByteType;
 
 	}
 
+	/**
+	 * Sets the texture type.
+	 *
+	 * @param {(UnsignedByteType|FloatType)} type - The texture type to set.
+	 * @return {LUTCubeLoader} A reference to this loader.
+	 */
 	setType( type ) {
 
-		if ( type !== UnsignedByteType && type !== FloatType ) {
-
-			throw new Error( 'LUTCubeLoader: Unsupported type' );
-
-		}
-
 		this.type = type;
 
 		return this;
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded Cube LUT 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({title:string,size:number,domainMin:Vector3,domainMax:Vector3,texture3D:Data3DTexture})} 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 );
@@ -66,6 +96,12 @@ export class LUTCubeLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given Cube LUT data and returns the resulting 3D data texture.
+	 *
+	 * @param {string} input - The raw Cube LUT data as a string.
+	 * @return {{title:string,size:number,domainMin:Vector3,domainMax:Vector3,texture3D:Data3DTexture}} The parsed Cube LUT.
+	 */
 	parse( input ) {
 
 		const regExpTitle = /TITLE +"([^"]*)"/;

package/examples/jsm/loaders/LUTImageLoader.js

@@ -8,19 +8,50 @@ import {
 	LinearFilter,
 } from 'three';
 
+/**
+ * A loader for loading LUT images.
+ *
+ * ```js
+ * const loader = new LUTImageLoader();
+ * const map = loader.loadAsync( 'luts/NeutralLUT.png' );
+ * ```
+ *
+ * @augments Loader
+ */
 export class LUTImageLoader extends Loader {
 
-	constructor( flipVertical = false ) {
-
-		//The NeutralLUT.png has green at the bottom for Unreal ang green at the top for Unity URP Color Lookup
-		//post-processing. If you're using lut image strips from a Unity pipeline then pass true to the constructor
-
-		super();
-
-		this.flip = flipVertical;
+	/**
+	 * Constructs a new LUT loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
+	constructor( manager ) {
+
+		super( manager );
+
+		/**
+		 * Whether to vertically flip the LUT or not.
+		 *
+		 * Depending on the LUT's origin, the texture has green at the bottom (e.g. for Unreal)
+		 * or green at the top (e.g. for Unity URP Color Lookup). If you're using lut image strips
+		 * from a Unity pipeline, then set this property to `true`.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.flip = false;
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded LUT
+	 * 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({size:number,texture3D:Data3DTexture})} 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 TextureLoader( this.manager );
@@ -36,11 +67,11 @@ export class LUTImageLoader extends Loader {
 
 				if ( texture.image.width < texture.image.height ) {
 
-					imageData = this.getImageData( texture );
+					imageData = this._getImageData( texture );
 
 				} else {
 
-					imageData = this.horz2Vert( texture );
+					imageData = this._horz2Vert( texture );
 
 				}
 
@@ -66,7 +97,42 @@ export class LUTImageLoader extends Loader {
 
 	}
 
-	getImageData( texture ) {
+	/**
+	 * Parses the given LUT data and returns the resulting 3D data texture.
+	 *
+	 * @param {Uint8ClampedArray} dataArray - The raw LUT data.
+	 * @param {number} size - The LUT size.
+	 * @return {{size:number,texture3D:Data3DTexture}} An object representing the parsed LUT.
+	 */
+	parse( dataArray, size ) {
+
+		const data = new Uint8Array( dataArray );
+
+		const texture3D = new Data3DTexture();
+		texture3D.image.data = data;
+		texture3D.image.width = size;
+		texture3D.image.height = size;
+		texture3D.image.depth = size;
+		texture3D.format = RGBAFormat;
+		texture3D.type = UnsignedByteType;
+		texture3D.magFilter = LinearFilter;
+		texture3D.minFilter = LinearFilter;
+		texture3D.wrapS = ClampToEdgeWrapping;
+		texture3D.wrapT = ClampToEdgeWrapping;
+		texture3D.wrapR = ClampToEdgeWrapping;
+		texture3D.generateMipmaps = false;
+		texture3D.needsUpdate = true;
+
+		return {
+			size,
+			texture3D,
+		};
+
+	}
+
+	// internal
+
+	_getImageData( texture ) {
 
 		const width = texture.image.width;
 		const height = texture.image.height;
@@ -90,7 +156,7 @@ export class LUTImageLoader extends Loader {
 
 	}
 
-	horz2Vert( texture ) {
+	_horz2Vert( texture ) {
 
 		const width = texture.image.height;
 		const height = texture.image.width;
@@ -120,30 +186,4 @@ export class LUTImageLoader extends Loader {
 
 	}
 
-	parse( dataArray, size ) {
-
-		const data = new Uint8Array( dataArray );
-
-		const texture3D = new Data3DTexture();
-		texture3D.image.data = data;
-		texture3D.image.width = size;
-		texture3D.image.height = size;
-		texture3D.image.depth = size;
-		texture3D.format = RGBAFormat;
-		texture3D.type = UnsignedByteType;
-		texture3D.magFilter = LinearFilter;
-		texture3D.minFilter = LinearFilter;
-		texture3D.wrapS = ClampToEdgeWrapping;
-		texture3D.wrapT = ClampToEdgeWrapping;
-		texture3D.wrapR = ClampToEdgeWrapping;
-		texture3D.generateMipmaps = false;
-		texture3D.needsUpdate = true;
-
-		return {
-			size,
-			texture3D,
-		};
-
-	}
-
 }

package/examples/jsm/loaders/LWOLoader.js

@@ -43,16 +43,47 @@ import { IFFParser } from './lwo/IFFParser.js';
 
 let _lwoTree;
 
+/**
+ * A loader for the LWO format.
+ *
+ * LWO3 and LWO2 formats are supported.
+ *
+ * References:
+ * - [LWO3 format specification]{@link https://static.lightwave3d.com/sdk/2019/html/filefmts/lwo3.html}
+ * - [LWO2 format specification]{@link https://static.lightwave3d.com/sdk/2019/html/filefmts/lwo2.html}
+ *
+ * ```js
+ * const loader = new LWOLoader();
+ * const lwoData = await loader.loadAsync( 'models/lwo/Objects/LWO3/Demo.lwo' );
+ *
+ * const mesh = object.meshes[ 0 ];
+ * scene.add( mesh );
+ * ```
+ *
+ * @augments Loader
+ */
 class LWOLoader extends Loader {
 
-	constructor( manager, parameters = {} ) {
+	/**
+	 * Constructs a new LWO loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
+	constructor( manager ) {
 
 		super( manager );
 
-		this.resourcePath = ( parameters.resourcePath !== undefined ) ? parameters.resourcePath : '';
-
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded LWO 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({meshes:Array<Mesh>,materials:Array<Material>})} 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;
@@ -96,6 +127,14 @@ class LWOLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given LWO data and returns the resulting meshes and materials.
+	 *
+	 * @param {ArrayBuffer} iffBuffer - The raw LWO data as an array buffer.
+	 * @param {string} path - The URL base path.
+	 * @param {string} modelName - The model name.
+	 * @return {{meshes:Array<Mesh>,materials:Array<Material>}} An object holding the parse meshes and materials.
+	 */
 	parse( iffBuffer, path, modelName ) {
 
 		_lwoTree = new IFFParser().parse( iffBuffer );
@@ -312,7 +351,7 @@ class MaterialParser {
 
 		const maps = this.parseTextureNodes( connections.maps );
 
-		this.parseAttributeImageMaps( connections.attributes, textures, maps, materialData.maps );
+		this.parseAttributeImageMaps( connections.attributes, textures, maps );
 
 		const attributes = this.parseAttributes( connections.attributes, maps );
 
@@ -496,7 +535,7 @@ class MaterialParser {
 
 				const mapData = attribute.maps[ 0 ];
 
-				const path = this.getTexturePathByIndex( mapData.imageIndex, textures );
+				const path = this.getTexturePathByIndex( mapData.imageIndex );
 				if ( ! path ) return;
 
 				const texture = this.loadTexture( path );
@@ -783,8 +822,8 @@ class GeometryParser {
 
 		geometry.computeVertexNormals();
 
-		this.parseUVs( geometry, layer, indices );
-		this.parseMorphTargets( geometry, layer, indices );
+		this.parseUVs( geometry, layer );
+		this.parseMorphTargets( geometry, layer );
 
 		// TODO: z may need to be reversed to account for coordinate system change
 		geometry.translate( - layer.pivot[ 0 ], - layer.pivot[ 1 ], - layer.pivot[ 2 ] );

package/examples/jsm/loaders/LottieLoader.js

@@ -8,14 +8,51 @@ import {
 
 import lottie from '../libs/lottie_canvas.module.js';
 
+/**
+ * A loader for the Lottie texture animation format.
+ *
+ * The loader returns an instance of {@link CanvasTexture} to represent
+ * the animated texture. Two additional properties are added to each texture:
+ * - `animation`: The return value of `lottie.loadAnimation()` which is an object
+ * with an API for controlling the animation's playback.
+ * - `image`: The image container.
+ *
+ * ```js
+ * const loader = new LottieLoader();
+ * loader.setQuality( 2 );
+ * const texture = await loader.loadAsync( 'textures/lottie/24017-lottie-logo-animation.json' );
+ *
+ * const geometry = new THREE.BoxGeometry();
+ * const material = new THREE.MeshBasicMaterial( { map: texture } );
+ * const mesh = new THREE.Mesh( geometry, material );
+ * scene.add( mesh );
+ * ```
+ *
+ * @augments Loader
+ */
 class LottieLoader extends Loader {
 
+	/**
+	 * Sets the texture quality.
+	 *
+	 * @param {number} value - The texture quality.
+	 */
 	setQuality( value ) {
 
 		this._quality = value;
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded Lottie 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(CanvasTexture)} 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.
+	 * @returns {CanvasTexture} The Lottie texture.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const quality = this._quality || 1;

package/examples/jsm/loaders/MD2Loader.js

@@ -91,14 +91,43 @@ const _normalData = [
 	[ - 0.587785, - 0.425325, - 0.688191 ], [ - 0.688191, - 0.587785, - 0.425325 ]
 ];
 
+/**
+ * A loader for the MD2 format.
+ *
+ * The loader represents the animations of the MD2 asset as an array of animation
+ * clips and stores them in the `animations` property of the geometry.
+ *
+ * ```js
+ * const loader = new MD2Loader();
+ * const geometry = await loader.loadAsync( './models/md2/ogro/ogro.md2' );
+ *
+ * const animations = geometry.animations;
+ * ```
+ *
+ * @augments Loader
+ */
 class MD2Loader extends Loader {
 
+	/**
+	 * Constructs a new MD2 loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded MD2 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;
@@ -134,6 +163,12 @@ class MD2Loader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given MD2 data and returns a geometry.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw MD2 data as an array buffer.
+	 * @return {BufferGeometry} The parsed geometry data.
+	 */
 	parse( buffer ) {
 
 		const data = new DataView( buffer );
@@ -388,7 +423,7 @@ class MD2Loader extends Loader {
 		geometry.morphAttributes.normal = morphNormals;
 		geometry.morphTargetsRelative = false;
 
-		geometry.animations = AnimationClip.CreateClipsFromMorphTargetSequences( frames, 10 );
+		geometry.animations = AnimationClip.CreateClipsFromMorphTargetSequences( frames, 10, false );
 
 		return geometry;
 

package/examples/jsm/loaders/MDDLoader.js

@@ -1,15 +1,3 @@
-/**
- * MDD is a special format that stores a position for every vertex in a model for every frame in an animation.
- * Similar to BVH, it can be used to transfer animation data between different 3D applications or engines.
- *
- * MDD stores its data in binary format (big endian) in the following way:
- *
- * number of frames (a single uint32)
- * number of vertices (a single uint32)
- * time values for each frame (sequence of float32)
- * vertex data for each frame (sequence of float32)
- */
-
 import {
 	AnimationClip,
 	BufferAttribute,
@@ -18,14 +6,63 @@ import {
 	NumberKeyframeTrack
 } from 'three';
 
+/**
+ * A loader for the MDD format.
+ *
+ * MDD stores a position for every vertex in a model for every frame in an animation.
+ * Similar to BVH, it can be used to transfer animation data between different 3D applications or engines.
+ *
+ * MDD stores its data in binary format (big endian) in the following way:
+ *
+ * - number of frames (a single uint32)
+ * - number of vertices (a single uint32)
+ * - time values for each frame (sequence of float32)
+ * - vertex data for each frame (sequence of float32)
+ *
+ * ```js
+ * const loader = new MDDLoader();
+ * const result = await loader.loadAsync( 'models/mdd/cube.mdd' );
+ *
+ * const morphTargets = result.morphTargets;
+ * const clip = result.clip;
+ * // clip.optimize(); // optional
+ *
+ * const geometry = new THREE.BoxGeometry();
+ * geometry.morphAttributes.position = morphTargets; // apply morph targets (vertex data must match)
+ *
+ * const material = new THREE.MeshBasicMaterial();
+ *
+ * const mesh = new THREE.Mesh( geometry, material );
+ * scene.add( mesh );
+ *
+ * const mixer = new THREE.AnimationMixer( mesh );
+ * mixer.clipAction( clip ).play();
+ * ```
+ *
+ * @augments Loader
+ */
 class MDDLoader extends Loader {
 
+	/**
+	 * Constructs a new MDD loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded MDD 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({clip:AnimationClip, morphTargets:Array<BufferAttribute>})} 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;
@@ -41,6 +78,13 @@ class MDDLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given MDD data and returns an object holding the animation clip and the respective
+	 * morph targets.
+	 *
+	 * @param {ArrayBuffer} data - The raw XYZ data as an array buffer.
+	 * @return {{clip:AnimationClip, morphTargets:Array<BufferAttribute>}} The result object.
+	 */
 	parse( data ) {
 
 		const view = new DataView( data );

package/examples/jsm/loaders/MTLLoader.js

@@ -14,9 +14,22 @@ import {
 } from 'three';
 
 /**
- * Loads a Wavefront .mtl file specifying materials
+ * A loader for the MTL format.
+ *
+ * The Material Template Library format (MTL) or .MTL File Format is a companion file format
+ * to OBJ that describes surface shading (material) properties of objects within one or more
+ * OBJ files.
+ *
+ * ```js
+ * const loader = new MTLLoader();
+ * const materials = await loader.loadAsync( 'models/obj/male02/male02.mtl' );
+ *
+ * const objLoader = new OBJLoader();
+ * objLoader.setMaterials( materials );
+ * ```
+ *
+ * @augments Loader
  */
-
 class MTLLoader extends Loader {
 
 	constructor( manager ) {
@@ -26,17 +39,13 @@ class MTLLoader extends Loader {
 	}
 
 	/**
-	 * Loads and parses a MTL asset from a URL.
-	 *
-	 * @param {string} url - URL to the MTL file.
-	 * @param {Function} [onLoad] - Callback invoked with the loaded object.
-	 * @param {Function} [onProgress] - Callback for download progress.
-	 * @param {Function} [onError] - Callback for download errors.
+	 * Starts loading from the given URL and passes the loaded MTL asset
+	 * to the `onLoad()` callback.
 	 *
-	 * @see {@link FileLoader#setPath} {@link FileLoader#setResourcePath}
-	 *
-	 * @note In order for relative texture references to resolve correctly
-	 * you must call setResourcePath() explicitly prior to load.
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function(MaterialCreator)} 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 ) {
 
@@ -74,6 +83,12 @@ class MTLLoader extends Loader {
 
 	}
 
+	/**
+	 * Sets the material options.
+	 *
+	 * @param {MTLLoader~MaterialOptions} value - The material options.
+	 * @return {MTLLoader} A reference to this loader.
+	 */
 	setMaterialOptions( value ) {
 
 		this.materialOptions = value;
@@ -82,16 +97,11 @@ class MTLLoader extends Loader {
 	}
 
 	/**
-	 * Parses a MTL file.
-	 *
-	 * @param {string} text - Content of MTL file
-	 * @param {string} path
-	 * @return {MaterialCreator}
-	 *
-	 * @see {@link FileLoader#setPath} {@link FileLoader#setResourcePath}
+	 * Parses the given MTL data and returns the resulting material creator.
 	 *
-	 * @note In order for relative texture references to resolve correctly
-	 * you must call setResourcePath() explicitly prior to parse.
+	 * @param {string} text - The raw MTL data as a string.
+	 * @param {string} path - The URL base path.
+	 * @return {MaterialCreator} The material creator.
 	 */
 	parse( text, path ) {
 
@@ -155,18 +165,13 @@ class MTLLoader extends Loader {
 }
 
 /**
- * Create a new MTLLoader.MaterialCreator
- * @param baseUrl - Url relative to which textures are loaded
- * @param options - Set of options on how to construct the materials
- *                  side: Which side to apply the material
- *                        FrontSide (default), THREE.BackSide, THREE.DoubleSide
- *                  wrap: What type of wrapping to apply for textures
- *                        RepeatWrapping (default), THREE.ClampToEdgeWrapping, THREE.MirroredRepeatWrapping
- *                  normalizeRGB: RGBs need to be normalized to 0-1 from 0-255
- *                                Default: false, assumed to be already normalized
- *                  ignoreZeroRGBs: Ignore values of RGBs (Ka,Kd,Ks) that are all 0's
- *                                  Default: false
- * @constructor
+ * Material options of `MTLLoader`.
+ *
+ * @typedef {Object} MTLLoader~MaterialOptions
+ * @property {(FrontSide|BackSide|DoubleSide)} [side=FrontSide] - Which side to apply the material.
+ * @property {(RepeatWrapping|ClampToEdgeWrapping|MirroredRepeatWrapping)} [wrap=RepeatWrapping] - What type of wrapping to apply for textures.
+ * @property {boolean} [normalizeRGB=false] - Whether RGB colors should be normalized to `0-1` from `0-255`.
+ * @property {boolean} [ignoreZeroRGBs=false] - Ignore values of RGBs (Ka,Kd,Ks) that are all 0's.
  */
 
 class MaterialCreator {