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

package/examples/jsm/geometries/BoxLineGeometry.js

@@ -3,8 +3,31 @@ import {
 	Float32BufferAttribute
 } from 'three';
 
+/**
+ * A special type of box geometry intended for {@link LineSegments}.
+ *
+ * ```js
+ * const geometry = new THREE.BoxLineGeometry();
+ * const material = new THREE.LineBasicMaterial( { color: 0x00ff00 } );
+ * const lines = new THREE.LineSegments( geometry, material );
+ * scene.add( lines );
+ * ```
+ *
+ * @augments BufferGeometry
+ * @three_import import { BoxLineGeometry } from 'three/addons/geometries/BoxLineGeometry.js';
+ */
 class BoxLineGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new box line geometry.
+	 *
+	 * @param {number} [width=1] - The width. That is, the length of the edges parallel to the X axis.
+	 * @param {number} [height=1] - The height. That is, the length of the edges parallel to the Y axis.
+	 * @param {number} [depth=1] - The depth. That is, the length of the edges parallel to the Z axis.
+	 * @param {number} [widthSegments=1] - Number of segmented rectangular sections along the width of the sides.
+	 * @param {number} [heightSegments=1] - Number of segmented rectangular sections along the height of the sides.
+	 * @param {number} [depthSegments=1] - Number of segmented rectangular sections along the depth of the sides.
+	 */
 	constructor( width = 1, height = 1, depth = 1, widthSegments = 1, heightSegments = 1, depthSegments = 1 ) {
 
 		super();

package/examples/jsm/geometries/ConvexGeometry.js

@@ -4,8 +4,27 @@ import {
 } from 'three';
 import { ConvexHull } from '../math/ConvexHull.js';
 
+/**
+ * This class can be used to generate a convex hull for a given array of 3D points.
+ * The average time complexity for this task is considered to be O(nlog(n)).
+ *
+ * ```js
+ * const geometry = new ConvexGeometry( points );
+ * const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } );
+ * const mesh = new THREE.Mesh( geometry, material );
+ * scene.add( mesh );
+ * ```
+ *
+ * @augments BufferGeometry
+ * @three_import import { ConvexGeometry } from 'three/addons/geometries/ConvexGeometry.js';
+ */
 class ConvexGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new convex geometry.
+	 *
+	 * @param {Array<Vector3>} points - An array of points in 3D space which should be enclosed by the convex hull.
+	 */
 	constructor( points = [] ) {
 
 		super();

package/examples/jsm/geometries/DecalGeometry.js

@@ -1,29 +1,43 @@
 import {
 	BufferGeometry,
+	Euler,
 	Float32BufferAttribute,
 	Matrix3,
 	Matrix4,
+	Mesh,
 	Vector3
 } from 'three';
 
 /**
- * You can use this geometry to create a decal mesh, that serves different kinds of purposes.
- * e.g. adding unique details to models, performing dynamic visual environmental changes or covering seams.
+ * This class can be used to create a decal mesh that serves different kinds of purposes e.g.
+ * adding unique details to models, performing dynamic visual environmental changes or covering seams.
  *
- * Constructor parameter:
+ * Please not that decal projections can be distorted when used around corners. More information at
+ * this GitHub issue: [Decal projections without distortions](https://github.com/mrdoob/three.js/issues/21187).
  *
- * mesh — Any mesh object
- * position — Position of the decal projector
- * orientation — Orientation of the decal projector
- * size — Size of the decal projector
+ * Reference: [How to project decals](http://blog.wolfire.com/2009/06/how-to-project-decals/)
  *
- * reference: http://blog.wolfire.com/2009/06/how-to-project-decals/
+ * ```js
+ * const geometry = new DecalGeometry( mesh, position, orientation, size );
+ * const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } );
+ * const mesh = new THREE.Mesh( geometry, material );
+ * scene.add( mesh );
+ * ```
  *
+ * @augments BufferGeometry
+ * @three_import import { DecalGeometry } from 'three/addons/geometries/DecalGeometry.js';
  */
-
 class DecalGeometry extends BufferGeometry {
 
-	constructor( mesh, position, orientation, size ) {
+	/**
+	 * Constructs a new decal geometry.
+	 *
+	 * @param {Mesh} [mesh] - The base mesh the decal should be projected on.
+	 * @param {Vector3} [position] - The position of the decal projector.
+	 * @param {Euler} [orientation] - The orientation of the decal projector.
+	 * @param {Vector3} [size] - The scale of the decal projector.
+	 */
+	constructor( mesh = new Mesh(), position = new Vector3(), orientation = new Euler(), size = new Vector3( 1, 1, 1 ) ) {
 
 		super();
 
@@ -55,9 +69,16 @@ class DecalGeometry extends BufferGeometry {
 		// build geometry
 
 		this.setAttribute( 'position', new Float32BufferAttribute( vertices, 3 ) );
-		this.setAttribute( 'normal', new Float32BufferAttribute( normals, 3 ) );
 		this.setAttribute( 'uv', new Float32BufferAttribute( uvs, 2 ) );
 
+		if ( normals.length > 0 ) {
+
+			this.setAttribute( 'normal', new Float32BufferAttribute( normals, 3 ) );
+
+		}
+
+		//
+
 		function generate() {
 
 			let decalVertices = [];
@@ -86,22 +107,40 @@ class DecalGeometry extends BufferGeometry {
 				for ( let i = 0; i < index.count; i ++ ) {
 
 					vertex.fromBufferAttribute( positionAttribute, index.getX( i ) );
-					normal.fromBufferAttribute( normalAttribute, index.getX( i ) );
 
-					pushDecalVertex( decalVertices, vertex, normal );
+					if ( normalAttribute ) {
+
+						normal.fromBufferAttribute( normalAttribute, index.getX( i ) );
+						pushDecalVertex( decalVertices, vertex, normal );
+
+					} else {
+
+						pushDecalVertex( decalVertices, vertex );
+
+					}
 
 				}
 
 			} else {
 
+				if ( positionAttribute === undefined ) return; // empty geometry
+
 				// non-indexed BufferGeometry
 
 				for ( let i = 0; i < positionAttribute.count; i ++ ) {
 
 					vertex.fromBufferAttribute( positionAttribute, i );
-					normal.fromBufferAttribute( normalAttribute, i );
 
-					pushDecalVertex( decalVertices, vertex, normal );
+					if ( normalAttribute ) {
+
+						normal.fromBufferAttribute( normalAttribute, i );
+						pushDecalVertex( decalVertices, vertex, normal );
+
+					} else {
+
+						pushDecalVertex( decalVertices, vertex );
+
+					}
 
 				}
 
@@ -136,22 +175,34 @@ class DecalGeometry extends BufferGeometry {
 				// now create vertex and normal buffer data
 
 				vertices.push( decalVertex.position.x, decalVertex.position.y, decalVertex.position.z );
-				normals.push( decalVertex.normal.x, decalVertex.normal.y, decalVertex.normal.z );
+
+				if ( decalVertex.normal !== null ) {
+
+					normals.push( decalVertex.normal.x, decalVertex.normal.y, decalVertex.normal.z );
+
+				}
 
 			}
 
 		}
 
-		function pushDecalVertex( decalVertices, vertex, normal ) {
+		function pushDecalVertex( decalVertices, vertex, normal = null ) {
 
 			// transform the vertex to world space, then to projector space
 
 			vertex.applyMatrix4( mesh.matrixWorld );
 			vertex.applyMatrix4( projectorMatrixInverse );
 
-			normal.applyNormalMatrix( normalMatrix );
+			if ( normal ) {
 
-			decalVertices.push( new DecalVertex( vertex.clone(), normal.clone() ) );
+				normal.applyNormalMatrix( normalMatrix );
+				decalVertices.push( new DecalVertex( vertex.clone(), normal.clone() ) );
+
+			} else {
+
+				decalVertices.push( new DecalVertex( vertex.clone() ) );
+
+			}
 
 		}
 
@@ -313,18 +364,25 @@ class DecalGeometry extends BufferGeometry {
 
 			const s0 = d0 / ( d0 - d1 );
 
-			const v = new DecalVertex(
-				new Vector3(
-					v0.position.x + s0 * ( v1.position.x - v0.position.x ),
-					v0.position.y + s0 * ( v1.position.y - v0.position.y ),
-					v0.position.z + s0 * ( v1.position.z - v0.position.z )
-				),
-				new Vector3(
+			const position = new Vector3(
+				v0.position.x + s0 * ( v1.position.x - v0.position.x ),
+				v0.position.y + s0 * ( v1.position.y - v0.position.y ),
+				v0.position.z + s0 * ( v1.position.z - v0.position.z )
+			);
+
+			let normal = null;
+
+			if ( v0.normal !== null && v1.normal !== null ) {
+
+				normal = new Vector3(
 					v0.normal.x + s0 * ( v1.normal.x - v0.normal.x ),
 					v0.normal.y + s0 * ( v1.normal.y - v0.normal.y ),
 					v0.normal.z + s0 * ( v1.normal.z - v0.normal.z )
-				)
-			);
+				);
+
+			}
+
+			const v = new DecalVertex( position, normal );
 
 			// need to clip more values (texture coordinates)? do it this way:
 			// intersectpoint.value = a.value + s * ( b.value - a.value );
@@ -341,7 +399,7 @@ class DecalGeometry extends BufferGeometry {
 
 class DecalVertex {
 
-	constructor( position, normal ) {
+	constructor( position, normal = null ) {
 
 		this.position = position;
 		this.normal = normal;
@@ -350,7 +408,10 @@ class DecalVertex {
 
 	clone() {
 
-		return new this.constructor( this.position.clone(), this.normal.clone() );
+		const position = this.position.clone();
+		const normal = ( this.normal !== null ) ? this.normal.clone() : null;
+
+		return new this.constructor( position, normal );
 
 	}
 

package/examples/jsm/geometries/ParametricFunctions.js

@@ -0,0 +1,100 @@
+
+/**
+ * @module ParametricFunctions
+ * @three_import import * as ParametricFunctions from 'three/addons/geometries/ParametricFunctions.js';
+ */
+
+/**
+ * A parametric function representing the Klein bottle.
+ *
+ * @param {number} v - The `v` coordinate on the surface in the range `[0,1]`.
+ * @param {number} u - The `u` coordinate on the surface in the range `[0,1]`.
+ * @param {Vector3} target - The target vector that is used to store the method's result.
+ */
+function klein( v, u, target ) {
+
+	u *= Math.PI;
+	v *= 2 * Math.PI;
+
+	u = u * 2;
+	let x, z;
+	if ( u < Math.PI ) {
+
+		x = 3 * Math.cos( u ) * ( 1 + Math.sin( u ) ) + ( 2 * ( 1 - Math.cos( u ) / 2 ) ) * Math.cos( u ) * Math.cos( v );
+		z = - 8 * Math.sin( u ) - 2 * ( 1 - Math.cos( u ) / 2 ) * Math.sin( u ) * Math.cos( v );
+
+	} else {
+
+		x = 3 * Math.cos( u ) * ( 1 + Math.sin( u ) ) + ( 2 * ( 1 - Math.cos( u ) / 2 ) ) * Math.cos( v + Math.PI );
+		z = - 8 * Math.sin( u );
+
+	}
+
+	const y = - 2 * ( 1 - Math.cos( u ) / 2 ) * Math.sin( v );
+
+	target.set( x, y, z );
+
+}
+
+/**
+ * A parametric function representing a flat plane.
+ *
+ * @param {number} u - The `u` coordinate on the surface in the range `[0,1]`.
+ * @param {number} v - The `v` coordinate on the surface in the range `[0,1]`.
+ * @param {Vector3} target - The target vector that is used to store the method's result.
+ */
+function plane( u, v, target ) {
+
+	target.set( u, 0, v );
+
+}
+
+/**
+ * A parametric function representing a flat mobius strip.
+ *
+ * @param {number} u - The `u` coordinate on the surface in the range `[0,1]`.
+ * @param {number} t - The `v` coordinate on the surface in the range `[0,1]`.
+ * @param {Vector3} target - The target vector that is used to store the method's result.
+ */
+function mobius( u, t, target ) {
+
+	// http://www.wolframalpha.com/input/?i=M%C3%B6bius+strip+parametric+equations&lk=1&a=ClashPrefs_*Surface.MoebiusStrip.SurfaceProperty.ParametricEquations-
+	u = u - 0.5;
+	const v = 2 * Math.PI * t;
+
+	const a = 2;
+
+	const x = Math.cos( v ) * ( a + u * Math.cos( v / 2 ) );
+	const y = Math.sin( v ) * ( a + u * Math.cos( v / 2 ) );
+	const z = u * Math.sin( v / 2 );
+
+	target.set( x, y, z );
+
+}
+
+/**
+ * A parametric function representing a volumetric mobius strip.
+ *
+ * @param {number} u - The `u` coordinate on the surface in the range `[0,1]`.
+ * @param {number} t - The `v` coordinate on the surface in the range `[0,1]`.
+ * @param {Vector3} target - The target vector that is used to store the method's result.
+ */
+function mobius3d( u, t, target ) {
+
+	u *= Math.PI;
+	t *= 2 * Math.PI;
+
+	u = u * 2;
+	const phi = u / 2;
+	const major = 2.25, a = 0.125, b = 0.65;
+
+	let x = a * Math.cos( t ) * Math.cos( phi ) - b * Math.sin( t ) * Math.sin( phi );
+	const z = a * Math.cos( t ) * Math.sin( phi ) + b * Math.sin( t ) * Math.cos( phi );
+	const y = ( major + x ) * Math.sin( u );
+	x = ( major + x ) * Math.cos( u );
+
+	target.set( x, y, z );
+
+}
+
+export { klein, plane, mobius, mobius3d };

package/examples/jsm/geometries/ParametricGeometry.js

@@ -1,22 +1,46 @@
-/**
- * Parametric Surfaces Geometry
- * based on the brilliant article by @prideout https://prideout.net/blog/old/blog/index.html@p=44.html
- */
-
 import {
 	BufferGeometry,
 	Float32BufferAttribute,
 	Vector3
 } from 'three';
 
+/**
+ * This class can be used to generate a geometry based on a parametric surface.
+ *
+ * Reference: [Mesh Generation with Python](https://prideout.net/blog/old/blog/index.html@p=44.html)
+ *
+ * ```js
+ * const geometry = new THREE.ParametricGeometry( klein, 25, 25 );
+ * const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } );
+ * const klein = new THREE.Mesh( geometry, material );
+ * scene.add( klein );
+ * ```
+ *
+ * @augments BufferGeometry
+ * @three_import import { ParametricGeometry } from 'three/addons/geometries/ParametricGeometry.js';
+ */
 class ParametricGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new parametric geometry.
+	 *
+	 * @param {ParametricGeometry~Func} func - The parametric function. Default is a function that generates a curved plane surface.
+	 * @param {number} [slices=8] - The number of slices to use for the parametric function.
+	 * @param {number} [stacks=8] - The stacks of slices to use for the parametric function.
+	 */
 	constructor( func = ( u, v, target ) => target.set( u, v, Math.cos( u ) * Math.sin( v ) ), slices = 8, stacks = 8 ) {
 
 		super();
 
 		this.type = 'ParametricGeometry';
 
+		/**
+		 * Holds the constructor parameters that have been
+		 * used to generate the geometry. Any modification
+		 * after instantiation does not change the geometry.
+		 *
+		 * @type {Object}
+		 */
 		this.parameters = {
 			func: func,
 			slices: slices,
@@ -136,4 +160,13 @@ class ParametricGeometry extends BufferGeometry {
 
 }
 
+/**
+ * Parametric function definition of `ParametricGeometry`.
+ *
+ * @callback ParametricGeometry~Func
+ * @param {number} u - The `u` coordinate on the surface in the range `[0,1]`.
+ * @param {number} v - The `v` coordinate on the surface in the range `[0,1]`.
+ * @param {Vector3} target - The target vector that is used to store the method's result.
+ */
+
 export { ParametricGeometry };

package/examples/jsm/geometries/RoundedBoxGeometry.js

@@ -38,20 +38,61 @@ function getUv( faceDirVector, normal, uvAxis, projectionAxis, radius, sideLengt
 
 }
 
+/**
+ * A special type of box geometry with rounded corners and edges.
+ *
+ * ```js
+ * const geometry = new THREE.RoundedBoxGeometry();
+ * const material = new THREE.MeshStandardMaterial( { color: 0x00ff00 } );
+ * const cube = new THREE.Mesh( geometry, material );
+ * scene.add( cube );
+ * ```
+ *
+ * @augments BoxGeometry
+ * @three_import import { RoundedBoxGeometry } from 'three/addons/geometries/RoundedBoxGeometry.js';
+ */
 class RoundedBoxGeometry extends BoxGeometry {
 
+	/**
+	 * Constructs a new rounded box geometry.
+	 *
+	 * @param {number} [width=1] - The width. That is, the length of the edges parallel to the X axis.
+	 * @param {number} [height=1] - The height. That is, the length of the edges parallel to the Y axis.
+	 * @param {number} [depth=1] - The depth. That is, the length of the edges parallel to the Z axis.
+	 * @param {number} [segments=2] - Number of segments that form the rounded corners.
+	 * @param {number} [radius=0.1] - The radius of the rounded corners.
+	 */
 	constructor( width = 1, height = 1, depth = 1, segments = 2, radius = 0.1 ) {
 
-		// ensure segments is odd so we have a plane connecting the rounded corners
-		segments = segments * 2 + 1;
+		// calculate total segments needed &
+		// ensure it's odd so that we have a plane connecting the rounded corners
+		const totalSegments = segments * 2 + 1;
 
 		// ensure radius isn't bigger than shortest side
 		radius = Math.min( width / 2, height / 2, depth / 2, radius );
 
-		super( 1, 1, 1, segments, segments, segments );
-
-		// if we just have one segment we're the same as a regular box
-		if ( segments === 1 ) return;
+		// start with a unit box geometry, its vertices will be modified to form the rounded box
+		super( 1, 1, 1, totalSegments, totalSegments, totalSegments );
+
+		this.type = 'RoundedBoxGeometry';
+
+		/**
+		 * Holds the constructor parameters that have been
+		 * used to generate the geometry. Any modification
+		 * after instantiation does not change the geometry.
+		 *
+		 * @type {Object}
+		 */
+		this.parameters = {
+			width: width,
+			height: height,
+			depth: depth,
+			segments: segments,
+			radius: radius,
+		};
+
+		// if totalSegments is 1, no rounding is needed - return regular box
+		if ( totalSegments === 1 ) return;
 
 		const geometry2 = this.toNonIndexed();
 
@@ -73,7 +114,7 @@ class RoundedBoxGeometry extends BoxGeometry {
 
 		const faceTris = positions.length / 6;
 		const faceDirVector = new Vector3();
-		const halfSegmentSize = 0.5 / segments;
+		const halfSegmentSize = 0.5 / totalSegments;
 
 		for ( let i = 0, j = 0; i < positions.length; i += 3, j += 2 ) {
 
@@ -150,6 +191,26 @@ class RoundedBoxGeometry extends BoxGeometry {
 
 	}
 
+	/**
+	 * Factory method for creating an instance of this class from the given
+	 * JSON object.
+	 *
+	 * @param {Object} data - A JSON object representing the serialized geometry.
+	 * @returns {RoundedBoxGeometry} A new instance.
+	 */
+	static fromJSON( data ) {
+
+		return new RoundedBoxGeometry(
+			data.width,
+			data.height,
+			data.depth,
+			data.segments,
+			data.radius
+		);
+
+	}
+
+
 }
 
 export { RoundedBoxGeometry };

package/examples/jsm/geometries/TeapotGeometry.js

@@ -9,53 +9,38 @@ import {
 /**
  * Tessellates the famous Utah teapot database by Martin Newell into triangles.
  *
- * Parameters: size = 50, segments = 10, bottom = true, lid = true, body = true,
- *   fitLid = true, blinn = true
- *
- * size is a relative scale: I've scaled the teapot to fit vertically between -1 and 1.
- * Think of it as a "radius".
- * segments - number of line segments to subdivide each patch edge;
- *   1 is possible but gives degenerates, so two is the real minimum.
- * bottom - boolean, if true (default) then the bottom patches are added. Some consider
- *   adding the bottom heresy, so set this to "false" to adhere to the One True Way.
- * lid - to remove the lid and look inside, set to true.
- * body - to remove the body and leave the lid, set this and "bottom" to false.
- * fitLid - the lid is a tad small in the original. This stretches it a bit so you can't
- *   see the teapot's insides through the gap.
- * blinn - Jim Blinn scaled the original data vertically by dividing by about 1.3 to look
- *   nicer. If you want to see the original teapot, similar to the real-world model, set
- *   this to false. True by default.
- *   See http://en.wikipedia.org/wiki/File:Original_Utah_Teapot.jpg for the original
- *   real-world teapot (from http://en.wikipedia.org/wiki/Utah_teapot).
- *
- * Note that the bottom (the last four patches) is not flat - blame Frank Crow, not me.
- *
  * The teapot should normally be rendered as a double sided object, since for some
  * patches both sides can be seen, e.g., the gap around the lid and inside the spout.
  *
- * Segments 'n' determines the number of triangles output.
- *   Total triangles = 32*2*n*n - 8*n    [degenerates at the top and bottom cusps are deleted]
+ * Segments 'n' determines the number of triangles output. Total triangles = 32*2*n*n - 8*n
+ * (degenerates at the top and bottom cusps are deleted).
  *
- *   size_factor   # triangles
- *       1          56
- *       2         240
- *       3         552
- *       4         992
+ * Code based on [SPD software](http://tog.acm.org/resources/SPD/)
+ * Created for the Udacity course [Interactive Rendering](http://bit.ly/ericity)
  *
- *      10        6320
- *      20       25440
- *      30       57360
- *
- * Code converted from my ancient SPD software, http://tog.acm.org/resources/SPD/
- * Created for the Udacity course "Interactive Rendering", http://bit.ly/ericity
- * YouTube video on teapot history: https://www.youtube.com/watch?v=DxMfblPzFNc
- *
- * See https://en.wikipedia.org/wiki/Utah_teapot for the history of the teapot
+ * ```js
+ * const geometry = new TeapotGeometry( 50, 18 );
+ * const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } );
+ * const teapot = new THREE.Mesh( geometry, material );
+ * scene.add( teapot );
+ * ```
  *
+ * @augments BufferGeometry
+ * @three_import import { TeapotGeometry } from 'three/addons/geometries/TeapotGeometry.js';
  */
-
 class TeapotGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new teapot geometry.
+	 *
+	 * @param {number} [size=50] - Relative scale of the teapot.
+	 * @param {number} [segments=10] - Number of line segments to subdivide each patch edge.
+	 * @param {boolean} [bottom=true] - Whether the bottom of the teapot is generated or not.
+	 * @param {boolean} [lid=true] - Whether the lid is generated or not.
+	 * @param {boolean} [body=true] - Whether the body is generated or not.
+	 * @param {boolean} [fitLid=true] - Whether the lid is slightly stretched to prevent gaps between the body and lid or not.
+	 * @param {boolean} [blinn=true] -  Whether the teapot is scaled vertically for better aesthetics or not.
+	 */
 	constructor( size = 50, segments = 10, bottom = true, lid = true, body = true, fitLid = true, blinn = true ) {
 
 		// 32 * 4 * 4 Bezier spline patches