three-zoo 0.5.5 → 0.6.0

package/dist/index.js

@@ -15,19 +15,15 @@ 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.
+ * Camera with independent horizontal and vertical FOV settings.
  */
 class DualFovCamera extends PerspectiveCamera {
     /**
-     * Creates a new DualFovCamera instance.
-     *
-     * @param horizontalFov - Horizontal field of view in degrees. Clamped between 1° and 179°.
-     * @param verticalFov - Vertical field of view in degrees. Clamped between 1° and 179°.
-     * @param aspect - Camera aspect ratio (width/height).
-     * @param near - Near clipping plane distance.
-     * @param far - Far clipping plane distance.
+     * @param horizontalFov - Horizontal FOV in degrees (clamped 1-179°)
+     * @param verticalFov - Vertical FOV in degrees (clamped 1-179°)
+     * @param aspect - Aspect ratio (width/height)
+     * @param near - Near clipping plane distance
+     * @param far - Far clipping plane distance
      */
     constructor(horizontalFov = DEFAULT_HORIZONTAL_FOV, verticalFov = DEFAULT_VERTICAL_FOV, aspect = DEFAULT_ASPECT, near = DEFAULT_NEAR, far = DEFAULT_FAR) {
         super(verticalFov, aspect, near, far);
@@ -36,44 +32,36 @@ class DualFovCamera extends PerspectiveCamera {
         this.updateProjectionMatrix();
     }
     /**
-     * Gets the horizontal field of view in degrees.
-     *
-     * @returns The horizontal FOV value
+     * @returns Horizontal FOV in degrees
      */
     get horizontalFov() {
         return this._private_horizontalFovInternal;
     }
     /**
-     * Gets the vertical field of view in degrees.
-     *
-     * @returns The vertical FOV value
+     * @returns Vertical FOV in degrees
      */
     get verticalFov() {
         return this._private_verticalFovInternal;
     }
     /**
-     * Sets the horizontal field of view in degrees.
-     *
-     * @param value - The horizontal FOV value in degrees. Clamped between 1° and 179°.
+     * @param value - Horizontal FOV in degrees (clamped 1-179°)
      */
     set horizontalFov(value) {
         this._private_horizontalFovInternal = MathUtils.clamp(value, MIN_FOV, MAX_FOV);
         this.updateProjectionMatrix();
     }
     /**
-     * Sets the vertical field of view in degrees.
-     *
-     * @param value - The vertical FOV value in degrees. Clamped between 1° and 179°.
+     * @param value - Vertical FOV in degrees (clamped 1-179°)
      */
     set verticalFov(value) {
         this._private_verticalFovInternal = MathUtils.clamp(value, MIN_FOV, MAX_FOV);
         this.updateProjectionMatrix();
     }
     /**
-     * Sets both horizontal and vertical field of view values.
+     * Sets both FOV values.
      *
-     * @param horizontal - Horizontal FOV in degrees. Clamped between 1° and 179°.
-     * @param vertical - Vertical FOV in degrees. Clamped between 1° and 179°.
+     * @param horizontal - Horizontal FOV in degrees (clamped 1-179°)
+     * @param vertical - Vertical FOV in degrees (clamped 1-179°)
      */
     setFov(horizontal, vertical) {
         this._private_horizontalFovInternal = MathUtils.clamp(horizontal, MIN_FOV, MAX_FOV);
@@ -81,9 +69,9 @@ class DualFovCamera extends PerspectiveCamera {
         this.updateProjectionMatrix();
     }
     /**
-     * Copies the field of view settings from another DualFovCamera.
+     * Copies FOV settings from another DualFovCamera.
      *
-     * @param source - The DualFovCamera to copy FOV settings from.
+     * @param source - Source camera to copy from
      */
     copyFovSettings(source) {
         this._private_horizontalFovInternal = source.horizontalFov;
@@ -91,13 +79,10 @@ class DualFovCamera extends PerspectiveCamera {
         this.updateProjectionMatrix();
     }
     /**
-     * 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
+     * Updates projection matrix based on FOV and aspect ratio.
      *
-     * Called when FOV values or aspect ratio changes.
+     * Landscape (aspect > 1): preserves horizontal FOV.
+     * Portrait (aspect ≤ 1): preserves vertical FOV.
      *
      * @override
      */
@@ -114,12 +99,9 @@ class DualFovCamera extends PerspectiveCamera {
         super.updateProjectionMatrix();
     }
     /**
-     * Gets the horizontal field of view after aspect ratio adjustments.
+     * Gets actual horizontal FOV after aspect ratio adjustments.
      *
-     * In landscape mode, returns the set horizontal FOV.
-     * In portrait mode, calculates the horizontal FOV from vertical FOV and aspect ratio.
-     *
-     * @returns The horizontal FOV in degrees
+     * @returns Horizontal FOV in degrees
      */
     getActualHorizontalFov() {
         if (this.aspect >= 1) {
@@ -129,12 +111,9 @@ class DualFovCamera extends PerspectiveCamera {
         return MathUtils.radToDeg(Math.atan(Math.tan(verticalRadians / 2) * this.aspect) * 2);
     }
     /**
-     * Gets the vertical field of view after aspect ratio adjustments.
-     *
-     * In portrait mode, returns the set vertical FOV.
-     * In landscape mode, calculates the vertical FOV from horizontal FOV and aspect ratio.
+     * Gets actual vertical FOV after aspect ratio adjustments.
      *
-     * @returns The vertical FOV in degrees
+     * @returns Vertical FOV in degrees
      */
     getActualVerticalFov() {
         if (this.aspect < 1) {
@@ -144,10 +123,7 @@ class DualFovCamera extends PerspectiveCamera {
         return MathUtils.radToDeg(Math.atan(Math.tan(horizontalRadians / 2) / this.aspect) * 2);
     }
     /**
-     * Adjusts the vertical field of view to fit specified points within the camera's view.
-     *
-     * Calculates the required vertical FOV to ensure all provided vertices
-     * are visible within the vertical bounds of the camera's frustum.
+     * Adjusts vertical FOV to fit points within camera view.
      *
      * @param vertices - Array of 3D points in world coordinates
      */
@@ -168,12 +144,9 @@ class DualFovCamera extends PerspectiveCamera {
         this.updateProjectionMatrix();
     }
     /**
-     * Adjusts the vertical field of view to fit a bounding box within the camera's view.
+     * Adjusts vertical FOV to fit bounding box within camera view.
      *
-     * Calculates the required vertical FOV to ensure the bounding box
-     * is visible within the vertical bounds of the camera's frustum.
-     *
-     * @param box - The 3D bounding box in world coordinates
+     * @param box - 3D bounding box in world coordinates
      */
     fitVerticalFovToBox(box) {
         this.fitVerticalFovToPoints([
@@ -188,13 +161,10 @@ class DualFovCamera extends PerspectiveCamera {
         ]);
     }
     /**
-     * Adjusts the vertical field of view to fit a skinned mesh within the camera's view.
-     *
-     * Updates the mesh's skeleton, applies bone transformations to vertices,
-     * and calculates the required vertical FOV to fit the deformed mesh
-     * within the vertical bounds of the camera's frustum.
+     * Adjusts vertical FOV to fit skinned mesh within camera view.
+     * Updates skeleton and applies bone transformations.
      *
-     * @param skinnedMesh - The skinned mesh with active skeleton
+     * @param skinnedMesh - Skinned mesh with active skeleton
      */
     fitVerticalFovToMesh(skinnedMesh) {
         skinnedMesh.updateWorldMatrix(true, true);
@@ -211,16 +181,10 @@ class DualFovCamera extends PerspectiveCamera {
         this.fitVerticalFovToPoints(points);
     }
     /**
-     * Points the camera to look at the center of mass of a skinned mesh.
+     * Points camera to look at skinned mesh center of mass.
+     * Uses iterative clustering to find main vertex concentration.
      *
-     * Updates the mesh's skeleton, applies bone transformations to vertices,
-     * calculates the center of mass using a clustering algorithm, and orients the camera
-     * to look at that point.
-     *
-     * The center of mass calculation uses iterative clustering to find the
-     * main concentration of vertices.
-     *
-     * @param skinnedMesh - The skinned mesh with active skeleton
+     * @param skinnedMesh - Skinned mesh with active skeleton
      */
     lookAtMeshCenterOfMass(skinnedMesh) {
         skinnedMesh.updateWorldMatrix(true, true);
@@ -235,11 +199,11 @@ class DualFovCamera extends PerspectiveCamera {
             points.push(target.clone());
         }
         /**
-         * Finds the main cluster center of 3D points using iterative refinement.
+         * Finds main cluster center using iterative refinement.
          *
          * @param points - Array of 3D points to cluster
          * @param iterations - Number of refinement iterations
-         * @returns The center point of the main cluster
+         * @returns Center point of main cluster
          */
         const findMainCluster = (points, iterations = 3) => {
             if (points.length === 0) {
@@ -266,12 +230,9 @@ class DualFovCamera extends PerspectiveCamera {
         this.lookAt(centerOfMass);
     }
     /**
-     * Creates a copy of this DualFovCamera.
-     *
-     * The cloned camera has identical FOV settings, position, rotation,
-     * and all other camera properties.
+     * Creates a copy of this camera with identical settings.
      *
-     * @returns A new DualFovCamera instance
+     * @returns New DualFovCamera instance
      * @override
      */
     clone() {
@@ -282,25 +243,17 @@ class DualFovCamera extends PerspectiveCamera {
 }
 
 /**
- * Utility class for finding and modifying objects in a Three.js scene graph.
+ * Static methods for traversing Three.js scene hierarchies.
  *
- * Provides static methods for traversing Three.js scene hierarchies,
- * searching for objects or materials, and performing batch operations.
- *
- * All methods perform depth-first traversal starting from the provided
- * root object and recursively processing all children.
+ * All methods use depth-first traversal.
  */
 class SceneTraversal {
     /**
-     * Finds the first object in the scene hierarchy with an exact name match.
-     *
-     * Performs depth-first search through the scene graph starting from the
-     * root object. Returns the first object whose name property matches
-     * the search string.
+     * Finds first object with exact name match.
      *
-     * @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
+     * @param object - Root object to start from
+     * @param name - Name to search for (case-sensitive)
+     * @returns First matching object or undefined
      */
     static getObjectByName(object, name) {
         if (object.name === name) {
@@ -312,18 +265,14 @@ class SceneTraversal {
                 return result;
             }
         }
-        return null;
+        return undefined;
     }
     /**
-     * Finds the first material in the scene hierarchy with an exact name match.
+     * Finds first material with exact name match from mesh objects.
      *
-     * Performs depth-first search through the scene graph, examining materials
-     * attached to Mesh objects. Handles both single materials and material arrays.
-     * Returns the first material whose name property 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
+     * @param object - Root object to start from
+     * @param name - Material name to search for (case-sensitive)
+     * @returns First matching material or undefined
      */
     static getMaterialByName(object, name) {
         if (object instanceof Mesh) {
@@ -344,18 +293,15 @@ class SceneTraversal {
                 return material;
             }
         }
-        return null;
+        return undefined;
     }
     /**
-     * Processes all objects of a specific type in the scene hierarchy.
-     *
-     * Performs depth-first traversal and executes the callback function
-     * for every object that is an instance of the specified type.
+     * Executes callback for all objects of specified type.
      *
-     * @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
+     * @template T - Type of objects to process
+     * @param object - Root object to start from
+     * @param type - Constructor to filter by
+     * @param callback - Function to execute for each matching object
      */
     static enumerateObjectsByType(object, type, callback) {
         if (object instanceof type) {
@@ -366,14 +312,47 @@ class SceneTraversal {
         }
     }
     /**
-     * Processes all materials found in mesh objects within the scene hierarchy.
+     * Executes callback for all materials of specified type from mesh objects.
      *
-     * Performs depth-first traversal, finding all Mesh objects and executing
-     * the callback function for each material. Handles both single
-     * materials and material arrays.
+     * @template T - Type of materials to process
+     * @param object - Root object to start from
+     * @param type - Constructor to filter by
+     * @param callback - Function to execute for each matching material
+     */
+    static enumerateMaterialsByType(object, type, callback) {
+        if (object instanceof Mesh) {
+            if (Array.isArray(object.material)) {
+                for (const material of object.material) {
+                    if (material instanceof type) {
+                        callback(material);
+                    }
+                }
+            }
+            else if (object.material instanceof type) {
+                callback(object.material);
+            }
+        }
+        for (const child of object.children) {
+            SceneTraversal.enumerateMaterialsByType(child, type, callback);
+        }
+    }
+    /**
+     * Executes callback for all objects in hierarchy.
+     *
+     * @param object - Root object to start from
+     * @param callback - Function to execute for each object
+     */
+    static enumerateObjects(object, callback) {
+        callback(object);
+        for (const child of object.children) {
+            SceneTraversal.enumerateObjects(child, callback);
+        }
+    }
+    /**
+     * Executes callback for all materials from mesh objects.
      *
-     * @param object - The root Object3D to start searching from
-     * @param callback - Function to execute for each material found
+     * @param object - Root object to start from
+     * @param callback - Function to execute for each material
      */
     static enumerateMaterials(object, callback) {
         if (object instanceof Mesh) {
@@ -391,15 +370,11 @@ class SceneTraversal {
         }
     }
     /**
-     * Finds all objects in the scene hierarchy that match filter criteria.
-     *
-     * Performs depth-first search and collects all objects that either match
-     * a regular expression pattern (applied to object names) or satisfy
-     * a predicate function.
+     * Returns all objects matching filter criteria.
      *
-     * @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
+     * @param object - Root object to start from
+     * @param filter - RegExp for object names or predicate function
+     * @returns Array of matching objects
      */
     static filterObjects(object, filter) {
         let result = [];
@@ -419,63 +394,62 @@ class SceneTraversal {
         return result;
     }
     /**
-     * Finds all materials in the scene hierarchy whose names match a pattern.
+     * Returns all materials matching filter criteria from mesh objects.
      *
-     * Performs depth-first search through all Mesh objects and collects materials
-     * whose name property matches the regular expression. Handles both
-     * single materials and material arrays.
-     *
-     * @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
+     * @param object - Root object to start from
+     * @param filter - RegExp for material names or predicate function
+     * @returns Array of matching materials
      */
-    static filterMaterials(object, name) {
+    static filterMaterials(object, filter) {
         let result = [];
         if (object instanceof Mesh) {
             if (Array.isArray(object.material)) {
                 for (const material of object.material) {
-                    if (material.name !== undefined && name.test(material.name)) {
+                    if (typeof filter === "function") {
+                        if (filter(material)) {
+                            result.push(material);
+                        }
+                    }
+                    else if (filter.test(material.name)) {
                         result.push(material);
                     }
                 }
             }
-            else {
-                if (object.material.name !== undefined &&
-                    name.test(object.material.name)) {
+            else if (typeof filter === "function") {
+                if (filter(object.material)) {
                     result.push(object.material);
                 }
             }
+            else if (filter.test(object.material.name)) {
+                result.push(object.material);
+            }
         }
         for (const child of object.children) {
-            result = result.concat(SceneTraversal.filterMaterials(child, name));
+            result = result.concat(SceneTraversal.filterMaterials(child, filter));
         }
         return result;
     }
     /**
-     * Finds all mesh objects that use materials with names matching a pattern.
-     *
-     * Performs depth-first search through all Mesh objects and collects mesh objects
-     * whose materials have names that match the regular expression.
+     * Returns all mesh objects that use any of the specified materials.
      *
-     * @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
+     * @param object - Root object to start from
+     * @param materials - Array of materials to search for
+     * @returns Array of mesh objects using the materials
      */
-    static findMaterialUsers(object, materialName) {
+    static findMaterialUsers(object, materials) {
         let result = [];
         if (object instanceof Mesh) {
             let hasMatchingMaterial = false;
             if (Array.isArray(object.material)) {
                 for (const material of object.material) {
-                    if (material.name !== undefined && materialName.test(material.name)) {
+                    if (materials.includes(material)) {
                         hasMatchingMaterial = true;
                         break;
                     }
                 }
             }
             else {
-                if (object.material.name !== undefined &&
-                    materialName.test(object.material.name)) {
+                if (materials.includes(object.material)) {
                     hasMatchingMaterial = true;
                 }
             }
@@ -484,22 +458,57 @@ class SceneTraversal {
             }
         }
         for (const child of object.children) {
-            result = result.concat(SceneTraversal.findMaterialUsers(child, materialName));
+            result = result.concat(SceneTraversal.findMaterialUsers(child, materials));
         }
         return result;
     }
+    /**
+     * Clones material by name and replaces all instances with the clone.
+     *
+     * @param object - Root object to start from
+     * @param name - Material name to search for (case-sensitive)
+     * @returns Cloned material or undefined if not found
+     */
+    static cloneMaterialByName(object, name) {
+        const originalMaterial = SceneTraversal.getMaterialByName(object, name);
+        if (!originalMaterial) {
+            return undefined;
+        }
+        const clonedMaterial = originalMaterial.clone();
+        SceneTraversal.replaceMaterial(object, originalMaterial, clonedMaterial);
+        return clonedMaterial;
+    }
+    /**
+     * Replaces all instances of a material with another material.
+     *
+     * @param object - Root object to start from
+     * @param oldMaterial - Material to replace
+     * @param newMaterial - Material to use as replacement
+     */
+    static replaceMaterial(object, oldMaterial, newMaterial) {
+        if (object instanceof Mesh) {
+            if (Array.isArray(object.material)) {
+                object.material = object.material.map((material) => material === oldMaterial ? newMaterial : material);
+            }
+            else if (object.material === oldMaterial) {
+                object.material = newMaterial;
+            }
+        }
+        for (const child of object.children) {
+            SceneTraversal.replaceMaterial(child, oldMaterial, newMaterial);
+        }
+    }
 }
 
 /** Number of components per vertex */
 const COMPONENT_COUNT = 3;
-/** Converts skinned meshes to static meshes */
+/** Converts skinned meshes to static meshes. */
 class SkinnedMeshBaker {
     /**
-     * Converts a skinned mesh to a static mesh in its current pose.
-     * The resulting mesh has no bones but looks identical.
+     * Converts skinned mesh to static mesh in current pose.
      *
      * @param skinnedMesh - Mesh to convert
-     * @returns Static mesh with baked vertex positions
+     * @returns Static mesh with baked positions
      */
     static bakePose(skinnedMesh) {
         const bakedGeometry = skinnedMesh.geometry.clone();
@@ -522,13 +531,13 @@ class SkinnedMeshBaker {
         return mesh;
     }
     /**
-     * Bakes a single frame from an animation into a static mesh.
+     * Bakes animation frame to static mesh.
      *
      * @param armature - Root object with bones
      * @param skinnedMesh - Mesh to convert
-     * @param timeOffset - Time in seconds within the animation
-     * @param clip - Animation to get the pose from
-     * @returns Static mesh with baked vertex positions
+     * @param timeOffset - Time in seconds within animation
+     * @param clip - Animation clip for pose
+     * @returns Static mesh with baked positions
      */
     static bakeAnimationFrame(armature, skinnedMesh, timeOffset, clip) {
         const mixer = new AnimationMixer(armature);
@@ -546,37 +555,15 @@ const METALNESS_BRIGHTNESS_FACTOR = 0.3;
 /** Factor for emissive color contribution when combining with base color */
 const EMISSIVE_CONTRIBUTION_FACTOR = 0.5;
 /**
- * Converts Three.js MeshStandardMaterial to MeshBasicMaterial.
- *
- * Handles translation from PBR StandardMaterial to unlit BasicMaterial.
- * Since BasicMaterial doesn't respond to lighting, applies compensation
- * techniques including brightness adjustments and emissive color combination.
+ * Converts MeshStandardMaterial to MeshBasicMaterial with brightness compensation.
  */
 class StandardToBasicConverter {
     /**
-     * Converts a MeshStandardMaterial to MeshBasicMaterial.
+     * Converts MeshStandardMaterial to MeshBasicMaterial.
      *
-     * Performs conversion from PBR StandardMaterial to unlit BasicMaterial
-     * with brightness compensation and property mapping.
-     *
-     * @param standardMaterial - The source MeshStandardMaterial to convert
-     * @param options - Configuration options for the conversion
-     * @returns A new MeshBasicMaterial with properties mapped from the standard material
-     *
-     * @example
-     * ```typescript
-     * const standardMaterial = new MeshStandardMaterial({
-     *   color: 0x00ff00,
-     *   metalness: 0.5,
-     *   emissive: 0x111111,
-     *   emissiveIntensity: 0.2
-     * });
-     *
-     * const basicMaterial = StandardToBasicConverter.convert(standardMaterial, {
-     *   brightnessFactor: 1.4,
-     *   combineEmissive: true
-     * });
-     * ```
+     * @param standardMaterial - Source material to convert
+     * @param options - Conversion options
+     * @returns New MeshBasicMaterial with mapped properties
      */
     static convert(standardMaterial, options = {}) {
         const config = {
@@ -605,11 +592,11 @@ class StandardToBasicConverter {
         return basicMaterial;
     }
     /**
-     * Copies basic material properties from source to target material.
+     * Copies basic material properties.
      *
-     * @param source - The source MeshStandardMaterial
-     * @param target - The target MeshBasicMaterial
-     * @param config - The resolved configuration options
+     * @param source - Source material
+     * @param target - Target material
+     * @param config - Configuration options
      * @internal
      */
     static copyBasicProperties(source, target, config) {
@@ -627,14 +614,11 @@ class StandardToBasicConverter {
         }
     }
     /**
-     * Converts color-related properties with lighting compensation.
+     * Converts color properties with lighting compensation.
      *
-     * Applies brightness compensation and optional emissive color combination
-     * to account for BasicMaterial's lack of lighting response.
-     *
-     * @param source - The source MeshStandardMaterial
-     * @param target - The target MeshBasicMaterial
-     * @param config - The resolved configuration options
+     * @param source - Source material
+     * @param target - Target material
+     * @param config - Configuration options
      * @internal
      */
     static convertColorProperties(source, target, config) {
@@ -660,13 +644,10 @@ class StandardToBasicConverter {
         target.color.b = Math.min(target.color.b, 1.0);
     }
     /**
-     * Converts and maps texture properties from Standard to Basic material.
-     *
-     * Transfers compatible texture maps including diffuse, alpha, environment,
-     * light, and AO maps.
+     * Converts texture properties from Standard to Basic material.
      *
-     * @param source - The source MeshStandardMaterial
-     * @param target - The target MeshBasicMaterial
+     * @param source - Source material
+     * @param target - Target material
      * @internal
      */
     static convertTextureMaps(source, target) {
@@ -703,10 +684,10 @@ class StandardToBasicConverter {
         this.copyUVTransforms(source, target);
     }
     /**
-     * Copies UV transformation properties for texture maps.
+     * Copies UV transformation properties.
      *
-     * @param source - The source MeshStandardMaterial
-     * @param target - The target MeshBasicMaterial
+     * @param source - Source material
+     * @param target - Target material
      * @internal
      */
     static copyUVTransforms(source, target) {
@@ -721,8 +702,8 @@ class StandardToBasicConverter {
     /**
      * Converts transparency and rendering properties.
      *
-     * @param source - The source MeshStandardMaterial
-     * @param target - The target MeshBasicMaterial
+     * @param source - Source material
+     * @param target - Target material
      * @internal
      */
     static convertTransparencyProperties(source, target) {
@@ -744,33 +725,15 @@ const ROUGHNESS_COLOR_ADJUSTMENT = 0.2;
 /** Minimum reflectivity boost for environment maps */
 const REFLECTIVITY_BOOST = 0.1;
 /**
- * Converts Three.js MeshStandardMaterial to MeshLambertMaterial.
- *
- * Handles translation between PBR properties of StandardMaterial and
- * the Lambertian reflectance model used by LambertMaterial. Applies
- * color compensation based on metalness and roughness values.
+ * Converts MeshStandardMaterial to MeshLambertMaterial with PBR compensation.
  */
 class StandardToLambertConverter {
     /**
-     * Converts a MeshStandardMaterial to MeshLambertMaterial.
-     *
-     * Performs conversion from PBR StandardMaterial to Lambert lighting model
-     * with color compensation based on metalness and roughness values.
-     *
-     * @param material - The source MeshStandardMaterial to convert
-     * @param options - Configuration options for the conversion
-     * @returns A new MeshLambertMaterial with properties mapped from the standard material
+     * Converts MeshStandardMaterial to MeshLambertMaterial.
      *
-     * @example
-     * ```typescript
-     * const standardMaterial = new MeshStandardMaterial({
-     *   color: 0xff0000,
-     *   metalness: 0.8,
-     *   roughness: 0.2
-     * });
-     *
-     * const lambertMaterial = StandardToLambertConverter.convert(standardMaterial);
-     * ```
+     * @param material - Source material to convert
+     * @param options - Conversion options
+     * @returns New MeshLambertMaterial with mapped properties
      */
     static convert(material, options = {}) {
         const config = {
@@ -798,11 +761,11 @@ class StandardToLambertConverter {
         return lambertMaterial;
     }
     /**
-     * Copies basic material properties from source to target material.
+     * Copies basic material properties.
      *
-     * @param source - The source MeshStandardMaterial
-     * @param target - The target MeshLambertMaterial
-     * @param config - The resolved configuration options
+     * @param source - Source material
+     * @param target - Target material
+     * @param config - Configuration options
      * @internal
      */
     static copyBasicProperties(source, target, config) {
@@ -821,14 +784,11 @@ class StandardToLambertConverter {
         }
     }
     /**
-     * Converts color-related properties with PBR compensation.
-     *
-     * Applies color adjustments to compensate for the loss of metalness and
-     * roughness information when converting to Lambert material.
+     * Converts color properties with PBR compensation.
      *
-     * @param source - The source MeshStandardMaterial
-     * @param target - The target MeshLambertMaterial
-     * @param config - The resolved configuration options
+     * @param source - Source material
+     * @param target - Target material
+     * @param config - Configuration options
      * @internal
      */
     static convertColorProperties(source, target, config) {
@@ -849,13 +809,10 @@ class StandardToLambertConverter {
         target.emissiveIntensity = source.emissiveIntensity;
     }
     /**
-     * Converts and maps texture properties from Standard to Lambert material.
+     * Converts texture properties from Standard to Lambert material.
      *
-     * Transfers compatible texture maps including diffuse, normal, emissive,
-     * AO, light maps, and environment maps.
-     *
-     * @param source - The source MeshStandardMaterial
-     * @param target - The target MeshLambertMaterial
+     * @param source - Source material
+     * @param target - Target material
      * @internal
      */
     static convertTextureMaps(source, target) {
@@ -895,10 +852,10 @@ class StandardToLambertConverter {
         this.copyUVTransforms(source, target);
     }
     /**
-     * Copies UV transformation properties for texture maps.
+     * Copies UV transformation properties.
      *
-     * @param source - The source MeshStandardMaterial
-     * @param target - The target MeshLambertMaterial
+     * @param source - Source material
+     * @param target - Target material
      * @internal
      */
     static copyUVTransforms(source, target) {
@@ -913,8 +870,8 @@ class StandardToLambertConverter {
     /**
      * Converts transparency and rendering properties.
      *
-     * @param source - The source MeshStandardMaterial
-     * @param target - The target MeshLambertMaterial
+     * @param source - Source material
+     * @param target - Target material
      * @internal
      */
     static convertTransparencyProperties(source, target) {
@@ -938,11 +895,7 @@ 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.
- *
- * Extends Three.js DirectionalLight to provide spherical coordinate control
- * (distance, elevation, azimuth) and shadow map configuration for bounding boxes.
- * Also supports sun direction calculation from HDR environment maps.
+ * Directional light with spherical positioning and HDR environment support.
  */
 class Sun extends DirectionalLight {
     constructor() {
@@ -960,64 +913,48 @@ class Sun extends DirectionalLight {
         this._private_tempSpherical = new Spherical();
     }
     /**
-     * Gets the distance from the light's position to the origin.
-     *
-     * @returns The distance in world units
+     * @returns Distance from light position to origin
      */
     get distance() {
         return this.position.length();
     }
     /**
-     * Gets the elevation angle from the spherical coordinates.
-     *
-     * @returns The elevation angle in radians (phi angle from Three.js Spherical coordinates)
+     * @returns Elevation angle in radians (phi angle)
      */
     get elevation() {
         return this._private_tempSpherical.setFromVector3(this.position).phi;
     }
     /**
-     * Gets the azimuth angle from the spherical coordinates.
-     *
-     * @returns The azimuth angle in radians (theta angle from Three.js Spherical coordinates)
+     * @returns Azimuth angle in radians (theta angle)
      */
     get azimuth() {
         return this._private_tempSpherical.setFromVector3(this.position).theta;
     }
     /**
-     * Sets the distance while preserving current elevation and azimuth angles.
-     *
-     * @param value - The new distance in world units
+     * @param value - New distance in world units
      */
     set distance(value) {
         this._private_tempSpherical.setFromVector3(this.position);
         this.position.setFromSphericalCoords(value, this._private_tempSpherical.phi, this._private_tempSpherical.theta);
     }
     /**
-     * Sets the elevation angle while preserving current distance and azimuth.
-     *
-     * @param value - The new elevation angle in radians (phi angle for Three.js Spherical coordinates)
+     * @param value - New elevation angle in radians (phi angle)
      */
     set elevation(value) {
         this._private_tempSpherical.setFromVector3(this.position);
         this.position.setFromSphericalCoords(this._private_tempSpherical.radius, value, this._private_tempSpherical.theta);
     }
     /**
-     * Sets the azimuth angle while preserving current distance and elevation.
-     *
-     * @param value - The new azimuth angle in radians (theta angle for Three.js Spherical coordinates)
+     * @param value - New azimuth angle in radians (theta angle)
      */
     set azimuth(value) {
         this._private_tempSpherical.setFromVector3(this.position);
         this.position.setFromSphericalCoords(this._private_tempSpherical.radius, this._private_tempSpherical.phi, value);
     }
     /**
-     * Configures the shadow camera frustum to cover a bounding box.
+     * Configures shadow camera frustum to cover bounding box.
      *
-     * Adjusts the directional light's shadow camera frustum to encompass the
-     * provided bounding box by transforming box corners to light space and
-     * setting camera bounds accordingly.
-     *
-     * @param box3 - The 3D bounding box to cover with shadows
+     * @param box3 - 3D bounding box to cover with shadows
      */
     configureShadowsForBoundingBox(box3) {
         const camera = this.shadow.camera;
@@ -1049,13 +986,10 @@ class Sun extends DirectionalLight {
         camera.updateProjectionMatrix();
     }
     /**
-     * Sets the sun's direction based on the brightest point in an HDR environment map.
-     *
-     * Analyzes an HDR texture to find the pixel with the highest luminance value
-     * and positions the sun to shine from that direction using spherical coordinates.
+     * Sets sun direction based on brightest point in HDR environment map.
      *
-     * @param texture - The HDR texture to analyze (must have image data available)
-     * @param distance - The distance to place the sun from the origin
+     * @param texture - HDR texture to analyze (must have image data)
+     * @param distance - Distance to place sun from origin
      */
     setDirectionFromHDRTexture(texture, distance = 1) {
         const data = texture.image.data;