three-zoo 0.5.3 → 0.5.5

package/dist/index.js

@@ -1,4 +1,4 @@
-import { PerspectiveCamera, MathUtils, Vector3, Mesh, BufferAttribute, AnimationMixer, DirectionalLight, Box3, Spherical, RGBAFormat } from 'three';
+import { PerspectiveCamera, MathUtils, Vector3, Mesh, BufferAttribute, AnimationMixer, MeshBasicMaterial, MeshLambertMaterial, DirectionalLight, Box3, Spherical, RGBAFormat } from 'three';
 
 /** Default horizontal field of view in degrees */
 const DEFAULT_HORIZONTAL_FOV = 90;
@@ -21,13 +21,13 @@ const MAX_FOV = 179;
  */
 class DualFovCamera extends PerspectiveCamera {
     /**
-     * Creates a new DualFovCamera instance with independent horizontal and vertical FOV control.
+     * Creates a new DualFovCamera instance.
      *
-     * @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.
+     * @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.
      */
     constructor(horizontalFov = DEFAULT_HORIZONTAL_FOV, verticalFov = DEFAULT_VERTICAL_FOV, aspect = DEFAULT_ASPECT, near = DEFAULT_NEAR, far = DEFAULT_FAR) {
         super(verticalFov, aspect, near, far);
@@ -36,17 +36,17 @@ class DualFovCamera extends PerspectiveCamera {
         this.updateProjectionMatrix();
     }
     /**
-     * Gets the current horizontal field of view in degrees.
+     * Gets the horizontal field of view in degrees.
      *
-     * @returns The horizontal FOV value between 1° and 179°
+     * @returns The horizontal FOV value
      */
     get horizontalFov() {
         return this._private_horizontalFovInternal;
     }
     /**
-     * Gets the current vertical field of view in degrees.
+     * Gets the vertical field of view in degrees.
      *
-     * @returns The vertical FOV value between 1° and 179°
+     * @returns The vertical FOV value
      */
     get verticalFov() {
         return this._private_verticalFovInternal;
@@ -54,7 +54,7 @@ class DualFovCamera extends PerspectiveCamera {
     /**
      * Sets the horizontal field of view in degrees.
      *
-     * @param value - The horizontal FOV value in degrees. Will be clamped between 1° and 179°.
+     * @param value - The horizontal FOV value in degrees. Clamped between 1° and 179°.
      */
     set horizontalFov(value) {
         this._private_horizontalFovInternal = MathUtils.clamp(value, MIN_FOV, MAX_FOV);
@@ -63,17 +63,17 @@ class DualFovCamera extends PerspectiveCamera {
     /**
      * Sets the vertical field of view in degrees.
      *
-     * @param value - The vertical FOV value in degrees. Will be clamped between 1° and 179°.
+     * @param value - The vertical FOV value in degrees. Clamped between 1° and 179°.
      */
     set verticalFov(value) {
         this._private_verticalFovInternal = MathUtils.clamp(value, MIN_FOV, MAX_FOV);
         this.updateProjectionMatrix();
     }
     /**
-     * Updates both horizontal and vertical field of view values simultaneously.
+     * Sets both horizontal and vertical field of view values.
      *
-     * @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°.
+     * @param horizontal - Horizontal FOV in degrees. Clamped between 1° and 179°.
+     * @param vertical - Vertical FOV in degrees. Clamped between 1° and 179°.
      */
     setFov(horizontal, vertical) {
         this._private_horizontalFovInternal = MathUtils.clamp(horizontal, MIN_FOV, MAX_FOV);
@@ -81,9 +81,9 @@ class DualFovCamera extends PerspectiveCamera {
         this.updateProjectionMatrix();
     }
     /**
-     * Copies the field of view settings from another DualFovCamera instance.
+     * Copies the field of view settings from another DualFovCamera.
      *
-     * @param source - The DualFovCamera instance to copy FOV settings from.
+     * @param source - The DualFovCamera to copy FOV settings from.
      */
     copyFovSettings(source) {
         this._private_horizontalFovInternal = source.horizontalFov;
@@ -97,7 +97,7 @@ class DualFovCamera extends PerspectiveCamera {
      * - **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.
+     * Called when FOV values or aspect ratio changes.
      *
      * @override
      */
@@ -114,12 +114,12 @@ class DualFovCamera extends PerspectiveCamera {
         super.updateProjectionMatrix();
     }
     /**
-     * Gets the actual horizontal field of view after aspect ratio adjustments.
+     * Gets the 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.
+     * In landscape mode, returns the set horizontal FOV.
+     * In portrait mode, calculates the horizontal FOV from vertical FOV and aspect ratio.
      *
-     * @returns The actual horizontal FOV in degrees
+     * @returns The horizontal FOV in degrees
      */
     getActualHorizontalFov() {
         if (this.aspect >= 1) {
@@ -129,12 +129,12 @@ class DualFovCamera extends PerspectiveCamera {
         return MathUtils.radToDeg(Math.atan(Math.tan(verticalRadians / 2) * this.aspect) * 2);
     }
     /**
-     * Gets the actual vertical field of view after aspect ratio adjustments.
+     * Gets the 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.
+     * In portrait mode, returns the set vertical FOV.
+     * In landscape mode, calculates the vertical FOV from horizontal FOV and aspect ratio.
      *
-     * @returns The actual vertical FOV in degrees
+     * @returns The vertical FOV in degrees
      */
     getActualVerticalFov() {
         if (this.aspect < 1) {
@@ -144,12 +144,12 @@ class DualFovCamera extends PerspectiveCamera {
         return MathUtils.radToDeg(Math.atan(Math.tan(horizontalRadians / 2) / this.aspect) * 2);
     }
     /**
-     * Adjusts the vertical field of view to fit all specified points within the camera's view.
+     * Adjusts the vertical field of view to fit specified points within the camera's view.
      *
-     * This method calculates the required vertical FOV to ensure all provided vertices
+     * 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
+     * @param vertices - Array of 3D points in world coordinates
      */
     fitVerticalFovToPoints(vertices) {
         const up = new Vector3(0, 1, 0).applyQuaternion(this.quaternion);
@@ -170,10 +170,10 @@ class DualFovCamera extends PerspectiveCamera {
     /**
      * 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
+     * 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) that should fit within the camera's vertical view
+     * @param box - The 3D bounding box in world coordinates
      */
     fitVerticalFovToBox(box) {
         this.fitVerticalFovToPoints([
@@ -190,11 +190,11 @@ class DualFovCamera extends PerspectiveCamera {
     /**
      * 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.
+     * 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.
      *
-     * @param skinnedMesh - The skinned mesh (with active skeleton) that should fit within the camera's vertical view
+     * @param skinnedMesh - The skinned mesh with active skeleton
      */
     fitVerticalFovToMesh(skinnedMesh) {
         skinnedMesh.updateWorldMatrix(true, true);
@@ -213,15 +213,14 @@ class DualFovCamera extends PerspectiveCamera {
     /**
      * 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
+     * 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 an iterative clustering approach to find the
-     * main concentration of vertices, which provides better results than a simple average
-     * for complex meshes.
+     * The center of mass calculation uses iterative clustering to find the
+     * main concentration of vertices.
      *
-     * @param skinnedMesh - The skinned mesh (with active skeleton) whose center of mass should be the camera's target
+     * @param skinnedMesh - The skinned mesh with active skeleton
      */
     lookAtMeshCenterOfMass(skinnedMesh) {
         skinnedMesh.updateWorldMatrix(true, true);
@@ -236,11 +235,11 @@ class DualFovCamera extends PerspectiveCamera {
             points.push(target.clone());
         }
         /**
-         * Finds the main cluster center of a set of 3D points using iterative refinement.
+         * Finds the main cluster center 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
+         * @param iterations - Number of refinement iterations
+         * @returns The center point of the main cluster
          */
         const findMainCluster = (points, iterations = 3) => {
             if (points.length === 0) {
@@ -267,12 +266,12 @@ class DualFovCamera extends PerspectiveCamera {
         this.lookAt(centerOfMass);
     }
     /**
-     * Creates a deep copy of this DualFovCamera instance.
+     * Creates a copy of this DualFovCamera.
      *
-     * The cloned camera will have identical FOV settings, position, rotation,
+     * The cloned camera has identical FOV settings, position, rotation,
      * and all other camera properties.
      *
-     * @returns A new DualFovCamera instance that is an exact copy of this one
+     * @returns A new DualFovCamera instance
      * @override
      */
     clone() {
@@ -285,25 +284,23 @@ class DualFovCamera extends PerspectiveCamera {
 /**
  * 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.
+ * Provides static methods for traversing Three.js scene hierarchies,
+ * searching for objects or materials, and performing batch operations.
  *
- * All methods perform depth-first traversal of the scene graph starting from
- * the provided root object and recursively processing all children.
+ * All methods perform depth-first traversal starting from the provided
+ * root object and recursively processing all children.
  */
 class SceneTraversal {
     /**
      * 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.
+     * Performs depth-first search through the scene graph starting from the
+     * root object. Returns the first object whose name property 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) {
@@ -320,15 +317,13 @@ class SceneTraversal {
     /**
      * Finds the first material in the scene hierarchy with an exact name match.
      *
-     * Performs a depth-first search through the scene graph, examining materials
+     * 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 encountered whose name property exactly matches
-     * the search string.
+     * 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
-  
      */
     static getMaterialByName(object, name) {
         if (object instanceof Mesh) {
@@ -354,15 +349,13 @@ class SceneTraversal {
     /**
      * 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.).
+     * Performs depth-first traversal and executes the callback function
+     * for every object that is an instance of the 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
-  
      */
     static enumerateObjectsByType(object, type, callback) {
         if (object instanceof type) {
@@ -375,13 +368,12 @@ class SceneTraversal {
     /**
      * 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.
+     * Performs depth-first traversal, finding all Mesh objects and executing
+     * the callback function for each material. Handles both single
+     * materials and material arrays.
      *
      * @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) {
@@ -399,16 +391,15 @@ class SceneTraversal {
         }
     }
     /**
-     * Finds all objects in the scene hierarchy that match the specified filter criteria.
+     * Finds all objects in the scene hierarchy that match 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.
+     * Performs depth-first search and collects all objects that either match
+     * a regular expression pattern (applied to object names) or satisfy
+     * a 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 = [];
@@ -428,29 +419,29 @@ class SceneTraversal {
         return result;
     }
     /**
-     * Finds all materials in the scene hierarchy whose names match a regular expression pattern.
+     * Finds all materials in the scene hierarchy whose names match a 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.
+     * 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
-  
      */
     static filterMaterials(object, name) {
         let result = [];
         if (object instanceof Mesh) {
             if (Array.isArray(object.material)) {
                 for (const material of object.material) {
-                    if (material.name && name.test(material.name)) {
+                    if (material.name !== undefined && name.test(material.name)) {
                         result.push(material);
                     }
                 }
             }
             else {
-                if (object.material.name && name.test(object.material.name)) {
+                if (object.material.name !== undefined &&
+                    name.test(object.material.name)) {
                     result.push(object.material);
                 }
             }
@@ -461,11 +452,10 @@ class SceneTraversal {
         return result;
     }
     /**
-     * Finds all objects (mesh users) that use materials with names matching a regular expression pattern.
+     * Finds all mesh objects that use materials with names matching a 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.
+     * Performs depth-first search through all Mesh objects and collects mesh objects
+     * whose materials have names that match the regular expression.
      *
      * @param object - The root Object3D to start searching from
      * @param materialName - Regular expression pattern to test against material names
@@ -477,14 +467,15 @@ class SceneTraversal {
             let hasMatchingMaterial = false;
             if (Array.isArray(object.material)) {
                 for (const material of object.material) {
-                    if (material.name && materialName.test(material.name)) {
+                    if (material.name !== undefined && materialName.test(material.name)) {
                         hasMatchingMaterial = true;
                         break;
                     }
                 }
             }
             else {
-                if (object.material.name && materialName.test(object.material.name)) {
+                if (object.material.name !== undefined &&
+                    materialName.test(object.material.name)) {
                     hasMatchingMaterial = true;
                 }
             }
@@ -501,11 +492,11 @@ class SceneTraversal {
 
 /** Number of components per vertex */
 const COMPONENT_COUNT = 3;
-/** Convert skinned meshes to regular static meshes */
+/** Converts skinned meshes to static meshes */
 class SkinnedMeshBaker {
     /**
-     * Convert a skinned mesh to a regular mesh in its current pose.
-     * The resulting mesh will have no bones but look identical.
+     * Converts a skinned mesh to a static mesh in its current pose.
+     * The resulting mesh has no bones but looks identical.
      *
      * @param skinnedMesh - Mesh to convert
      * @returns Static mesh with baked vertex positions
@@ -531,9 +522,9 @@ class SkinnedMeshBaker {
         return mesh;
     }
     /**
-     * Bake a single frame from an animation into a static mesh.
+     * Bakes a single frame from an animation into a static mesh.
      *
-     * @param armature - Root object with bones (usually from GLTF)
+     * @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
@@ -550,6 +541,392 @@ class SkinnedMeshBaker {
     }
 }
 
+/** Factor for metalness brightness adjustment */
+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.
+ */
+class StandardToBasicConverter {
+    /**
+     * Converts a 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
+     * });
+     * ```
+     */
+    static convert(standardMaterial, options = {}) {
+        const config = {
+            preserveName: true,
+            copyUserData: true,
+            disposeOriginal: false,
+            combineEmissive: true,
+            brightnessFactor: 1.3,
+            ...options,
+        };
+        // Create new Basic material
+        const basicMaterial = new MeshBasicMaterial();
+        // Copy basic material properties
+        this.copyBasicProperties(standardMaterial, basicMaterial, config);
+        // Handle color properties with lighting compensation
+        this.convertColorProperties(standardMaterial, basicMaterial, config);
+        // Handle texture maps
+        this.convertTextureMaps(standardMaterial, basicMaterial);
+        // Handle transparency and alpha
+        this.convertTransparencyProperties(standardMaterial, basicMaterial);
+        // Cleanup if requested
+        if (config.disposeOriginal) {
+            standardMaterial.dispose();
+        }
+        basicMaterial.needsUpdate = true;
+        return basicMaterial;
+    }
+    /**
+     * Copies basic material properties from source to target material.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshBasicMaterial
+     * @param config - The resolved configuration options
+     * @internal
+     */
+    static copyBasicProperties(source, target, config) {
+        if (config.preserveName) {
+            target.name = source.name;
+        }
+        target.side = source.side;
+        target.visible = source.visible;
+        target.fog = source.fog;
+        target.wireframe = source.wireframe;
+        target.wireframeLinewidth = source.wireframeLinewidth;
+        target.vertexColors = source.vertexColors;
+        if (config.copyUserData) {
+            target.userData = { ...source.userData };
+        }
+    }
+    /**
+     * Converts color-related 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
+     * @internal
+     */
+    static convertColorProperties(source, target, config) {
+        // Base color conversion with brightness compensation
+        target.color = source.color.clone();
+        // Apply brightness compensation since BasicMaterial doesn't respond to lighting
+        target.color.multiplyScalar(config.brightnessFactor);
+        // Adjust for metalness - metallic materials tend to be darker without lighting
+        if (source.metalness > 0) {
+            const metalnessBrightness = 1 + source.metalness * METALNESS_BRIGHTNESS_FACTOR;
+            target.color.multiplyScalar(metalnessBrightness);
+        }
+        // Combine emissive color if requested
+        if (config.combineEmissive) {
+            const emissiveContribution = source.emissive
+                .clone()
+                .multiplyScalar(source.emissiveIntensity * EMISSIVE_CONTRIBUTION_FACTOR);
+            target.color.add(emissiveContribution);
+        }
+        // Ensure color doesn't exceed valid range
+        target.color.r = Math.min(target.color.r, 1.0);
+        target.color.g = Math.min(target.color.g, 1.0);
+        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.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshBasicMaterial
+     * @internal
+     */
+    static convertTextureMaps(source, target) {
+        // Main diffuse/albedo map
+        if (source.map) {
+            target.map = source.map;
+        }
+        // Alpha map
+        if (source.alphaMap) {
+            target.alphaMap = source.alphaMap;
+        }
+        // Environment map (BasicMaterial supports this for reflections)
+        if (source.envMap) {
+            target.envMap = source.envMap;
+            // Use metalness to determine reflectivity
+            target.reflectivity = source.metalness;
+        }
+        // Light map (BasicMaterial supports this)
+        if (source.lightMap) {
+            target.lightMap = source.lightMap;
+            target.lightMapIntensity = source.lightMapIntensity;
+        }
+        // AO map (BasicMaterial supports this)
+        if (source.aoMap) {
+            target.aoMap = source.aoMap;
+            target.aoMapIntensity = source.aoMapIntensity;
+        }
+        // Specular map (BasicMaterial supports this)
+        if (source.metalnessMap) {
+            // Use metalness map as specular map for some reflective effect
+            target.specularMap = source.metalnessMap;
+        }
+        // Copy UV transforms
+        this.copyUVTransforms(source, target);
+    }
+    /**
+     * Copies UV transformation properties for texture maps.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshBasicMaterial
+     * @internal
+     */
+    static copyUVTransforms(source, target) {
+        // Main texture UV transform
+        if (source.map && target.map) {
+            target.map.offset.copy(source.map.offset);
+            target.map.repeat.copy(source.map.repeat);
+            target.map.rotation = source.map.rotation;
+            target.map.center.copy(source.map.center);
+        }
+    }
+    /**
+     * Converts transparency and rendering properties.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshBasicMaterial
+     * @internal
+     */
+    static convertTransparencyProperties(source, target) {
+        target.transparent = source.transparent;
+        target.opacity = source.opacity;
+        target.alphaTest = source.alphaTest;
+        target.depthTest = source.depthTest;
+        target.depthWrite = source.depthWrite;
+        target.blending = source.blending;
+    }
+}
+
+/** Factor for metalness darkness adjustment */
+const METALNESS_DARKNESS_FACTOR = 0.3;
+/** Roughness threshold for additional darkening */
+const ROUGHNESS_THRESHOLD = 0.5;
+/** Factor for roughness color adjustment */
+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.
+ */
+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
+     *
+     * @example
+     * ```typescript
+     * const standardMaterial = new MeshStandardMaterial({
+     *   color: 0xff0000,
+     *   metalness: 0.8,
+     *   roughness: 0.2
+     * });
+     *
+     * const lambertMaterial = StandardToLambertConverter.convert(standardMaterial);
+     * ```
+     */
+    static convert(material, options = {}) {
+        const config = {
+            preserveName: true,
+            copyUserData: true,
+            disposeOriginal: false,
+            roughnessColorFactor: 0.8,
+            ...options,
+        };
+        // Create new Lambert material
+        const lambertMaterial = new MeshLambertMaterial();
+        // Copy basic material properties
+        this.copyBasicProperties(material, lambertMaterial, config);
+        // Handle color properties with roughness compensation
+        this.convertColorProperties(material, lambertMaterial, config);
+        // Handle texture maps
+        this.convertTextureMaps(material, lambertMaterial);
+        // Handle transparency and alpha
+        this.convertTransparencyProperties(material, lambertMaterial);
+        // Cleanup if requested
+        if (config.disposeOriginal) {
+            material.dispose();
+        }
+        lambertMaterial.needsUpdate = true;
+        return lambertMaterial;
+    }
+    /**
+     * Copies basic material properties from source to target material.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshLambertMaterial
+     * @param config - The resolved configuration options
+     * @internal
+     */
+    static copyBasicProperties(source, target, config) {
+        if (config.preserveName) {
+            target.name = source.name;
+        }
+        target.side = source.side;
+        target.visible = source.visible;
+        target.fog = source.fog;
+        target.wireframe = source.wireframe;
+        target.wireframeLinewidth = source.wireframeLinewidth;
+        target.vertexColors = source.vertexColors;
+        target.flatShading = source.flatShading;
+        if (config.copyUserData) {
+            target.userData = { ...source.userData };
+        }
+    }
+    /**
+     * 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.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshLambertMaterial
+     * @param config - The resolved configuration options
+     * @internal
+     */
+    static convertColorProperties(source, target, config) {
+        target.color = source.color.clone();
+        // Adjust color based on metalness and roughness for better visual match
+        if (source.metalness > 0) {
+            // Metallic materials tend to be darker in Lambert shading
+            const metalnessFactor = 1 - source.metalness * METALNESS_DARKNESS_FACTOR;
+            target.color.multiplyScalar(metalnessFactor);
+        }
+        if (source.roughness > ROUGHNESS_THRESHOLD) {
+            // Rough materials appear slightly darker
+            const roughnessFactor = config.roughnessColorFactor +
+                source.roughness * ROUGHNESS_COLOR_ADJUSTMENT;
+            target.color.multiplyScalar(roughnessFactor);
+        }
+        target.emissive = source.emissive.clone();
+        target.emissiveIntensity = source.emissiveIntensity;
+    }
+    /**
+     * Converts and maps 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
+     * @internal
+     */
+    static convertTextureMaps(source, target) {
+        // Diffuse/Albedo map
+        if (source.map) {
+            target.map = source.map;
+        }
+        // Emissive map
+        if (source.emissiveMap) {
+            target.emissiveMap = source.emissiveMap;
+        }
+        // Normal map (Lambert materials support normal mapping)
+        if (source.normalMap) {
+            target.normalMap = source.normalMap;
+            target.normalScale = source.normalScale.clone();
+        }
+        // Light map
+        if (source.lightMap) {
+            target.lightMap = source.lightMap;
+            target.lightMapIntensity = source.lightMapIntensity;
+        }
+        // AO map
+        if (source.aoMap) {
+            target.aoMap = source.aoMap;
+            target.aoMapIntensity = source.aoMapIntensity;
+        }
+        // Environment map (for reflections)
+        if (source.envMap) {
+            target.envMap = source.envMap;
+            target.reflectivity = Math.min(source.metalness + REFLECTIVITY_BOOST, 1.0);
+        }
+        // Alpha map
+        if (source.alphaMap) {
+            target.alphaMap = source.alphaMap;
+        }
+        // Copy UV transforms
+        this.copyUVTransforms(source, target);
+    }
+    /**
+     * Copies UV transformation properties for texture maps.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshLambertMaterial
+     * @internal
+     */
+    static copyUVTransforms(source, target) {
+        // Main texture UV transform
+        if (source.map && target.map) {
+            target.map.offset.copy(source.map.offset);
+            target.map.repeat.copy(source.map.repeat);
+            target.map.rotation = source.map.rotation;
+            target.map.center.copy(source.map.center);
+        }
+    }
+    /**
+     * Converts transparency and rendering properties.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshLambertMaterial
+     * @internal
+     */
+    static convertTransparencyProperties(source, target) {
+        target.transparent = source.transparent;
+        target.opacity = source.opacity;
+        target.alphaTest = source.alphaTest;
+        target.depthTest = source.depthTest;
+        target.depthWrite = source.depthWrite;
+        target.blending = source.blending;
+    }
+}
+
 /** Number of color channels in RGBA format */
 const RGBA_CHANNEL_COUNT = 4;
 /** Number of color channels in RGB format */
@@ -561,11 +938,11 @@ 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 and advanced shadow mapping.
+ * A directional light with spherical positioning controls.
  *
- * 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.
+ * 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.
  */
 class Sun extends DirectionalLight {
     constructor() {
@@ -583,7 +960,7 @@ class Sun extends DirectionalLight {
         this._private_tempSpherical = new Spherical();
     }
     /**
-     * Gets the distance from the light to its target (origin).
+     * Gets the distance from the light's position to the origin.
      *
      * @returns The distance in world units
      */
@@ -591,17 +968,17 @@ class Sun extends DirectionalLight {
         return this.position.length();
     }
     /**
-     * Gets the elevation angle (vertical angle from the horizontal plane).
+     * Gets the elevation angle from the spherical coordinates.
      *
-     * @returns The elevation angle in radians (0 = horizontal, π/2 = directly above)
+     * @returns The elevation angle in radians (phi angle from Three.js Spherical coordinates)
      */
     get elevation() {
         return this._private_tempSpherical.setFromVector3(this.position).phi;
     }
     /**
-     * Gets the azimuth angle (horizontal rotation around the target).
+     * Gets the azimuth angle from the spherical coordinates.
      *
-     * @returns The azimuth angle in radians (0 = positive X axis, π/2 = positive Z axis)
+     * @returns The azimuth angle in radians (theta angle from Three.js Spherical coordinates)
      */
     get azimuth() {
         return this._private_tempSpherical.setFromVector3(this.position).theta;
@@ -618,7 +995,7 @@ class Sun extends DirectionalLight {
     /**
      * Sets the elevation angle while preserving current distance and azimuth.
      *
-     * @param value - The new elevation angle in radians (0 = horizontal, π/2 = directly above)
+     * @param value - The new elevation angle in radians (phi angle for Three.js Spherical coordinates)
      */
     set elevation(value) {
         this._private_tempSpherical.setFromVector3(this.position);
@@ -627,18 +1004,18 @@ class Sun extends DirectionalLight {
     /**
      * 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)
+     * @param value - The new azimuth angle in radians (theta angle for Three.js Spherical coordinates)
      */
     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 to optimally cover a bounding box.
+     * Configures the shadow camera frustum to 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.
+     * 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
      */
@@ -674,12 +1051,11 @@ class Sun extends DirectionalLight {
     /**
      * 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.
+     * 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.
      *
      * @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)
+     * @param distance - The distance to place the sun from the origin
      */
     setDirectionFromHDRTexture(texture, distance = 1) {
         const data = texture.image.data;
@@ -711,5 +1087,5 @@ class Sun extends DirectionalLight {
     }
 }
 
-export { DualFovCamera, SceneTraversal, SkinnedMeshBaker, Sun };
+export { DualFovCamera, SceneTraversal, SkinnedMeshBaker, StandardToBasicConverter, StandardToLambertConverter, Sun };
 //# sourceMappingURL=index.js.map