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

package/examples/jsm/loaders/STLLoader.js

@@ -10,65 +10,69 @@ import {
 } from 'three';
 
 /**
- * Description: A THREE loader for STL ASCII files, as created by Solidworks and other CAD programs.
+ * A loader for the STL format, as created by Solidworks and other CAD programs.
  *
- * Supports both binary and ASCII encoded files, with automatic detection of type.
- *
- * The loader returns a non-indexed buffer geometry.
+ * Supports both binary and ASCII encoded files. The loader returns a non-indexed buffer geometry.
  *
  * Limitations:
- *  Binary decoding supports "Magics" color format (http://en.wikipedia.org/wiki/STL_(file_format)#Color_in_binary_STL).
- *  There is perhaps some question as to how valid it is to always assume little-endian-ness.
- *  ASCII decoding assumes file is UTF-8.
- *
- * Usage:
- *  const loader = new STLLoader();
- *  loader.load( './models/stl/slotted_disk.stl', function ( geometry ) {
- *    scene.add( new THREE.Mesh( geometry ) );
- *  });
+ * - Binary decoding supports "Magics" color format (http://en.wikipedia.org/wiki/STL_(file_format)#Color_in_binary_STL).
+ * - There is perhaps some question as to how valid it is to always assume little-endian-ness.
+ * - ASCII decoding assumes file is UTF-8.
  *
+ * ```js
+ * const loader = new STLLoader();
+ * const geometry = await loader.loadAsync( './models/stl/slotted_disk.stl' )
+ * scene.add( new THREE.Mesh( geometry ) );
+ * ```
  * For binary STLs geometry might contain colors for vertices. To use it:
- *  // use the same code to load STL as above
- *  if (geometry.hasColors) {
- *    material = new THREE.MeshPhongMaterial({ opacity: geometry.alpha, vertexColors: true });
- *  } else { .... }
- *  const mesh = new THREE.Mesh( geometry, material );
- *
+ * ```js
+ * // use the same code to load STL as above
+ * if ( geometry.hasColors ) {
+ * 	material = new THREE.MeshPhongMaterial( { opacity: geometry.alpha, vertexColors: true } );
+ * }
+ * const mesh = new THREE.Mesh( geometry, material );
+ * ```
  * For ASCII STLs containing multiple solids, each solid is assigned to a different group.
  * Groups can be used to assign a different color by defining an array of materials with the same length of
  * geometry.groups and passing it to the Mesh constructor:
  *
- * const mesh = new THREE.Mesh( geometry, material );
- *
- * For example:
+ * ```js
+ * const materials = [];
+ * const nGeometryGroups = geometry.groups.length;
  *
- *  const materials = [];
- *  const nGeometryGroups = geometry.groups.length;
+ * for ( let i = 0; i < nGeometryGroups; i ++ ) {
+ * 	const material = new THREE.MeshPhongMaterial( { color: colorMap[ i ], wireframe: false } );
+ * 	materials.push( material );
+ * }
  *
- *  const colorMap = ...; // Some logic to index colors.
+ * const mesh = new THREE.Mesh(geometry, materials);
+ * ```
  *
- *  for (let i = 0; i < nGeometryGroups; i++) {
- *
- *		const material = new THREE.MeshPhongMaterial({
- *			color: colorMap[i],
- *			wireframe: false
- *		});
- *
- *  }
- *
- *  materials.push(material);
- *  const mesh = new THREE.Mesh(geometry, materials);
+ * @augments Loader
+ * @three_import import { STLLoader } from 'three/addons/loaders/STLLoader.js';
  */
-
-
 class STLLoader extends Loader {
 
+	/**
+	 * Constructs a new STL loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded STL asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function(BufferGeometry)} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -105,6 +109,12 @@ class STLLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given STL data and returns the resulting geometry.
+	 *
+	 * @param {ArrayBuffer} data - The raw STL data as an array buffer.
+	 * @return {BufferGeometry} The parsed geometry.
+	 */
 	parse( data ) {
 
 		function isBinary( data ) {

package/examples/jsm/loaders/SVGLoader.js

@@ -16,20 +16,85 @@ import {
 
 const COLOR_SPACE_SVG = SRGBColorSpace;
 
+/**
+ * A loader for the SVG format.
+ *
+ * Scalable Vector Graphics is an XML-based vector image format for two-dimensional graphics
+ * with support for interactivity and animation.
+ *
+ * ```js
+ * const loader = new SVGLoader();
+ * const data = await loader.loadAsync( 'data/svgSample.svg' );
+ *
+ * const paths = data.paths;
+ * const group = new THREE.Group();
+ *
+ * for ( let i = 0; i < paths.length; i ++ ) {
+ *
+ * 	const path = paths[ i ];
+ * 	const material = new THREE.MeshBasicMaterial( {
+ * 		color: path.color,
+ * 		side: THREE.DoubleSide,
+ * 		depthWrite: false
+ * 	} );
+ *
+ * 	const shapes = SVGLoader.createShapes( path );
+ *
+ * 	for ( let j = 0; j < shapes.length; j ++ ) {
+ *
+ * 		const shape = shapes[ j ];
+ * 		const geometry = new THREE.ShapeGeometry( shape );
+ * 		const mesh = new THREE.Mesh( geometry, material );
+ * 		group.add( mesh );
+ *
+ * 	}
+ *
+ * }
+ *
+ * scene.add( group );
+ * ```
+ *
+ * @augments Loader
+ * @three_import import { SVGLoader } from 'three/addons/loaders/SVGLoader.js';
+ */
 class SVGLoader extends Loader {
 
+	/**
+	 * Constructs a new SVG loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
-		// Default dots per inch
+		/**
+		 * Default dots per inch.
+		 *
+		 * @type {number}
+		 * @default 90
+		 */
 		this.defaultDPI = 90;
 
-		// Accepted units: 'mm', 'cm', 'in', 'pt', 'pc', 'px'
+		/**
+		 * Default unit.
+		 *
+		 * @type {('mm'|'cm'|'in'|'pt'|'pc'|'px')}
+		 * @default 'px'
+		 */
 		this.defaultUnit = 'px';
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded SVG asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function({paths:Array<ShapePath>,xml:string})} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -64,6 +129,13 @@ class SVGLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given SVG data and returns the resulting data.
+	 *
+	 * @param {string} text - The raw SVG data as a string.
+	 * @return {{paths:Array<ShapePath>,xml:string}} An object holding an array of shape paths and the
+	 * SVG XML document.
+	 */
 	parse( text ) {
 
 		const scope = this;
@@ -775,6 +847,7 @@ class SVGLoader extends Loader {
 		* According to https://www.w3.org/TR/SVG/shapes.html#RectElementRXAttribute
 		* rounded corner should be rendered to elliptical arc, but bezier curve does the job well enough
 		*/
+
 		function parseRectNode( node ) {
 
 			const x = parseFloatWithUnits( node.getAttribute( 'x' ) || 0 );
@@ -1009,7 +1082,7 @@ class SVGLoader extends Loader {
 				};
 
 				if ( node.hasAttribute( svgName ) ) style[ jsName ] = adjustFunction( node.getAttribute( svgName ) );
-				if ( stylesheetStyles[ svgName ] ) style[ jsName ] = adjustFunction( stylesheetStyles[ svgName ] );
+				if ( stylesheetStyles[ jsName ] ) style[ jsName ] = adjustFunction( stylesheetStyles[ jsName ] );
 				if ( node.style && node.style[ svgName ] !== '' ) style[ jsName ] = adjustFunction( node.style[ svgName ] );
 
 			}
@@ -1429,8 +1502,8 @@ class SVGLoader extends Loader {
 
 			if ( node.nodeName === 'use' && ( node.hasAttribute( 'x' ) || node.hasAttribute( 'y' ) ) ) {
 
-				const tx = parseFloatWithUnits( node.getAttribute( 'x' ) );
-				const ty = parseFloatWithUnits( node.getAttribute( 'y' ) );
+				const tx = parseFloatWithUnits( node.getAttribute( 'x' ) || 0 );
+				const ty = parseFloatWithUnits( node.getAttribute( 'y' ) || 0 );
 
 				transform.translate( tx, ty );
 
@@ -1633,7 +1706,7 @@ class SVGLoader extends Loader {
 					( curve.aEndAngle - curve.aStartAngle ) % ( 2 * Math.PI ) < Number.EPSILON;
 
 				// Do not touch angles of a full ellipse because after transformation they
-				// would converge to a sinle value effectively removing the whole curve
+				// would converge to a single value effectively removing the whole curve
 
 				if ( ! isFullEllipse ) {
 
@@ -1916,11 +1989,14 @@ class SVGLoader extends Loader {
 
 	}
 
+	/**
+	 * Creates from the given shape path and array of shapes.
+	 *
+	 * @param {ShapePath} shapePath - The shape path.
+	 * @return {Array<Shape>} An array of shapes.
+	 */
 	static createShapes( shapePath ) {
 
-		// Param shapePath: a shapepath as returned by the parse function of this class
-		// Returns Shape object
-
 		const BIGNUMBER = 999999999;
 
 		const IntersectionLocationType = {
@@ -2124,7 +2200,7 @@ class SVGLoader extends Loader {
 
 				// check if the center of the bounding box is in the bounding box of the paths.
 				// this is a pruning method to limit the search of intersections in paths that can't envelop of the current path.
-				// if a path envelops another path. The center of that oter path, has to be inside the bounding box of the enveloping path.
+				// if a path envelops another path. The center of that other path, has to be inside the bounding box of the enveloping path.
 				if ( path.boundingBox.containsPoint( center ) ) {
 
 					const intersections = getIntersections( scanline, path.points );
@@ -2360,15 +2436,18 @@ class SVGLoader extends Loader {
 
 	}
 
+	/**
+	 * Returns a stroke style object from the given parameters.
+	 *
+	 * @param {number} [width=1] - The stroke width.
+	 * @param {string} [color='#000'] - The stroke color, as  returned by {@link Color#getStyle}.
+	 * @param {'round'|'bevel'|'miter'|'miter-limit'} [lineJoin='miter'] - The line join style.
+	 * @param {'round'|'square'|'butt'} [lineCap='butt'] - The line cap style.
+	 * @param {number} [miterLimit=4] - Maximum join length, in multiples of the `width` parameter (join is truncated if it exceeds that distance).
+	 * @return {Object} The style object.
+	 */
 	static getStrokeStyle( width, color, lineJoin, lineCap, miterLimit ) {
 
-		// Param width: Stroke width
-		// Param color: As returned by THREE.Color.getStyle()
-		// Param lineJoin: One of "round", "bevel", "miter" or "miter-limit"
-		// Param lineCap: One of "round", "square" or "butt"
-		// Param miterLimit: Maximum join length, in multiples of the "width" parameter (join is truncated if it exceeds that distance)
-		// Returns style object
-
 		width = width !== undefined ? width : 1;
 		color = color !== undefined ? color : '#000';
 		lineJoin = lineJoin !== undefined ? lineJoin : 'miter';
@@ -2385,16 +2464,18 @@ class SVGLoader extends Loader {
 
 	}
 
+	/**
+	 * Creates a stroke from an array of points.
+	 *
+	 * @param {Array<Vector2>} points - The points in 2D space. Minimum 2 points. The path can be open or closed (last point equals to first point).
+	 * @param {Object} style - Object with SVG properties as returned by `SVGLoader.getStrokeStyle()`, or `SVGLoader.parse()` in the `path.userData.style` object.
+	 * @param {number} [arcDivisions=12] - Arc divisions for round joins and endcaps.
+	 * @param {number} [minDistance=0.001] - Points closer to this distance will be merged.
+	 * @return {?BufferGeometry} The stroke geometry. UV coordinates are generated ('u' along path. 'v' across it, from left to right).
+	 * Returns `null` if not geometry was generated.
+	 */
 	static pointsToStroke( points, style, arcDivisions, minDistance ) {
 
-		// Generates a stroke with some width around the given path.
-		// The path can be open or closed (last point equals to first point)
-		// Param points: Array of Vector2D (the path). Minimum 2 points.
-		// Param style: Object with SVG properties as returned by SVGLoader.getStrokeStyle(), or SVGLoader.parse() in the path.userData.style object
-		// Params arcDivisions: Arc divisions for round joins and endcaps. (Optional)
-		// Param minDistance: Points closer to this distance will be merged. (Optional)
-		// Returns BufferGeometry with stroke triangles (In plane z = 0). UV coordinates are generated ('u' along path. 'v' across it, from left to right)
-
 		const vertices = [];
 		const normals = [];
 		const uvs = [];
@@ -2414,6 +2495,19 @@ class SVGLoader extends Loader {
 
 	}
 
+	/**
+	 * Creates a stroke from an array of points.
+	 *
+	 * @param {Array<Vector2>} points - The points in 2D space. Minimum 2 points.
+	 * @param {Object} style - Object with SVG properties as returned by `SVGLoader.getStrokeStyle()`, or `SVGLoader.parse()` in the `path.userData.style` object.
+	 * @param {number} [arcDivisions=12] - Arc divisions for round joins and endcaps.
+	 * @param {number} [minDistance=0.001] - Points closer to this distance will be merged.
+	 * @param {Array<number>} vertices - An array holding vertices.
+	 * @param {Array<number>} normals - An array holding normals.
+	 * @param {Array<number>} uvs - An array holding uvs.
+	 * @param {number} [vertexOffset=0] - The vertex offset.
+	 * @return {number} The number of vertices.
+	 */
 	static pointsToStrokeWithBuffers( points, style, arcDivisions, minDistance, vertices, normals, uvs, vertexOffset ) {
 
 		// This function can be called to update existing arrays or buffers.