@plastic-software/three 0.174.0 → 0.175.1

package/examples/jsm/curves/NURBSUtils.js

@@ -3,26 +3,16 @@ import {
 	Vector4
 } from 'three';
 
+/** @module NURBSUtils */
+
 /**
- * NURBS utils
+ * Finds knot vector span.
  *
- * See NURBSCurve and NURBSSurface.
- **/
-
-
-/**************************************************************
- *	NURBS Utils
- **************************************************************/
-
-/*
-Finds knot vector span.
-
-p : degree
-u : parametric value
-U : knot vector
-
-returns the 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 +53,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 +94,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 +125,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 +257,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 +312,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 +347,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 +387,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 +404,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 +452,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 );
@@ -530,7 +515,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,23 @@ 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`.
+ */
 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 +57,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

@@ -9,8 +9,21 @@ import {
 } from 'three';
 import { FullScreenQuad } from '../postprocessing/Pass.js';
 
+/**
+ * A class that creates an anaglyph effect.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link AnaglyphPassNode}.
+ */
 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
@@ -94,6 +107,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 +124,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();
@@ -130,6 +156,10 @@ class AnaglyphEffect {
 
 		};
 
+		/**
+		 * Frees internal resources. This method should be called
+		 * when the effect is no longer required.
+		 */
 		this.dispose = function () {
 
 			_renderTargetL.dispose();

package/examples/jsm/effects/AsciiEffect.js

@@ -1,11 +1,17 @@
 /**
- * Ascii generation is based on https://github.com/hassadee/jsascii/blob/master/jsascii.js
+ * A class that creates an ASCII effect.
  *
- * 16 April 2012 - @blurspline
+ * The ASCII generation is based on [jsascii]{@link https://github.com/hassadee/jsascii/blob/master/jsascii.js}.
  */
-
 class AsciiEffect {
 
+	/**
+	 * Constructs a new ASCII effect.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 * @param {string} [charSet=' .:-=+*#%@'] - The char set.
+	 * @param {AsciiEffect~Options} [options] - The configuration parameter.
+	 */
 	constructor( renderer, charSet = ' .:-=+*#%@', options = {} ) {
 
 		// ' .,:;=|iI+hHOE#`$';
@@ -14,12 +20,12 @@ class AsciiEffect {
 
 		// Some ASCII settings
 
-		const fResolution = options[ 'resolution' ] || 0.15; // Higher for more details
+		const fResolution = options[ 'resolution' ] || 0.15;
 		const iScale = options[ 'scale' ] || 1;
-		const bColor = options[ 'color' ] || false; // nice but slows down rendering!
-		const bAlpha = options[ 'alpha' ] || false; // Transparency
-		const bBlock = options[ 'block' ] || false; // blocked characters. like good O dos
-		const bInvert = options[ 'invert' ] || false; // black is white, white is black
+		const bColor = options[ 'color' ] || false;
+		const bAlpha = options[ 'alpha' ] || false;
+		const bBlock = options[ 'block' ] || false;
+		const bInvert = options[ 'invert' ] || false;
 		const strResolution = options[ 'strResolution' ] || 'low';
 
 		let width, height;
@@ -33,6 +39,12 @@ class AsciiEffect {
 		let iWidth, iHeight;
 		let oImg;
 
+		/**
+		 * Resizes the effect.
+		 *
+		 * @param {number} w - The width of the effect in logical pixels.
+		 * @param {number} h - The height of the effect in logical pixels.
+		 */
 		this.setSize = function ( w, h ) {
 
 			width = w;
@@ -44,7 +56,13 @@ class AsciiEffect {
 
 		};
 
-
+		/**
+		 * 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 ) {
 
 			renderer.render( scene, camera );
@@ -52,6 +70,12 @@ class AsciiEffect {
 
 		};
 
+		/**
+		 * The DOM element of the effect. This element must be used instead of the
+		 * default {@link WebGLRenderer#domElement}.
+		 *
+		 * @type {HTMLDivElement}
+		 */
 		this.domElement = domElement;
 
 
@@ -77,8 +101,8 @@ class AsciiEffect {
 
 			}
 
-			oAscii.cellSpacing = 0;
-			oAscii.cellPadding = 0;
+			oAscii.cellSpacing = '0';
+			oAscii.cellPadding = '0';
 
 			const oStyle = oAscii.style;
 			oStyle.whiteSpace = 'pre';
@@ -94,8 +118,6 @@ class AsciiEffect {
 		}
 
 
-		const aDefaultCharList = ( ' .,:;i1tfLCG08@' ).split( '' );
-		const aDefaultColorCharList = ( ' CGO08@' ).split( '' );
 		const strFont = 'courier new, monospace';
 
 		const oCanvasImg = renderer.domElement;
@@ -114,9 +136,19 @@ class AsciiEffect {
 
 		}
 
-		let aCharList = ( bColor ? aDefaultColorCharList : aDefaultCharList );
+		let aCharList;
+		if ( charSet ) {
+
+			aCharList = ( charSet ).split( '' );
+
+		} else {
+
+			const aDefaultCharList = ( ' .,:;i1tfLCG08@' ).split( '' );
+			const aDefaultColorCharList = ( ' CGO08@' ).split( '' );
+			aCharList = ( bColor ? aDefaultColorCharList : aDefaultCharList );
+
+		}
 
-		if ( charSet ) aCharList = charSet;
 
 		// Setup dom
 
@@ -260,4 +292,17 @@ class AsciiEffect {
 
 }
 
+/**
+ * This type represents configuration settings of `AsciiEffect`.
+ *
+ * @typedef {Object} AsciiEffect~Options
+ * @property {number} [resolution=0.15] - A higher value leads to more details.
+ * @property {number} [scale=1] - The scale of the effect.
+ * @property {boolean} [color=false] - Whether colors should be enabled or not. Better quality but slows down rendering.
+ * @property {boolean} [alpha=false] - Whether transparency should be enabled or not.
+ * @property {boolean} [block=false] - Whether blocked characters should be enabled or not.
+ * @property {boolean} [invert=false] - Whether colors should be inverted or not.
+ * @property {('low'|'medium'|'high')} [strResolution='low'] - The string resolution.
+ **/
+
 export { AsciiEffect };