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

package/examples/jsm/math/OBB.js

@@ -37,18 +37,53 @@ const matrix = new Matrix4();
 const inverse = new Matrix4();
 const localRay = new Ray();
 
-// OBB
-
+/**
+ * Represents an oriented bounding box (OBB) in 3D space.
+ *
+ * @three_import import { OBB } from 'three/addons/math/OBB.js';
+ */
 class OBB {
 
+	/**
+	 * Constructs a new OBB.
+	 *
+	 * @param {Vector3} [center] - The center of the OBB.
+	 * @param {Vector3} [halfSize] - Positive halfwidth extents of the OBB along each axis.
+	 * @param {Matrix3} [rotation] - The rotation of the OBB.
+	 */
 	constructor( center = new Vector3(), halfSize = new Vector3(), rotation = new Matrix3() ) {
 
+		/**
+		 * The center of the OBB.
+		 *
+		 * @type {Vector3}
+		 */
 		this.center = center;
+
+		/**
+		 * Positive halfwidth extents of the OBB along each axis.
+		 *
+		 * @type {Vector3}
+		 */
 		this.halfSize = halfSize;
+
+		/**
+		 * The rotation of the OBB.
+		 *
+		 * @type {Matrix3}
+		 */
 		this.rotation = rotation;
 
 	}
 
+	/**
+	 * Sets the OBBs components to the given values.
+	 *
+	 * @param {Vector3} [center] - The center of the OBB.
+	 * @param {Vector3} [halfSize] - Positive halfwidth extents of the OBB along each axis.
+	 * @param {Matrix3} [rotation] - The rotation of the OBB.
+	 * @return {OBB} A reference to this OBB.
+	 */
 	set( center, halfSize, rotation ) {
 
 		this.center = center;
@@ -59,6 +94,12 @@ class OBB {
 
 	}
 
+	/**
+	 * Copies the values of the given OBB to this instance.
+	 *
+	 * @param {OBB} obb - The OBB to copy.
+	 * @return {OBB} A reference to this OBB.
+	 */
 	copy( obb ) {
 
 		this.center.copy( obb.center );
@@ -69,23 +110,40 @@ class OBB {
 
 	}
 
+	/**
+	 * Returns a new OBB with copied values from this instance.
+	 *
+	 * @return {OBB} A clone of this instance.
+	 */
 	clone() {
 
 		return new this.constructor().copy( this );
 
 	}
 
-	getSize( result ) {
+	/**
+	 * Returns the size of this OBB.
+	 *
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {Vector3} The size.
+	 */
+	getSize( target ) {
 
-		return result.copy( this.halfSize ).multiplyScalar( 2 );
+		return target.copy( this.halfSize ).multiplyScalar( 2 );
 
 	}
 
 	/**
-	* Reference: Closest Point on OBB to Point in Real-Time Collision Detection
-	* by Christer Ericson (chapter 5.1.4)
-	*/
-	clampPoint( point, result ) {
+	 * Clamps the given point within the bounds of this OBB.
+	 *
+	 * @param {Vector3} point - The point that should be clamped within the bounds of this OBB.
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @returns {Vector3} - The clamped point.
+	 */
+	clampPoint( point, target ) {
+
+		// Reference: Closest Point on OBB to Point in Real-Time Collision Detection
+		// by Christer Ericson (chapter 5.1.4)
 
 		const halfSize = this.halfSize;
 
@@ -94,23 +152,29 @@ class OBB {
 
 		// start at the center position of the OBB
 
-		result.copy( this.center );
+		target.copy( this.center );
 
 		// project the target onto the OBB axes and walk towards that point
 
 		const x = MathUtils.clamp( v1.dot( xAxis ), - halfSize.x, halfSize.x );
-		result.add( xAxis.multiplyScalar( x ) );
+		target.add( xAxis.multiplyScalar( x ) );
 
 		const y = MathUtils.clamp( v1.dot( yAxis ), - halfSize.y, halfSize.y );
-		result.add( yAxis.multiplyScalar( y ) );
+		target.add( yAxis.multiplyScalar( y ) );
 
 		const z = MathUtils.clamp( v1.dot( zAxis ), - halfSize.z, halfSize.z );
-		result.add( zAxis.multiplyScalar( z ) );
+		target.add( zAxis.multiplyScalar( z ) );
 
-		return result;
+		return target;
 
 	}
 
+	/**
+	 * Returns `true` if the given point lies within this OBB.
+	 *
+	 * @param {Vector3} point - The point to test.
+	 * @returns {boolean} - Whether the given point lies within this OBB or not.
+	 */
 	containsPoint( point ) {
 
 		v1.subVectors( point, this.center );
@@ -124,12 +188,24 @@ class OBB {
 
 	}
 
+	/**
+	 * Returns `true` if the given AABB intersects this OBB.
+	 *
+	 * @param {Box3} box3 - The AABB to test.
+	 * @returns {boolean} - Whether the given AABB intersects this OBB or not.
+	 */
 	intersectsBox3( box3 ) {
 
 		return this.intersectsOBB( obb.fromBox3( box3 ) );
 
 	}
 
+	/**
+	 * Returns `true` if the given bounding sphere intersects this OBB.
+	 *
+	 * @param {Sphere} sphere - The bounding sphere to test.
+	 * @returns {boolean} - Whether the given bounding sphere intersects this OBB or not.
+	 */
 	intersectsSphere( sphere ) {
 
 		// find the point on the OBB closest to the sphere center
@@ -143,12 +219,17 @@ class OBB {
 	}
 
 	/**
-	* Reference: OBB-OBB Intersection in Real-Time Collision Detection
-	* by Christer Ericson (chapter 4.4.1)
-	*
-	*/
+	 * Returns `true` if the given OBB intersects this OBB.
+	 *
+	 * @param {OBB} obb - The OBB to test.
+	 * @param {number} [epsilon=Number.EPSILON] - A small value to prevent arithmetic errors.
+	 * @returns {boolean} - Whether the given OBB intersects this OBB or not.
+	 */
 	intersectsOBB( obb, epsilon = Number.EPSILON ) {
 
+		// Reference: OBB-OBB Intersection in Real-Time Collision Detection
+		// by Christer Ericson (chapter 4.4.1)
+
 		// prepare data structures (the code uses the same nomenclature like the reference)
 
 		a.c = this.center;
@@ -283,11 +364,16 @@ class OBB {
 	}
 
 	/**
-	* Reference: Testing Box Against Plane in Real-Time Collision Detection
-	* by Christer Ericson (chapter 5.2.3)
-	*/
+	 * Returns `true` if the given plane intersects this OBB.
+	 *
+	 * @param {Plane} plane - The plane to test.
+	 * @returns {boolean} Whether the given plane intersects this OBB or not.
+	 */
 	intersectsPlane( plane ) {
 
+		// Reference: Testing Box Against Plane in Real-Time Collision Detection
+		// by Christer Ericson (chapter 5.2.3)
+
 		this.rotation.extractBasis( xAxis, yAxis, zAxis );
 
 		// compute the projection interval radius of this OBB onto L(t) = this->center + t * p.normal;
@@ -307,10 +393,14 @@ class OBB {
 	}
 
 	/**
-	* Performs a ray/OBB intersection test and stores the intersection point
-	* to the given 3D vector. If no intersection is detected, *null* is returned.
-	*/
-	intersectRay( ray, result ) {
+	 * Performs a ray/OBB intersection test and stores the intersection point
+	 * in the given 3D vector.
+	 *
+	 * @param {Ray} ray - The ray to test.
+	 * @param {Vector3} target - The target vector that is used to store the method's result.
+	 * @return {?Vector3} The intersection point. If no intersection is detected, `null` is returned.
+	 */
+	intersectRay( ray, target ) {
 
 		// the idea is to perform the intersection test in the local space
 		// of the OBB.
@@ -330,11 +420,11 @@ class OBB {
 
 		// perform ray <-> AABB intersection test
 
-		if ( localRay.intersectBox( aabb, result ) ) {
+		if ( localRay.intersectBox( aabb, target ) ) {
 
 			// transform the intersection point back to world space
 
-			return result.applyMatrix4( matrix );
+			return target.applyMatrix4( matrix );
 
 		} else {
 
@@ -345,15 +435,23 @@ class OBB {
 	}
 
 	/**
-	* Performs a ray/OBB intersection test. Returns either true or false if
-	* there is a intersection or not.
-	*/
+	 * Returns `true` if the given ray intersects this OBB.
+	 *
+	 * @param {Ray} ray - The ray to test.
+	 * @returns {boolean} Whether the given ray intersects this OBB or not.
+	 */
 	intersectsRay( ray ) {
 
 		return this.intersectRay( ray, v1 ) !== null;
 
 	}
 
+	/**
+	 * Defines an OBB based on the given AABB.
+	 *
+	 * @param {Box3} box3 - The AABB to setup the OBB from.
+	 * @return {OBB} A reference of this OBB.
+	 */
 	fromBox3( box3 ) {
 
 		box3.getCenter( this.center );
@@ -366,6 +464,12 @@ class OBB {
 
 	}
 
+	/**
+	 * Returns `true` if the given OBB is equal to this OBB.
+	 *
+	 * @param {OBB} obb - The OBB to test.
+	 * @returns {boolean} Whether the given OBB is equal to this OBB or not.
+	 */
 	equals( obb ) {
 
 		return obb.center.equals( this.center ) &&
@@ -374,6 +478,14 @@ class OBB {
 
 	}
 
+	/**
+	 * Applies the given transformation matrix to this OBB. This method can be
+	 * used to transform the bounding volume with the world matrix of a 3D object
+	 * in order to keep both entities in sync.
+	 *
+	 * @param {Matrix4} matrix - The matrix to apply.
+	 * @return {OBB} A reference of this OBB.
+	 */
 	applyMatrix4( matrix ) {
 
 		const e = matrix.elements;

package/examples/jsm/math/Octree.js

@@ -17,8 +17,10 @@ const _point2 = new Vector3();
 const _plane = new Plane();
 const _line1 = new Line3();
 const _line2 = new Line3();
+const _box = new Box3();
 const _sphere = new Sphere();
 const _capsule = new Capsule();
+const _center = new Vector3();
 
 const _temp1 = new Vector3();
 const _temp2 = new Vector3();
@@ -81,19 +83,86 @@ function lineToLineClosestPoints( line1, line2, target1 = null, target2 = null )
 
 }
 
+/**
+ * An octree is a hierarchical tree data structure used to partition a three-dimensional
+ * space by recursively subdividing it into eight octants.
+ *
+ * This particular implementation can have up to sixteen levels and stores up to eight triangles
+ * in leaf nodes.
+ *
+ * `Octree` can be used in games to compute collision between the game world and colliders from
+ * the player or other dynamic 3D objects.
+ *
+ *
+ * ```js
+ * const octree = new Octree().fromGraphNode( scene );
+ * const result = octree.capsuleIntersect( playerCollider ); // collision detection
+ * ```
+ *
+ * @three_import import { Octree } from 'three/addons/math/Octree.js';
+ */
 class Octree {
 
+	/**
+	 * Constructs a new Octree.
+	 *
+	 * @param {Box3} [box] - The base box with enclose the entire Octree.
+	 */
 	constructor( box ) {
 
+		/**
+		 * The base box with enclose the entire Octree.
+		 *
+		 * @type {Box3}
+		 */
 		this.box = box;
+
+		/**
+		 * The bounds of the Octree. Compared to {@link Octree#box}, no
+		 * margin is applied.
+		 *
+		 * @type {Box3}
+		 */
 		this.bounds = new Box3();
 
+		/**
+		 * Can by used for layers configuration for refine testing.
+		 *
+		 * @type {Layers}
+		 */
+		this.layers = new Layers();
+
+		/**
+		 * The number of triangles a leaf can store before it is split.
+		 *
+		 * @type {number}
+		 * @default 8
+		 */
+		this.trianglesPerLeaf = 8;
+
+		/**
+		 * The maximum level of the Octree. It defines the maximum
+		 * hierarchical depth of the data structure.
+		 *
+		 * @type {number}
+		 * @default 16
+		 */
+		this.maxLevel = 16;
+
+		// private
+
 		this.subTrees = [];
 		this.triangles = [];
-		this.layers = new Layers();
 
 	}
 
+	/**
+	 * Adds the given triangle to the Octree. The triangle vertices are clamped if they exceed
+	 * the bounds of the Octree.
+	 *
+	 * @param {Triangle} triangle - The triangle to add.
+	 * @return {Octree} A reference to this Octree.
+	 */
 	addTriangle( triangle ) {
 
 		this.bounds.min.x = Math.min( this.bounds.min.x, triangle.a.x, triangle.b.x, triangle.c.x );
@@ -109,6 +178,11 @@ class Octree {
 
 	}
 
+	/**
+	 * Prepares {@link Octree#box} for the build.
+	 *
+	 * @return {Octree} A reference to this Octree.
+	 */
 	calcBox() {
 
 		this.box = this.bounds.clone();
@@ -122,6 +196,13 @@ class Octree {
 
 	}
 
+	/**
+	 * Splits the Octree. This method is used recursively when
+	 * building the Octree.
+	 *
+	 * @param {number} level - The current level.
+	 * @return {Octree} A reference to this Octree.
+	 */
 	split( level ) {
 
 		if ( ! this.box ) return;
@@ -169,7 +250,7 @@ class Octree {
 
 			const len = subTrees[ i ].triangles.length;
 
-			if ( len > 8 && level < 16 ) {
+			if ( len > this.trianglesPerLeaf && level < this.maxLevel ) {
 
 				subTrees[ i ].split( level + 1 );
 
@@ -187,6 +268,11 @@ class Octree {
 
 	}
 
+	/**
+	 * Builds the Octree.
+	 *
+	 * @return {Octree} A reference to this Octree.
+	 */
 	build() {
 
 		this.calcBox();
@@ -196,6 +282,12 @@ class Octree {
 
 	}
 
+	/**
+	 * Computes the triangles that potentially intersect with the given ray.
+	 *
+	 * @param {Ray} ray - The ray to test.
+	 * @param {Array<Triangle>} triangles - The target array that holds the triangles.
+	 */
 	getRayTriangles( ray, triangles ) {
 
 		for ( let i = 0; i < this.subTrees.length; i ++ ) {
@@ -219,10 +311,16 @@ class Octree {
 
 		}
 
-		return triangles;
-
 	}
 
+	/**
+	 * Computes the intersection between the given capsule and triangle.
+	 *
+	 * @param {Capsule} capsule - The capsule to test.
+	 * @param {Triangle} triangle - The triangle to test.
+	 * @return {Object|false} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	triangleCapsuleIntersect( capsule, triangle ) {
 
 		triangle.getPlane( _plane );
@@ -277,6 +375,69 @@ class Octree {
 
 	}
 
+	/**
+	 * Computes the intersection between the given bounding box and triangle.
+	 *
+	 * @param {Box3} box - The bounding box to test.
+	 * @param {Triangle} triangle - The triangle to test.
+	 * @return {Object|false} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
+	triangleBoxIntersect( box, triangle ) {
+
+		// cheap check
+
+		if ( Math.max( triangle.a.x, triangle.b.x, triangle.c.x ) < box.min.x ||
+				Math.min( triangle.a.x, triangle.b.x, triangle.c.x ) > box.max.x ||
+				Math.max( triangle.a.y, triangle.b.y, triangle.c.y ) < box.min.y ||
+				Math.min( triangle.a.y, triangle.b.y, triangle.c.y ) > box.max.y ||
+				Math.max( triangle.a.z, triangle.b.z, triangle.c.z ) < box.min.z ||
+				Math.min( triangle.a.z, triangle.b.z, triangle.c.z ) > box.max.z ) {
+
+			return false;
+
+		}
+
+		// expensive check
+
+		if ( ! box.intersectsTriangle( triangle ) ) return false;
+
+		// there is an intersection, now compute collision data
+
+		triangle.getPlane( _plane );
+
+		// determine which corner of the box is "deepest" into the plane
+
+		_v1.x = ( _plane.normal.x > 0 ) ? box.min.x : box.max.x;
+		_v1.y = ( _plane.normal.y > 0 ) ? box.min.y : box.max.y;
+		_v1.z = ( _plane.normal.z > 0 ) ? box.min.z : box.max.z;
+
+		// Calculate the distance from the plane to that corner (the distance will be negative
+		// because of the intersection)
+
+		const distance = _plane.distanceToPoint( _v1 );
+
+		const intersection = {
+			depth: - distance, // Flip sign so depth is positive
+			normal: _plane.normal.clone(),
+			point: _v1.clone()
+		};
+
+		// project the point onto the triangle surface
+		intersection.point.addScaledVector( intersection.normal, distance );
+
+		return intersection;
+
+	}
+
+	/**
+	 * Computes the intersection between the given sphere and triangle.
+	 *
+	 * @param {Sphere} sphere - The sphere to test.
+	 * @param {Triangle} triangle - The triangle to test.
+	 * @return {Object|false} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	triangleSphereIntersect( sphere, triangle ) {
 
 		triangle.getPlane( _plane );
@@ -319,6 +480,12 @@ class Octree {
 
 	}
 
+	/**
+	 * Computes the triangles that potentially intersect with the given bounding sphere.
+	 *
+	 * @param {Sphere} sphere - The sphere to test.
+	 * @param {Array<Triangle>} triangles - The target array that holds the triangles.
+	 */
 	getSphereTriangles( sphere, triangles ) {
 
 		for ( let i = 0; i < this.subTrees.length; i ++ ) {
@@ -345,6 +512,44 @@ class Octree {
 
 	}
 
+	/**
+	 * Computes the triangles that potentially intersect with the given bounding box.
+	 *
+	 * @param {Box3} box - The bounding box.
+	 * @param {Array<Triangle>} triangles - The target array that holds the triangles.
+	 */
+	getBoxTriangles( box, triangles ) {
+
+		for ( let i = 0; i < this.subTrees.length; i ++ ) {
+
+			const subTree = this.subTrees[ i ];
+
+			if ( ! box.intersectsBox( subTree.box ) ) continue;
+
+			if ( subTree.triangles.length > 0 ) {
+
+				for ( let j = 0; j < subTree.triangles.length; j ++ ) {
+
+					if ( triangles.indexOf( subTree.triangles[ j ] ) === - 1 ) triangles.push( subTree.triangles[ j ] );
+
+				}
+
+			} else {
+
+				subTree.getBoxTriangles( box, triangles );
+
+			}
+
+		}
+
+	}
+
+	/**
+	 * Computes the triangles that potentially intersect with the given capsule.
+	 *
+	 * @param {Capsule} capsule - The capsule to test.
+	 * @param {Array<Triangle>} triangles - The target array that holds the triangles.
+	 */
 	getCapsuleTriangles( capsule, triangles ) {
 
 		for ( let i = 0; i < this.subTrees.length; i ++ ) {
@@ -371,6 +576,54 @@ class Octree {
 
 	}
 
+	/**
+	 * Performs a bounding box intersection test with this Octree.
+	 *
+	 * @param {Box3} box - The bounding box to test.
+	 * @return {Object|boolean} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
+	boxIntersect( box ) {
+
+		_box.copy( box );
+
+		const triangles = [];
+		let result, hit = false;
+
+		this.getBoxTriangles( box, triangles );
+
+		for ( let i = 0; i < triangles.length; i ++ ) {
+
+			if ( result = this.triangleBoxIntersect( _box, triangles[ i ] ) ) {
+
+				hit = true;
+
+				_box.translate( result.normal.multiplyScalar( result.depth ) );
+
+			}
+
+		}
+
+		if ( hit ) {
+
+			const collisionVector = _box.getCenter( _center ).sub( box.getCenter( _v1 ) );
+			const depth = collisionVector.length();
+
+			return { normal: collisionVector.normalize(), depth: depth };
+
+		}
+
+		return false;
+
+	}
+
+	/**
+	 * Performs a bounding sphere intersection test with this Octree.
+	 *
+	 * @param {Sphere} sphere - The bounding sphere to test.
+	 * @return {Object|boolean} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	sphereIntersect( sphere ) {
 
 		_sphere.copy( sphere );
@@ -405,6 +658,13 @@ class Octree {
 
 	}
 
+	/**
+	 * Performs a capsule intersection test with this Octree.
+	 *
+	 * @param {Capsule} capsule - The capsule to test.
+	 * @return {Object|boolean} The intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	capsuleIntersect( capsule ) {
 
 		_capsule.copy( capsule );
@@ -428,7 +688,7 @@ class Octree {
 
 		if ( hit ) {
 
-			const collisionVector = _capsule.getCenter( new Vector3() ).sub( capsule.getCenter( _v1 ) );
+			const collisionVector = _capsule.getCenter( _center ).sub( capsule.getCenter( _v1 ) );
 			const depth = collisionVector.length();
 
 			return { normal: collisionVector.normalize(), depth: depth };
@@ -439,10 +699,15 @@ class Octree {
 
 	}
 
+	/**
+	 * Performs a ray intersection test with this Octree.
+	 *
+	 * @param {Ray} ray - The ray to test.
+	 * @return {Object|boolean} The nearest intersection object. If no intersection
+	 * is detected, the method returns `false`.
+	 */
 	rayIntersect( ray ) {
 
-		if ( ray.direction.length() === 0 ) return;
-
 		const triangles = [];
 		let triangle, position, distance = 1e100;
 
@@ -472,6 +737,12 @@ class Octree {
 
 	}
 
+	/**
+	 * Constructs the Octree from the given 3D object.
+	 *
+	 * @param {Object3D} group - The scene graph node.
+	 * @return {Octree} A reference to this Octree.
+	 */
 	fromGraphNode( group ) {
 
 		group.updateWorldMatrix( true, true );
@@ -529,6 +800,11 @@ class Octree {
 
 	}
 
+	/**
+	 * Clears the Octree by making it empty.
+	 *
+	 * @return {Octree} A reference to this Octree.
+	 */
 	clear() {
 
 		this.box = null;