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

package/examples/jsm/webxr/OculusHandModel.js

@@ -4,18 +4,78 @@ import { XRHandMeshModel } from './XRHandMeshModel.js';
 const TOUCH_RADIUS = 0.01;
 const POINTING_JOINT = 'index-finger-tip';
 
+/**
+ * Represents an Oculus hand model.
+ *
+ * @augments Object3D
+ * @three_import import { OculusHandModel } from 'three/addons/webxr/OculusHandModel.js';
+ */
 class OculusHandModel extends Object3D {
 
+	/**
+	 * Constructs a new Oculus hand model.
+	 *
+	 * @param {Group} controller - The hand controller.
+	 * @param {?Loader} [loader=null] - A loader that is used to load hand models.
+	 * @param {?Function} [onLoad=null] - A callback that is executed when a hand model has been loaded.
+	 */
 	constructor( controller, loader = null, onLoad = null ) {
 
 		super();
 
+		/**
+		 * The hand controller.
+		 *
+		 * @type {Group}
+		 */
 		this.controller = controller;
+
+		/**
+		 * The motion controller.
+		 *
+		 * @type {?MotionController}
+		 * @default null
+		 */
 		this.motionController = null;
+
+		/**
+		 * The model's environment map.
+		 *
+		 * @type {?Texture}
+		 * @default null
+		 */
 		this.envMap = null;
+
+		/**
+		 * A loader that is used to load hand models.
+		 *
+		 * @type {?Loader}
+		 * @default null
+		 */
 		this.loader = loader;
+
+		/**
+		 * A callback that is executed when a hand model has been loaded.
+		 *
+		 * @type {?Function}
+		 * @default null
+		 */
 		this.onLoad = onLoad;
 
+		/**
+		 * The path to the model repository.
+		 *
+		 * @type {?string}
+		 * @default null
+		 */
+		this.path = null;
+
+		/**
+		 * The model mesh.
+		 *
+		 * @type {Mesh}
+		 * @default null
+		 */
 		this.mesh = null;
 
 		controller.addEventListener( 'connected', ( event ) => {
@@ -41,6 +101,12 @@ class OculusHandModel extends Object3D {
 
 	}
 
+	/**
+	 * Overwritten with a custom implementation. Makes sure the motion controller updates the mesh.
+	 *
+	 * @param {boolean} [force=false] - When set to `true`, a recomputation of world matrices is forced even
+	 * when {@link Object3D#matrixWorldAutoUpdate} is set to `false`.
+	 */
 	updateMatrixWorld( force ) {
 
 		super.updateMatrixWorld( force );
@@ -53,6 +119,11 @@ class OculusHandModel extends Object3D {
 
 	}
 
+	/**
+	 * Returns the pointer position which is the position of the index finger tip.
+	 *
+	 * @return {?Vector3} The pointer position. Returns `null` if not index finger tip joint was found.
+	 */
 	getPointerPosition() {
 
 		const indexFingerTip = this.controller.joints[ POINTING_JOINT ];
@@ -68,6 +139,13 @@ class OculusHandModel extends Object3D {
 
 	}
 
+	/**
+	 * Returns `true` if the current pointer position (the index finger tip) intersections
+	 * with the given box object.
+	 *
+	 *  @param {Mesh} boxObject - The box object.
+	 * @return {boolean} Whether an intersection was found or not.
+	 */
 	intersectBoxObject( boxObject ) {
 
 		const pointerPosition = this.getPointerPosition();
@@ -85,6 +163,12 @@ class OculusHandModel extends Object3D {
 
 	}
 
+	/**
+	 * Executed actions depending on the interaction state with
+	 * the given button.
+	 *
+	 *  @param {Object} button - The button.
+	 */
 	checkButton( button ) {
 
 		if ( this.intersectBoxObject( button ) ) {

package/examples/jsm/webxr/OculusHandPointerModel.js

@@ -1,4 +1,4 @@
-import * as THREE from 'three';
+import { BufferGeometry, Float32BufferAttribute, Matrix4, Mesh, MeshBasicMaterial, Object3D, Raycaster, SphereGeometry, Vector3 } from 'three';
 
 const PINCH_MAX = 0.05;
 const PINCH_THRESHOLD = 0.02;
@@ -13,19 +13,42 @@ const POINTER_LENGTH = 0.035;
 const POINTER_SEGMENTS = 16;
 const POINTER_RINGS = 12;
 const POINTER_HEMISPHERE_ANGLE = 110;
-const YAXIS = /* @__PURE__ */ new THREE.Vector3( 0, 1, 0 );
-const ZAXIS = /* @__PURE__ */ new THREE.Vector3( 0, 0, 1 );
+const YAXIS = /* @__PURE__ */ new Vector3( 0, 1, 0 );
+const ZAXIS = /* @__PURE__ */ new Vector3( 0, 0, 1 );
 
 const CURSOR_RADIUS = 0.02;
 const CURSOR_MAX_DISTANCE = 1.5;
 
-class OculusHandPointerModel extends THREE.Object3D {
-
+/**
+ * Represents an Oculus hand pointer model.
+ *
+ * @augments Object3D
+ * @three_import import { OculusHandPointerModel } from 'three/addons/webxr/OculusHandPointerModel.js';
+ */
+class OculusHandPointerModel extends Object3D {
+
+	/**
+	 * Constructs a new Oculus hand model.
+	 *
+	 * @param {Group} hand - The hand controller.
+	 * @param {Group} controller - The WebXR controller in target ray space.
+	 */
 	constructor( hand, controller ) {
 
 		super();
 
+		/**
+		 * The hand controller.
+		 *
+		 * @type {Group}
+		 */
 		this.hand = hand;
+
+		/**
+		 * The WebXR controller in target ray space.
+		 *
+		 * @type {Group}
+		 */
 		this.controller = controller;
 
 		// Unused
@@ -33,15 +56,61 @@ class OculusHandPointerModel extends THREE.Object3D {
 		this.envMap = null;
 		this.mesh = null;
 
+		/**
+		 * The pointer geometry.
+		 *
+		 * @type {?BufferGeometry}
+		 * @default null
+		 */
 		this.pointerGeometry = null;
+
+		/**
+		 * The pointer mesh.
+		 *
+		 * @type {?Mesh}
+		 * @default null
+		 */
 		this.pointerMesh = null;
+
+		/**
+		 * The pointer object that holds the pointer mesh.
+		 *
+		 * @type {?Object3D}
+		 * @default null
+		 */
 		this.pointerObject = null;
 
+		/**
+		 * Whether the model is pinched or not.
+		 *
+		 * @type {?boolean}
+		 * @default false
+		 */
 		this.pinched = false;
+
+		/**
+		 * Whether the model is attached or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.attached = false;
 
+		/**
+		 * The cursor object.
+		 *
+		 * @type {?Mesh}
+		 * @default null
+		 */
 		this.cursorObject = null;
 
+		/**
+		 * The internal raycaster used for detecting
+		 * intersections.
+		 *
+		 * @type {?Raycaster}
+		 * @default null
+		 */
 		this.raycaster = null;
 
 		this._onConnected = this._onConnected.bind( this );
@@ -96,7 +165,7 @@ class OculusHandPointerModel extends THREE.Object3D {
 
 		const vertices = this.pointerGeometry.attributes.position.array;
 		// first ring for front face
-		const frontFaceBase = new THREE.Vector3(
+		const frontFaceBase = new Vector3(
 			POINTER_FRONT_RADIUS,
 			0,
 			- 1 * ( POINTER_LENGTH - rearRadius )
@@ -104,7 +173,7 @@ class OculusHandPointerModel extends THREE.Object3D {
 		this._drawVerticesRing( vertices, frontFaceBase, 0 );
 
 		// rings for rear hemisphere
-		const rearBase = new THREE.Vector3(
+		const rearBase = new Vector3(
 			Math.sin( ( Math.PI * POINTER_HEMISPHERE_ANGLE ) / 180 ) * rearRadius,
 			Math.cos( ( Math.PI * POINTER_HEMISPHERE_ANGLE ) / 180 ) * rearRadius,
 			0
@@ -122,7 +191,7 @@ class OculusHandPointerModel extends THREE.Object3D {
 		// front and rear face center vertices
 		const frontCenterIndex = POINTER_SEGMENTS * ( 1 + POINTER_RINGS );
 		const rearCenterIndex = POINTER_SEGMENTS * ( 1 + POINTER_RINGS ) + 1;
-		const frontCenter = new THREE.Vector3(
+		const frontCenter = new Vector3(
 			0,
 			0,
 			- 1 * ( POINTER_LENGTH - rearRadius )
@@ -130,19 +199,22 @@ class OculusHandPointerModel extends THREE.Object3D {
 		vertices[ frontCenterIndex * 3 ] = frontCenter.x;
 		vertices[ frontCenterIndex * 3 + 1 ] = frontCenter.y;
 		vertices[ frontCenterIndex * 3 + 2 ] = frontCenter.z;
-		const rearCenter = new THREE.Vector3( 0, 0, rearRadius );
+		const rearCenter = new Vector3( 0, 0, rearRadius );
 		vertices[ rearCenterIndex * 3 ] = rearCenter.x;
 		vertices[ rearCenterIndex * 3 + 1 ] = rearCenter.y;
 		vertices[ rearCenterIndex * 3 + 2 ] = rearCenter.z;
 
 		this.pointerGeometry.setAttribute(
 			'position',
-			new THREE.Float32BufferAttribute( vertices, 3 )
+			new Float32BufferAttribute( vertices, 3 )
 		);
 		// verticesNeedUpdate = true;
 
 	}
 
+	/**
+	 * Creates a pointer mesh and adds it to this model.
+	 */
 	createPointer() {
 
 		let i, j;
@@ -151,11 +223,11 @@ class OculusHandPointerModel extends THREE.Object3D {
 		).fill( 0 );
 		// const vertices = [];
 		const indices = [];
-		this.pointerGeometry = new THREE.BufferGeometry();
+		this.pointerGeometry = new BufferGeometry();
 
 		this.pointerGeometry.setAttribute(
 			'position',
-			new THREE.Float32BufferAttribute( vertices, 3 )
+			new Float32BufferAttribute( vertices, 3 )
 		);
 
 		this._updatePointerVertices( POINTER_REAR_RADIUS );
@@ -213,27 +285,27 @@ class OculusHandPointerModel extends THREE.Object3D {
 			POINTER_SEGMENTS * POINTER_RINGS
 		);
 
-		const material = new THREE.MeshBasicMaterial();
+		const material = new MeshBasicMaterial();
 		material.transparent = true;
 		material.opacity = POINTER_OPACITY_MIN;
 
 		this.pointerGeometry.setIndex( indices );
 
-		this.pointerMesh = new THREE.Mesh( this.pointerGeometry, material );
+		this.pointerMesh = new Mesh( this.pointerGeometry, material );
 
 		this.pointerMesh.position.set( 0, 0, - 1 * POINTER_REAR_RADIUS );
-		this.pointerObject = new THREE.Object3D();
+		this.pointerObject = new Object3D();
 		this.pointerObject.add( this.pointerMesh );
 
-		this.raycaster = new THREE.Raycaster();
+		this.raycaster = new Raycaster();
 
 		// create cursor
-		const cursorGeometry = new THREE.SphereGeometry( CURSOR_RADIUS, 10, 10 );
-		const cursorMaterial = new THREE.MeshBasicMaterial();
+		const cursorGeometry = new SphereGeometry( CURSOR_RADIUS, 10, 10 );
+		const cursorMaterial = new MeshBasicMaterial();
 		cursorMaterial.transparent = true;
 		cursorMaterial.opacity = POINTER_OPACITY_MIN;
 
-		this.cursorObject = new THREE.Mesh( cursorGeometry, cursorMaterial );
+		this.cursorObject = new Mesh( cursorGeometry, cursorMaterial );
 		this.pointerObject.add( this.cursorObject );
 
 		this.add( this.pointerObject );
@@ -248,7 +320,7 @@ class OculusHandPointerModel extends THREE.Object3D {
 		if ( this.raycaster ) {
 
 			const pointerMatrix = this.pointerObject.matrixWorld;
-			const tempMatrix = new THREE.Matrix4();
+			const tempMatrix = new Matrix4();
 			tempMatrix.identity().extractRotation( pointerMatrix );
 			this.raycaster.ray.origin.setFromMatrixPosition( pointerMatrix );
 			this.raycaster.ray.direction.set( 0, 0, - 1 ).applyMatrix4( tempMatrix );
@@ -320,6 +392,12 @@ class OculusHandPointerModel extends THREE.Object3D {
 
 	}
 
+	/**
+	 * Overwritten with a custom implementation. Makes sure the internal pointer and raycaster are updated.
+	 *
+	 * @param {boolean} [force=false] - When set to `true`, a recomputation of world matrices is forced even
+	 * when {@link Object3D#matrixWorldAutoUpdate} is set to `false`.
+	 */
 	updateMatrixWorld( force ) {
 
 		super.updateMatrixWorld( force );
@@ -332,24 +410,47 @@ class OculusHandPointerModel extends THREE.Object3D {
 
 	}
 
+	/**
+	 * Returns `true` is the model is pinched.
+	 *
+	 * @return {boolean} Whether the model is pinched or not.
+	 */
 	isPinched() {
 
 		return this.pinched;
 
 	}
 
+	/**
+	 * Sets the attached state.
+	 *
+	 * @param {boolean} attached - Whether the model is attached or not.
+	 */
 	setAttached( attached ) {
 
 		this.attached = attached;
 
 	}
 
+	/**
+	 * Returns `true` is the model is attached.
+	 *
+	 * @return {boolean} Whether the model is attached or not.
+	 */
 	isAttached() {
 
 		return this.attached;
 
 	}
 
+	/**
+	 * Performs an intersection test with the model's raycaster and the given object.
+	 *
+	 * @param {Object3D} object - The 3D object to check for intersection with the ray.
+	 * @param {boolean} [recursive=true] - If set to `true`, it also checks all descendants.
+	 * Otherwise it only checks intersection with the object.
+	 * @return {Array<Raycaster~Intersection>} An array holding the intersection points.
+	 */
 	intersectObject( object, recursive = true ) {
 
 		if ( this.raycaster ) {
@@ -360,6 +461,14 @@ class OculusHandPointerModel extends THREE.Object3D {
 
 	}
 
+	/**
+	 * Performs an intersection test with the model's raycaster and the given objects.
+	 *
+	 * @param {Array<Object3D>} objects - The 3D objects to check for intersection with the ray.
+	 * @param {boolean} [recursive=true] - If set to `true`, it also checks all descendants.
+	 * Otherwise it only checks intersection with the object.
+	 * @return {Array<Raycaster~Intersection>} An array holding the intersection points.
+	 */
 	intersectObjects( objects, recursive = true ) {
 
 		if ( this.raycaster ) {
@@ -370,12 +479,20 @@ class OculusHandPointerModel extends THREE.Object3D {
 
 	}
 
+	/**
+	 * Checks for intersections between the model's raycaster and the given objects. The method
+	 * updates the cursor object to the intersection point.
+	 *
+	 * @param {Array<Object3D>} objects - The 3D objects to check for intersection with the ray.
+	 * @param {boolean} [recursive=false] - If set to `true`, it also checks all descendants.
+	 * Otherwise it only checks intersection with the object.
+	 */
 	checkIntersections( objects, recursive = false ) {
 
 		if ( this.raycaster && ! this.attached ) {
 
 			const intersections = this.raycaster.intersectObjects( objects, recursive );
-			const direction = new THREE.Vector3( 0, 0, - 1 );
+			const direction = new Vector3( 0, 0, - 1 );
 			if ( intersections.length > 0 ) {
 
 				const intersection = intersections[ 0 ];
@@ -392,9 +509,14 @@ class OculusHandPointerModel extends THREE.Object3D {
 
 	}
 
+	/**
+	 * Sets the cursor to the given distance.
+	 *
+	 * @param {number} distance - The distance to set the cursor to.
+	 */
 	setCursor( distance ) {
 
-		const direction = new THREE.Vector3( 0, 0, - 1 );
+		const direction = new Vector3( 0, 0, - 1 );
 		if ( this.raycaster && ! this.attached ) {
 
 			this.cursorObject.position.copy( direction.multiplyScalar( distance ) );
@@ -403,6 +525,10 @@ class OculusHandPointerModel extends THREE.Object3D {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		this._onDisconnected();

package/examples/jsm/webxr/Text2D.js

@@ -1,5 +1,19 @@
-import * as THREE from 'three';
+import { DoubleSide, Mesh, MeshBasicMaterial, PlaneGeometry, Texture } from 'three';
 
+/**
+ * @module Text2D
+ * @three_import import * as Text2D from 'three/addons/webxr/Text2D.js';
+ */
+
+/**
+ * A helper function for creating a simple plane mesh
+ * that can be used as a text label. The mesh's material
+ * holds a canvas texture that displays the given message.
+ *
+ * @param {string} message - The message to display.
+ * @param {number} height - The labels height.
+ * @return {Mesh} The plane mesh representing a text label.
+ */
 function createText( message, height ) {
 
 	const canvas = document.createElement( 'canvas' );
@@ -17,20 +31,20 @@ function createText( message, height ) {
 	context.fillStyle = '#ffffff';
 	context.fillText( message, textWidth / 2, textHeight / 2 );
 
-	const texture = new THREE.Texture( canvas );
+	const texture = new Texture( canvas );
 	texture.needsUpdate = true;
 
-	const material = new THREE.MeshBasicMaterial( {
+	const material = new MeshBasicMaterial( {
 		color: 0xffffff,
-		side: THREE.DoubleSide,
+		side: DoubleSide,
 		map: texture,
 		transparent: true,
 	} );
-	const geometry = new THREE.PlaneGeometry(
+	const geometry = new PlaneGeometry(
 		( height * textWidth ) / textHeight,
 		height
 	);
-	const plane = new THREE.Mesh( geometry, material );
+	const plane = new Mesh( geometry, material );
 	return plane;
 
 }

package/examples/jsm/webxr/VRButton.js

@@ -1,5 +1,24 @@
+/**
+ * A utility class for creating a button that allows to initiate
+ * immersive VR sessions based on WebXR. The button can be created
+ * with a factory method and then appended ot the website's DOM.
+ *
+ * ```js
+ * document.body.appendChild( VRButton.createButton( renderer ) );
+ * ```
+ *
+ * @hideconstructor
+ * @three_import import { VRButton } from 'three/addons/webxr/VRButton.js';
+ */
 class VRButton {
 
+	/**
+	 * Constructs a new VR button.
+	 *
+	 * @param {WebGLRenderer|WebGPURenderer} renderer - The renderer.
+	 * @param {XRSessionInit} [sessionInit] - The a configuration object for the AR session.
+	 * @return {HTMLElement} The button or an error message if `immersive-ar` isn't supported.
+	 */
 	static createButton( renderer, sessionInit = {} ) {
 
 		const button = document.createElement( 'button' );
@@ -207,6 +226,11 @@ class VRButton {
 
 	}
 
+	/**
+	 * Registers a `sessiongranted` event listener. When a session is granted, the {@link VRButton#xrSessionIsGranted}
+	 * flag will evaluate to `true`. This method is automatically called by the module itself so there
+	 * should be no need to use it on app level.
+	 */
 	static registerSessionGrantedListener() {
 
 		if ( typeof navigator !== 'undefined' && 'xr' in navigator ) {
@@ -227,6 +251,13 @@ class VRButton {
 
 }
 
+/**
+ * Whether a XR session has been granted or not.
+ *
+ * @static
+ * @type {boolean}
+ * @default false
+ */
 VRButton.xrSessionIsGranted = false;
 VRButton.registerSessionGrantedListener();
 

package/examples/jsm/webxr/XRButton.js

@@ -1,5 +1,28 @@
+/**
+ * A utility class for creating a button that allows to initiate
+ * immersive XR sessions based on WebXR. The button can be created
+ * with a factory method and then appended ot the website's DOM.
+ *
+ * ```js
+ * document.body.appendChild( XRButton.createButton( renderer ) );
+ * ```
+ *
+ * Compared to {@link ARButton} and {@link VRButton}, this class will
+ * try to offer an immersive AR session first. If the device does not
+ * support this type of session, it uses an immersive VR session.
+ *
+ * @hideconstructor
+ * @three_import import { XRButton } from 'three/addons/webxr/XRButton.js';
+ */
 class XRButton {
 
+	/**
+	 * Constructs a new XR button.
+	 *
+	 * @param {WebGLRenderer|WebGPURenderer} renderer - The renderer.
+	 * @param {XRSessionInit} [sessionInit] - The a configuration object for the AR session.
+	 * @return {HTMLElement} The button or an error message if WebXR isn't supported.
+	 */
 	static createButton( renderer, sessionInit = {} ) {
 
 		const button = document.createElement( 'button' );