@needle-tools/three 0.169.20-experimental.0 → 0.183.2-canary.0

package/examples/jsm/loaders/LUTImageLoader.js

@@ -8,19 +8,51 @@ import {
 	LinearFilter,
 } from 'three';
 
+/**
+ * A loader for loading LUT images.
+ *
+ * ```js
+ * const loader = new LUTImageLoader();
+ * const map = loader.loadAsync( 'luts/NeutralLUT.png' );
+ * ```
+ *
+ * @augments Loader
+ * @three_import import { LUTImageLoader } from 'three/addons/loaders/LUTImageLoader.js';
+ */
 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 +68,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 +98,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 +157,7 @@ export class LUTImageLoader extends Loader {
 
 	}
 
-	horz2Vert( texture ) {
+	_horz2Vert( texture ) {
 
 		const width = texture.image.height;
 		const height = texture.image.width;
@@ -120,30 +187,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

@@ -1,16 +1,3 @@
-/**
- * @version 1.1.1
- *
- * @desc Load files in LWO3 and LWO2 format on Three.js
- *
- * LWO3 format specification:
- *  https://static.lightwave3d.com/sdk/2019/html/filefmts/lwo3.html
- *
- * LWO2 format specification:
- *  https://static.lightwave3d.com/sdk/2019/html/filefmts/lwo2.html
- *
- **/
-
 import {
 	AddOperation,
 	BackSide,
@@ -36,23 +23,56 @@ import {
 	RepeatWrapping,
 	SRGBColorSpace,
 	TextureLoader,
-	Vector2
+	Vector2,
+	Vector3
 } from 'three';
 
 import { IFFParser } from './lwo/IFFParser.js';
 
 let _lwoTree;
 
+/**
+ * A loader for the LWO format.
+ *
+ * LWO3 and LWO2 formats are supported.
+ *
+ * References:
+ * - [LWO3 format specification](https://static.lightwave3d.com/sdk/2019/html/filefmts/lwo3.html)
+ * - [LWO2 format specification](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
+ * @three_import import { LWOLoader } from 'three/addons/loaders/LWOLoader.js';
+ */
 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 +116,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 );
@@ -158,8 +186,6 @@ class LWOTreeParser {
 
 		} );
 
-		this.applyPivots( finalMeshes );
-
 		return finalMeshes;
 
 	}
@@ -177,38 +203,14 @@ class LWOTreeParser {
 		if ( layer.name ) mesh.name = layer.name;
 		else mesh.name = this.defaultLayerName + '_layer_' + layer.number;
 
-		mesh.userData.pivot = layer.pivot;
-
-		return mesh;
+		const pivot = layer.pivot;
+		if ( pivot[ 0 ] !== 0 || pivot[ 1 ] !== 0 || pivot[ 2 ] !== 0 ) {
 
-	}
+			mesh.pivot = new Vector3( pivot[ 0 ], pivot[ 1 ], pivot[ 2 ] );
 
-	// TODO: may need to be reversed in z to convert LWO to three.js coordinates
-	applyPivots( meshes ) {
-
-		meshes.forEach( function ( mesh ) {
-
-			mesh.traverse( function ( child ) {
-
-				const pivot = child.userData.pivot;
-
-				child.position.x += pivot[ 0 ];
-				child.position.y += pivot[ 1 ];
-				child.position.z += pivot[ 2 ];
-
-				if ( child.parent ) {
-
-					const parentPivot = child.parent.userData.pivot;
-
-					child.position.x -= parentPivot[ 0 ];
-					child.position.y -= parentPivot[ 1 ];
-					child.position.z -= parentPivot[ 2 ];
-
-				}
-
-			} );
+		}
 
-		} );
+		return mesh;
 
 	}
 
@@ -312,7 +314,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 +498,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,15 +785,8 @@ class GeometryParser {
 
 		geometry.computeVertexNormals();
 
-		this.parseUVs( geometry, layer, indices );
-		this.parseMorphTargets( geometry, layer, indices );
-
-		// TODO: z may need to be reversed to account for coordinate system change
-		geometry.translate( - layer.pivot[ 0 ], - layer.pivot[ 1 ], - layer.pivot[ 2 ] );
-
-		// let userData = geometry.userData;
-		// geometry = geometry.toNonIndexed()
-		// geometry.userData = userData;
+		this.parseUVs( geometry, layer );
+		this.parseMorphTargets( geometry, layer );
 
 		return geometry;
 

package/examples/jsm/loaders/LottieLoader.js

@@ -8,20 +8,73 @@ 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
+ * @three_import import { LottieLoader } from 'three/addons/loaders/LottieLoader.js';
+ */
 class LottieLoader extends Loader {
 
+	/**
+	 * Constructs a new Lottie loader.
+	 *
+	 * @deprecated The loader has been deprecated and will be removed with r186. Use lottie-web instead and create your animated texture manually.
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
+	constructor( manager ) {
+
+		super( manager );
+
+		console.warn( 'THREE.LottieLoader: The loader has been deprecated and will be removed with r186. Use lottie-web instead and create your animated texture manually.' );
+
+	}
+
+	/**
+	 * 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;
 
 		const texture = new CanvasTexture();
 		texture.minFilter = NearestFilter;
+		texture.generateMipmaps = false;
 		texture.colorSpace = SRGBColorSpace;
 
 		const loader = new FileLoader( this.manager );
@@ -32,7 +85,7 @@ class LottieLoader extends Loader {
 
 			const data = JSON.parse( text );
 
-			// lottie uses container.offetWidth and offsetHeight
+			// lottie uses container.offsetWidth and offsetHeight
 			// to define width/height
 
 			const container = document.createElement( 'div' );

package/examples/jsm/loaders/MD2Loader.js

@@ -91,14 +91,44 @@ 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
+ * @three_import import { MD2Loader } from 'three/addons/loaders/MD2Loader.js';
+ */
 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 +164,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 +424,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,64 @@ 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
+ * @three_import import { MDDLoader } from 'three/addons/loaders/MDDLoader.js';
+ */
 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 +79,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 );