super-three 0.173.4 → 0.175.0

package/examples/jsm/loaders/EXRLoader.js

@@ -11,13 +11,8 @@ import {
 } from 'three';
 import * as fflate from '../libs/fflate.module.js';
 
-/**
- * OpenEXR loader currently supports uncompressed, ZIP(S), RLE, PIZ and DWA/B compression.
- * Supports reading as UnsignedByte, HalfFloat and Float type data texture.
- *
- * Referred to the original Industrial Light & Magic OpenEXR implementation and the TinyEXR / Syoyo Fujita
- * implementation, so I have preserved their copyright notices.
- */
+// Referred to the original Industrial Light & Magic OpenEXR implementation and the TinyEXR / Syoyo Fujita
+// implementation, so I have preserved their copyright notices.
 
 // /*
 // Copyright (c) 2014 - 2017, Syoyo Fujita
@@ -84,16 +79,47 @@ import * as fflate from '../libs/fflate.module.js';
 
 // // End of OpenEXR license -------------------------------------------------
 
+
+/**
+ * A loader for the OpenEXR texture format.
+ *
+ * `EXRLoader` currently supports uncompressed, ZIP(S), RLE, PIZ and DWA/B compression.
+ * Supports reading as UnsignedByte, HalfFloat and Float type data texture.
+ *
+ * ```js
+ * const loader = new EXRLoader();
+ * const texture = await loader.loadAsync( 'textures/memorial.exr' );
+ * ```
+ *
+ * @augments DataTextureLoader
+ */
 class EXRLoader extends DataTextureLoader {
 
+	/**
+	 * Constructs a new EXR loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * The texture type.
+		 *
+		 * @type {(HalfFloatType|FloatType)}
+		 * @default HalfFloatType
+		 */
 		this.type = HalfFloatType;
 
 	}
 
+	/**
+	 * Parses the given EXR texture data.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw texture data.
+	 * @return {DataTextureLoader~TexData} An object representing the parsed texture data.
+	 */
 	parse( buffer ) {
 
 		const USHORT_RANGE = ( 1 << 16 );
@@ -2229,7 +2255,7 @@ class EXRLoader extends DataTextureLoader {
 
 				const attributeName = parseNullTerminatedString( buffer, offset );
 
-				if ( attributeName == 0 ) {
+				if ( attributeName === '' ) {
 
 					keepReading = false;
 
@@ -2533,6 +2559,12 @@ class EXRLoader extends DataTextureLoader {
 
 	}
 
+	/**
+	 * Sets the texture type.
+	 *
+	 * @param {(HalfFloatType|FloatType)} value - The texture type to set.
+	 * @return {RGBMLoader} A reference to this loader.
+	 */
 	setDataType( value ) {
 
 		this.type = value;

package/examples/jsm/loaders/FBXLoader.js

@@ -47,34 +47,55 @@ import {
 import * as fflate from '../libs/fflate.module.js';
 import { NURBSCurve } from '../curves/NURBSCurve.js';
 
+let fbxTree;
+let connections;
+let sceneGraph;
+
 /**
- * Loader loads FBX file and generates Group representing FBX scene.
- * Requires FBX file to be >= 7.0 and in ASCII or >= 6400 in Binary format
- * Versions lower than this may load but will probably have errors
+ * A loader for the FBX format.
+ *
+ * Requires FBX file to be >= 7.0 and in ASCII or >= 6400 in Binary format.
+ * Versions lower than this may load but will probably have errors.
  *
  * Needs Support:
- *  Morph normals / blend shape normals
+ * - Morph normals / blend shape normals
  *
  * FBX format references:
- * 	https://help.autodesk.com/view/FBX/2017/ENU/?guid=__cpp_ref_index_html (C++ SDK reference)
+ * - [C++ SDK reference]{@link https://help.autodesk.com/view/FBX/2017/ENU/?guid=__cpp_ref_index_html}
  *
  * Binary format specification:
- *	https://code.blender.org/2013/08/fbx-binary-file-format-specification/
+ * - [FBX binary file format specification]{@link https://code.blender.org/2013/08/fbx-binary-file-format-specification/}
+ *
+ * ```js
+ * const loader = new FBXLoader();
+ * const object = await loader.loadAsync( 'models/fbx/stanford-bunny.fbx' );
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
  */
-
-
-let fbxTree;
-let connections;
-let sceneGraph;
-
 class FBXLoader extends Loader {
 
+	/**
+	 * Constructs a new FBX loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded FBX 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;
@@ -113,6 +134,13 @@ class FBXLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given FBX data and returns the resulting group.
+	 *
+	 * @param {Array} FBXBuffer - The raw FBX data as an array buffer.
+	 * @param {string} path - The URL base path.
+	 * @return {Group} An object representing the parsed asset.
+	 */
 	parse( FBXBuffer, path ) {
 
 		if ( isFbxFormatBinary( FBXBuffer ) ) {
@@ -1011,7 +1039,7 @@ class FBXTreeParser {
 						skeleton.bones[ i ] = bone;
 
 						// In cases where a bone is shared between multiple meshes
-						// duplicate the bone here and and it as a child of the first bone
+						// duplicate the bone here and add it as a child of the first bone
 						if ( subBone !== null ) {
 
 							bone.add( subBone );
@@ -1298,6 +1326,35 @@ class FBXTreeParser {
 
 		}
 
+		// Sanitization: If geometry has groups, then it must match the provided material array.
+		// If not, we need to clean up the `group.materialIndex` properties inside the groups and point at a (new) default material.
+		// This isn't well defined; Unity creates default material, while Blender implicitly uses the previous material in the list.
+		if ( geometry.groups.length > 0 ) {
+
+			let needsDefaultMaterial = false;
+
+			for ( let i = 0, il = geometry.groups.length; i < il; i ++ ) {
+
+				const group = geometry.groups[ i ];
+
+				if ( group.materialIndex < 0 || group.materialIndex >= materials.length ) {
+
+					group.materialIndex = materials.length;
+					needsDefaultMaterial = true;
+
+				}
+
+			}
+
+			if ( needsDefaultMaterial ) {
+
+				const defaultMaterial = new MeshPhongMaterial();
+				materials.push( defaultMaterial );
+
+			}
+
+		}
+
 		if ( geometry.FBX_Deformer ) {
 
 			model = new SkinnedMesh( geometry, material );
@@ -2706,7 +2763,7 @@ class AnimationParser {
 	}
 
 	// parse nodes in FBXTree.Objects.AnimationStack. These are the top level node in the animation
-	// hierarchy. Each Stack node will be used to create a AnimationClip
+	// hierarchy. Each Stack node will be used to create an AnimationClip
 	parseAnimStacks( layersMap ) {
 
 		const rawStacks = fbxTree.Objects.AnimationStack;

package/examples/jsm/loaders/FontLoader.js

@@ -4,14 +4,40 @@ import {
 	ShapePath
 } from 'three';
 
+/**
+ * A loader for loading fonts.
+ *
+ * You can convert fonts online using [facetype.js]{@link https://gero3.github.io/facetype.js/}.
+ *
+ * ```js
+ * const loader = new FontLoader();
+ * const font = await loader.loadAsync( 'fonts/helvetiker_regular.typeface.json' );
+ * ```
+ *
+ * @augments Loader
+ */
 class FontLoader extends Loader {
 
+	/**
+	 * Constructs a new font loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded font
+	 * 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(Font)} 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;
@@ -30,6 +56,12 @@ class FontLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given font data and returns the resulting font.
+	 *
+	 * @param {Object} json - The raw font data as a JSON object.
+	 * @return {Font} The font.
+	 */
 	parse( json ) {
 
 		return new Font( json );
@@ -38,20 +70,46 @@ class FontLoader extends Loader {
 
 }
 
-//
-
+/**
+ * Class representing a font.
+ */
 class Font {
 
+	/**
+	 * Constructs a new font.
+	 *
+	 * @param {Object} data - The font data as JSON.
+	 */
 	constructor( data ) {
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isFont = true;
 
 		this.type = 'Font';
 
+		/**
+		 * The font data as JSON.
+		 *
+		 * @type {Object}
+		 */
 		this.data = data;
 
 	}
 
+	/**
+	 * Generates geometry shapes from the given text and size. The result of this method
+	 * should be used with {@link ShapeGeometry} to generate the actual geometry data.
+	 *
+	 * @param {string} text - The text.
+	 * @param {number} [size=100] - The text size.
+	 * @return {Array<Shape>} An array of shapes representing the text.
+	 */
 	generateShapes( text, size = 100 ) {
 
 		const shapes = [];

package/examples/jsm/loaders/GCodeLoader.js

@@ -9,26 +9,48 @@ import {
 } from 'three';
 
 /**
- * GCodeLoader is used to load gcode files usually used for 3D printing or CNC applications.
+ * A loader for the GCode format.
  *
- * Gcode files are composed by commands used by machines to create objects.
+ * GCode files are usually used for 3D printing or CNC applications.
  *
- * @class GCodeLoader
+ * ```js
+ * const loader = new GCodeLoader();
+ * const object = await loader.loadAsync( 'models/gcode/benchy.gcode' );
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
  */
-
 class GCodeLoader extends Loader {
 
 	/**
-	 * @param {Manager} manager Loading manager.
+	 * Constructs a new GCode loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
 	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * Whether to split layers or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.splitLayer = false;
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded GCode 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;
@@ -63,6 +85,12 @@ class GCodeLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given GCode data and returns a group with lines.
+	 *
+	 * @param {string} data - The raw Gcode data as a string.
+	 * @return {Group} The parsed GCode asset.
+	 */
 	parse( data ) {
 
 		let state = { x: 0, y: 0, z: 0, e: 0, f: 0, extruding: false, relative: false };