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

package/examples/jsm/loaders/NRRDLoader.js

@@ -4,17 +4,42 @@ import {
 	Matrix4,
 	Vector3
 } from 'three';
-import * as fflate from '../libs/fflate.module.js';
+import { gunzipSync } 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
+ * @three_import import { NRRDLoader } from 'three/addons/loaders/NRRDLoader.js';
+ */
 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 +76,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
@@ -232,7 +264,7 @@ class NRRDLoader extends Loader {
 
 		}
 
-		//parse the data when registred as one of this type : 'text', 'ascii', 'txt'
+		//parse the data when registered as one of this type : 'text', 'ascii', 'txt'
 		function parseDataAsText( data, start, end ) {
 
 			let number = '';
@@ -307,7 +339,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;
@@ -324,7 +356,7 @@ class NRRDLoader extends Loader {
 
 			// we need to decompress the datastream
 			// here we start the unzipping and get a typed Uint8Array back
-			_data = fflate.gunzipSync( new Uint8Array( _data ) );
+			_data = gunzipSync( new Uint8Array( _data ) );
 
 		} else if ( headerObject.encoding === 'ascii' || headerObject.encoding === 'text' || headerObject.encoding === 'txt' || headerObject.encoding === 'hex' ) {
 
@@ -485,7 +517,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

@@ -433,19 +433,55 @@ function ParserState() {
 
 }
 
-//
 
+/**
+ * A loader for the OBJ format.
+ *
+ * The [OBJ format](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
+ * @three_import import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
+ */
 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;
 		this.materialsLoader = new MTLLoader( manager );
 
 	}
 
+	/**
+	 * 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;
@@ -510,7 +546,7 @@ class OBJLoader extends Loader {
 
 	}
 
-	setMTLLoader ( loader ) { 
+	setMTLLoader ( loader ) {
 
 		this.materialsLoader = loader;
 
@@ -518,6 +554,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;
@@ -526,6 +568,13 @@ class OBJLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given OBJ data and returns the resulting group.
+	 *
+	 * @param {string} text - The raw OBJ data as a string.
+	 * @param {boolean} parseOnly - If true, only parse without creating meshes.
+	 * @return {Group} The parsed OBJ.
+	 */
 	parse( text, parseOnly = false ) {
 
 		const state = new ParserState();

package/examples/jsm/loaders/PCDLoader.js

@@ -10,16 +10,58 @@ 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
+ * @three_import import { PCDLoader } from 'three/addons/loaders/PCDLoader.js';
+ */
 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 +97,78 @@ class PCDLoader extends Loader {
 
 	}
 
+	/**
+	 * Get dataview value by field type and size.
+	 *
+	 * @private
+	 * @param {DataView} dataview - The DataView to read from.
+	 * @param {number} offset - The offset to start reading from.
+	 * @param {'F' | 'U' | 'I'} type - Field type.
+	 * @param {number} size - Field size.
+	 * @returns {number} Field value.
+	 */
+	_getDataView( dataview, offset, type, size ) {
+
+		switch ( type ) {
+
+			case 'F': {
+
+				if ( size === 8 ) {
+
+					return dataview.getFloat64( offset, this.littleEndian );
+
+				}
+
+				return dataview.getFloat32( offset, this.littleEndian );
+
+			}
+
+			case 'I': {
+
+				if ( size === 1 ) {
+
+					return dataview.getInt8( offset );
+
+				}
+
+				if ( size === 2 ) {
+
+					return dataview.getInt16( offset, this.littleEndian );
+
+				}
+
+				return dataview.getInt32( offset, this.littleEndian );
+
+			}
+
+			case 'U': {
+
+				if ( size === 1 ) {
+
+					return dataview.getUint8( offset );
+
+				}
+
+				if ( size === 2 ) {
+
+					return dataview.getUint16( offset, this.littleEndian );
+
+				}
+
+				return dataview.getUint32( offset, this.littleEndian );
+
+			}
+
+		}
+
+	}
+
+	/**
+	 * 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
@@ -112,9 +226,40 @@ class PCDLoader extends Loader {
 
 		}
 
-		function parseHeader( data ) {
+		function parseHeader( binaryData ) {
 
 			const PCDheader = {};
+
+			const buffer = new Uint8Array( binaryData );
+
+			let data = '', line = '', i = 0, end = false;
+
+			const max = buffer.length;
+
+			while ( i < max && end === false ) {
+
+				const char = String.fromCharCode( buffer[ i ++ ] );
+
+				if ( char === '\n' || char === '\r' ) {
+
+					if ( line.trim().toLowerCase().startsWith( 'data' ) ) {
+
+						end = true;
+
+					}
+
+					line = '';
+
+				} else {
+
+					line += char;
+
+				}
+
+				data += char;
+
+			}
+
 			const result1 = data.search( /[\r\n]DATA\s(\S*)\s/i );
 			const result2 = /[\r\n]DATA\s(\S*)\s/i.exec( data.slice( result1 - 1 ) );
 
@@ -220,11 +365,9 @@ class PCDLoader extends Loader {
 
 		}
 
-		const textData = new TextDecoder().decode( data );
-
-		// parse header (always ascii format)
+		// parse header
 
-		const PCDheader = parseHeader( textData );
+		const PCDheader = parseHeader( data );
 
 		// parse data
 
@@ -241,6 +384,7 @@ class PCDLoader extends Loader {
 		if ( PCDheader.data === 'ascii' ) {
 
 			const offset = PCDheader.offset;
+			const textData = new TextDecoder().decode( data );
 			const pcdData = textData.slice( PCDheader.headerLen );
 			const lines = pcdData.split( '\n' );
 
@@ -333,9 +477,9 @@ class PCDLoader extends Loader {
 					const xIndex = PCDheader.fields.indexOf( 'x' );
 					const yIndex = PCDheader.fields.indexOf( 'y' );
 					const zIndex = PCDheader.fields.indexOf( 'z' );
-					position.push( dataview.getFloat32( ( PCDheader.points * offset.x ) + PCDheader.size[ xIndex ] * i, this.littleEndian ) );
-					position.push( dataview.getFloat32( ( PCDheader.points * offset.y ) + PCDheader.size[ yIndex ] * i, this.littleEndian ) );
-					position.push( dataview.getFloat32( ( PCDheader.points * offset.z ) + PCDheader.size[ zIndex ] * i, this.littleEndian ) );
+					position.push( this._getDataView( dataview, ( PCDheader.points * offset.x ) + PCDheader.size[ xIndex ] * i, PCDheader.type[ xIndex ], PCDheader.size[ xIndex ] ) );
+					position.push( this._getDataView( dataview, ( PCDheader.points * offset.y ) + PCDheader.size[ yIndex ] * i, PCDheader.type[ yIndex ], PCDheader.size[ yIndex ] ) );
+					position.push( this._getDataView( dataview, ( PCDheader.points * offset.z ) + PCDheader.size[ zIndex ] * i, PCDheader.type[ zIndex ], PCDheader.size[ zIndex ] ) );
 
 				}
 
@@ -358,23 +502,23 @@ class PCDLoader extends Loader {
 					const xIndex = PCDheader.fields.indexOf( 'normal_x' );
 					const yIndex = PCDheader.fields.indexOf( 'normal_y' );
 					const zIndex = PCDheader.fields.indexOf( 'normal_z' );
-					normal.push( dataview.getFloat32( ( PCDheader.points * offset.normal_x ) + PCDheader.size[ xIndex ] * i, this.littleEndian ) );
-					normal.push( dataview.getFloat32( ( PCDheader.points * offset.normal_y ) + PCDheader.size[ yIndex ] * i, this.littleEndian ) );
-					normal.push( dataview.getFloat32( ( PCDheader.points * offset.normal_z ) + PCDheader.size[ zIndex ] * i, this.littleEndian ) );
+					normal.push( this._getDataView( dataview, ( PCDheader.points * offset.normal_x ) + PCDheader.size[ xIndex ] * i, PCDheader.type[ xIndex ], PCDheader.size[ xIndex ] ) );
+					normal.push( this._getDataView( dataview, ( PCDheader.points * offset.normal_y ) + PCDheader.size[ yIndex ] * i, PCDheader.type[ yIndex ], PCDheader.size[ yIndex ] ) );
+					normal.push( this._getDataView( dataview, ( PCDheader.points * offset.normal_z ) + PCDheader.size[ zIndex ] * i, PCDheader.type[ zIndex ], PCDheader.size[ zIndex ] ) );
 
 				}
 
 				if ( offset.intensity !== undefined ) {
 
 					const intensityIndex = PCDheader.fields.indexOf( 'intensity' );
-					intensity.push( dataview.getFloat32( ( PCDheader.points * offset.intensity ) + PCDheader.size[ intensityIndex ] * i, this.littleEndian ) );
+					intensity.push( this._getDataView( dataview, ( PCDheader.points * offset.intensity ) + PCDheader.size[ intensityIndex ] * i, PCDheader.type[ intensityIndex ], PCDheader.size[ intensityIndex ] ) );
 
 				}
 
 				if ( offset.label !== undefined ) {
 
 					const labelIndex = PCDheader.fields.indexOf( 'label' );
-					label.push( dataview.getInt32( ( PCDheader.points * offset.label ) + PCDheader.size[ labelIndex ] * i, this.littleEndian ) );
+					label.push( this._getDataView( dataview, ( PCDheader.points * offset.label ) + PCDheader.size[ labelIndex ] * i, PCDheader.type[ labelIndex ], PCDheader.size[ labelIndex ] ) );
 
 				}
 
@@ -393,9 +537,12 @@ class PCDLoader extends Loader {
 
 				if ( offset.x !== undefined ) {
 
-					position.push( dataview.getFloat32( row + offset.x, this.littleEndian ) );
-					position.push( dataview.getFloat32( row + offset.y, this.littleEndian ) );
-					position.push( dataview.getFloat32( row + offset.z, this.littleEndian ) );
+					const xIndex = PCDheader.fields.indexOf( 'x' );
+					const yIndex = PCDheader.fields.indexOf( 'y' );
+					const zIndex = PCDheader.fields.indexOf( 'z' );
+					position.push( this._getDataView( dataview, row + offset.x, PCDheader.type[ xIndex ], PCDheader.size[ xIndex ] ) );
+					position.push( this._getDataView( dataview, row + offset.y, PCDheader.type[ yIndex ], PCDheader.size[ yIndex ] ) );
+					position.push( this._getDataView( dataview, row + offset.z, PCDheader.type[ zIndex ], PCDheader.size[ zIndex ] ) );
 
 				}
 
@@ -413,21 +560,26 @@ class PCDLoader extends Loader {
 
 				if ( offset.normal_x !== undefined ) {
 
-					normal.push( dataview.getFloat32( row + offset.normal_x, this.littleEndian ) );
-					normal.push( dataview.getFloat32( row + offset.normal_y, this.littleEndian ) );
-					normal.push( dataview.getFloat32( row + offset.normal_z, this.littleEndian ) );
+					const xIndex = PCDheader.fields.indexOf( 'normal_x' );
+					const yIndex = PCDheader.fields.indexOf( 'normal_y' );
+					const zIndex = PCDheader.fields.indexOf( 'normal_z' );
+					normal.push( this._getDataView( dataview, row + offset.normal_x, PCDheader.type[ xIndex ], PCDheader.size[ xIndex ] ) );
+					normal.push( this._getDataView( dataview, row + offset.normal_y, PCDheader.type[ yIndex ], PCDheader.size[ yIndex ] ) );
+					normal.push( this._getDataView( dataview, row + offset.normal_z, PCDheader.type[ zIndex ], PCDheader.size[ zIndex ] ) );
 
 				}
 
 				if ( offset.intensity !== undefined ) {
 
-					intensity.push( dataview.getFloat32( row + offset.intensity, this.littleEndian ) );
+					const intensityIndex = PCDheader.fields.indexOf( 'intensity' );
+					intensity.push( this._getDataView( dataview, row + offset.intensity, PCDheader.type[ intensityIndex ], PCDheader.size[ intensityIndex ] ) );
 
 				}
 
 				if ( offset.label !== undefined ) {
 
-					label.push( dataview.getInt32( row + offset.label, this.littleEndian ) );
+					const labelIndex = PCDheader.fields.indexOf( 'label' );
+					label.push( this._getDataView( dataview, row + offset.label, PCDheader.type[ labelIndex ], PCDheader.size[ labelIndex ] ) );
 
 				}
 

package/examples/jsm/loaders/PDBLoader.js

@@ -7,14 +7,46 @@ import {
 	SRGBColorSpace
 } from 'three';
 
+/**
+ * A loader for the PDB format.
+ *
+ * The [Protein Data Bank](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
+ * @three_import import { PDBLoader } from 'three/addons/loaders/PDBLoader.js';
+ */
 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 +81,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*$/, '' );