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

package/examples/jsm/curves/CurveExtras.js

@@ -13,10 +13,21 @@ import {
  * https://prideout.net/blog/old/blog/index.html@p=44.html
  */
 
-// GrannyKnot
-
+/**
+ * A Granny Knot curve.
+ *
+ * @augments Curve
+ * @three_import import { GrannyKnot } from 'three/addons/curves/CurveExtras.js';
+ */
 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 +44,40 @@ class GrannyKnot extends Curve {
 
 }
 
-// HeartCurve
-
+/**
+ * A heart curve.
+ *
+ * @augments Curve
+ * @three_import import { HeartCurve } from 'three/addons/curves/CurveExtras.js';
+ */
 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 +94,40 @@ class HeartCurve extends Curve {
 
 }
 
-// Viviani's Curve
-
+/**
+ * A Viviani curve.
+ *
+ * @augments Curve
+ * @three_import import { VivianiCurve } from 'three/addons/curves/CurveExtras.js';
+ */
 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 +145,21 @@ class VivianiCurve extends Curve {
 
 }
 
-// KnotCurve
-
+/**
+ * A knot curve.
+ *
+ * @augments Curve
+ * @three_import import { KnotCurve } from 'three/addons/curves/CurveExtras.js';
+ */
 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 +179,21 @@ class KnotCurve extends Curve {
 
 }
 
-
-// HelixCurve
-
+/**
+ * A helix curve.
+ *
+ * @augments Curve
+ * @three_import import { HelixCurve } from 'three/addons/curves/CurveExtras.js';
+ */
 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 +213,40 @@ class HelixCurve extends Curve {
 
 }
 
-// TrefoilKnot
-
+/**
+ * A Trefoil Knot.
+ *
+ * @augments Curve
+ * @three_import import { TrefoilKnot } from 'three/addons/curves/CurveExtras.js';
+ */
 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 +263,40 @@ class TrefoilKnot extends Curve {
 
 }
 
-// TorusKnot
-
+/**
+ * A torus knot.
+ *
+ * @augments Curve
+ * @three_import import { TorusKnot } from 'three/addons/curves/CurveExtras.js';
+ */
 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 +316,40 @@ class TorusKnot extends Curve {
 
 }
 
-// CinquefoilKnot
-
+/**
+ * A Cinquefoil Knot.
+ *
+ * @augments Curve
+ * @three_import import { CinquefoilKnot } from 'three/addons/curves/CurveExtras.js';
+ */
 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 +369,40 @@ class CinquefoilKnot extends Curve {
 
 }
 
-
-// TrefoilPolynomialKnot
-
+/**
+ * A Trefoil Polynomial Knot.
+ *
+ * @augments Curve
+ * @three_import import { TrefoilPolynomialKnot } from 'three/addons/curves/CurveExtras.js';
+ */
 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 +426,40 @@ function scaleTo( x, y, t ) {
 
 }
 
-// FigureEightPolynomialKnot
-
+/**
+ * A Figure Eight Polynomial Knot.
+ *
+ * @augments Curve
+ * @three_import import { FigureEightPolynomialKnot } from 'three/addons/curves/CurveExtras.js';
+ */
 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 +476,40 @@ class FigureEightPolynomialKnot extends Curve {
 
 }
 
-// DecoratedTorusKnot4a
-
+/**
+ * A Decorated Torus Knot 4a.
+ *
+ * @augments Curve
+ * @three_import import { DecoratedTorusKnot4a } from 'three/addons/curves/CurveExtras.js';
+ */
 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 +526,40 @@ class DecoratedTorusKnot4a extends Curve {
 
 }
 
-// DecoratedTorusKnot4b
-
+/**
+ * A Decorated Torus Knot 4b.
+ *
+ * @augments Curve
+ * @three_import import { DecoratedTorusKnot4b } from 'three/addons/curves/CurveExtras.js';
+ */
 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 +576,40 @@ class DecoratedTorusKnot4b extends Curve {
 
 }
 
-
-// DecoratedTorusKnot5a
-
+/**
+ * A Decorated Torus Knot 5a.
+ *
+ * @augments Curve
+ * @three_import import { DecoratedTorusKnot5a } from 'three/addons/curves/CurveExtras.js';
+ */
 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 +626,40 @@ class DecoratedTorusKnot5a extends Curve {
 
 }
 
-// DecoratedTorusKnot5c
-
+/**
+ * A Decorated Torus Knot 5c.
+ *
+ * @augments Curve
+ * @three_import import { DecoratedTorusKnot5c } from 'three/addons/curves/CurveExtras.js';
+ */
 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,67 @@ 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
+ * @three_import import { NURBSCurve } from 'three/addons/curves/NURBSCurve.js';
+ */
 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;
-		this.endKnot = endKnot || ( this.knots.length - 1 );
 
-		for ( let i = 0; i < controlPoints.length; ++ i ) {
+		/**
+		 * Index of the end knot into the `knots` array.
+		 *
+		 * @type {number}
+		 */
+		this.endKnot = endKnot || knotsLength;
+
+		for ( let i = 0; i < pointsLength; ++ i ) {
 
 			// ensure Vector4 for control points
 			const point = controlPoints[ i ];
@@ -43,6 +76,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;
@@ -63,6 +103,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;
@@ -75,6 +122,34 @@ class NURBSCurve extends Curve {
 
 	}
 
+	toJSON() {
+
+		const data = super.toJSON();
+
+		data.degree = this.degree;
+		data.knots = [ ...this.knots ];
+		data.controlPoints = this.controlPoints.map( p => p.toArray() );
+		data.startKnot = this.startKnot;
+		data.endKnot = this.endKnot;
+
+		return data;
+
+	}
+
+	fromJSON( json ) {
+
+		super.fromJSON( json );
+
+		this.degree = json.degree;
+		this.knots = [ ...json.knots ];
+		this.controlPoints = json.controlPoints.map( p => new Vector4( p[ 0 ], p[ 1 ], p[ 2 ], p[ 3 ] ) );
+		this.startKnot = json.startKnot;
+		this.endKnot = json.endKnot;
+
+		return this;
+
+	}
+
 }
 
 export { NURBSCurve };