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

package/examples/jsm/curves/NURBSSurface.js

@@ -4,19 +4,58 @@ import {
 import * as NURBSUtils from '../curves/NURBSUtils.js';
 
 /**
- * NURBS surface object
+ * This class represents a NURBS surface.
  *
- * Implementation is based on (x, y [, z=0 [, w=1]]) control points with w=weight.
- **/
-
+ * Implementation is based on `(x, y [, z=0 [, w=1]])` control points with `w=weight`.
+ *
+ * @three_import import { NURBSSurface } from 'three/addons/curves/NURBSSurface.js';
+ */
 class NURBSSurface {
 
-	constructor( degree1, degree2, knots1, knots2 /* arrays of reals */, controlPoints /* array^2 of Vector(2|3|4) */ ) {
-
+	/**
+	 * Constructs a new NURBS surface.
+	 *
+	 * @param {number} degree1 - The first NURBS degree.
+	 * @param {number} degree2 - The second NURBS degree.
+	 * @param {Array<number>} knots1 - The first knots as a flat array of numbers.
+	 * @param {Array<number>} knots2 - The second knots as a flat array of numbers.
+	 * @param {Array<Array<Vector2|Vector3|Vector4>>} controlPoints - An array^2 holding control points.
+	 */
+	constructor( degree1, degree2, knots1, knots2, controlPoints ) {
+
+		/**
+		 * The first NURBS degree.
+		 *
+		 * @type {number}
+		 */
 		this.degree1 = degree1;
+
+		/**
+		 * The second NURBS degree.
+		 *
+		 * @type {number}
+		 */
 		this.degree2 = degree2;
+
+		/**
+		 * The first knots as a flat array of numbers.
+		 *
+		 * @type {Array<number>}
+		 */
 		this.knots1 = knots1;
+
+		/**
+		 * The second knots as a flat array of numbers.
+		 *
+		 * @type {Array<number>}
+		 */
 		this.knots2 = knots2;
+
+		/**
+		 *  An array holding arrays of control points.
+		 *
+		 * @type {Array<Array<Vector2|Vector3|Vector4>>}
+		 */
 		this.controlPoints = [];
 
 		const len1 = knots1.length - degree1 - 1;
@@ -38,6 +77,13 @@ class NURBSSurface {
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor. This vector lies on the NURBS surface.
+	 *
+	 * @param {number} t1 - The first interpolation factor representing the `u` position on the surface. Must be in the range `[0,1]`.
+	 * @param {number} t2 - The second interpolation factor representing the `v` position on the surface. Must be in the range `[0,1]`.
+	 * @param {Vector3} target - The target vector the result is written to.
+	 */
 	getPoint( t1, t2, target ) {
 
 		const u = this.knots1[ 0 ] + t1 * ( this.knots1[ this.knots1.length - 1 ] - this.knots1[ 0 ] ); // linear mapping t1->u

package/examples/jsm/curves/NURBSUtils.js

@@ -4,25 +4,18 @@ import {
 } from 'three';
 
 /**
- * NURBS utils
- *
- * See NURBSCurve and NURBSSurface.
- **/
-
-
-/**************************************************************
- *	NURBS Utils
- **************************************************************/
-
-/*
-Finds knot vector span.
+ * @module NURBSUtils
+ * @three_import import * as NURBSUtils from 'three/addons/curves/NURBSUtils.js';
+ */
 
-p : degree
-u : parametric value
-U : knot vector
-
-returns the span
-*/
+/**
+ * Finds knot vector span.
+ *
+ * @param {number} p - The degree.
+ * @param {number} u - The parametric value.
+ * @param {Array<number>} U - The knot vector.
+ * @return {number} The span.
+ */
 function findSpan( p, u, U ) {
 
 	const n = U.length - p - 1;
@@ -63,17 +56,15 @@ function findSpan( p, u, U ) {
 
 }
 
-
-/*
-Calculate basis functions. See The NURBS Book, page 70, algorithm A2.2
-
-span : span in which u lies
-u    : parametric point
-p    : degree
-U    : knot vector
-
-returns array[p+1] with basis functions values.
-*/
+/**
+ * Calculates basis functions. See The NURBS Book, page 70, algorithm A2.2.
+ *
+ * @param {number} span - The span in which `u` lies.
+ * @param {number} u - The parametric value.
+ * @param {number} p - The degree.
+ * @param {Array<number>} U - The knot vector.
+ * @return {Array<number>} Array[p+1] with basis functions values.
+ */
 function calcBasisFunctions( span, u, p, U ) {
 
 	const N = [];
@@ -106,17 +97,15 @@ function calcBasisFunctions( span, u, p, U ) {
 
 }
 
-
-/*
-Calculate B-Spline curve points. See The NURBS Book, page 82, algorithm A3.1.
-
-p : degree of B-Spline
-U : knot vector
-P : control points (x, y, z, w)
-u : parametric point
-
-returns point for given u
-*/
+/**
+ * Calculates B-Spline curve points. See The NURBS Book, page 82, algorithm A3.1.
+ *
+ * @param {number} p - The degree of the B-Spline.
+ * @param {Array<number>} U - The knot vector.
+ * @param {Array<Vector4>} P - The control points
+ * @param {number} u - The parametric point.
+ * @return {Vector4} The point for given `u`.
+ */
 function calcBSplinePoint( p, U, P, u ) {
 
 	const span = findSpan( p, u, U );
@@ -139,18 +128,16 @@ function calcBSplinePoint( p, U, P, u ) {
 
 }
 
-
-/*
-Calculate basis functions derivatives. See The NURBS Book, page 72, algorithm A2.3.
-
-span : span in which u lies
-u    : parametric point
-p    : degree
-n    : number of derivatives to calculate
-U    : knot vector
-
-returns array[n+1][p+1] with basis functions derivatives
-*/
+/**
+ * Calculates basis functions derivatives. See The NURBS Book, page 72, algorithm A2.3.
+ *
+ * @param {number} span - The span in which `u` lies.
+ * @param {number} u - The parametric point.
+ * @param {number} p - The degree.
+ * @param {number} n - number of derivatives to calculate
+ * @param {Array<number>} U - The knot vector.
+ * @return {Array<Array<number>>} An array[n+1][p+1] with basis functions derivatives.
+ */
 function calcBasisFunctionDerivatives( span, u, p, n, U ) {
 
 	const zeroArr = [];
@@ -273,18 +260,16 @@ function calcBasisFunctionDerivatives( span, u, p, n, U ) {
 
 }
 
-
-/*
-	Calculate derivatives of a B-Spline. See The NURBS Book, page 93, algorithm A3.2.
-
-	p  : degree
-	U  : knot vector
-	P  : control points
-	u  : Parametric points
-	nd : number of derivatives
-
-	returns array[d+1] with derivatives
-	*/
+/**
+ * Calculates derivatives of a B-Spline. See The NURBS Book, page 93, algorithm A3.2.
+ *
+ * @param {number} p - The degree.
+ * @param {Array<number>} U - The knot vector.
+ * @param {Array<Vector4>} P - The control points
+ * @param {number} u - The parametric point.
+ * @param {number} nd - The number of derivatives.
+ * @return {Array<Vector4>} An array[d+1] with derivatives.
+ */
 function calcBSplineDerivatives( p, U, P, u, nd ) {
 
 	const du = nd < p ? nd : p;
@@ -330,12 +315,13 @@ function calcBSplineDerivatives( p, U, P, u, nd ) {
 
 }
 
-
-/*
-Calculate "K over I"
-
-returns k!/(i!(k-i)!)
-*/
+/**
+ * Calculates "K over I".
+ *
+ * @param {number} k - The K value.
+ * @param {number} i - The I value.
+ * @return {number} k!/(i!(k-i)!)
+ */
 function calcKoverI( k, i ) {
 
 	let nom = 1;
@@ -364,14 +350,12 @@ function calcKoverI( k, i ) {
 
 }
 
-
-/*
-Calculate derivatives (0-nd) of rational curve. See The NURBS Book, page 127, algorithm A4.2.
-
-Pders : result of function calcBSplineDerivatives
-
-returns array with derivatives for rational curve.
-*/
+/**
+ * Calculates derivatives (0-nd) of rational curve. See The NURBS Book, page 127, algorithm A4.2.
+ *
+ * @param {Array<Vector4>} Pders - Array with derivatives.
+ * @return {Array<Vector3>} An array with derivatives for rational curve.
+ */
 function calcRationalCurveDerivatives( Pders ) {
 
 	const nd = Pders.length;
@@ -406,18 +390,16 @@ function calcRationalCurveDerivatives( Pders ) {
 
 }
 
-
-/*
-Calculate NURBS curve derivatives. See The NURBS Book, page 127, algorithm A4.2.
-
-p  : degree
-U  : knot vector
-P  : control points in homogeneous space
-u  : parametric points
-nd : number of derivatives
-
-returns array with derivatives.
-*/
+/**
+ * Calculates NURBS curve derivatives. See The NURBS Book, page 127, algorithm A4.2.
+ *
+ * @param {number} p - The degree.
+ * @param {Array<number>} U - The knot vector.
+ * @param {Array<Vector4>} P - The control points in homogeneous space.
+ * @param {number} u - The parametric point.
+ * @param {number} nd - The number of derivatives.
+ * @return {Array<Vector3>} array with derivatives for rational curve.
+ */
 function calcNURBSDerivatives( p, U, P, u, nd ) {
 
 	const Pders = calcBSplineDerivatives( p, U, P, u, nd );
@@ -425,17 +407,18 @@ function calcNURBSDerivatives( p, U, P, u, nd ) {
 
 }
 
-
-/*
-Calculate rational B-Spline surface point. See The NURBS Book, page 134, algorithm A4.3.
-
-p, q : degrees of B-Spline surface
-U, V : knot vectors
-P    : control points (x, y, z, w)
-u, v : parametric values
-
-returns point for given (u, v)
-*/
+/**
+ * Calculates a rational B-Spline surface point. See The NURBS Book, page 134, algorithm A4.3.
+ *
+ * @param {number} p - The first degree of B-Spline surface.
+ * @param {number} q - The second degree of B-Spline surface.
+ * @param {Array<number>} U - The first knot vector.
+ * @param {Array<number>} V - The second knot vector.
+ * @param {Array<Array<Vector4>>} P - The control points in homogeneous space.
+ * @param {number} u - The first parametric point.
+ * @param {number} v - The second parametric point.
+ * @param {Vector3} target - The target vector.
+ */
 function calcSurfacePoint( p, q, U, V, P, u, v, target ) {
 
 	const uspan = findSpan( p, u, U );
@@ -472,16 +455,21 @@ function calcSurfacePoint( p, q, U, V, P, u, v, target ) {
 
 }
 
-/*
-Calculate rational B-Spline volume point. See The NURBS Book, page 134, algorithm A4.3.
-
-p, q, r   : degrees of B-Splinevolume
-U, V, W   : knot vectors
-P         : control points (x, y, z, w)
-u, v, w   : parametric values
-
-returns point for given (u, v, w)
-*/
+/**
+ * Calculates a rational B-Spline volume point. See The NURBS Book, page 134, algorithm A4.3.
+ *
+ * @param {number} p - The first degree of B-Spline surface.
+ * @param {number} q - The second degree of B-Spline surface.
+ * @param {number} r - The third degree of B-Spline surface.
+ * @param {Array<number>} U - The first knot vector.
+ * @param {Array<number>} V - The second knot vector.
+ * @param {Array<number>} W - The third knot vector.
+ * @param {Array<Array<Array<Vector4>>>} P - The control points in homogeneous space.
+ * @param {number} u - The first parametric point.
+ * @param {number} v - The second parametric point.
+ * @param {number} w - The third parametric point.
+ * @param {Vector3} target - The target vector.
+ */
 function calcVolumePoint( p, q, r, U, V, W, P, u, v, w, target ) {
 
 	const uspan = findSpan( p, u, U );
@@ -513,13 +501,16 @@ function calcVolumePoint( p, q, r, U, V, W, P, u, v, w, target ) {
 		}
 
 	}
+
 	const Sw = new Vector4( 0, 0, 0, 0 );
 	for ( let m = 0; m <= r; ++ m ) {
+
 		for ( let l = 0; l <= q; ++ l ) {
 
 			Sw.add( temp[ m ][ l ].multiplyScalar( Nw[ m ] ).multiplyScalar( Nv[ l ] ) );
 
 		}
+
 	}
 
 	Sw.divideScalar( Sw.w );
@@ -527,7 +518,6 @@ function calcVolumePoint( p, q, r, U, V, W, P, u, v, w, target ) {
 
 }
 
-
 export {
 	findSpan,
 	calcBasisFunctions,

package/examples/jsm/curves/NURBSVolume.js

@@ -4,13 +4,25 @@ import {
 import * as NURBSUtils from '../curves/NURBSUtils.js';
 
 /**
- * NURBS volume object
+ * This class represents a NURBS volume.
  *
- * Implementation is based on (x, y, z [, w=1]]) control points with w=weight.
- **/
-
+ * Implementation is based on `(x, y [, z=0 [, w=1]])` control points with `w=weight`.
+ *
+ * @three_import import { NURBSVolume } from 'three/addons/curves/NURBSVolume.js';
+ */
 class NURBSVolume {
 
+	/**
+	 * Constructs a new NURBS surface.
+	 *
+	 * @param {number} degree1 - The first NURBS degree.
+	 * @param {number} degree2 - The second NURBS degree.
+	 * @param {number} degree3 - The third NURBS degree.
+	 * @param {Array<number>} knots1 - The first knots as a flat array of numbers.
+	 * @param {Array<number>} knots2 - The second knots as a flat array of numbers.
+	 * @param {Array<number>} knots3 - The third knots as a flat array of numbers.
+	 * @param {Array<Array<Array<Vector2|Vector3|Vector4>>>} controlPoints - An array^3 holding control points.
+	 */
 	constructor( degree1, degree2, degree3, knots1, knots2, knots3 /* arrays of reals */, controlPoints /* array^3 of Vector(2|3|4) */ ) {
 
 		this.degree1 = degree1;
@@ -47,6 +59,14 @@ class NURBSVolume {
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor. This vector lies within the NURBS volume.
+	 *
+	 * @param {number} t1 - The first interpolation factor representing the `u` position within the volume. Must be in the range `[0,1]`.
+	 * @param {number} t2 - The second interpolation factor representing the `v` position within the volume. Must be in the range `[0,1]`.
+	 * @param {number} t3 - The third interpolation factor representing the `w` position within the volume. Must be in the range `[0,1]`.
+	 * @param {Vector3} target - The target vector the result is written to.
+	 */
 	getPoint( t1, t2, t3, target ) {
 
 		const u = this.knots1[ 0 ] + t1 * ( this.knots1[ this.knots1.length - 1 ] - this.knots1[ 0 ] ); // linear mapping t1->u

package/examples/jsm/effects/AnaglyphEffect.js

@@ -1,16 +1,53 @@
 import {
 	LinearFilter,
+	MathUtils,
 	Matrix3,
 	NearestFilter,
+	PerspectiveCamera,
 	RGBAFormat,
 	ShaderMaterial,
-	StereoCamera,
+	Vector3,
 	WebGLRenderTarget
 } from 'three';
 import { FullScreenQuad } from '../postprocessing/Pass.js';
-
+import { frameCorners } from '../utils/CameraUtils.js';
+
+const _cameraL = /*@__PURE__*/ new PerspectiveCamera();
+const _cameraR = /*@__PURE__*/ new PerspectiveCamera();
+
+// Reusable vectors for screen corner calculations
+const _eyeL = /*@__PURE__*/ new Vector3();
+const _eyeR = /*@__PURE__*/ new Vector3();
+const _screenCenter = /*@__PURE__*/ new Vector3();
+const _screenBottomLeft = /*@__PURE__*/ new Vector3();
+const _screenBottomRight = /*@__PURE__*/ new Vector3();
+const _screenTopLeft = /*@__PURE__*/ new Vector3();
+const _right = /*@__PURE__*/ new Vector3();
+const _up = /*@__PURE__*/ new Vector3();
+const _forward = /*@__PURE__*/ new Vector3();
+
+/**
+ * A class that creates an anaglyph effect using physically-correct
+ * off-axis stereo projection.
+ *
+ * This implementation uses CameraUtils.frameCorners() to align stereo
+ * camera frustums to a virtual screen plane, providing accurate depth
+ * perception with zero parallax at the plane distance.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link AnaglyphPassNode}.
+ *
+ * @three_import import { AnaglyphEffect } from 'three/addons/effects/AnaglyphEffect.js';
+ */
 class AnaglyphEffect {
 
+	/**
+	 * Constructs a new anaglyph effect.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 * @param {number} width - The width of the effect in physical pixels.
+	 * @param {number} height - The height of the effect in physical pixels.
+	 */
 	constructor( renderer, width = 512, height = 512 ) {
 
 		// Dubois matrices from https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.7.6968&rep=rep1&type=pdf#page=4
@@ -27,13 +64,38 @@ class AnaglyphEffect {
 			- 0.00155529, - 0.0184503, 1.2264
 		] );
 
-		const _stereo = new StereoCamera();
+		/**
+		 * The interpupillary distance (eye separation) in world units.
+		 * Typical human IPD is 0.064 meters (64mm).
+		 *
+		 * @type {number}
+		 * @default 0.064
+		 */
+		this.eyeSep = 0.064;
+
+		/**
+		 * The distance in world units from the viewer to the virtual
+		 * screen plane where zero parallax (screen depth) occurs.
+		 * Objects at this distance appear at the screen surface.
+		 * Objects closer appear in front of the screen (negative parallax).
+		 * Objects further appear behind the screen (positive parallax).
+		 *
+		 * The screen dimensions are derived from the camera's FOV and aspect ratio
+		 * at this distance, ensuring the stereo view matches the camera's field of view.
+		 *
+		 * @type {number}
+		 * @default 0.5
+		 */
+		this.planeDistance = 0.5;
 
 		const _params = { minFilter: LinearFilter, magFilter: NearestFilter, format: RGBAFormat };
 
 		const _renderTargetL = new WebGLRenderTarget( width, height, _params );
 		const _renderTargetR = new WebGLRenderTarget( width, height, _params );
 
+		_cameraL.layers.enable( 1 );
+		_cameraR.layers.enable( 2 );
+
 		const _material = new ShaderMaterial( {
 
 			uniforms: {
@@ -94,6 +156,12 @@ class AnaglyphEffect {
 
 		const _quad = new FullScreenQuad( _material );
 
+		/**
+		 * Resizes the effect.
+		 *
+		 * @param {number} width - The width of the effect in logical pixels.
+		 * @param {number} height - The height of the effect in logical pixels.
+		 */
 		this.setSize = function ( width, height ) {
 
 			renderer.setSize( width, height );
@@ -105,6 +173,13 @@ class AnaglyphEffect {
 
 		};
 
+		/**
+		 * When using this effect, this method should be called instead of the
+		 * default {@link WebGLRenderer#render}.
+		 *
+		 * @param {Object3D} scene - The scene to render.
+		 * @param {Camera} camera - The camera.
+		 */
 		this.render = function ( scene, camera ) {
 
 			const currentRenderTarget = renderer.getRenderTarget();
@@ -113,16 +188,64 @@ class AnaglyphEffect {
 
 			if ( camera.parent === null && camera.matrixWorldAutoUpdate === true ) camera.updateMatrixWorld();
 
-			_stereo.update( camera );
-
+			// Get the camera's local coordinate axes from its world matrix
+			camera.matrixWorld.extractBasis( _right, _up, _forward );
+			_right.normalize();
+			_up.normalize();
+			_forward.normalize();
+
+			// Calculate eye positions
+			const halfSep = this.eyeSep / 2;
+			_eyeL.copy( camera.position ).addScaledVector( _right, - halfSep );
+			_eyeR.copy( camera.position ).addScaledVector( _right, halfSep );
+
+			// Calculate screen center (at planeDistance in front of the camera center)
+			_screenCenter.copy( camera.position ).addScaledVector( _forward, - this.planeDistance );
+
+			// Calculate screen dimensions from camera FOV and aspect ratio
+			const halfHeight = this.planeDistance * Math.tan( MathUtils.DEG2RAD * camera.fov / 2 );
+			const halfWidth = halfHeight * camera.aspect;
+
+			// Calculate screen corners
+			_screenBottomLeft.copy( _screenCenter )
+				.addScaledVector( _right, - halfWidth )
+				.addScaledVector( _up, - halfHeight );
+
+			_screenBottomRight.copy( _screenCenter )
+				.addScaledVector( _right, halfWidth )
+				.addScaledVector( _up, - halfHeight );
+
+			_screenTopLeft.copy( _screenCenter )
+				.addScaledVector( _right, - halfWidth )
+				.addScaledVector( _up, halfHeight );
+
+			// Set up left eye camera
+			_cameraL.position.copy( _eyeL );
+			_cameraL.near = camera.near;
+			_cameraL.far = camera.far;
+			frameCorners( _cameraL, _screenBottomLeft, _screenBottomRight, _screenTopLeft, true );
+			_cameraL.matrixWorld.compose( _cameraL.position, _cameraL.quaternion, _cameraL.scale );
+			_cameraL.matrixWorldInverse.copy( _cameraL.matrixWorld ).invert();
+
+			// Set up right eye camera
+			_cameraR.position.copy( _eyeR );
+			_cameraR.near = camera.near;
+			_cameraR.far = camera.far;
+			frameCorners( _cameraR, _screenBottomLeft, _screenBottomRight, _screenTopLeft, true );
+			_cameraR.matrixWorld.compose( _cameraR.position, _cameraR.quaternion, _cameraR.scale );
+			_cameraR.matrixWorldInverse.copy( _cameraR.matrixWorld ).invert();
+
+			// Render left eye
 			renderer.setRenderTarget( _renderTargetL );
 			renderer.clear();
-			renderer.render( scene, _stereo.cameraL );
+			renderer.render( scene, _cameraL );
 
+			// Render right eye
 			renderer.setRenderTarget( _renderTargetR );
 			renderer.clear();
-			renderer.render( scene, _stereo.cameraR );
+			renderer.render( scene, _cameraR );
 
+			// Composite anaglyph
 			renderer.setRenderTarget( null );
 			_quad.render( renderer );
 
@@ -130,6 +253,10 @@ class AnaglyphEffect {
 
 		};
 
+		/**
+		 * Frees internal resources. This method should be called
+		 * when the effect is no longer required.
+		 */
 		this.dispose = function () {
 
 			_renderTargetL.dispose();