@plastic-software/three 0.174.0 → 0.175.1

package/src/geometries/ExtrudeGeometry.js

@@ -1,25 +1,3 @@
-/**
- * Creates extruded geometry from a path shape.
- *
- * parameters = {
- *
- *  curveSegments: <int>, // number of points on the curves
- *  steps: <int>, // number of points for z-side extrusions / used for subdividing segments of extrude spline too
- *  depth: <float>, // Depth to extrude the shape
- *
- *  bevelEnabled: <bool>, // turn on bevel
- *  bevelThickness: <float>, // how deep into the original shape bevel goes
- *  bevelSize: <float>, // how far from shape outline (including bevelOffset) is bevel
- *  bevelOffset: <float>, // how far from shape outline does bevel start
- *  bevelSegments: <int>, // number of bevel layers
- *
- *  extrudePath: <THREE.Curve> // curve to extrude shape along
- *
- *  UVGenerator: <Object> // object that provides UV generator functions
- *
- * }
- */
-
 import { BufferGeometry } from '../core/BufferGeometry.js';
 import { Float32BufferAttribute } from '../core/BufferAttribute.js';
 import * as Curves from '../extras/curves/Curves.js';
@@ -55,17 +33,7 @@ class ExtrudeGeometry extends BufferGeometry {
 	 * Constructs a new extrude geometry.
 	 *
 	 * @param {Shape|Array<Shape>} [shapes] - A shape or an array of shapes.
-	 * @param {Object} [options={}] - The extrude settings.
-	 * @param {number} [options.curveSegments=12] - Number of points on the curves.
-	 * @param {number} [options.steps=1] - Number of points used for subdividing segments along the depth of the extruded spline.
-	 * @param {number} [options.depth=1] - Depth to extrude the shape.
-	 * @param {boolean} [options.bevelEnabled=true] - Whether to beveling to the shape or not.
-	 * @param {number} [options.bevelThickness=0.2] - How deep into the original shape the bevel goes.
-	 * @param {number} [options.bevelSize=bevelThickness-0.1] - Distance from the shape outline that the bevel extends.
-	 * @param {number} [options.bevelOffset=0] - Distance from the shape outline that the bevel starts.
-	 * @param {number} [options.bevelSegments=3] - Number of bevel layers.
-	 * @param {Curve} [options.extrudePath=3] - A 3D spline path along which the shape should be extruded. Bevels not supported for path extrusion.
-	 * @param {Object} [options.UVGenerator] - An object that provides UV generator functions for custom UV generation.
+	 * @param {ExtrudeGeometry~Options} [options] - The extrude settings.
 	 */
 	constructor( shapes = new Shape( [ new Vector2( 0.5, 0.5 ), new Vector2( - 0.5, 0.5 ), new Vector2( - 0.5, - 0.5 ), new Vector2( 0.5, - 0.5 ) ] ), options = {} ) {
 
@@ -194,14 +162,53 @@ class ExtrudeGeometry extends BufferGeometry {
 
 			}
 
+			/**Merges index-adjacent points that are within a threshold distance of each other. Array is modified in-place. Threshold distance is empirical, and scaled based on the magnitude of point coordinates.
+			 * @param {Array<Vector2>} points
+			*/
+			function mergeOverlappingPoints( points ) {
+
+				const THRESHOLD = 1e-10;
+				const THRESHOLD_SQ = THRESHOLD * THRESHOLD;
+				let prevPos = points[ 0 ];
+				for ( let i = 1; i <= points.length; i ++ ) {
+
+					const currentIndex = i % points.length;
+					const currentPos = points[ currentIndex ];
+					const dx = currentPos.x - prevPos.x;
+					const dy = currentPos.y - prevPos.y;
+					const distSq = dx * dx + dy * dy;
+
+					const scalingFactorSqrt = Math.max(
+						Math.abs( currentPos.x ),
+						Math.abs( currentPos.y ),
+						Math.abs( prevPos.x ),
+						Math.abs( prevPos.y )
+					);
+					const thesholdSqScaled = THRESHOLD_SQ * scalingFactorSqrt * scalingFactorSqrt;
+					if ( distSq <= thesholdSqScaled ) {
+
+						points.splice( currentIndex, 1 );
+						i --;
+						continue;
 
-			const faces = ShapeUtils.triangulateShape( vertices, holes );
+					}
+
+					prevPos = currentPos;
+
+				}
+
+			}
+
+			mergeOverlappingPoints( vertices );
+			holes.forEach( mergeOverlappingPoints );
+
+			const numHoles = holes.length;
 
 			/* Vertices */
 
 			const contour = vertices; // vertices has all points but contour has only points of circumference
 
-			for ( let h = 0, hl = holes.length; h < hl; h ++ ) {
+			for ( let h = 0; h < numHoles; h ++ ) {
 
 				const ahole = holes[ h ];
 
@@ -218,7 +225,7 @@ class ExtrudeGeometry extends BufferGeometry {
 
 			}
 
-			const vlen = vertices.length, flen = faces.length;
+			const vlen = vertices.length;
 
 
 			// Find directions for point movement
@@ -365,7 +372,7 @@ class ExtrudeGeometry extends BufferGeometry {
 			const holesMovements = [];
 			let oneHoleMovements, verticesMovements = contourMovements.concat();
 
-			for ( let h = 0, hl = holes.length; h < hl; h ++ ) {
+			for ( let h = 0, hl = numHoles; h < hl; h ++ ) {
 
 				const ahole = holes[ h ];
 
@@ -386,6 +393,8 @@ class ExtrudeGeometry extends BufferGeometry {
 
 			}
 
+			const contractedContourVertices = [];
+			const expandedHoleVertices = [];
 
 			// Loop bevelSegments, 1 for the front, 1 for the back
 
@@ -404,28 +413,36 @@ class ExtrudeGeometry extends BufferGeometry {
 					const vert = scalePt2( contour[ i ], contourMovements[ i ], bs );
 
 					v( vert.x, vert.y, - z );
+					if ( t == 0 ) contractedContourVertices.push( vert );
 
 				}
 
 				// expand holes
 
-				for ( let h = 0, hl = holes.length; h < hl; h ++ ) {
+				for ( let h = 0, hl = numHoles; h < hl; h ++ ) {
 
 					const ahole = holes[ h ];
 					oneHoleMovements = holesMovements[ h ];
-
+					const oneHoleVertices = [];
 					for ( let i = 0, il = ahole.length; i < il; i ++ ) {
 
 						const vert = scalePt2( ahole[ i ], oneHoleMovements[ i ], bs );
 
 						v( vert.x, vert.y, - z );
+						if ( t == 0 ) oneHoleVertices.push( vert );
 
 					}
 
+					if ( t == 0 ) expandedHoleVertices.push( oneHoleVertices );
+
 				}
 
 			}
 
+			const faces = ShapeUtils.triangulateShape( contractedContourVertices, expandedHoleVertices );
+
+			const flen = faces.length;
+
 			const bs = bevelSize + bevelOffset;
 
 			// Back facing vertices
@@ -862,5 +879,20 @@ function toJSON( shapes, options, data ) {
 
 }
 
+/**
+ * Represents the `options` type of the geometry's constructor.
+ *
+ * @typedef {Object} ExtrudeGeometry~Options
+ * @property {number} [curveSegments=12] - Number of points on the curves.
+ * @property {number} [steps=1] - Number of points used for subdividing segments along the depth of the extruded spline.
+ * @property {number} [depth=1] - Depth to extrude the shape.
+ * @property {boolean} [bevelEnabled=true] - Whether to beveling to the shape or not.
+ * @property {number} [bevelThickness=0.2] - How deep into the original shape the bevel goes.
+ * @property {number} [bevelSize=bevelThickness-0.1] - Distance from the shape outline that the bevel extends.
+ * @property {number} [bevelOffset=0] - Distance from the shape outline that the bevel starts.
+ * @property {number} [bevelSegments=3] - Number of bevel layers.
+ * @property {?Curve} [extrudePath=null] - A 3D spline path along which the shape should be extruded. Bevels not supported for path extrusion.
+ * @property {Object} [UVGenerator] - An object that provides UV generator functions for custom UV generation.
+ **/
 
 export { ExtrudeGeometry };

package/src/geometries/LatheGeometry.js

@@ -25,7 +25,7 @@ class LatheGeometry extends BufferGeometry {
 	/**
 	 * Constructs a new lathe geometry.
 	 *
-	 * @param {Array<Vector2>} [points] - An array of points in 2D space. The x-coordinate of each point
+	 * @param {Array<Vector2|Vector3>} [points] - An array of points in 2D space. The x-coordinate of each point
 	 * must be greater than zero.
 	 * @param {number} [segments=12] - The number of circumference segments to generate.
 	 * @param {number} [phiStart=0] - The starting angle in radians.

package/src/lights/LightShadow.js

@@ -10,7 +10,7 @@ const _lookTarget = /*@__PURE__*/ new Vector3();
 
 /**
  * Abstract base class for light shadow classes. These classes
- * represent the shadow configuration for different ligth types.
+ * represent the shadow configuration for different light types.
  *
  * @abstract
  */

package/src/lights/webgpu/IESSpotLight.js

@@ -22,7 +22,7 @@ class IESSpotLight extends SpotLight {
 		super( color, intensity, distance, angle, penumbra, decay );
 
 		/**
-		 * TOOD
+		 * TODO
 		 *
 		 * @type {?Texture}
 		 * @default null

package/src/loaders/AnimationLoader.js

@@ -2,14 +2,39 @@ import { AnimationClip } from '../animation/AnimationClip.js';
 import { FileLoader } from './FileLoader.js';
 import { Loader } from './Loader.js';
 
+/**
+ * Class for loading animation clips in the JSON format. The files are internally
+ * loaded via {@link FileLoader}.
+ *
+ * ```js
+ * const loader = new THREE.AnimationLoader();
+ * const animations = await loader.loadAsync( 'animations/animation.js' );
+ * ```
+ *
+ * @augments Loader
+ */
 class AnimationLoader extends Loader {
 
+	/**
+	 * Constructs a new animation loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and pass the loaded animations as an array
+	 * holding instances of {@link AnimationClip} 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(Array<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;
@@ -44,6 +69,12 @@ class AnimationLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given JSON object and returns an array of animation clips.
+	 *
+	 * @param {Object} json - The serialized animation clips.
+	 * @return {Array<AnimationClip>} The parsed animation clips.
+	 */
 	parse( json ) {
 
 		const animations = [];

package/src/loaders/AudioLoader.js

@@ -2,14 +2,45 @@ import { AudioContext } from '../audio/AudioContext.js';
 import { FileLoader } from './FileLoader.js';
 import { Loader } from './Loader.js';
 
+/**
+ * Class for loading audio buffers. Audios are internally
+ * loaded via {@link FileLoader}.
+ *
+ * ```js
+ * const audioListener = new THREE.AudioListener();
+ * const ambientSound = new THREE.Audio( audioListener );
+ *
+ * const loader = new THREE.AudioLoader();
+ * const audioBuffer = await loader.loadAsync( 'audio/ambient_ocean.ogg' );
+ *
+ * ambientSound.setBuffer( audioBuffer );
+ * ambientSound.play();
+ * ```
+ *
+ * @augments Loader
+ */
 class AudioLoader extends Loader {
 
+	/**
+	 * Constructs a new audio loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded audio buffer
+	 * 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(AudioBuffer)} 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;

package/src/loaders/BufferGeometryLoader.js

@@ -10,14 +10,42 @@ import { InterleavedBufferAttribute } from '../core/InterleavedBufferAttribute.j
 import { InterleavedBuffer } from '../core/InterleavedBuffer.js';
 import { getTypedArray } from '../utils.js';
 
+/**
+ * Class for loading geometries. The files are internally
+ * loaded via {@link FileLoader}.
+ *
+ * ```js
+ * const loader = new THREE.BufferGeometryLoader();
+ * const geometry = await loader.loadAsync( 'models/json/pressure.json' );
+ *
+ * const material = new THREE.MeshBasicMaterial( { color: 0xF5F5F5 } );
+ * const object = new THREE.Mesh( geometry, material );
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
+ */
 class BufferGeometryLoader extends Loader {
 
+	/**
+	 * Constructs a new geometry loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and pass the loaded geometry 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;
@@ -52,6 +80,12 @@ class BufferGeometryLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given JSON object and returns a geometry.
+	 *
+	 * @param {Object} json - The serialized geometry.
+	 * @return {BufferGeometry} The parsed geometry.
+	 */
 	parse( json ) {
 
 		const interleavedBufferMap = {};

package/src/loaders/Cache.js

@@ -1,9 +1,36 @@
+/**
+ * @class
+ * @classdesc A simple caching system, used internally by {@link FileLoader}.
+ * To enable caching across all loaders that use {@link FileLoader}, add `THREE.Cache.enabled = true.` once in your app.
+ * @hideconstructor
+ */
 const Cache = {
 
+	/**
+	 * Whether caching is enabled or not.
+	 *
+	 * @static
+	 * @type {boolean}
+	 * @default false
+	 */
 	enabled: false,
 
+	/**
+	 * A dictionary that holds cached files.
+	 *
+	 * @static
+	 * @type {Object<string,Object>}
+	 */
 	files: {},
 
+	/**
+	 * Adds a cache entry with a key to reference the file. If this key already
+	 * holds a file, it is overwritten.
+	 *
+	 * @static
+	 * @param {string} key - The key to reference the cached file.
+	 * @param {Object} file -  The file to be cached.
+	 */
 	add: function ( key, file ) {
 
 		if ( this.enabled === false ) return;
@@ -14,6 +41,13 @@ const Cache = {
 
 	},
 
+	/**
+	 * Gets the cached value for the given key.
+	 *
+	 * @static
+	 * @param {string} key - The key to reference the cached file.
+	 * @return {Object|undefined} The cached file. If the key does not exist `undefined` is returned.
+	 */
 	get: function ( key ) {
 
 		if ( this.enabled === false ) return;
@@ -24,12 +58,23 @@ const Cache = {
 
 	},
 
+	/**
+	 * Removes the cached file associated with the given key.
+	 *
+	 * @static
+	 * @param {string} key - The key to reference the cached file.
+	 */
 	remove: function ( key ) {
 
 		delete this.files[ key ];
 
 	},
 
+	/**
+	 * Remove all values from the cache.
+	 *
+	 * @static
+	 */
 	clear: function () {
 
 		this.files = {};

package/src/loaders/CompressedTextureLoader.js

@@ -4,19 +4,40 @@ import { CompressedTexture } from '../textures/CompressedTexture.js';
 import { Loader } from './Loader.js';
 
 /**
- * Abstract Base class to block based textures loader (dds, pvr, ...)
+ * Abstract base class for loading compressed texture formats S3TC, ASTC or ETC.
+ * Textures are internally loaded via {@link FileLoader}.
  *
- * Sub classes have to implement the parse() method which will be used in load().
+ * Derived classes have to implement the `parse()` method which holds the parsing
+ * for the respective format.
+ *
+ * @abstract
+ * @augments Loader
  */
-
 class CompressedTextureLoader extends Loader {
 
+	/**
+	 * Constructs a new compressed texture loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded compressed texture
+	 * to the `onLoad()` callback. The method also returns a new texture object which can
+	 * directly be used for material creation. If you do it this way, the texture
+	 * may pop up in your scene once the respective loading process is finished.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function(CompressedTexture)} 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.
+	 * @return {CompressedTexture} The compressed texture.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -130,5 +151,17 @@ class CompressedTextureLoader extends Loader {
 
 }
 
+/**
+ * Represents the result object type of the `parse()` method.
+ *
+ * @typedef {Object} CompressedTextureLoader~TexData
+ * @property {number} width - The width of the base mip.
+ * @property {number} height - The width of the base mip.
+ * @property {boolean} isCubemap - Whether the data represent a cubemap or not.
+ * @property {number} mipmapCount - The mipmap count.
+ * @property {Array<{data:TypedArray,width:number,height:number}>} mipmaps - An array holding the mipmaps.
+ * Each entry holds the data and the dimensions for each level.
+ * @property {number} format - The texture format.
+ **/
 
 export { CompressedTextureLoader };

package/src/loaders/CubeTextureLoader.js

@@ -3,14 +3,59 @@ import { CubeTexture } from '../textures/CubeTexture.js';
 import { Loader } from './Loader.js';
 import { SRGBColorSpace } from '../constants.js';
 
+/**
+ * Class for loading cube textures. Images are internally loaded via {@link ImageLoader}.
+ *
+ * The loader returns an instance of {@link CubeTexture} and expects the cube map to
+ * be defined as six separate images representing the sides of a cube. Other cube map definitions
+ * like vertical and horizontal cross, column and row layouts are not supported.
+ *
+ * Note that, by convention, cube maps are specified in a coordinate system
+ * in which positive-x is to the right when looking up the positive-z axis --
+ * in other words, using a left-handed coordinate system. Since three.js uses
+ * a right-handed coordinate system, environment maps used in three.js will
+ * have pos-x and neg-x swapped.
+ *
+ * The loaded cube texture is in sRGB color space. Meaning {@link Texture#colorSpace}
+ * is set to `SRGBColorSpace` by default.
+ *
+ * ```js
+ * const loader = new THREE.CubeTextureLoader().setPath( 'textures/cubeMaps/' );
+ * const cubeTexture = await loader.loadAsync( [
+ * 	'px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png', 'nz.png'
+ * ] );
+ * scene.background = cubeTexture;
+ * ```
+ *
+ * @augments Loader
+ */
 class CubeTextureLoader extends Loader {
 
+	/**
+	 * Constructs a new cube texture loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and pass the fully loaded cube texture
+	 * to the `onLoad()` callback. The method also returns a new cube texture object which can
+	 * directly be used for material creation. If you do it this way, the cube texture
+	 * may pop up in your scene once the respective loading process is finished.
+	 *
+	 * @param {Array<string>} urls - Array of 6 URLs to images, one for each side of the
+	 * cube texture. The urls should be specified in the following order: pos-x,
+	 * neg-x, pos-y, neg-y, pos-z, neg-z. An array of data URIs are allowed as well.
+	 * @param {function(CubeTexture)} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Unsupported in this loader.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 * @return {CubeTexture} The cube texture.
+	 */
 	load( urls, onLoad, onProgress, onError ) {
 
 		const texture = new CubeTexture();

package/src/loaders/DataTextureLoader.js

@@ -4,19 +4,40 @@ import { DataTexture } from '../textures/DataTexture.js';
 import { Loader } from './Loader.js';
 
 /**
- * Abstract Base class to load generic binary textures formats (rgbe, hdr, ...)
+ * Abstract base class for loading binary texture formats RGBE, EXR or TGA.
+ * Textures are internally loaded via {@link FileLoader}.
  *
- * Sub classes have to implement the parse() method which will be used in load().
+ * Derived classes have to implement the `parse()` method which holds the parsing
+ * for the respective format.
+ *
+ * @abstract
+ * @augments Loader
  */
-
 class DataTextureLoader extends Loader {
 
+	/**
+	 * Constructs a new data texture loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded data texture
+	 * to the `onLoad()` callback. The method also returns a new texture object which can
+	 * directly be used for material creation. If you do it this way, the texture
+	 * may pop up in your scene once the respective loading process is finished.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function(DataTexture)} 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.
+	 * @return {DataTexture} The data texture.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -127,5 +148,25 @@ class DataTextureLoader extends Loader {
 
 }
 
+/**
+ * Represents the result object type of the `parse()` method.
+ *
+ * @typedef {Object} DataTextureLoader~TexData
+ * @property {Object} [image] - An object holding width, height and the texture data.
+ * @property {number} [width] - The width of the base mip.
+ * @property {number} [height] - The width of the base mip.
+ * @property {TypedArray} [data] - The texture data.
+ * @property {number} [format] - The texture format.
+ * @property {number} [type] - The texture type.
+ * @property {boolean} [flipY] - If set to `true`, the texture is flipped along the vertical axis when uploaded to the GPU.
+ * @property {number} [wrapS=ClampToEdgeWrapping] - The wrapS value.
+ * @property {number} [wrapT=ClampToEdgeWrapping] - The wrapT value.
+ * @property {number} [anisotropy=1] - The anisotropy value.
+ * @property {boolean} [generateMipmaps] - Whether to generate mipmaps or not.
+ * @property {string} [colorSpace] - The color space.
+ * @property {number} [magFilter] - The mag filter.
+ * @property {number} [minFilter] - The min filter.
+ * @property {Array<Object>} [mipmaps] - The mipmaps.
+ **/
 
 export { DataTextureLoader };