@plastic-software/three 0.174.0 → 0.175.1

package/examples/jsm/utils/BufferGeometryUtils.js

@@ -11,6 +11,27 @@ import {
 	Vector3,
 } from 'three';
 
+/** @module BufferGeometryUtils */
+
+/**
+ * Computes vertex tangents using the MikkTSpace algorithm. MikkTSpace generates the same tangents consistently,
+ * and is used in most modelling tools and normal map bakers. Use MikkTSpace for materials with normal maps,
+ * because inconsistent tangents may lead to subtle visual issues in the normal map, particularly around mirrored
+ * UV seams.
+ *
+ * In comparison to this method, {@link BufferGeometry#computeTangents} (a custom algorithm) generates tangents that
+ * probably will not match the tangents in other software. The custom algorithm is sufficient for general use with a
+ * custom material, and may be faster than MikkTSpace.
+ *
+ * Returns the original BufferGeometry. Indexed geometries will be de-indexed. Requires position, normal, and uv attributes.
+ *
+ * @param {BufferGeometry} geometry - The geometry to compute tangents for.
+ * @param {Object} MikkTSpace - Instance of `examples/jsm/libs/mikktspace.module.js`, or `mikktspace` npm package.
+ * Await `MikkTSpace.ready` before use.
+ * @param {boolean} [negateSign=true] - Whether to negate the sign component (.w) of each tangent.
+ * Required for normal map conventions in some formats, including glTF.
+ * @return {BufferGeometry} The updated geometry.
+ */
 function computeMikkTSpaceTangents( geometry, MikkTSpace, negateSign = true ) {
 
 	if ( ! MikkTSpace || ! MikkTSpace.isReady ) {
@@ -100,9 +121,11 @@ function computeMikkTSpaceTangents( geometry, MikkTSpace, negateSign = true ) {
 }
 
 /**
- * @param  {Array<BufferGeometry>} geometries
- * @param  {boolean} useGroups
- * @return {BufferGeometry}
+ * Merges a set of geometries into a single instance. All geometries must have compatible attributes.
+ *
+ * @param {Array<BufferGeometry>} geometries - The geometries to merge.
+ * @param {boolean} [useGroups=false] - Whether to use groups or not.
+ * @return {?BufferGeometry} The merged geometry. Returns `null` if the merge does not succeed.
  */
 function mergeGeometries( geometries, useGroups = false ) {
 
@@ -296,8 +319,11 @@ function mergeGeometries( geometries, useGroups = false ) {
 }
 
 /**
- * @param {Array<BufferAttribute>} attributes
- * @return {BufferAttribute}
+ * Merges a set of attributes into a single instance. All attributes must have compatible properties and types.
+ * Instances of {@link InterleavedBufferAttribute} are not supported.
+ *
+ * @param {Array<BufferAttribute>} attributes - The attributes to merge.
+ * @return {?BufferAttribute} The merged attribute. Returns `null` if the merge does not succeed.
  */
 function mergeAttributes( attributes ) {
 
@@ -389,10 +415,12 @@ function mergeAttributes( attributes ) {
 }
 
 /**
- * @param {BufferAttribute} attribute
- * @return {BufferAttribute}
+ * Performs a deep clone of the given buffer attribute.
+ *
+ * @param {BufferAttribute} attribute - The attribute to clone.
+ * @return {BufferAttribute} The cloned attribute.
  */
-export function deepCloneAttribute( attribute ) {
+function deepCloneAttribute( attribute ) {
 
 	if ( attribute.isInstancedInterleavedBufferAttribute || attribute.isInterleavedBufferAttribute ) {
 
@@ -411,8 +439,11 @@ export function deepCloneAttribute( attribute ) {
 }
 
 /**
- * @param {Array<BufferAttribute>} attributes
- * @return {Array<InterleavedBufferAttribute>}
+ * Interleaves a set of attributes and returns a new array of corresponding attributes that share a
+ * single {@link InterleavedBuffer} instance. All attributes must have compatible types.
+ *
+ * @param {Array<BufferAttribute>} attributes - The attributes to interleave.
+ * @return {Array<InterleavedBufferAttribute>} An array of interleaved attributes. If interleave does not succeed, the method returns `null`.
  */
 function interleaveAttributes( attributes ) {
 
@@ -475,8 +506,13 @@ function interleaveAttributes( attributes ) {
 
 }
 
-// returns a new, non-interleaved version of the provided attribute
-export function deinterleaveAttribute( attribute ) {
+/**
+ * Returns a new, non-interleaved version of the given attribute.
+ *
+ * @param {InterleavedBufferAttribute} attribute - The interleaved attribute.
+ * @return {BufferAttribute} The non-interleaved attribute.
+ */
+function deinterleaveAttribute( attribute ) {
 
 	const cons = attribute.data.array.constructor;
 	const count = attribute.count;
@@ -523,8 +559,12 @@ export function deinterleaveAttribute( attribute ) {
 
 }
 
-// deinterleaves all attributes on the geometry
-export function deinterleaveGeometry( geometry ) {
+/**
+ * Deinterleaves all attributes on the given geometry.
+ *
+ * @param {BufferGeometry} geometry - The geometry to deinterleave.
+ */
+function deinterleaveGeometry( geometry ) {
 
 	const attributes = geometry.attributes;
 	const morphTargets = geometry.morphTargets;
@@ -567,8 +607,10 @@ export function deinterleaveGeometry( geometry ) {
 }
 
 /**
- * @param {BufferGeometry} geometry
- * @return {number}
+ * Returns the amount of bytes used by all attributes to represent the geometry.
+ *
+ * @param {BufferGeometry} geometry - The geometry.
+ * @return {number} The estimate bytes used.
  */
 function estimateBytesUsed( geometry ) {
 
@@ -590,9 +632,11 @@ function estimateBytesUsed( geometry ) {
 }
 
 /**
- * @param {BufferGeometry} geometry
- * @param {number} tolerance
- * @return {BufferGeometry}
+ * Returns a new geometry with vertices for which all similar vertex attributes (within tolerance) are merged.
+ *
+ * @param {BufferGeometry} geometry - The geometry to merge vertices for.
+ * @param {number} [tolerance=1e-4] - The tolerance value.
+ * @return {BufferGeometry} - The new geometry with merged vertices.
  */
 function mergeVertices( geometry, tolerance = 1e-4 ) {
 
@@ -753,9 +797,12 @@ function mergeVertices( geometry, tolerance = 1e-4 ) {
 }
 
 /**
- * @param {BufferGeometry} geometry
- * @param {number} drawMode
- * @return {BufferGeometry}
+ * Returns a new indexed geometry based on `TrianglesDrawMode` draw mode.
+ * This mode corresponds to the `gl.TRIANGLES` primitive in WebGL.
+ *
+ * @param {BufferGeometry} geometry - The geometry to convert.
+ * @param {number} drawMode - The current draw mode.
+ * @return {BufferGeometry} The new geometry using `TrianglesDrawMode`.
  */
 function toTrianglesDrawMode( geometry, drawMode ) {
 
@@ -864,9 +911,13 @@ function toTrianglesDrawMode( geometry, drawMode ) {
 
 /**
  * Calculates the morphed attributes of a morphed/skinned BufferGeometry.
- * Helpful for Raytracing or Decals.
- * @param {Mesh | Line | Points} object An instance of Mesh, Line or Points.
- * @return {Object} An Object with original position/normal attributes and morphed ones.
+ *
+ * Helpful for Raytracing or Decals (i.e. a `DecalGeometry` applied to a morphed Object with a `BufferGeometry`
+ * will use the original `BufferGeometry`, not the morphed/skinned one, generating an incorrect result.
+ * Using this function to create a shadow `Object3`D the `DecalGeometry` can be correctly generated).
+ *
+ * @param {Mesh|Line|Points} object - The 3D object to compute morph attributes for.
+ * @return {Object} An object with original position/normal attributes and morphed ones.
  */
 function computeMorphedAttributes( object ) {
 
@@ -1142,6 +1193,12 @@ function computeMorphedAttributes( object ) {
 
 }
 
+/**
+ * Merges the {@link BufferGeometry#groups} for the given geometry.
+ *
+ * @param {BufferGeometry} geometry - The geometry to modify.
+ * @return {BufferGeometry} - The updated geometry
+ */
 function mergeGroups( geometry ) {
 
 	if ( geometry.groups.length === 0 ) {
@@ -1244,15 +1301,14 @@ function mergeGroups( geometry ) {
 
 }
 
-
 /**
  * Modifies the supplied geometry if it is non-indexed, otherwise creates a new,
  * non-indexed geometry. Returns the geometry with smooth normals everywhere except
  * faces that meet at an angle greater than the crease angle.
  *
- * @param {BufferGeometry} geometry
- * @param {number} [creaseAngle]
- * @return {BufferGeometry}
+ * @param {BufferGeometry} geometry - The geometry to modify.
+ * @param {number} [creaseAngle=Math.PI/3] - The crease angle in radians.
+ * @return {BufferGeometry} - The updated geometry
  */
 function toCreasedNormals( geometry, creaseAngle = Math.PI / 3 /* 60 degrees */ ) {
 
@@ -1363,6 +1419,9 @@ export {
 	computeMikkTSpaceTangents,
 	mergeGeometries,
 	mergeAttributes,
+	deepCloneAttribute,
+	deinterleaveAttribute,
+	deinterleaveGeometry,
 	interleaveAttributes,
 	estimateBytesUsed,
 	mergeVertices,

package/examples/jsm/utils/CameraUtils.js

@@ -4,6 +4,8 @@ import {
 	Vector3
 } from 'three';
 
+/** @module CameraUtils */
+
 const _va = /*@__PURE__*/ new Vector3(), // from pe to pa
 	_vb = /*@__PURE__*/ new Vector3(), // from pe to pb
 	_vc = /*@__PURE__*/ new Vector3(), // from pe to pc
@@ -14,16 +16,17 @@ const _va = /*@__PURE__*/ new Vector3(), // from pe to pa
 	_quat = /*@__PURE__*/ new Quaternion(); // temporary quaternion
 
 
-/** Set a PerspectiveCamera's projectionMatrix and quaternion
+/**
+ * Set projection matrix and the orientation of a perspective camera
  * to exactly frame the corners of an arbitrary rectangle.
  * NOTE: This function ignores the standard parameters;
- * do not call updateProjectionMatrix() after this!
+ * do not call `updateProjectionMatrix()` after this.
  *
- * @param {PerspectiveCamera} camera
- * @param {Vector3} bottomLeftCorner
- * @param {Vector3} bottomRightCorner
- * @param {Vector3} topLeftCorner
- * @param {boolean} [estimateViewFrustum=false]
+ * @param {PerspectiveCamera} camera - The camera.
+ * @param {Vector3} bottomLeftCorner - The bottom-left corner point.
+ * @param {Vector3} bottomRightCorner - The bottom-right corner point.
+ * @param {Vector3} topLeftCorner - The top-left corner point.
+ * @param {boolean} [estimateViewFrustum=false] - If set to `true`, the function tries to estimate the camera's FOV.
  */
 function frameCorners( camera, bottomLeftCorner, bottomRightCorner, topLeftCorner, estimateViewFrustum = false ) {
 

package/examples/jsm/utils/GeometryCompressionUtils.js

@@ -1,10 +1,3 @@
-/**
- * Octahedron and Quantization encodings based on work by:
- *
- * @link https://github.com/tsherif/mesh-quantization-example
- *
- */
-
 import {
 	BufferAttribute,
 	Matrix3,
@@ -12,14 +5,15 @@ import {
 	Vector3
 } from 'three';
 
+/** @module GeometryCompressionUtils */
 
+// Octahedron and Quantization encodings based on work by: https://github.com/tsherif/mesh-quantization-example
 
 /**
- * Make the input geometry's normal attribute encoded and compressed by 3 different methods.
- *
- * @param {THREE.BufferGeometry} geometry
- * @param {string} encodeMethod		"DEFAULT" || "OCT1Byte" || "OCT2Byte" || "ANGLES"
+ * Compressed the given geometry's `normal` attribute by the selected encode method.
  *
+ * @param {BufferGeometry} geometry - The geometry whose normals should be compressed.
+ * @param {('DEFAULT'|'OCT1Byte'|'OCT2Byte'|'ANGLES')} encodeMethod - The compression method.
  */
 function compressNormals( geometry, encodeMethod ) {
 
@@ -27,7 +21,7 @@ function compressNormals( geometry, encodeMethod ) {
 
 	if ( ! normal ) {
 
-		console.error( 'Geometry must contain normal attribute. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressNormals(): Geometry must contain normal attribute.' );
 
 	}
 
@@ -35,7 +29,7 @@ function compressNormals( geometry, encodeMethod ) {
 
 	if ( normal.itemSize != 3 ) {
 
-		console.error( 'normal.itemSize is not 3, which cannot be encoded. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressNormals(): normal.itemSize is not 3, which cannot be encoded.' );
 
 	}
 
@@ -63,11 +57,10 @@ function compressNormals( geometry, encodeMethod ) {
 
 	} else if ( encodeMethod == 'OCT1Byte' ) {
 
-		/**
-		* It is not recommended to use 1-byte octahedron normals encoding unless you want to extremely reduce the memory usage
-		* As it makes vertex data not aligned to a 4 byte boundary which may harm some WebGL implementations and sometimes the normal distortion is visible
-		* Please refer to @zeux 's comments in https://github.com/mrdoob/three.js/pull/18208
-		*/
+
+		// It is not recommended to use 1-byte octahedron normals encoding unless you want to extremely reduce the memory usage
+		// As it makes vertex data not aligned to a 4 byte boundary which may harm some WebGL implementations and sometimes the normal distortion is visible
+		// Please refer to @zeux 's comments in https://github.com/mrdoob/three.js/pull/18208
 
 		result = new Int8Array( count * 2 );
 
@@ -127,20 +120,18 @@ function compressNormals( geometry, encodeMethod ) {
 
 }
 
-
 /**
-	 * Make the input geometry's position attribute encoded and compressed.
-	 *
-	 * @param {THREE.BufferGeometry} geometry
-	 *
-	 */
+ * Compressed the given geometry's `position` attribute.
+ *
+ * @param {BufferGeometry} geometry - The geometry whose position values should be compressed.
+ */
 function compressPositions( geometry ) {
 
 	const position = geometry.attributes.position;
 
 	if ( ! position ) {
 
-		console.error( 'Geometry must contain position attribute. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressPositions(): Geometry must contain position attribute.' );
 
 	}
 
@@ -148,7 +139,7 @@ function compressPositions( geometry ) {
 
 	if ( position.itemSize != 3 ) {
 
-		console.error( 'position.itemSize is not 3, which cannot be packed. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressPositions(): position.itemSize is not 3, which cannot be packed.' );
 
 	}
 
@@ -171,10 +162,9 @@ function compressPositions( geometry ) {
 }
 
 /**
- * Make the input geometry's uv attribute encoded and compressed.
- *
- * @param {THREE.BufferGeometry} geometry
+ * Compressed the given geometry's `uv` attribute.
  *
+ * @param {BufferGeometry} geometry - The geometry whose texture coordinates should be compressed.
  */
 function compressUvs( geometry ) {
 
@@ -182,7 +172,7 @@ function compressUvs( geometry ) {
 
 	if ( ! uvs ) {
 
-		console.error( 'Geometry must contain uv attribute. ' );
+		console.error( 'THREE.GeometryCompressionUtils.compressUvs(): Geometry must contain uv attribute.' );
 
 	}
 

package/examples/jsm/utils/GeometryUtils.js

@@ -1,20 +1,20 @@
 import { Vector3 } from 'three';
 
+/** @module GeometryUtils */
 
 /**
- * Generates 2D-Coordinates in a very fast way.
+ * Generates 2D-Coordinates along a Hilbert curve.
  *
- * Based on work by:
- * @link http://www.openprocessing.org/sketch/15493
+ * Based on work by: {@link http://www.openprocessing.org/sketch/15493}
  *
- * @param {Vector3} center - Center of Hilbert curve.
+ * @param {Vector3} [center] - Center of Hilbert curve.
  * @param {number} [size=10] - Total width of Hilbert curve.
  * @param {number} [iterations=10] - Number of subdivisions.
  * @param {number} [v0=0] - Corner index -X, -Z.
  * @param {number} [v1=1] - Corner index -X, +Z.
  * @param {number} [v2=2] - Corner index +X, +Z.
  * @param {number} [v3=3] - Corner index +X, -Z.
- * @returns {Array<Array<number>>} The Hilbert curve points.
+ * @returns {Array<Vector3>} The Hilbert curve points.
  */
 function hilbert2D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1, v0 = 0, v1 = 1, v2 = 2, v3 = 3 ) {
 
@@ -52,12 +52,11 @@ function hilbert2D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1,
 }
 
 /**
- * Generates 3D-Coordinates in a very fast way.
+ * Generates 3D-Coordinates along a Hilbert curve.
  *
- * Based on work by:
- * @link https://openprocessing.org/user/5654
+ * Based on work by: {@link https://openprocessing.org/user/5654}
  *
- * @param {Vector3} [center=new Vector3( 0, 0, 0 )] - Center of Hilbert curve.
+ * @param {Vector3} [center] - Center of Hilbert curve.
  * @param {number} [size=10] - Total width of Hilbert curve.
  * @param {number} [iterations=1] - Number of subdivisions.
  * @param {number} [v0=0] - Corner index -X, +Y, -Z.
@@ -68,7 +67,7 @@ function hilbert2D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1,
  * @param {number} [v5=5] - Corner index +X, -Y, +Z.
  * @param {number} [v6=6] - Corner index +X, +Y, +Z.
  * @param {number} [v7=7] - Corner index +X, +Y, -Z.
- * @returns {Array<Array<number>>}  - The Hilbert curve points.
+ * @returns {Array<Vector3>}  - The Hilbert curve points.
  */
 function hilbert3D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1, v0 = 0, v1 = 1, v2 = 2, v3 = 3, v4 = 4, v5 = 5, v6 = 6, v7 = 7 ) {
 
@@ -119,12 +118,12 @@ function hilbert3D( center = new Vector3( 0, 0, 0 ), size = 10, iterations = 1,
 }
 
 /**
- * Generates a Gosper curve (lying in the XY plane)
+ * Generates a Gosper curve (lying in the XY plane).
  *
- * https://gist.github.com/nitaku/6521802
+ * Reference: {@link https://gist.github.com/nitaku/6521802}
  *
  * @param {number} [size=1] - The size of a single gosper island.
- * @return {Array<[number, number, number]>} The gosper island points.
+ * @return {Array<number>} The gosper island points.
  */
 function gosper( size = 1 ) {
 

package/examples/jsm/utils/LDrawUtils.js

@@ -9,14 +9,21 @@ import {
 
 import { mergeGeometries } from './BufferGeometryUtils.js';
 
+/**
+ * Utility class for LDraw models.
+ */
 class LDrawUtils {
 
+	/**
+	 * Merges geometries in the given object by materials and returns a new group object.
+	 * Use on not indexed geometries. The object buffers reference the old object ones.
+	 * Special treatment is done to the conditional lines generated by LDrawLoader.
+	 *
+	 * @param {Object3D} object - The object to merge.
+	 * @returns {Group} The merged object.
+	 */
 	static mergeObject( object ) {
 
-		// Merges geometries in object by materials and returns new object. Use on not indexed geometries.
-		// The object buffers reference the old object ones.
-		// Special treatment is done to the conditional lines generated by LDrawLoader.
-
 		function extractGroup( geometry, group, elementSize, isConditionalLine ) {
 
 			// Extracts a group from a geometry as a new geometry (with attribute buffers referencing original buffers)

package/examples/jsm/utils/SceneOptimizer.js

@@ -1,7 +1,18 @@
 import * as THREE from 'three';
 
+/**
+ * This class can be used to optimized scenes by converting
+ * individual meshes into {@link BatchedMesh}. This component
+ * is an experimental attempt to implement auto-batching in three.js.
+ */
 class SceneOptimizer {
 
+	/**
+	 * Constructs a new scene optimizer.
+	 *
+	 * @param {Scene} scene - The scene to optimize.
+	 * @param {SceneOptimizer~Options} options - The configuration options.
+	 */
 	constructor( scene, options = {} ) {
 
 		this.scene = scene;
@@ -9,7 +20,7 @@ class SceneOptimizer {
 
 	}
 
-	bufferToHash( buffer ) {
+	_bufferToHash( buffer ) {
 
 		let hash = 0;
 		if ( buffer.byteLength !== 0 ) {
@@ -43,7 +54,7 @@ class SceneOptimizer {
 
 	}
 
-	getMaterialPropertiesHash( material ) {
+	_getMaterialPropertiesHash( material ) {
 
 		const mapProps = [
 			'map',
@@ -128,7 +139,7 @@ class SceneOptimizer {
 
 	}
 
-	getAttributesSignature( geometry ) {
+	_getAttributesSignature( geometry ) {
 
 		return Object.keys( geometry.attributes )
 			.sort()
@@ -142,24 +153,24 @@ class SceneOptimizer {
 
 	}
 
-	getGeometryHash( geometry ) {
+	_getGeometryHash( geometry ) {
 
 		const indexHash = geometry.index
-			? this.bufferToHash( geometry.index.array )
+			? this._bufferToHash( geometry.index.array )
 			: 'noIndex';
-		const positionHash = this.bufferToHash( geometry.attributes.position.array );
-		const attributesSignature = this.getAttributesSignature( geometry );
+		const positionHash = this._bufferToHash( geometry.attributes.position.array );
+		const attributesSignature = this._getAttributesSignature( geometry );
 		return `${indexHash}_${positionHash}_${attributesSignature}`;
 
 	}
 
-	getBatchKey( materialProps, attributesSignature ) {
+	_getBatchKey( materialProps, attributesSignature ) {
 
 		return `${materialProps}_${attributesSignature}`;
 
 	}
 
-	analyzeModel() {
+	_analyzeModel() {
 
 		const batchGroups = new Map();
 		const singleGroups = new Map();
@@ -170,10 +181,10 @@ class SceneOptimizer {
 
 			if ( ! node.isMesh ) return;
 
-			const materialProps = this.getMaterialPropertiesHash( node.material );
-			const attributesSignature = this.getAttributesSignature( node.geometry );
-			const batchKey = this.getBatchKey( materialProps, attributesSignature );
-			const geometryHash = this.getGeometryHash( node.geometry );
+			const materialProps = this._getMaterialPropertiesHash( node.material );
+			const attributesSignature = this._getAttributesSignature( node.geometry );
+			const batchKey = this._getBatchKey( materialProps, attributesSignature );
+			const geometryHash = this._getGeometryHash( node.geometry );
 			uniqueGeometries.add( geometryHash );
 
 			if ( ! batchGroups.has( batchKey ) ) {
@@ -222,7 +233,7 @@ class SceneOptimizer {
 
 	}
 
-	createBatchedMeshes( batchGroups ) {
+	_createBatchedMeshes( batchGroups ) {
 
 		const meshesToRemove = new Set();
 
@@ -269,7 +280,7 @@ class SceneOptimizer {
 
 			for ( const mesh of group.meshes ) {
 
-				const geometryHash = this.getGeometryHash( mesh.geometry );
+				const geometryHash = this._getGeometryHash( mesh.geometry );
 
 				if ( ! geometryIds.has( geometryHash ) ) {
 
@@ -308,6 +319,11 @@ class SceneOptimizer {
 
 	}
 
+	/**
+	 * Removes empty nodes from all descendants of the given 3D object.
+	 *
+	 * @param {Object3D} object - The 3D object to process.
+	 */
 	removeEmptyNodes( object ) {
 
 		const children = [ ...object.children ];
@@ -327,6 +343,11 @@ class SceneOptimizer {
 
 	}
 
+	/**
+	 * Removes the given array of meshes from the scene.
+	 *
+	 * @param {Set<Mesh>} meshesToRemove - The meshes to remove.
+	 */
 	disposeMeshes( meshesToRemove ) {
 
 		meshesToRemove.forEach( ( mesh ) => {
@@ -356,7 +377,7 @@ class SceneOptimizer {
 
 	}
 
-	logDebugInfo( stats ) {
+	_logDebugInfo( stats ) {
 
 		console.group( 'Scene Optimization Results' );
 		console.log( `Original meshes: ${stats.originalMeshes}` );
@@ -368,10 +389,18 @@ class SceneOptimizer {
 
 	}
 
+	/**
+	 * Performs the auto-baching by identifying groups of meshes in the scene
+	 * that can be represented as a single {@link BatchedMesh}. The method modifies
+	 * the scene by adding instances of `BatchedMesh` and removing the now redundant
+	 * individual meshes.
+	 *
+	 * @return {Scene} The optimized scene.
+	 */
 	toBatchedMesh() {
 
-		const { batchGroups, singleGroups, uniqueGeometries } = this.analyzeModel();
-		const meshesToRemove = this.createBatchedMeshes( batchGroups );
+		const { batchGroups, singleGroups, uniqueGeometries } = this._analyzeModel();
+		const meshesToRemove = this._createBatchedMeshes( batchGroups );
 
 		this.disposeMeshes( meshesToRemove );
 		this.removeEmptyNodes( this.scene );
@@ -390,7 +419,7 @@ class SceneOptimizer {
 				reductionRatio: ( ( 1 - totalFinalMeshes / totalOriginalMeshes ) * 100 ).toFixed( 1 ),
 			};
 
-			this.logDebugInfo( stats );
+			this._logDebugInfo( stats );
 
 		}
 
@@ -398,7 +427,17 @@ class SceneOptimizer {
 
 	}
 
-	// Placeholder for future implementation
+	/**
+	 * Performs the auto-instancing by identifying groups of meshes in the scene
+	 * that can be represented as a single {@link InstancedMesh}. The method modifies
+	 * the scene by adding instances of `InstancedMesh` and removing the now redundant
+	 * individual meshes.
+	 *
+	 * This method is not yet implemented.
+	 *
+	 * @abstract
+	 * @return {Scene} The optimized scene.
+	 */
 	toInstancingMesh() {
 
 		throw new Error( 'InstancedMesh optimization not implemented yet' );
@@ -407,4 +446,11 @@ class SceneOptimizer {
 
 }
 
+/**
+ * Constructor options of `SceneOptimizer`.
+ *
+ * @typedef {Object} SceneOptimizer~Options
+ * @property {boolean} [debug=false] - Whether to enable debug mode or not.
+ **/
+
 export { SceneOptimizer };