@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/curves/CurveExtras.js

@@ -13,10 +13,20 @@ import {
  * https://prideout.net/blog/old/blog/index.html@p=44.html
  */
 
-// GrannyKnot
-
+/**
+ * A Granny Knot curve.
+ *
+ * @augments Curve
+ */
 class GrannyKnot extends Curve {
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -33,18 +43,39 @@ class GrannyKnot extends Curve {
 
 }
 
-// HeartCurve
-
+/**
+ * A heart curve.
+ *
+ * @augments Curve
+ */
 class HeartCurve extends Curve {
 
+	/**
+	 * Constructs a new heart curve.
+	 *
+	 * @param {number} [scale=5] - The curve's scale.
+	 */
 	constructor( scale = 5 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 5
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -61,18 +92,39 @@ class HeartCurve extends Curve {
 
 }
 
-// Viviani's Curve
-
+/**
+ * A Viviani curve.
+ *
+ * @augments Curve
+ */
 class VivianiCurve extends Curve {
 
+	/**
+	 * Constructs a new Viviani curve.
+	 *
+	 * @param {number} [scale=70] - The curve's scale.
+	 */
 	constructor( scale = 70 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 70
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -90,10 +142,20 @@ class VivianiCurve extends Curve {
 
 }
 
-// KnotCurve
-
+/**
+ * A knot curve.
+ *
+ * @augments Curve
+ */
 class KnotCurve extends Curve {
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -113,11 +175,20 @@ class KnotCurve extends Curve {
 
 }
 
-
-// HelixCurve
-
+/**
+ * A helix curve.
+ *
+ * @augments Curve
+ */
 class HelixCurve extends Curve {
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -137,18 +208,39 @@ class HelixCurve extends Curve {
 
 }
 
-// TrefoilKnot
-
+/**
+ * A Trefoil Knot.
+ *
+ * @augments Curve
+ */
 class TrefoilKnot extends Curve {
 
+	/**
+	 * Constructs a new Trefoil Knot.
+	 *
+	 * @param {number} [scale=10] - The curve's scale.
+	 */
 	constructor( scale = 10 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 10
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -165,18 +257,39 @@ class TrefoilKnot extends Curve {
 
 }
 
-// TorusKnot
-
+/**
+ * A torus knot.
+ *
+ * @augments Curve
+ */
 class TorusKnot extends Curve {
 
+	/**
+	 * Constructs a new torus knot.
+	 *
+	 * @param {number} [scale=10] - The curve's scale.
+	 */
 	constructor( scale = 10 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 10
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -196,18 +309,39 @@ class TorusKnot extends Curve {
 
 }
 
-// CinquefoilKnot
-
+/**
+ * A Cinquefoil Knot.
+ *
+ * @augments Curve
+ */
 class CinquefoilKnot extends Curve {
 
+	/**
+	 * Constructs a new Cinquefoil Knot.
+	 *
+	 * @param {number} [scale=10] - The curve's scale.
+	 */
 	constructor( scale = 10 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 10
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -227,19 +361,39 @@ class CinquefoilKnot extends Curve {
 
 }
 
-
-// TrefoilPolynomialKnot
-
+/**
+ * A Trefoil Polynomial Knot.
+ *
+ * @augments Curve
+ */
 class TrefoilPolynomialKnot extends Curve {
 
+	/**
+	 * Constructs a new Trefoil Polynomial Knot.
+	 *
+	 * @param {number} [scale=10] - The curve's scale.
+	 */
 	constructor( scale = 10 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 10
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -263,18 +417,39 @@ function scaleTo( x, y, t ) {
 
 }
 
-// FigureEightPolynomialKnot
-
+/**
+ * A Figure Eight Polynomial Knot.
+ *
+ * @augments Curve
+ */
 class FigureEightPolynomialKnot extends Curve {
 
+	/**
+	 * Constructs a new Figure Eight Polynomial Knot.
+	 *
+	 * @param {number} [scale=1] - The curve's scale.
+	 */
 	constructor( scale = 1 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -291,18 +466,39 @@ class FigureEightPolynomialKnot extends Curve {
 
 }
 
-// DecoratedTorusKnot4a
-
+/**
+ * A Decorated Torus Knot 4a.
+ *
+ * @augments Curve
+ */
 class DecoratedTorusKnot4a extends Curve {
 
+	/**
+	 * Constructs a new Decorated Torus Knot 4a.
+	 *
+	 * @param {number} [scale=1] - The curve's scale.
+	 */
 	constructor( scale = 40 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 40
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -319,18 +515,39 @@ class DecoratedTorusKnot4a extends Curve {
 
 }
 
-// DecoratedTorusKnot4b
-
+/**
+ * A Decorated Torus Knot 4b.
+ *
+ * @augments Curve
+ */
 class DecoratedTorusKnot4b extends Curve {
 
+	/**
+	 * Constructs a new Decorated Torus Knot 4b.
+	 *
+	 * @param {number} [scale=1] - The curve's scale.
+	 */
 	constructor( scale = 40 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 40
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -347,19 +564,39 @@ class DecoratedTorusKnot4b extends Curve {
 
 }
 
-
-// DecoratedTorusKnot5a
-
+/**
+ * A Decorated Torus Knot 5a.
+ *
+ * @augments Curve
+ */
 class DecoratedTorusKnot5a extends Curve {
 
+	/**
+	 * Constructs a new Decorated Torus Knot 5a.
+	 *
+	 * @param {number} [scale=1] - The curve's scale.
+	 */
 	constructor( scale = 40 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 40
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -376,18 +613,39 @@ class DecoratedTorusKnot5a extends Curve {
 
 }
 
-// DecoratedTorusKnot5c
-
+/**
+ * A Decorated Torus Knot 5c.
+ *
+ * @augments Curve
+ */
 class DecoratedTorusKnot5c extends Curve {
 
+	/**
+	 * Constructs a new Decorated Torus Knot 5c.
+	 *
+	 * @param {number} [scale=1] - The curve's scale.
+	 */
 	constructor( scale = 40 ) {
 
 		super();
 
+		/**
+		 * The curve's scale.
+		 *
+		 * @type {number}
+		 * @default 40
+		 */
 		this.scale = scale;
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;

package/examples/jsm/curves/NURBSCurve.js

@@ -6,34 +6,63 @@ import {
 import * as NURBSUtils from '../curves/NURBSUtils.js';
 
 /**
- * NURBS curve object
+ * This class represents a NURBS curve.
  *
- * Derives from Curve, overriding getPoint and getTangent.
+ * 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.
- *
- **/
-
+ * @augments Curve
+ */
 class NURBSCurve extends Curve {
 
-	constructor(
-		degree,
-		knots /* array of reals */,
-		controlPoints /* array of Vector(2|3|4) */,
-		startKnot /* index in knots */,
-		endKnot /* index in knots */
-	) {
+	/**
+	 * Constructs a new NURBS curve.
+	 *
+	 * @param {number} degree - The NURBS degree.
+	 * @param {Array<number>} knots - The knots as a flat array of numbers.
+	 * @param {Array<Vector2|Vector3|Vector4>} controlPoints - An array holding control points.
+	 * @param {number} [startKnot] - Index of the start knot into the `knots` array.
+	 * @param {number} [endKnot] - Index of the end knot into the `knots` array.
+	 */
+	constructor( degree, knots, controlPoints, startKnot, endKnot ) {
 
 		super();
 
 		const knotsLength = knots ? knots.length - 1 : 0;
 		const pointsLength = controlPoints ? controlPoints.length : 0;
 
+		/**
+		 * The NURBS degree.
+		 *
+		 * @type {number}
+		 */
 		this.degree = degree;
+
+		/**
+		 * The knots as a flat array of numbers.
+		 *
+		 * @type {Array<number>}
+		 */
 		this.knots = knots;
+
+		/**
+		 * An array of control points.
+		 *
+		 * @type {Array<Vector4>}
+		 */
 		this.controlPoints = [];
-		// Used by periodic NURBS to remove hidden spans
+
+		/**
+		 * Index of the start knot into the `knots` array.
+		 *
+		 * @type {number}
+		 */
 		this.startKnot = startKnot || 0;
+
+		/**
+		 * Index of the end knot into the `knots` array.
+		 *
+		 * @type {number}
+		 */
 		this.endKnot = endKnot || knotsLength;
 
 		for ( let i = 0; i < pointsLength; ++ i ) {
@@ -46,6 +75,13 @@ class NURBSCurve extends Curve {
 
 	}
 
+	/**
+	 * This method returns a vector in 3D space for the given interpolation factor.
+	 *
+	 * @param {number} t - A interpolation factor representing a position on the curve. Must be in the range `[0,1]`.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The position on the curve.
+	 */
 	getPoint( t, optionalTarget = new Vector3() ) {
 
 		const point = optionalTarget;
@@ -66,6 +102,13 @@ class NURBSCurve extends Curve {
 
 	}
 
+	/**
+	 * Returns a unit vector tangent for the given interpolation factor.
+	 *
+	 * @param {number} t - The interpolation factor.
+	 * @param {Vector3} [optionalTarget] - The optional target vector the result is written to.
+	 * @return {Vector3} The tangent vector.
+	 */
 	getTangent( t, optionalTarget = new Vector3() ) {
 
 		const tangent = optionalTarget;

package/examples/jsm/curves/NURBSSurface.js

@@ -4,19 +4,56 @@ 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`.
+ */
 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 +75,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