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

package/examples/jsm/tsl/utils/Raymarching.js

@@ -0,0 +1,70 @@
+import { varying, vec4, modelWorldMatrixInverse, cameraPosition, positionGeometry, float, Fn, Loop, max, min, vec2, vec3 } from 'three/tsl';
+
+/**
+ * @module Raymarching
+ * @three_import import { RaymarchingBox } from 'three/addons/tsl/utils/Raymarching.js';
+ */
+
+const hitBox = /*@__PURE__*/ Fn( ( { orig, dir } ) => {
+
+	const box_min = vec3( - 0.5 );
+	const box_max = vec3( 0.5 );
+
+	const inv_dir = dir.reciprocal();
+
+	const tmin_tmp = box_min.sub( orig ).mul( inv_dir );
+	const tmax_tmp = box_max.sub( orig ).mul( inv_dir );
+
+	const tmin = min( tmin_tmp, tmax_tmp );
+	const tmax = max( tmin_tmp, tmax_tmp );
+
+	const t0 = max( tmin.x, max( tmin.y, tmin.z ) );
+	const t1 = min( tmax.x, min( tmax.y, tmax.z ) );
+
+	return vec2( t0, t1 );
+
+} );
+
+/**
+ * TSL function for performing raymarching in a box-area using the specified number of steps
+ * and a callback function.
+ *
+ * ```js
+ * RaymarchingBox( count, ( { positionRay } ) => {
+ *
+ * } );
+ * ```
+ *
+ * @tsl
+ * @function
+ * @param {number|Node} steps - The number of steps for raymarching.
+ * @param {Function|FunctionNode} callback - The callback function to execute at each step.
+ */
+export const RaymarchingBox = ( steps, callback ) => {
+
+	const vOrigin = varying( vec3( modelWorldMatrixInverse.mul( vec4( cameraPosition, 1.0 ) ) ) );
+	const vDirection = varying( positionGeometry.sub( vOrigin ) );
+
+	const rayDir = vDirection.normalize();
+	const bounds = vec2( hitBox( { orig: vOrigin, dir: rayDir } ) ).toVar();
+
+	bounds.x.greaterThan( bounds.y ).discard();
+
+	bounds.assign( vec2( max( bounds.x, 0.0 ), bounds.y ) );
+
+	const inc = vec3( rayDir.abs().reciprocal() ).toVar();
+	const delta = float( min( inc.x, min( inc.y, inc.z ) ) ).toVar();
+
+	delta.divAssign( float( steps ) );
+
+	const positionRay = vec3( vOrigin.add( bounds.x.mul( rayDir ) ) ).toVar();
+
+	Loop( { type: 'float', start: bounds.x, end: bounds.y, update: delta }, () => {
+
+		callback( { positionRay } );
+
+		positionRay.addAssign( rayDir.mul( delta ) );
+
+	} );
+
+};

package/examples/jsm/utils/BufferGeometryUtils.js

@@ -11,6 +11,30 @@ import {
 	Vector3,
 } from 'three';
 
+/**
+ * @module BufferGeometryUtils
+ * @three_import import * as BufferGeometryUtils from 'three/addons/utils/BufferGeometryUtils.js';
+ */
+
+/**
+ * Computes vertex tangents using the MikkTSpace algorithm. MikkTSpace generates the same tangents consistently,
+ * and is used in most modelling tools and normal map bakers. Use MikkTSpace for materials with normal maps,
+ * because inconsistent tangents may lead to subtle visual issues in the normal map, particularly around mirrored
+ * UV seams.
+ *
+ * In comparison to this method, {@link BufferGeometry#computeTangents} (a custom algorithm) generates tangents that
+ * probably will not match the tangents in other software. The custom algorithm is sufficient for general use with a
+ * custom material, and may be faster than MikkTSpace.
+ *
+ * Returns the original BufferGeometry. Indexed geometries will be de-indexed. Requires position, normal, and uv attributes.
+ *
+ * @param {BufferGeometry} geometry - The geometry to compute tangents for.
+ * @param {Object} MikkTSpace - Instance of `examples/jsm/libs/mikktspace.module.js`, or `mikktspace` npm package.
+ * Await `MikkTSpace.ready` before use.
+ * @param {boolean} [negateSign=true] - Whether to negate the sign component (.w) of each tangent.
+ * Required for normal map conventions in some formats, including glTF.
+ * @return {BufferGeometry} The updated geometry.
+ */
 function computeMikkTSpaceTangents( geometry, MikkTSpace, negateSign = true ) {
 
 	if ( ! MikkTSpace || ! MikkTSpace.isReady ) {
@@ -100,9 +124,11 @@ function computeMikkTSpaceTangents( geometry, MikkTSpace, negateSign = true ) {
 }
 
 /**
- * @param  {Array<BufferGeometry>} geometries
- * @param  {Boolean} useGroups
- * @return {BufferGeometry}
+ * Merges a set of geometries into a single instance. All geometries must have compatible attributes.
+ *
+ * @param {Array<BufferGeometry>} geometries - The geometries to merge.
+ * @param {boolean} [useGroups=false] - Whether to use groups or not.
+ * @return {?BufferGeometry} The merged geometry. Returns `null` if the merge does not succeed.
  */
 function mergeGeometries( geometries, useGroups = false ) {
 
@@ -296,8 +322,11 @@ function mergeGeometries( geometries, useGroups = false ) {
 }
 
 /**
- * @param {Array<BufferAttribute>} attributes
- * @return {BufferAttribute}
+ * Merges a set of attributes into a single instance. All attributes must have compatible properties and types.
+ * Instances of {@link InterleavedBufferAttribute} are not supported.
+ *
+ * @param {Array<BufferAttribute>} attributes - The attributes to merge.
+ * @return {?BufferAttribute} The merged attribute. Returns `null` if the merge does not succeed.
  */
 function mergeAttributes( attributes ) {
 
@@ -389,10 +418,12 @@ function mergeAttributes( attributes ) {
 }
 
 /**
- * @param {BufferAttribute}
- * @return {BufferAttribute}
+ * Performs a deep clone of the given buffer attribute.
+ *
+ * @param {BufferAttribute} attribute - The attribute to clone.
+ * @return {BufferAttribute} The cloned attribute.
  */
-export function deepCloneAttribute( attribute ) {
+function deepCloneAttribute( attribute ) {
 
 	if ( attribute.isInstancedInterleavedBufferAttribute || attribute.isInterleavedBufferAttribute ) {
 
@@ -411,8 +442,11 @@ export function deepCloneAttribute( attribute ) {
 }
 
 /**
- * @param {Array<BufferAttribute>} attributes
- * @return {Array<InterleavedBufferAttribute>}
+ * Interleaves a set of attributes and returns a new array of corresponding attributes that share a
+ * single {@link InterleavedBuffer} instance. All attributes must have compatible types.
+ *
+ * @param {Array<BufferAttribute>} attributes - The attributes to interleave.
+ * @return {?Array<InterleavedBufferAttribute>} An array of interleaved attributes. If interleave does not succeed, the method returns `null`.
  */
 function interleaveAttributes( attributes ) {
 
@@ -475,8 +509,13 @@ function interleaveAttributes( attributes ) {
 
 }
 
-// returns a new, non-interleaved version of the provided attribute
-export function deinterleaveAttribute( attribute ) {
+/**
+ * Returns a new, non-interleaved version of the given attribute.
+ *
+ * @param {InterleavedBufferAttribute} attribute - The interleaved attribute.
+ * @return {BufferAttribute} The non-interleaved attribute.
+ */
+function deinterleaveAttribute( attribute ) {
 
 	const cons = attribute.data.array.constructor;
 	const count = attribute.count;
@@ -523,8 +562,12 @@ export function deinterleaveAttribute( attribute ) {
 
 }
 
-// deinterleaves all attributes on the geometry
-export function deinterleaveGeometry( geometry ) {
+/**
+ * Deinterleaves all attributes on the given geometry.
+ *
+ * @param {BufferGeometry} geometry - The geometry to deinterleave.
+ */
+function deinterleaveGeometry( geometry ) {
 
 	const attributes = geometry.attributes;
 	const morphTargets = geometry.morphTargets;
@@ -567,8 +610,10 @@ export function deinterleaveGeometry( geometry ) {
 }
 
 /**
- * @param {BufferGeometry} geometry
- * @return {number}
+ * Returns the amount of bytes used by all attributes to represent the geometry.
+ *
+ * @param {BufferGeometry} geometry - The geometry.
+ * @return {number} The estimate bytes used.
  */
 function estimateBytesUsed( geometry ) {
 
@@ -590,9 +635,11 @@ function estimateBytesUsed( geometry ) {
 }
 
 /**
- * @param {BufferGeometry} geometry
- * @param {number} tolerance
- * @return {BufferGeometry}
+ * Returns a new geometry with vertices for which all similar vertex attributes (within tolerance) are merged.
+ *
+ * @param {BufferGeometry} geometry - The geometry to merge vertices for.
+ * @param {number} [tolerance=1e-4] - The tolerance value.
+ * @return {BufferGeometry} - The new geometry with merged vertices.
  */
 function mergeVertices( geometry, tolerance = 1e-4 ) {
 
@@ -753,9 +800,12 @@ function mergeVertices( geometry, tolerance = 1e-4 ) {
 }
 
 /**
- * @param {BufferGeometry} geometry
- * @param {number} drawMode
- * @return {BufferGeometry}
+ * Returns a new indexed geometry based on `TrianglesDrawMode` draw mode.
+ * This mode corresponds to the `gl.TRIANGLES` primitive in WebGL.
+ *
+ * @param {BufferGeometry} geometry - The geometry to convert.
+ * @param {number} drawMode - The current draw mode.
+ * @return {BufferGeometry} The new geometry using `TrianglesDrawMode`.
  */
 function toTrianglesDrawMode( geometry, drawMode ) {
 
@@ -864,9 +914,13 @@ function toTrianglesDrawMode( geometry, drawMode ) {
 
 /**
  * Calculates the morphed attributes of a morphed/skinned BufferGeometry.
- * Helpful for Raytracing or Decals.
- * @param {Mesh | Line | Points} object An instance of Mesh, Line or Points.
- * @return {Object} An Object with original position/normal attributes and morphed ones.
+ *
+ * Helpful for Raytracing or Decals (i.e. a `DecalGeometry` applied to a morphed Object with a `BufferGeometry`
+ * will use the original `BufferGeometry`, not the morphed/skinned one, generating an incorrect result.
+ * Using this function to create a shadow `Object3`D the `DecalGeometry` can be correctly generated).
+ *
+ * @param {Mesh|Line|Points} object - The 3D object to compute morph attributes for.
+ * @return {Object} An object with original position/normal attributes and morphed ones.
  */
 function computeMorphedAttributes( object ) {
 
@@ -1142,6 +1196,12 @@ function computeMorphedAttributes( object ) {
 
 }
 
+/**
+ * Merges the {@link BufferGeometry#groups} for the given geometry.
+ *
+ * @param {BufferGeometry} geometry - The geometry to modify.
+ * @return {BufferGeometry} - The updated geometry
+ */
 function mergeGroups( geometry ) {
 
 	if ( geometry.groups.length === 0 ) {
@@ -1244,15 +1304,14 @@ function mergeGroups( geometry ) {
 
 }
 
-
 /**
  * Modifies the supplied geometry if it is non-indexed, otherwise creates a new,
  * non-indexed geometry. Returns the geometry with smooth normals everywhere except
  * faces that meet at an angle greater than the crease angle.
  *
- * @param {BufferGeometry} geometry
- * @param {number} [creaseAngle]
- * @return {BufferGeometry}
+ * @param {BufferGeometry} geometry - The geometry to modify.
+ * @param {number} [creaseAngle=Math.PI/3] - The crease angle in radians.
+ * @return {BufferGeometry} - The updated geometry
  */
 function toCreasedNormals( geometry, creaseAngle = Math.PI / 3 /* 60 degrees */ ) {
 
@@ -1363,6 +1422,9 @@ export {
 	computeMikkTSpaceTangents,
 	mergeGeometries,
 	mergeAttributes,
+	deepCloneAttribute,
+	deinterleaveAttribute,
+	deinterleaveGeometry,
 	interleaveAttributes,
 	estimateBytesUsed,
 	mergeVertices,

package/examples/jsm/utils/CameraUtils.js

@@ -4,6 +4,11 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * @module CameraUtils
+ * @three_import import * as CameraUtils from 'three/addons/utils/CameraUtils.js';
+ */
+
 const _va = /*@__PURE__*/ new Vector3(), // from pe to pa
 	_vb = /*@__PURE__*/ new Vector3(), // from pe to pb
 	_vc = /*@__PURE__*/ new Vector3(), // from pe to pc
@@ -14,14 +19,18 @@ const _va = /*@__PURE__*/ new Vector3(), // from pe to pa
 	_quat = /*@__PURE__*/ new Quaternion(); // temporary quaternion
 
 
-/** Set a PerspectiveCamera's projectionMatrix and quaternion
+/**
+ * Set projection matrix and the orientation of a perspective camera
  * to exactly frame the corners of an arbitrary rectangle.
  * NOTE: This function ignores the standard parameters;
- * do not call updateProjectionMatrix() after this!
- * @param {Vector3} bottomLeftCorner
- * @param {Vector3} bottomRightCorner
- * @param {Vector3} topLeftCorner
- * @param {boolean} estimateViewFrustum */
+ * do not call `updateProjectionMatrix()` after this.
+ *
+ * @param {PerspectiveCamera} camera - The camera.
+ * @param {Vector3} bottomLeftCorner - The bottom-left corner point.
+ * @param {Vector3} bottomRightCorner - The bottom-right corner point.
+ * @param {Vector3} topLeftCorner - The top-left corner point.
+ * @param {boolean} [estimateViewFrustum=false] - If set to `true`, the function tries to estimate the camera's FOV.
+ */
 function frameCorners( camera, bottomLeftCorner, bottomRightCorner, topLeftCorner, estimateViewFrustum = false ) {
 
 	const pa = bottomLeftCorner, pb = bottomRightCorner, pc = topLeftCorner;

package/examples/jsm/utils/GeometryCompressionUtils.js

@@ -1,10 +1,3 @@
-/**
- * Octahedron and Quantization encodings based on work by:
- *
- * @link https://github.com/tsherif/mesh-quantization-example
- *
- */
-
 import {
 	BufferAttribute,
 	Matrix3,
@@ -12,14 +5,18 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * @module GeometryCompressionUtils
+ * @three_import import * as GeometryCompressionUtils from 'three/addons/utils/GeometryCompressionUtils.js';
+ */
 
+// Octahedron and Quantization encodings based on work by: https://github.com/tsherif/mesh-quantization-example
 
 /**
- * Make the input geometry's normal attribute encoded and compressed by 3 different methods.
- *
- * @param {THREE.BufferGeometry} geometry
- * @param {String} encodeMethod		"DEFAULT" || "OCT1Byte" || "OCT2Byte" || "ANGLES"
+ * Compressed the given geometry's `normal` attribute by the selected encode method.
  *
+ * @param {BufferGeometry} geometry - The geometry whose normals should be compressed.
+ * @param {('DEFAULT'|'OCT1Byte'|'OCT2Byte'|'ANGLES')} encodeMethod - The compression method.
  */
 function compressNormals( geometry, encodeMethod ) {
 
@@ -27,7 +24,7 @@ function compressNormals( geometry, encodeMethod ) {
 
 	if ( ! normal ) {
 
-		console.error( 'Geometry must contain normal attribute. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressNormals(): Geometry must contain normal attribute.' );
 
 	}
 
@@ -35,7 +32,7 @@ function compressNormals( geometry, encodeMethod ) {
 
 	if ( normal.itemSize != 3 ) {
 
-		console.error( 'normal.itemSize is not 3, which cannot be encoded. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressNormals(): normal.itemSize is not 3, which cannot be encoded.' );
 
 	}
 
@@ -63,11 +60,10 @@ function compressNormals( geometry, encodeMethod ) {
 
 	} else if ( encodeMethod == 'OCT1Byte' ) {
 
-		/**
-		* It is not recommended to use 1-byte octahedron normals encoding unless you want to extremely reduce the memory usage
-		* As it makes vertex data not aligned to a 4 byte boundary which may harm some WebGL implementations and sometimes the normal distortion is visible
-		* Please refer to @zeux 's comments in https://github.com/mrdoob/three.js/pull/18208
-		*/
+
+		// It is not recommended to use 1-byte octahedron normals encoding unless you want to extremely reduce the memory usage
+		// As it makes vertex data not aligned to a 4 byte boundary which may harm some WebGL implementations and sometimes the normal distortion is visible
+		// Please refer to @zeux 's comments in https://github.com/mrdoob/three.js/pull/18208
 
 		result = new Int8Array( count * 2 );
 
@@ -127,20 +123,18 @@ function compressNormals( geometry, encodeMethod ) {
 
 }
 
-
 /**
-	 * Make the input geometry's position attribute encoded and compressed.
-	 *
-	 * @param {THREE.BufferGeometry} geometry
-	 *
-	 */
+ * Compressed the given geometry's `position` attribute.
+ *
+ * @param {BufferGeometry} geometry - The geometry whose position values should be compressed.
+ */
 function compressPositions( geometry ) {
 
 	const position = geometry.attributes.position;
 
 	if ( ! position ) {
 
-		console.error( 'Geometry must contain position attribute. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressPositions(): Geometry must contain position attribute.' );
 
 	}
 
@@ -148,7 +142,7 @@ function compressPositions( geometry ) {
 
 	if ( position.itemSize != 3 ) {
 
-		console.error( 'position.itemSize is not 3, which cannot be packed. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressPositions(): position.itemSize is not 3, which cannot be packed.' );
 
 	}
 
@@ -171,10 +165,9 @@ function compressPositions( geometry ) {
 }
 
 /**
- * Make the input geometry's uv attribute encoded and compressed.
- *
- * @param {THREE.BufferGeometry} geometry
+ * Compressed the given geometry's `uv` attribute.
  *
+ * @param {BufferGeometry} geometry - The geometry whose texture coordinates should be compressed.
  */
 function compressUvs( geometry ) {
 
@@ -182,7 +175,7 @@ function compressUvs( geometry ) {
 
 	if ( ! uvs ) {
 
-		console.error( 'Geometry must contain uv attribute. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressUvs(): Geometry must contain uv attribute.' );
 
 	}
 

package/examples/jsm/utils/GeometryUtils.js

@@ -1,19 +1,23 @@
 import { Vector3 } from 'three';
 
+/**
+ * @module GeometryUtils
+ * @three_import import * as GeometryUtils from 'three/addons/utils/GeometryUtils.js';
+ */
 
 /**
- * Generates 2D-Coordinates in a very fast way.
+ * Generates 2D-Coordinates along a Hilbert curve.
  *
- * Based on work by:
- * @link http://www.openprocessing.org/sketch/15493
+ * Based on work by: {@link http://www.openprocessing.org/sketch/15493}
  *
- * @param center     Center of Hilbert curve.
- * @param size       Total width of Hilbert curve.
- * @param iterations Number of subdivisions.
- * @param v0         Corner index -X, -Z.
- * @param v1         Corner index -X, +Z.
- * @param v2         Corner index +X, +Z.
- * @param v3         Corner index +X, -Z.
+ * @param {Vector3} [center] - Center of Hilbert curve.
+ * @param {number} [size=10] - Total width of Hilbert curve.
+ * @param {number} [iterations=10] - Number of subdivisions.
+ * @param {number} [v0=0] - Corner index -X, -Z.
+ * @param {number} [v1=1] - Corner index -X, +Z.
+ * @param {number} [v2=2] - Corner index +X, +Z.
+ * @param {number} [v3=3] - Corner index +X, -Z.
+ * @returns {Array<Vector3>} The Hilbert curve points.
  */
 function hilbert2D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1, v0 = 0, v1 = 1, v2 = 2, v3 = 3 ) {
 
@@ -51,22 +55,22 @@ function hilbert2D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1,
 }
 
 /**
- * Generates 3D-Coordinates in a very fast way.
+ * Generates 3D-Coordinates along a Hilbert curve.
  *
- * Based on work by:
- * @link https://openprocessing.org/user/5654
+ * Based on work by: {@link https://openprocessing.org/user/5654}
  *
- * @param center     Center of Hilbert curve.
- * @param size       Total width of Hilbert curve.
- * @param iterations Number of subdivisions.
- * @param v0         Corner index -X, +Y, -Z.
- * @param v1         Corner index -X, +Y, +Z.
- * @param v2         Corner index -X, -Y, +Z.
- * @param v3         Corner index -X, -Y, -Z.
- * @param v4         Corner index +X, -Y, -Z.
- * @param v5         Corner index +X, -Y, +Z.
- * @param v6         Corner index +X, +Y, +Z.
- * @param v7         Corner index +X, +Y, -Z.
+ * @param {Vector3} [center] - Center of Hilbert curve.
+ * @param {number} [size=10] - Total width of Hilbert curve.
+ * @param {number} [iterations=1] - Number of subdivisions.
+ * @param {number} [v0=0] - Corner index -X, +Y, -Z.
+ * @param {number} [v1=1] - Corner index -X, +Y, +Z.
+ * @param {number} [v2=2] - Corner index -X, -Y, +Z.
+ * @param {number} [v3=3] - Corner index -X, -Y, -Z.
+ * @param {number} [v4=4] - Corner index +X, -Y, -Z.
+ * @param {number} [v5=5] - Corner index +X, -Y, +Z.
+ * @param {number} [v6=6] - Corner index +X, +Y, +Z.
+ * @param {number} [v7=7] - Corner index +X, +Y, -Z.
+ * @returns {Array<Vector3>}  - The Hilbert curve points.
  */
 function hilbert3D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1, v0 = 0, v1 = 1, v2 = 2, v3 = 3, v4 = 4, v5 = 5, v6 = 6, v7 = 7 ) {
 
@@ -117,11 +121,12 @@ function hilbert3D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1,
 }
 
 /**
- * Generates a Gosper curve (lying in the XY plane)
+ * Generates a Gosper curve (lying in the XY plane).
  *
- * https://gist.github.com/nitaku/6521802
+ * Reference: {@link https://gist.github.com/nitaku/6521802}
  *
- * @param size The size of a single gosper island.
+ * @param {number} [size=1] - The size of a single gosper island.
+ * @return {Array<number>} The gosper island points.
  */
 function gosper( size = 1 ) {
 

package/examples/jsm/utils/LDrawUtils.js

@@ -9,14 +9,23 @@ import {
 
 import { mergeGeometries } from './BufferGeometryUtils.js';
 
+/**
+ * Utility class for LDraw models.
+ *
+ * @three_import import { LDrawUtils } from 'three/addons/utils/LDrawUtils.js';
+ */
 class LDrawUtils {
 
+	/**
+	 * Merges geometries in the given object by materials and returns a new group object.
+	 * Use on not indexed geometries. The object buffers reference the old object ones.
+	 * Special treatment is done to the conditional lines generated by LDrawLoader.
+	 *
+	 * @param {Object3D} object - The object to merge.
+	 * @returns {Group} The merged object.
+	 */
 	static mergeObject( object ) {
 
-		// Merges geometries in object by materials and returns new object. Use on not indexed geometries.
-		// The object buffers reference the old object ones.
-		// Special treatment is done to the conditional lines generated by LDrawLoader.
-
 		function extractGroup( geometry, group, elementSize, isConditionalLine ) {
 
 			// Extracts a group from a geometry as a new geometry (with attribute buffers referencing original buffers)
@@ -110,7 +119,7 @@ class LDrawUtils {
 
 		object.traverse( c => {
 
-			if ( c.isMesh | c.isLineSegments ) {
+			if ( c.isMesh || c.isLineSegments ) {
 
 				const elemSize = c.isMesh ? 3 : 2;