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

package/examples/jsm/lines/webgpu/Line2.js

@@ -1,14 +1,40 @@
+import { Line2NodeMaterial } from 'three/webgpu';
+
 import { LineSegments2 } from './LineSegments2.js';
 import { LineGeometry } from '../LineGeometry.js';
 
-import { Line2NodeMaterial } from 'three';
-
+/**
+ * A polyline drawn between vertices.
+ *
+ * This adds functionality beyond {@link Line}, like arbitrary line width and changing width to
+ * be in world units.It extends {@link LineSegments2}, simplifying constructing segments from a
+ * chain of points.
+ *
+ * This module can only be used with {@link WebGPURenderer}. When using {@link WebGLRenderer},
+ * import the class from `lines/Line2.js`.
+ *
+ * @augments LineSegments2
+ * @three_import import { Line2 } from 'three/addons/lines/webgpu/Line2.js';
+ */
 class Line2 extends LineSegments2 {
 
+	/**
+	 * Constructs a new wide line.
+	 *
+	 * @param {LineGeometry} [geometry] - The line geometry.
+	 * @param {Line2NodeMaterial} [material] - The line material.
+	 */
 	constructor( geometry = new LineGeometry(), material = new Line2NodeMaterial( { color: Math.random() * 0xffffff } ) ) {
 
 		super( geometry, material );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLine2 = true;
 
 		this.type = 'Line2';

package/examples/jsm/lines/webgpu/LineSegments2.js

@@ -9,11 +9,10 @@ import {
 	Sphere,
 	Vector3,
 	Vector4,
-	Line2NodeMaterial
-} from 'three';
-import { LineSegmentsGeometry } from '../../lines/LineSegmentsGeometry.js';
-
-const _viewport = new Vector4();
+	Line2NodeMaterial,
+	Vector2
+} from 'three/webgpu';
+import { LineSegmentsGeometry } from '../LineSegmentsGeometry.js';
 
 const _start = new Vector3();
 const _end = new Vector3();
@@ -30,6 +29,7 @@ const _closestPoint = new Vector3();
 const _box = new Box3();
 const _sphere = new Sphere();
 const _clipToWorldVector = new Vector4();
+const _viewport = new Vector4();
 
 let _ray, _lineWidth;
 
@@ -94,10 +94,10 @@ function raycastWorldUnits( lineSegments, intersects ) {
 function raycastScreenSpace( lineSegments, camera, intersects ) {
 
 	const projectionMatrix = camera.projectionMatrix;
-	const material = lineSegments.material;
-	const resolution = material.resolution;
 	const matrixWorld = lineSegments.matrixWorld;
 
+	const resolution = lineSegments._resolution;
+
 	const geometry = lineSegments.geometry;
 	const instanceStart = geometry.attributes.instanceStart;
 	const instanceEnd = geometry.attributes.instanceEnd;
@@ -224,22 +224,57 @@ function raycastScreenSpace( lineSegments, camera, intersects ) {
 
 }
 
+/**
+ * A series of lines drawn between pairs of vertices.
+ *
+ * This adds functionality beyond {@link LineSegments}, like arbitrary line width and changing width
+ * to be in world units. {@link Line2} extends this object, forming a polyline instead of individual
+ * segments.
+ *
+ * This module can only be used with {@link WebGPURenderer}. When using {@link WebGLRenderer},
+ * import the class from `lines/LineSegments2.js`.
+ *
+ * @augments Mesh
+ * @three_import import { LineSegments2 } from 'three/addons/lines/webgpu/LineSegments2.js';
+ */
 class LineSegments2 extends Mesh {
 
+	/**
+	 * Constructs a new wide line.
+	 *
+	 * @param {LineSegmentsGeometry} [geometry] - The line geometry.
+	 * @param {Line2NodeMaterial} [material] - The line material.
+	 */
 	constructor( geometry = new LineSegmentsGeometry(), material = new Line2NodeMaterial( { color: Math.random() * 0xffffff } ) ) {
 
 		super( geometry, material );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLineSegments2 = true;
 
 		this.type = 'LineSegments2';
 
-	}
+		this._resolution = new Vector2();
 
-	// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
+	}
 
+	/**
+	 * Computes an array of distance values which are necessary for rendering dashed lines.
+	 * For each vertex in the geometry, the method calculates the cumulative length from the
+	 * current point to the very beginning of the line.
+	 *
+	 * @return {LineSegments2} A reference to this instance.
+	 */
 	computeLineDistances() {
 
+		// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
+
 		const geometry = this.geometry;
 
 		const instanceStart = geometry.attributes.instanceStart;
@@ -265,6 +300,19 @@ class LineSegments2 extends Mesh {
 
 	}
 
+	onBeforeRender( renderer ) {
+
+		renderer.getViewport( _viewport );
+		this._resolution.set( _viewport.z, _viewport.w );
+
+	}
+
+	/**
+	 * Computes intersection points between a casted ray and this instance.
+	 *
+	 * @param {Raycaster} raycaster - The raycaster.
+	 * @param {Array<Object>} intersects - The target array that holds the intersection points.
+	 */
 	raycast( raycaster, intersects ) {
 
 		const worldUnits = this.material.worldUnits;
@@ -304,7 +352,7 @@ class LineSegments2 extends Mesh {
 		} else {
 
 			const distanceToSphere = Math.max( camera.near, _sphere.distanceToPoint( _ray.origin ) );
-			sphereMargin = getWorldSpaceHalfWidth( camera, distanceToSphere, material.resolution );
+			sphereMargin = getWorldSpaceHalfWidth( camera, distanceToSphere, this._resolution );
 
 		}
 
@@ -334,7 +382,7 @@ class LineSegments2 extends Mesh {
 		} else {
 
 			const distanceToBox = Math.max( camera.near, _box.distanceToPoint( _ray.origin ) );
-			boxMargin = getWorldSpaceHalfWidth( camera, distanceToBox, material.resolution );
+			boxMargin = getWorldSpaceHalfWidth( camera, distanceToBox, this._resolution );
 
 		}
 
@@ -358,19 +406,6 @@ class LineSegments2 extends Mesh {
 
 	}
 
-	onBeforeRender( renderer ) {
-
-		const uniforms = this.material.uniforms;
-
-		if ( uniforms && uniforms.resolution ) {
-
-			renderer.getViewport( _viewport );
-			this.material.uniforms.resolution.value.set( _viewport.z, _viewport.w );
-
-		}
-
-	}
-
 }
 
 export { LineSegments2 };

package/examples/jsm/lines/webgpu/Wireframe.js

@@ -0,0 +1,86 @@
+import {
+	InstancedInterleavedBuffer,
+	InterleavedBufferAttribute,
+	Line2NodeMaterial,
+	Mesh,
+	Vector3
+} from 'three/webgpu';
+
+import { LineSegmentsGeometry } from '../LineSegmentsGeometry.js';
+
+const _start = new Vector3();
+const _end = new Vector3();
+
+/**
+ * A class for creating wireframes based on wide lines.
+ *
+ * This module can only be used with {@link WebGPURenderer}. When using {@link WebGLRenderer},
+ * import the class from `lines/Wireframe.js`.
+ *
+ * @augments Mesh
+ * @three_import import { Wireframe } from 'three/addons/lines/webgpu/Wireframe.js';
+ */
+class Wireframe extends Mesh {
+
+	/**
+	 * Constructs a new wireframe.
+	 *
+	 * @param {LineSegmentsGeometry} [geometry] - The line geometry.
+	 * @param {Line2NodeMaterial} [material] - The line material.
+	 */
+	constructor( geometry = new LineSegmentsGeometry(), material = new Line2NodeMaterial( { color: Math.random() * 0xffffff } ) ) {
+
+		super( geometry, material );
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isWireframe = true;
+
+		this.type = 'Wireframe';
+
+	}
+
+	/**
+	 * Computes an array of distance values which are necessary for rendering dashed lines.
+	 * For each vertex in the geometry, the method calculates the cumulative length from the
+	 * current point to the very beginning of the line.
+	 *
+	 * @return {Wireframe} A reference to this instance.
+	 */
+	computeLineDistances() {
+
+		// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
+
+		const geometry = this.geometry;
+
+		const instanceStart = geometry.attributes.instanceStart;
+		const instanceEnd = geometry.attributes.instanceEnd;
+		const lineDistances = new Float32Array( 2 * instanceStart.count );
+
+		for ( let i = 0, j = 0, l = instanceStart.count; i < l; i ++, j += 2 ) {
+
+			_start.fromBufferAttribute( instanceStart, i );
+			_end.fromBufferAttribute( instanceEnd, i );
+
+			lineDistances[ j ] = ( j === 0 ) ? 0 : lineDistances[ j - 1 ];
+			lineDistances[ j + 1 ] = lineDistances[ j ] + _start.distanceTo( _end );
+
+		}
+
+		const instanceDistanceBuffer = new InstancedInterleavedBuffer( lineDistances, 2, 1 ); // d0, d1
+
+		geometry.setAttribute( 'instanceDistanceStart', new InterleavedBufferAttribute( instanceDistanceBuffer, 1, 0 ) ); // d0
+		geometry.setAttribute( 'instanceDistanceEnd', new InterleavedBufferAttribute( instanceDistanceBuffer, 1, 1 ) ); // d1
+
+		return this;
+
+	}
+
+}
+
+export { Wireframe };

package/examples/jsm/loaders/3DMLoader.js

@@ -23,19 +23,47 @@ import {
 	SpotLight,
 	Sprite,
 	SpriteMaterial,
-	TextureLoader
+	TextureLoader,
+	EquirectangularReflectionMapping
 } from 'three';
 
 import { EXRLoader } from '../loaders/EXRLoader.js';
 
 const _taskCache = new WeakMap();
 
+/**
+ * A loader for Rhinoceros 3D files and objects.
+ *
+ * Rhinoceros is a 3D modeler used to create, edit, analyze, document, render,
+ * animate, and translate NURBS curves, surfaces, breps, extrusions, point clouds,
+ * as well as polygon meshes and SubD objects. `rhino3dm.js` is compiled to WebAssembly
+ * from the open source geometry library `openNURBS`. The loader currently uses
+ * `rhino3dm.js 8.4.0`.
+ *
+ * ```js
+ * const loader = new Rhino3dmLoader();
+ * loader.setLibraryPath( 'https://cdn.jsdelivr.net/npm/rhino3dm@8.0.1' );
+ *
+ * const object = await loader.loadAsync( 'models/3dm/Rhino_Logo.3dm' );
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
+ * @three_import import { Rhino3dmLoader } from 'three/addons/loaders/3DMLoader.js';
+ */
 class Rhino3dmLoader extends Loader {
 
+	/**
+	 * Constructs a new Rhino 3DM loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		// internals
+
 		this.libraryPath = '';
 		this.libraryPending = null;
 		this.libraryBinary = null;
@@ -54,6 +82,12 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Path to a folder containing the JS and WASM libraries.
+	 *
+	 * @param {string} path - The library path to set.
+	 * @return {Rhino3dmLoader} A reference to this loader.
+	 */
 	setLibraryPath( path ) {
 
 		this.libraryPath = path;
@@ -62,6 +96,14 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Sets the maximum number of Web Workers to be used during decoding.
+	 * A lower limit may be preferable if workers are also for other
+	 * tasks in the application.
+	 *
+	 * @param {number} workerLimit - The worker limit.
+	 * @return {Rhino3dmLoader} A reference to this loader.
+	 */
 	setWorkerLimit( workerLimit ) {
 
 		this.workerLimit = workerLimit;
@@ -70,6 +112,15 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded 3DM 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(Object3D)} 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 loader = new FileLoader( this.manager );
@@ -105,12 +156,22 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Prints debug messages to the browser console.
+	 */
 	debug() {
 
 		console.log( 'Task load: ', this.workerPool.map( ( worker ) => worker._taskLoad ) );
 
 	}
 
+	/**
+	 * Decodes the 3DM asset data with a Web Worker.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw 3DM asset data as an array buffer.
+	 * @param {string} url - The asset URL.
+	 * @return {Promise<Object3D>} A Promise that resolved with the decoded 3D object.
+	 */
 	decodeObjects( buffer, url ) {
 
 		let worker;
@@ -170,6 +231,14 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given 3DM data and passes the loaded 3DM asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {ArrayBuffer} data - The raw 3DM asset data as an array buffer.
+	 * @param {function(Object3D)} onLoad - Executed when the loading process has been finished.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	parse( data, onLoad, onError ) {
 
 		this.decodeObjects( data, '' )
@@ -439,7 +508,7 @@ class Rhino3dmLoader extends Loader {
 
 			new EXRLoader().load( renderEnvironment.image, function ( texture ) {
 
-				texture.mapping = THREE.EquirectangularReflectionMapping;
+				texture.mapping = EquirectangularReflectionMapping;
 				mat.envMap = texture;
 
 			} );
@@ -629,7 +698,7 @@ class Rhino3dmLoader extends Loader {
 
 				geometry = loader.parse( obj.geometry );
 
-				if ( geometry.attributes.hasOwnProperty( 'color' ) ) {
+				if ( geometry.hasAttribute( 'color' ) ) {
 
 					material = new PointsMaterial( { vertexColors: true, sizeAttenuation: false, size: 2 } );
 
@@ -672,7 +741,7 @@ class Rhino3dmLoader extends Loader {
 				}
 
 
-				if ( geometry.attributes.hasOwnProperty( 'color' ) ) {
+				if ( geometry.hasAttribute( 'color' ) ) {
 
 					mat.vertexColors = true;
 
@@ -745,6 +814,7 @@ class Rhino3dmLoader extends Loader {
 
 				const texture = new CanvasTexture( ctx.canvas );
 				texture.minFilter = LinearFilter;
+				texture.generateMipmaps = false;
 				texture.wrapS = ClampToEdgeWrapping;
 				texture.wrapT = ClampToEdgeWrapping;
 
@@ -961,6 +1031,10 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the loader is no longer required.
+	 */
 	dispose() {
 
 		for ( let i = 0; i < this.workerPool.length; ++ i ) {
@@ -971,8 +1045,6 @@ class Rhino3dmLoader extends Loader {
 
 		this.workerPool.length = 0;
 
-		return this;
-
 	}
 
 }