three-zoo 0.4.7 → 0.5.0

package/dist/index.js

@@ -1,102 +1,157 @@
-import { PerspectiveCamera, MathUtils, Vector3, Box3, Mesh, InstancedMesh, FrontSide, BufferAttribute, AnimationMixer, DirectionalLight, Spherical, RGBAFormat } from 'three';
+import { PerspectiveCamera, MathUtils, Vector3, Mesh, BufferAttribute, AnimationMixer, DirectionalLight, Box3, Spherical, RGBAFormat } from 'three';
 
+/** Default horizontal field of view in degrees */
 const DEFAULT_HORIZONTAL_FOV = 90;
+/** Default vertical field of view in degrees */
 const DEFAULT_VERTICAL_FOV = 90;
+/** Default aspect ratio (width/height) */
 const DEFAULT_ASPECT = 1;
+/** Default near clipping plane distance */
 const DEFAULT_NEAR = 1;
+/** Default far clipping plane distance */
 const DEFAULT_FAR = 1000;
+/** Minimum allowed field of view in degrees */
 const MIN_FOV = 1;
+/** Maximum allowed field of view in degrees */
 const MAX_FOV = 179;
 /**
  * A camera that supports independent horizontal and vertical FOV settings.
  * Extends Three.js PerspectiveCamera to allow separate control over horizontal
  * and vertical fields of view.
  */
-class BiFovCamera extends PerspectiveCamera {
+class DualFovCamera extends PerspectiveCamera {
     /**
-     * @param horizontalFov - Horizontal FOV in degrees (90° default)
-     * @param verticalFov - Vertical FOV in degrees (90° default)
-     * @param aspect - Width/height ratio (1 default)
-     * @param near - Near clipping plane (1 default)
-     * @param far - Far clipping plane (1000 default)
+     * Creates a new DualFovCamera instance with independent horizontal and vertical FOV control.
+     *
+     * @param horizontalFov - Horizontal field of view in degrees. Must be between 1° and 179°. Defaults to 90°.
+     * @param verticalFov - Vertical field of view in degrees. Must be between 1° and 179°. Defaults to 90°.
+     * @param aspect - Camera aspect ratio (width/height). Defaults to 1.
+     * @param near - Near clipping plane distance. Must be greater than 0. Defaults to 1.
+     * @param far - Far clipping plane distance. Must be greater than near plane. Defaults to 1000.
      */
     constructor(horizontalFov = DEFAULT_HORIZONTAL_FOV, verticalFov = DEFAULT_VERTICAL_FOV, aspect = DEFAULT_ASPECT, near = DEFAULT_NEAR, far = DEFAULT_FAR) {
         super(verticalFov, aspect, near, far);
-        this.horizontalFovInternal = horizontalFov;
-        this.verticalFovInternal = verticalFov;
+        this._private_horizontalFovInternal = horizontalFov;
+        this._private_verticalFovInternal = verticalFov;
         this.updateProjectionMatrix();
     }
-    /** Current horizontal FOV in degrees */
+    /**
+     * Gets the current horizontal field of view in degrees.
+     *
+     * @returns The horizontal FOV value between 1° and 179°
+     */
     get horizontalFov() {
-        return this.horizontalFovInternal;
+        return this._private_horizontalFovInternal;
     }
-    /** Current vertical FOV in degrees */
+    /**
+     * Gets the current vertical field of view in degrees.
+     *
+     * @returns The vertical FOV value between 1° and 179°
+     */
     get verticalFov() {
-        return this.verticalFovInternal;
+        return this._private_verticalFovInternal;
     }
-    /** Set horizontal FOV in degrees (clamped between 1° and 179°) */
+    /**
+     * Sets the horizontal field of view in degrees.
+     *
+     * @param value - The horizontal FOV value in degrees. Will be clamped between 1° and 179°.
+     */
     set horizontalFov(value) {
-        this.horizontalFovInternal = MathUtils.clamp(value, MIN_FOV, MAX_FOV);
+        this._private_horizontalFovInternal = MathUtils.clamp(value, MIN_FOV, MAX_FOV);
         this.updateProjectionMatrix();
     }
-    /** Set vertical FOV in degrees (clamped between 1° and 179°) */
+    /**
+     * Sets the vertical field of view in degrees.
+     *
+     * @param value - The vertical FOV value in degrees. Will be clamped between 1° and 179°.
+     */
     set verticalFov(value) {
-        this.verticalFovInternal = MathUtils.clamp(value, MIN_FOV, MAX_FOV);
+        this._private_verticalFovInternal = MathUtils.clamp(value, MIN_FOV, MAX_FOV);
         this.updateProjectionMatrix();
     }
     /**
-     * Update both horizontal and vertical FOV
-     * @param horizontal - Horizontal FOV in degrees
-     * @param vertical - Vertical FOV in degrees
+     * Updates both horizontal and vertical field of view values simultaneously.
+     *
+     * @param horizontal - Horizontal FOV in degrees. Will be clamped between 1° and 179°.
+     * @param vertical - Vertical FOV in degrees. Will be clamped between 1° and 179°.
      */
     setFov(horizontal, vertical) {
-        this.horizontalFovInternal = MathUtils.clamp(horizontal, MIN_FOV, MAX_FOV);
-        this.verticalFovInternal = MathUtils.clamp(vertical, MIN_FOV, MAX_FOV);
+        this._private_horizontalFovInternal = MathUtils.clamp(horizontal, MIN_FOV, MAX_FOV);
+        this._private_verticalFovInternal = MathUtils.clamp(vertical, MIN_FOV, MAX_FOV);
         this.updateProjectionMatrix();
     }
     /**
-     * Copy FOV settings from another BiFovCamera
-     * @param source - Camera to copy from
+     * Copies the field of view settings from another DualFovCamera instance.
+     *
+     * @param source - The DualFovCamera instance to copy FOV settings from.
      */
     copyFovSettings(source) {
-        this.horizontalFovInternal = source.horizontalFov;
-        this.verticalFovInternal = source.verticalFov;
+        this._private_horizontalFovInternal = source.horizontalFov;
+        this._private_verticalFovInternal = source.verticalFov;
         this.updateProjectionMatrix();
     }
     /**
-     * Updates the projection matrix based on FOV settings and aspect ratio.
-     * In landscape: preserves horizontal FOV
-     * In portrait: preserves vertical FOV
+     * Updates the projection matrix based on current FOV settings and aspect ratio.
+     *
+     * The behavior differs based on orientation:
+     * - **Landscape mode (aspect > 1)**: Preserves horizontal FOV, calculates vertical FOV
+     * - **Portrait mode (aspect ≤ 1)**: Preserves vertical FOV, calculates horizontal FOV
+     *
+     * This method is automatically called when FOV values or aspect ratio changes.
+     *
+     * @override
      */
     updateProjectionMatrix() {
         if (this.aspect > 1) {
             // Landscape orientation: preserve horizontal FOV
-            const radians = MathUtils.degToRad(this.horizontalFovInternal);
+            const radians = MathUtils.degToRad(this._private_horizontalFovInternal);
             this.fov = MathUtils.radToDeg(Math.atan(Math.tan(radians / 2) / this.aspect) * 2);
         }
         else {
             // Portrait orientation: preserve vertical FOV
-            this.fov = this.verticalFovInternal;
+            this.fov = this._private_verticalFovInternal;
         }
         super.updateProjectionMatrix();
     }
-    /** Get actual horizontal FOV after aspect ratio adjustments */
-    getEffectiveHorizontalFov() {
+    /**
+     * Gets the actual horizontal field of view after aspect ratio adjustments.
+     *
+     * In landscape mode, this returns the set horizontal FOV.
+     * In portrait mode, this calculates the actual horizontal FOV based on the vertical FOV and aspect ratio.
+     *
+     * @returns The actual horizontal FOV in degrees
+     */
+    getActualHorizontalFov() {
         if (this.aspect >= 1) {
-            return this.horizontalFovInternal;
+            return this._private_horizontalFovInternal;
         }
-        const verticalRadians = MathUtils.degToRad(this.verticalFovInternal);
+        const verticalRadians = MathUtils.degToRad(this._private_verticalFovInternal);
         return MathUtils.radToDeg(Math.atan(Math.tan(verticalRadians / 2) * this.aspect) * 2);
     }
-    /** Get actual vertical FOV after aspect ratio adjustments */
-    getEffectiveVerticalFov() {
+    /**
+     * Gets the actual vertical field of view after aspect ratio adjustments.
+     *
+     * In portrait mode, this returns the set vertical FOV.
+     * In landscape mode, this calculates the actual vertical FOV based on the horizontal FOV and aspect ratio.
+     *
+     * @returns The actual vertical FOV in degrees
+     */
+    getActualVerticalFov() {
         if (this.aspect < 1) {
-            return this.verticalFovInternal;
+            return this._private_verticalFovInternal;
         }
-        const horizontalRadians = MathUtils.degToRad(this.horizontalFovInternal);
+        const horizontalRadians = MathUtils.degToRad(this._private_horizontalFovInternal);
         return MathUtils.radToDeg(Math.atan(Math.tan(horizontalRadians / 2) / this.aspect) * 2);
     }
-    fitPointsVerticalFov(vertices) {
+    /**
+     * Adjusts the vertical field of view to fit all specified points within the camera's view.
+     *
+     * This method calculates the required vertical FOV to ensure all provided vertices
+     * are visible within the vertical bounds of the camera's frustum.
+     *
+     * @param vertices - Array of 3D points (in world coordinates) that should fit within the camera's vertical view
+     */
+    fitVerticalFovToPoints(vertices) {
         const up = new Vector3(0, 1, 0).applyQuaternion(this.quaternion);
         let maxVerticalAngle = 0;
         for (const vertex of vertices) {
@@ -109,11 +164,19 @@ class BiFovCamera extends PerspectiveCamera {
             }
         }
         const requiredFov = MathUtils.radToDeg(2 * maxVerticalAngle);
-        this.verticalFovInternal = MathUtils.clamp(requiredFov, MIN_FOV, MAX_FOV);
+        this._private_verticalFovInternal = MathUtils.clamp(requiredFov, MIN_FOV, MAX_FOV);
         this.updateProjectionMatrix();
     }
-    fitBoxVerticalFov(box) {
-        this.fitPointsVerticalFov([
+    /**
+     * Adjusts the vertical field of view to fit a bounding box within the camera's view.
+     *
+     * This method calculates the required vertical FOV to ensure the entire bounding box
+     * is visible within the vertical bounds of the camera's frustum.
+     *
+     * @param box - The 3D bounding box (in world coordinates) that should fit within the camera's vertical view
+     */
+    fitVerticalFovToBox(box) {
+        this.fitVerticalFovToPoints([
             new Vector3(box.min.x, box.min.y, box.min.z),
             new Vector3(box.min.x, box.min.y, box.max.z),
             new Vector3(box.min.x, box.max.y, box.min.z),
@@ -124,7 +187,16 @@ class BiFovCamera extends PerspectiveCamera {
             new Vector3(box.max.x, box.max.y, box.max.z),
         ]);
     }
-    fitSkinnedMeshVerticalFov(skinnedMesh) {
+    /**
+     * Adjusts the vertical field of view to fit a skinned mesh within the camera's view.
+     *
+     * This method updates the mesh's skeleton, applies bone transformations to all vertices,
+     * and then calculates the required vertical FOV to ensure the entire deformed mesh
+     * is visible within the vertical bounds of the camera's frustum.
+     *
+     * @param skinnedMesh - The skinned mesh (with active skeleton) that should fit within the camera's vertical view
+     */
+    fitVerticalFovToMesh(skinnedMesh) {
         skinnedMesh.updateWorldMatrix(true, true);
         skinnedMesh.skeleton.update();
         const bakedGeometry = skinnedMesh.geometry;
@@ -136,9 +208,22 @@ class BiFovCamera extends PerspectiveCamera {
             skinnedMesh.applyBoneTransform(i, target);
             points.push(target.clone());
         }
-        this.fitPointsVerticalFov(points);
+        this.fitVerticalFovToPoints(points);
     }
-    lookAtCenterOfMass(skinnedMesh) {
+    /**
+     * Points the camera to look at the center of mass of a skinned mesh.
+     *
+     * This method updates the mesh's skeleton, applies bone transformations to all vertices,
+     * calculates the center of mass using a clustering algorithm, and then orients the camera
+     * to look at that point.
+     *
+     * The center of mass calculation uses an iterative clustering approach to find the
+     * main concentration of vertices, which provides better results than a simple average
+     * for complex meshes.
+     *
+     * @param skinnedMesh - The skinned mesh (with active skeleton) whose center of mass should be the camera's target
+     */
+    lookAtMeshCenterOfMass(skinnedMesh) {
         skinnedMesh.updateWorldMatrix(true, true);
         skinnedMesh.skeleton.update();
         const bakedGeometry = skinnedMesh.geometry;
@@ -150,6 +235,13 @@ class BiFovCamera extends PerspectiveCamera {
             skinnedMesh.applyBoneTransform(i, target);
             points.push(target.clone());
         }
+        /**
+         * Finds the main cluster center of a set of 3D points using iterative refinement.
+         *
+         * @param points - Array of 3D points to cluster
+         * @param iterations - Number of refinement iterations to perform
+         * @returns The calculated center point of the main cluster
+         */
         const findMainCluster = (points, iterations = 3) => {
             if (points.length === 0) {
                 return new Vector3();
@@ -174,116 +266,45 @@ class BiFovCamera extends PerspectiveCamera {
         const centerOfMass = findMainCluster(points);
         this.lookAt(centerOfMass);
     }
+    /**
+     * Creates a deep copy of this DualFovCamera instance.
+     *
+     * The cloned camera will have identical FOV settings, position, rotation,
+     * and all other camera properties.
+     *
+     * @returns A new DualFovCamera instance that is an exact copy of this one
+     * @override
+     */
     clone() {
-        const camera = new BiFovCamera(this.horizontalFovInternal, this.verticalFovInternal, this.aspect, this.near, this.far);
+        const camera = new DualFovCamera(this._private_horizontalFovInternal, this._private_verticalFovInternal, this.aspect, this.near, this.far);
         camera.copy(this, true);
         return camera;
     }
 }
 
 /**
- * Box3 with additional convenience methods for width, height, depth, etc.
- */
-class Bounds extends Box3 {
-    constructor(object) {
-        super();
-        /** Temporary vector for calculations */
-        this.tempVector3A = new Vector3();
-        if (object) {
-            this.setFromObject(object);
-        }
-    }
-    /** Width (x-axis length) */
-    get width() {
-        return this.max.x - this.min.x;
-    }
-    /** Height (y-axis length) */
-    get height() {
-        return this.max.y - this.min.y;
-    }
-    /** Depth (z-axis length) */
-    get depth() {
-        return this.max.z - this.min.z;
-    }
-    /** Length of the box's diagonal */
-    get diagonal() {
-        return this.tempVector3A.subVectors(this.max, this.min).length();
-    }
-    setFromSkinnedMesh(skinnedMesh) {
-        skinnedMesh.updateWorldMatrix(true, true);
-        skinnedMesh.skeleton.update();
-        const geometry = skinnedMesh.geometry;
-        const position = geometry.attributes["position"];
-        const target = new Vector3();
-        const points = [];
-        for (let i = 0; i < position.count; i++) {
-            target.fromBufferAttribute(position, i);
-            skinnedMesh.applyBoneTransform(i, target);
-            points.push(target.clone());
-        }
-        this.setFromPoints(points);
-        return this;
-    }
-    /** Volume (width * height * depth) */
-    getVolume() {
-        return this.width * this.height * this.depth;
-    }
-    /** Surface area (sum of all six faces) */
-    getSurfaceArea() {
-        const w = this.width;
-        const h = this.height;
-        const d = this.depth;
-        return 2 * (w * h + h * d + d * w);
-    }
-}
-
-const POSITION_COMPONENT_COUNT = 3;
-const NORMAL_COMPONENT_COUNT = 3;
-/**
- * Internal utility to identify identical geometries.
- * @internal
+ * Utility class for finding and modifying objects in a Three.js scene graph.
+ *
+ * This class provides static methods for traversing Three.js scene hierarchies,
+ * searching for specific objects or materials, and performing batch operations
+ * on collections of scene objects.
+ *
+ * All methods perform depth-first traversal of the scene graph starting from
+ * the provided root object and recursively processing all children.
  */
-class GeometryHasher {
-    /**
-     * Creates a hash for a geometry based on its vertex data.
-     * Vertices that differ by less than tolerance are considered the same.
-     *
-     * @param geometry - Geometry to hash
-     * @param tolerance - How close vertices need to be to count as identical
-     * @returns Hash string that's the same for matching geometries
-     * @internal
-     */
-    static getGeometryHash(geometry, tolerance) {
-        const position = geometry.attributes["position"];
-        const positionArray = position.array;
-        const positionHashParts = [];
-        // Sample vertex positions with tolerance
-        for (let i = 0; i < positionArray.length; i += POSITION_COMPONENT_COUNT) {
-            const x = Math.round(positionArray[i] / tolerance);
-            const y = Math.round(positionArray[i + 1] / tolerance);
-            const z = Math.round(positionArray[i + 2] / tolerance);
-            positionHashParts.push(`${x},${y},${z}`);
-        }
-        // Hash normal data if available
-        const normal = geometry.attributes["normal"];
-        const normalHashParts = [];
-        const normalArray = normal.array;
-        for (let i = 0; i < normalArray.length; i += NORMAL_COMPONENT_COUNT) {
-            const x = Math.round(normalArray[i] / tolerance);
-            const y = Math.round(normalArray[i + 1] / tolerance);
-            const z = Math.round(normalArray[i + 2] / tolerance);
-            normalHashParts.push(`${x},${y},${z}`);
-        }
-        // Combine position and normal hashes
-        const positionHash = positionHashParts.join("|");
-        const normalHash = normalHashParts.join("|");
-        return `${positionHash}#${normalHash}`;
-    }
-}
-
-/** Find and modify objects in a Three.js scene */
 class SceneTraversal {
-    /** Find first object with exact name match */
+    /**
+     * Finds the first object in the scene hierarchy with an exact name match.
+     *
+     * Performs a depth-first search through the scene graph starting from the provided
+     * root object. Returns the first object encountered whose name property exactly
+     * matches the search string.
+     *
+     * @param object - The root Object3D to start searching from
+     * @param name - The exact name to search for (case-sensitive)
+     * @returns The first matching Object3D, or null if no match is found
+  
+     */
     static getObjectByName(object, name) {
         if (object.name === name) {
             return object;
@@ -296,7 +317,19 @@ class SceneTraversal {
         }
         return null;
     }
-    /** Find first material with exact name match */
+    /**
+     * Finds the first material in the scene hierarchy with an exact name match.
+     *
+     * Performs a depth-first search through the scene graph, examining materials
+     * attached to Mesh objects. Handles both single materials and material arrays.
+     * Returns the first material encountered whose name property exactly matches
+     * the search string.
+     *
+     * @param object - The root Object3D to start searching from
+     * @param name - The exact material name to search for (case-sensitive)
+     * @returns The first matching Material, or null if no match is found
+  
+     */
     static getMaterialByName(object, name) {
         if (object instanceof Mesh) {
             if (Array.isArray(object.material)) {
@@ -318,7 +351,19 @@ class SceneTraversal {
         }
         return null;
     }
-    /** Process all objects of a specific type */
+    /**
+     * Processes all objects of a specific type in the scene hierarchy.
+     *
+     * Performs a depth-first traversal and executes the provided callback function
+     * for every object that is an instance of the specified type. This is useful
+     * for batch operations on specific object types (e.g., all lights, all meshes, etc.).
+     *
+     * @template T - The type of objects to process
+     * @param object - The root Object3D to start searching from
+     * @param type - The constructor/class to filter by (e.g., DirectionalLight, Mesh)
+     * @param callback - Function to execute for each matching object instance
+  
+     */
     static enumerateObjectsByType(object, type, callback) {
         if (object instanceof type) {
             callback(object);
@@ -327,7 +372,17 @@ class SceneTraversal {
             SceneTraversal.enumerateObjectsByType(child, type, callback);
         }
     }
-    /** Process all materials in meshes */
+    /**
+     * Processes all materials found in mesh objects within the scene hierarchy.
+     *
+     * Performs a depth-first traversal, finding all Mesh objects and executing
+     * the provided callback function for each material. Handles both single
+     * materials and material arrays properly.
+     *
+     * @param object - The root Object3D to start searching from
+     * @param callback - Function to execute for each material found
+  
+     */
     static enumerateMaterials(object, callback) {
         if (object instanceof Mesh) {
             if (Array.isArray(object.material)) {
@@ -343,7 +398,18 @@ class SceneTraversal {
             SceneTraversal.enumerateMaterials(child, callback);
         }
     }
-    /** Find all objects whose names match a pattern */
+    /**
+     * Finds all objects in the scene hierarchy that match the specified filter criteria.
+     *
+     * Performs a depth-first search and collects all objects that either match
+     * a regular expression pattern (applied to the object's name) or satisfy
+     * a custom predicate function.
+     *
+     * @param object - The root Object3D to start searching from
+     * @param filter - Either a RegExp to test against object names, or a predicate function
+     * @returns Array of all matching Object3D instances
+  
+     */
     static filterObjects(object, filter) {
         let result = [];
         if (typeof filter === "function") {
@@ -361,7 +427,18 @@ class SceneTraversal {
         }
         return result;
     }
-    /** Find all materials whose names match a pattern */
+    /**
+     * Finds all materials in the scene hierarchy whose names match a regular expression pattern.
+     *
+     * Performs a depth-first search through all Mesh objects and collects materials
+     * whose name property matches the provided regular expression. Handles both
+     * single materials and material arrays properly.
+     *
+     * @param object - The root Object3D to start searching from
+     * @param name - Regular expression pattern to test against material names
+     * @returns Array of all matching Material instances
+  
+     */
     static filterMaterials(object, name) {
         let result = [];
         if (object instanceof Mesh) {
@@ -383,194 +460,42 @@ class SceneTraversal {
         }
         return result;
     }
-    /** Set shadow properties on meshes */
-    static setShadowRecursive(object, castShadow = true, receiveShadow = true, filter) {
-        if (object instanceof Mesh || "isMesh" in object) {
-            object.castShadow = castShadow;
-            object.receiveShadow = receiveShadow;
-        }
-        for (const child of object.children) {
-            SceneTraversal.setShadowRecursive(child, castShadow, receiveShadow, filter);
-        }
-    }
-}
-
-const MIN_INSTANCE_COUNT = 2;
-const DEFAULT_TOLERANCE = 1e-6;
-/**
- * Combines identical meshes into instanced versions for better performance.
- * Meshes are considered identical if they share the same geometry and materials.
- */
-class InstanceAssembler {
-    /**
-     * Find meshes that can be instanced and combine them.
-     * Only processes meshes that:
-     * - Have no children
-     * - Pass the filter function (if any)
-     * - Share geometry with at least one other mesh
-     *
-     * @param container - Object containing meshes to process
-     * @param options - Optional settings
-     */
-    static assemble(container, options = {}) {
-        var _a, _b;
-        const dictionary = new Map();
-        const instances = [];
-        const tolerance = (_a = options.geometryTolerance) !== null && _a !== void 0 ? _a : DEFAULT_TOLERANCE;
-        const geometryHashes = new Map();
-        SceneTraversal.enumerateObjectsByType(container, Mesh, (child) => {
-            var _a;
-            if (child.children.length === 0 &&
-                (!options.filter || options.filter(child))) {
-                const materials = Array.isArray(child.material)
-                    ? child.material
-                    : [child.material];
-                let geometryHash = geometryHashes.get(child.geometry.uuid);
-                if (!geometryHash) {
-                    geometryHash = GeometryHasher.getGeometryHash(child.geometry, tolerance);
-                    geometryHashes.set(child.geometry.uuid, geometryHash);
-                }
-                const materialKey = materials.map((m) => m.uuid).join(",");
-                const compositeKey = `${geometryHash}|${materialKey}`;
-                const entry = (_a = dictionary.get(compositeKey)) !== null && _a !== void 0 ? _a : {
-                    meshes: [],
-                    materials,
-                    castShadow: false,
-                    receiveShadow: false,
-                };
-                if (child.castShadow) {
-                    entry.castShadow = true;
-                }
-                if (child.receiveShadow) {
-                    entry.receiveShadow = true;
+    /**
+     * Finds all objects (mesh users) that use materials with names matching a regular expression pattern.
+     *
+     * Performs a depth-first search through all Mesh objects and collects the mesh objects
+     * whose materials have names that match the provided regular expression. This is useful
+     * for finding all objects that use specific material types or naming patterns.
+     *
+     * @param object - The root Object3D to start searching from
+     * @param materialName - Regular expression pattern to test against material names
+     * @returns Array of all Mesh objects that use materials with matching names
+     */
+    static findMaterialUsers(object, materialName) {
+        let result = [];
+        if (object instanceof Mesh) {
+            let hasMatchingMaterial = false;
+            if (Array.isArray(object.material)) {
+                for (const material of object.material) {
+                    if (material.name && materialName.test(material.name)) {
+                        hasMatchingMaterial = true;
+                        break;
+                    }
                 }
-                entry.meshes.push(child);
-                dictionary.set(compositeKey, entry);
             }
-        });
-        for (const descriptor of dictionary.values()) {
-            if (descriptor.meshes.length < MIN_INSTANCE_COUNT) {
-                continue;
-            }
-            const { meshes, materials, castShadow, receiveShadow } = descriptor;
-            const sortedMeshes = meshes.sort((a, b) => a.name.localeCompare(b.name));
-            const defaultMesh = sortedMeshes[0];
-            const instancedMesh = new InstancedMesh(defaultMesh.geometry, materials.length === 1 ? materials[0] : materials, sortedMeshes.length);
-            instancedMesh.name = defaultMesh.name;
-            instancedMesh.castShadow = castShadow;
-            instancedMesh.receiveShadow = receiveShadow;
-            for (let i = 0; i < sortedMeshes.length; i++) {
-                const mesh = sortedMeshes[i];
-                mesh.updateWorldMatrix(true, false);
-                instancedMesh.setMatrixAt(i, mesh.matrixWorld);
-                instancedMesh.userData[mesh.uuid] = mesh.userData;
+            else {
+                if (object.material.name && materialName.test(object.material.name)) {
+                    hasMatchingMaterial = true;
+                }
             }
-            instancedMesh.instanceMatrix.needsUpdate = true;
-            instances.push(instancedMesh);
-            for (const mesh of sortedMeshes) {
-                (_b = mesh.parent) === null || _b === void 0 ? void 0 : _b.remove(mesh);
+            if (hasMatchingMaterial) {
+                result.push(object);
             }
         }
-        if (instances.length > 0) {
-            container.add(...instances);
-        }
-    }
-}
-
-/**
- * Clones the given 3D object and its descendants, ensuring that any `SkinnedMesh` instances are
- * correctly associated with their bones. Bones are also cloned, and must be descendants of the
- * object passed to this method. Other data, like geometries and materials, are reused by reference.
- *
- * @param {Object3D} source - The 3D object to clone.
- * @return {Object3D} The cloned 3D object.
- */
-function clone( source ) {
-
-	const sourceLookup = new Map();
-	const cloneLookup = new Map();
-
-	const clone = source.clone();
-
-	parallelTraverse( source, clone, function ( sourceNode, clonedNode ) {
-
-		sourceLookup.set( clonedNode, sourceNode );
-		cloneLookup.set( sourceNode, clonedNode );
-
-	} );
-
-	clone.traverse( function ( node ) {
-
-		if ( ! node.isSkinnedMesh ) return;
-
-		const clonedMesh = node;
-		const sourceMesh = sourceLookup.get( node );
-		const sourceBones = sourceMesh.skeleton.bones;
-
-		clonedMesh.skeleton = sourceMesh.skeleton.clone();
-		clonedMesh.bindMatrix.copy( sourceMesh.bindMatrix );
-
-		clonedMesh.skeleton.bones = sourceBones.map( function ( bone ) {
-
-			return cloneLookup.get( bone );
-
-		} );
-
-		clonedMesh.bind( clonedMesh.skeleton, clonedMesh.bindMatrix );
-
-	} );
-
-	return clone;
-
-}
-
-function parallelTraverse( a, b, callback ) {
-
-	callback( a, b );
-
-	for ( let i = 0; i < a.children.length; i ++ ) {
-
-		parallelTraverse( a.children[ i ], b.children[ i ], callback );
-
-	}
-
-}
-
-/** Post-processes a scene based on name patterns */
-class SceneProcessor {
-    /**
-     * Process a scene to set up materials and shadows.
-     *
-     * @param object - Scene to process
-     * @param options - How to process the scene
-     * @returns Processed scene root objects
-     */
-    static process(object, options) {
-        const container = options.cloneAsset !== false ? clone(object) : object;
-        if (options.assembleInstances !== false) {
-            InstanceAssembler.assemble(container);
+        for (const child of object.children) {
+            result = result.concat(SceneTraversal.findMaterialUsers(child, materialName));
         }
-        SceneTraversal.enumerateMaterials(container, (material) => {
-            var _a, _b, _c, _d, _e, _f, _g;
-            material.transparent =
-                (_b = (_a = options.transparentMaterialRegExp) === null || _a === void 0 ? void 0 : _a.test(material.name)) !== null && _b !== void 0 ? _b : false;
-            material.depthWrite = !((_d = (_c = options.noDepthWriteMaterialRegExp) === null || _c === void 0 ? void 0 : _c.test(material.name)) !== null && _d !== void 0 ? _d : false);
-            material.alphaTest = ((_e = options.alphaTestMaterialRegExp) === null || _e === void 0 ? void 0 : _e.test(material.name))
-                ? 0.5
-                : 0;
-            material.alphaHash =
-                (_g = (_f = options.alphaHashMaterialRegExp) === null || _f === void 0 ? void 0 : _f.test(material.name)) !== null && _g !== void 0 ? _g : false;
-            material.side = FrontSide;
-            material.forceSinglePass = true;
-            material.depthTest = true;
-        });
-        SceneTraversal.enumerateObjectsByType(container, Mesh, (child) => {
-            var _a, _b, _c, _d;
-            child.castShadow = (_b = (_a = options.castShadowRegExp) === null || _a === void 0 ? void 0 : _a.test(child.name)) !== null && _b !== void 0 ? _b : false;
-            child.receiveShadow =
-                (_d = (_c = options.receiveShadowRegExp) === null || _c === void 0 ? void 0 : _c.test(child.name)) !== null && _d !== void 0 ? _d : false;
-        });
-        return container.children;
+        return result;
     }
 }
 
@@ -625,75 +550,118 @@ class SkinnedMeshBaker {
     }
 }
 
+/** Number of color channels in RGBA format */
 const RGBA_CHANNEL_COUNT = 4;
+/** Number of color channels in RGB format */
 const RGB_CHANNEL_COUNT = 3;
+/** Red channel weight for luminance calculation (ITU-R BT.709) */
 const LUMINANCE_R = 0.2126;
+/** Green channel weight for luminance calculation (ITU-R BT.709) */
 const LUMINANCE_G = 0.7152;
+/** Blue channel weight for luminance calculation (ITU-R BT.709) */
 const LUMINANCE_B = 0.0722;
-/** A directional light with spherical positioning controls */
+/**
+ * A directional light with spherical positioning controls and advanced shadow mapping.
+ *
+ * Extends Three.js DirectionalLight to provide intuitive spherical coordinate control
+ * (distance, elevation, azimuth) and automatic shadow map configuration for bounding boxes.
+ * Also supports automatic sun direction calculation from HDR environment maps.
+ */
 class Sun extends DirectionalLight {
     constructor() {
         super(...arguments);
-        /** Internal vectors to avoid garbage collection */
-        this.tempVector3D0 = new Vector3();
-        this.tempVector3D1 = new Vector3();
-        this.tempVector3D2 = new Vector3();
-        this.tempVector3D3 = new Vector3();
-        this.tempVector3D4 = new Vector3();
-        this.tempVector3D5 = new Vector3();
-        this.tempVector3D6 = new Vector3();
-        this.tempVector3D7 = new Vector3();
-        this.tempBox3 = new Box3();
-        this.tempSpherical = new Spherical();
-    }
-    /** Distance from the light to its target */
+        /** Internal vectors to avoid garbage collection during calculations */
+        this._private_tempVector3D0 = new Vector3();
+        this._private_tempVector3D1 = new Vector3();
+        this._private_tempVector3D2 = new Vector3();
+        this._private_tempVector3D3 = new Vector3();
+        this._private_tempVector3D4 = new Vector3();
+        this._private_tempVector3D5 = new Vector3();
+        this._private_tempVector3D6 = new Vector3();
+        this._private_tempVector3D7 = new Vector3();
+        this._private_tempBox3 = new Box3();
+        this._private_tempSpherical = new Spherical();
+    }
+    /**
+     * Gets the distance from the light to its target (origin).
+     *
+     * @returns The distance in world units
+     */
     get distance() {
         return this.position.length();
     }
-    /** Vertical angle from the ground in radians */
+    /**
+     * Gets the elevation angle (vertical angle from the horizontal plane).
+     *
+     * @returns The elevation angle in radians (0 = horizontal, π/2 = directly above)
+     */
     get elevation() {
-        return this.tempSpherical.setFromVector3(this.position).phi;
+        return this._private_tempSpherical.setFromVector3(this.position).phi;
     }
-    /** Horizontal angle around the target in radians */
+    /**
+     * Gets the azimuth angle (horizontal rotation around the target).
+     *
+     * @returns The azimuth angle in radians (0 = positive X axis, π/2 = positive Z axis)
+     */
     get azimuth() {
-        return this.tempSpherical.setFromVector3(this.position).theta;
+        return this._private_tempSpherical.setFromVector3(this.position).theta;
     }
-    /** Set distance while keeping current angles */
+    /**
+     * Sets the distance while preserving current elevation and azimuth angles.
+     *
+     * @param value - The new distance in world units
+     */
     set distance(value) {
-        this.tempSpherical.setFromVector3(this.position);
-        this.position.setFromSphericalCoords(value, this.tempSpherical.phi, this.tempSpherical.theta);
+        this._private_tempSpherical.setFromVector3(this.position);
+        this.position.setFromSphericalCoords(value, this._private_tempSpherical.phi, this._private_tempSpherical.theta);
     }
-    /** Set elevation while keeping current distance and azimuth */
+    /**
+     * Sets the elevation angle while preserving current distance and azimuth.
+     *
+     * @param value - The new elevation angle in radians (0 = horizontal, π/2 = directly above)
+     */
     set elevation(value) {
-        this.tempSpherical.setFromVector3(this.position);
-        this.position.setFromSphericalCoords(this.tempSpherical.radius, value, this.tempSpherical.theta);
+        this._private_tempSpherical.setFromVector3(this.position);
+        this.position.setFromSphericalCoords(this._private_tempSpherical.radius, value, this._private_tempSpherical.theta);
     }
-    /** Set azimuth while keeping current distance and elevation */
+    /**
+     * Sets the azimuth angle while preserving current distance and elevation.
+     *
+     * @param value - The new azimuth angle in radians (0 = positive X axis, π/2 = positive Z axis)
+     */
     set azimuth(value) {
-        this.tempSpherical.setFromVector3(this.position);
-        this.position.setFromSphericalCoords(this.tempSpherical.radius, this.tempSpherical.phi, value);
+        this._private_tempSpherical.setFromVector3(this.position);
+        this.position.setFromSphericalCoords(this._private_tempSpherical.radius, this._private_tempSpherical.phi, value);
     }
-    /** Configure shadows to cover all corners of a bounding box */
-    setShadowMapFromBox3(box3) {
+    /**
+     * Configures the shadow camera to optimally cover a bounding box.
+     *
+     * This method automatically adjusts the directional light's shadow camera frustum
+     * to perfectly encompass the provided bounding box, ensuring efficient shadow map
+     * usage and eliminating shadow clipping issues.
+     *
+     * @param box3 - The 3D bounding box to cover with shadows
+     */
+    configureShadowsForBoundingBox(box3) {
         const camera = this.shadow.camera;
         this.target.updateWorldMatrix(true, false);
-        this.lookAt(this.target.getWorldPosition(this.tempVector3D0));
+        this.lookAt(this.target.getWorldPosition(this._private_tempVector3D0));
         this.updateWorldMatrix(true, false);
         const points = [
-            this.tempVector3D0.set(box3.min.x, box3.min.y, box3.min.z),
-            this.tempVector3D1.set(box3.min.x, box3.min.y, box3.max.z),
-            this.tempVector3D2.set(box3.min.x, box3.max.y, box3.min.z),
-            this.tempVector3D3.set(box3.min.x, box3.max.y, box3.max.z),
-            this.tempVector3D4.set(box3.max.x, box3.min.y, box3.min.z),
-            this.tempVector3D5.set(box3.max.x, box3.min.y, box3.max.z),
-            this.tempVector3D6.set(box3.max.x, box3.max.y, box3.min.z),
-            this.tempVector3D7.set(box3.max.x, box3.max.y, box3.max.z),
+            this._private_tempVector3D0.set(box3.min.x, box3.min.y, box3.min.z),
+            this._private_tempVector3D1.set(box3.min.x, box3.min.y, box3.max.z),
+            this._private_tempVector3D2.set(box3.min.x, box3.max.y, box3.min.z),
+            this._private_tempVector3D3.set(box3.min.x, box3.max.y, box3.max.z),
+            this._private_tempVector3D4.set(box3.max.x, box3.min.y, box3.min.z),
+            this._private_tempVector3D5.set(box3.max.x, box3.min.y, box3.max.z),
+            this._private_tempVector3D6.set(box3.max.x, box3.max.y, box3.min.z),
+            this._private_tempVector3D7.set(box3.max.x, box3.max.y, box3.max.z),
         ];
         const inverseMatrix = this.matrixWorld.clone().invert();
         for (const point of points) {
             point.applyMatrix4(inverseMatrix);
         }
-        const newBox3 = this.tempBox3.setFromPoints(points);
+        const newBox3 = this._private_tempBox3.setFromPoints(points);
         camera.left = newBox3.min.x;
         camera.bottom = newBox3.min.y;
         camera.near = -newBox3.max.z;
@@ -703,8 +671,17 @@ class Sun extends DirectionalLight {
         camera.updateWorldMatrix(true, false);
         camera.updateProjectionMatrix();
     }
-    /** Set light direction based on brightest point in an HDR texture */
-    setDirectionFromHDR(texture, distance = 1) {
+    /**
+     * Sets the sun's direction based on the brightest point in an HDR environment map.
+     *
+     * This method analyzes an HDR texture to find the pixel with the highest luminance
+     * value and positions the sun to shine from that direction. This is useful for
+     * creating realistic lighting that matches HDR environment maps.
+     *
+     * @param texture - The HDR texture to analyze (must have image data available)
+     * @param distance - The distance to place the sun from the origin (defaults to 1)
+     */
+    setDirectionFromHDRTexture(texture, distance = 1) {
         const data = texture.image.data;
         const width = texture.image.width;
         const height = texture.image.height;
@@ -734,5 +711,5 @@ class Sun extends DirectionalLight {
     }
 }
 
-export { BiFovCamera, Bounds, InstanceAssembler, SceneProcessor, SceneTraversal, SkinnedMeshBaker, Sun };
+export { DualFovCamera, SceneTraversal, SkinnedMeshBaker, Sun };
 //# sourceMappingURL=index.js.map