three-zoo 0.4.2 → 0.4.3

package/dist/index.js

@@ -1,31 +1,24 @@
 import { PerspectiveCamera, MathUtils, Box3, Vector3, Mesh, InstancedMesh, FrontSide, BufferAttribute, AnimationMixer, DirectionalLight, Spherical, RGBAFormat } from 'three';
 
-/**
- * Default camera settings
- */
 const DEFAULT_HORIZONTAL_FOV = 90;
 const DEFAULT_VERTICAL_FOV = 90;
 const DEFAULT_ASPECT = 1;
 const DEFAULT_NEAR = 1;
 const DEFAULT_FAR = 1000;
+const MIN_FOV = 1;
+const MAX_FOV = 179;
 /**
- * BiFovCamera - A specialized PerspectiveCamera that supports independent horizontal and vertical FOV settings
- *
- * This camera extends Three.js PerspectiveCamera to provide better control over the field of view,
- * allowing separate horizontal and vertical FOV values. The camera automatically adjusts its projection
- * matrix based on the aspect ratio to maintain proper perspective.
- *
- * @extends PerspectiveCamera
+ * 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 {
     /**
-     * Creates a new BiFovCamera instance
-     *
-     * @param horizontalFov - Horizontal field of view in degrees (default: 90)
-     * @param verticalFov - Vertical field of view in degrees (default: 90)
-     * @param aspect - Aspect ratio (width/height) of the viewport (default: 1)
-     * @param near - Near clipping plane distance (default: 1)
-     * @param far - Far clipping plane distance (default: 1000)
+     * @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)
      */
     constructor(horizontalFov = DEFAULT_HORIZONTAL_FOV, verticalFov = DEFAULT_VERTICAL_FOV, aspect = DEFAULT_ASPECT, near = DEFAULT_NEAR, far = DEFAULT_FAR) {
         super(verticalFov, aspect, near, far);
@@ -33,47 +26,37 @@ class BiFovCamera extends PerspectiveCamera {
         this.verticalFovInternal = verticalFov;
         this.updateProjectionMatrix();
     }
-    /**
-     * Gets the horizontal field of view in degrees
-     */
+    /** Current horizontal FOV in degrees */
     get horizontalFov() {
         return this.horizontalFovInternal;
     }
-    /**
-     * Gets the vertical field of view in degrees
-     */
+    /** Current vertical FOV in degrees */
     get verticalFov() {
         return this.verticalFovInternal;
     }
-    /**
-     * Sets the horizontal field of view in degrees
-     * @param value - The new horizontal FOV value
-     */
+    /** Set horizontal FOV in degrees (clamped between 1° and 179°) */
     set horizontalFov(value) {
-        this.horizontalFovInternal = MathUtils.clamp(value, 1, 179);
+        this.horizontalFovInternal = MathUtils.clamp(value, MIN_FOV, MAX_FOV);
         this.updateProjectionMatrix();
     }
-    /**
-     * Sets the vertical field of view in degrees
-     * @param value - The new vertical FOV value
-     */
+    /** Set vertical FOV in degrees (clamped between 1° and 179°) */
     set verticalFov(value) {
-        this.verticalFovInternal = MathUtils.clamp(value, 1, 179);
+        this.verticalFovInternal = MathUtils.clamp(value, MIN_FOV, MAX_FOV);
         this.updateProjectionMatrix();
     }
     /**
-     * Updates both horizontal and vertical FOV simultaneously
-     * @param horizontal - New horizontal FOV in degrees
-     * @param vertical - New vertical FOV in degrees
+     * Update both horizontal and vertical FOV
+     * @param horizontal - Horizontal FOV in degrees
+     * @param vertical - Vertical FOV in degrees
      */
     setFov(horizontal, vertical) {
-        this.horizontalFovInternal = MathUtils.clamp(horizontal, 1, 179);
-        this.verticalFovInternal = MathUtils.clamp(vertical, 1, 179);
+        this.horizontalFovInternal = MathUtils.clamp(horizontal, MIN_FOV, MAX_FOV);
+        this.verticalFovInternal = MathUtils.clamp(vertical, MIN_FOV, MAX_FOV);
         this.updateProjectionMatrix();
     }
     /**
-     * Copies FOV settings from another BiFovCamera
-     * @param source - The camera to copy settings from
+     * Copy FOV settings from another BiFovCamera
+     * @param source - Camera to copy from
      */
     copyFovSettings(source) {
         this.horizontalFovInternal = source.horizontalFov;
@@ -81,9 +64,9 @@ class BiFovCamera extends PerspectiveCamera {
         this.updateProjectionMatrix();
     }
     /**
-     * Updates the projection matrix based on current FOV settings and aspect ratio
-     * For aspect ratios >= 1 (landscape), horizontal FOV is preserved
-     * For aspect ratios < 1 (portrait), vertical FOV is preserved
+     * Updates the projection matrix based on FOV settings and aspect ratio.
+     * In landscape: preserves horizontal FOV
+     * In portrait: preserves vertical FOV
      */
     updateProjectionMatrix() {
         if (this.aspect >= 1) {
@@ -97,9 +80,7 @@ class BiFovCamera extends PerspectiveCamera {
         }
         super.updateProjectionMatrix();
     }
-    /**
-     * Returns the actual horizontal FOV after aspect ratio adjustments
-     */
+    /** Get actual horizontal FOV after aspect ratio adjustments */
     getEffectiveHorizontalFov() {
         if (this.aspect >= 1) {
             return this.horizontalFovInternal;
@@ -107,9 +88,7 @@ class BiFovCamera extends PerspectiveCamera {
         const verticalRadians = MathUtils.degToRad(this.verticalFovInternal);
         return MathUtils.radToDeg(Math.atan(Math.tan(verticalRadians / 2) * this.aspect) * 2);
     }
-    /**
-     * Returns the actual vertical FOV after aspect ratio adjustments
-     */
+    /** Get actual vertical FOV after aspect ratio adjustments */
     getEffectiveVerticalFov() {
         if (this.aspect < 1) {
             return this.verticalFovInternal;
@@ -117,9 +96,7 @@ class BiFovCamera extends PerspectiveCamera {
         const horizontalRadians = MathUtils.degToRad(this.horizontalFovInternal);
         return MathUtils.radToDeg(Math.atan(Math.tan(horizontalRadians / 2) / this.aspect) * 2);
     }
-    /**
-     * Creates a clone of this camera with the same properties
-     */
+    /** Create a clone of this camera */
     clone() {
         const camera = new BiFovCamera(this.horizontalFovInternal, this.verticalFovInternal, this.aspect, this.near, this.far);
         camera.copy(this, true);
@@ -127,44 +104,39 @@ class BiFovCamera extends PerspectiveCamera {
     }
 }
 
+/**
+ * Box3 with additional convenience methods for width, height, depth, etc.
+ */
 class Bounds extends Box3 {
-    constructor() {
-        super(...arguments);
+    constructor(object) {
+        super();
+        /** Temporary vector for calculations */
         this.tempVector3A = new Vector3();
+        if (object) {
+            this.setFromObject(object);
+        }
     }
-    /**
-     * Gets the width (x-axis length) of the bounding box
-     */
+    /** Width (x-axis length) */
     get width() {
         return this.max.x - this.min.x;
     }
-    /**
-     * Gets the height (y-axis length) of the bounding box
-     */
+    /** Height (y-axis length) */
     get height() {
         return this.max.y - this.min.y;
     }
-    /**
-     * Gets the depth (z-axis length) of the bounding box
-     */
+    /** Depth (z-axis length) */
     get depth() {
         return this.max.z - this.min.z;
     }
-    /**
-     * Gets the length of the box's diagonal
-     */
+    /** Length of the box's diagonal */
     get diagonal() {
         return this.tempVector3A.subVectors(this.max, this.min).length();
     }
-    /**
-     * Gets the volume of the bounding box
-     */
+    /** Volume (width * height * depth) */
     getVolume() {
         return this.width * this.height * this.depth;
     }
-    /**
-     * Gets the surface area of the bounding box
-     */
+    /** Surface area (sum of all six faces) */
     getSurfaceArea() {
         const w = this.width;
         const h = this.height;
@@ -173,73 +145,53 @@ class Bounds extends Box3 {
     }
 }
 
+const POSITION_COMPONENT_COUNT = 3;
+const NORMAL_COMPONENT_COUNT = 3;
 /**
- * Utility class for comparing and hashing BufferGeometry instances with tolerance support.
+ * Internal utility to identify identical geometries.
+ * @internal
  */
 class GeometryHasher {
     /**
-     * Generates a consistent hash for a BufferGeometry based on its contents and tolerance.
+     * Creates a hash for a geometry based on its vertex data.
+     * Vertices that differ by less than tolerance are considered the same.
      *
-     * @param geometry - The geometry to hash
-     * @param tolerance - Precision level for number comparison (values within tolerance are considered equal)
-     * @returns A string hash that will be identical for geometrically equivalent geometries
-     */
-    static getGeometryHash(geometry, tolerance = 1e-6) {
-        const hashParts = [];
-        // Process attributes
-        const attributes = geometry.attributes;
-        const attributeNames = Object.keys(attributes).sort(); // Sort for consistent order
-        for (const name of attributeNames) {
-            const attribute = attributes[name];
-            hashParts.push(`${name}:${attribute.itemSize}:${this.getAttributeHash(attribute, tolerance)}`);
-        }
-        // Process index if present
-        if (geometry.index) {
-            hashParts.push(`index:${this.getAttributeHash(geometry.index, tolerance)}`);
-        }
-        return hashParts.join("|");
-    }
-    /**
-     * Compares two BufferGeometry instances for approximate equality.
-     * Early exit if UUIDs match (same object or cloned geometry).
+     * @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 compare(firstGeometry, secondGeometry, tolerance = 1e-6) {
-        if (firstGeometry.uuid === secondGeometry.uuid) {
-            return true;
+    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}`);
         }
-        // Use hash comparison for consistent results
-        return (this.getGeometryHash(firstGeometry, tolerance) ===
-            this.getGeometryHash(secondGeometry, tolerance));
-    }
-    /**
-     * Generates a hash for a buffer attribute with tolerance.
-     */
-    static getAttributeHash(attribute, tolerance) {
-        const array = attribute.array;
-        const itemSize = "itemSize" in attribute ? attribute.itemSize : 1;
-        const hashParts = [];
-        // Group values by their "tolerance buckets"
-        for (let i = 0; i < array.length; i += itemSize) {
-            const itemValues = [];
-            for (let j = 0; j < itemSize; j++) {
-                const val = array[i + j];
-                // Round to nearest tolerance multiple to group similar values
-                itemValues.push(Math.round(val / tolerance) * tolerance);
-            }
-            hashParts.push(itemValues.join(","));
+        // 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}`);
         }
-        return hashParts.join(";");
-    }
-    /**
-     * Compares two buffer attributes with tolerance.
-     */
-    static compareBufferAttributes(firstAttribute, secondAttribute, tolerance) {
-        return (this.getAttributeHash(firstAttribute, tolerance) ===
-            this.getAttributeHash(secondAttribute, tolerance));
+        // 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 */
     static getObjectByName(object, name) {
         if (object.name === name) {
             return object;
@@ -252,6 +204,7 @@ class SceneTraversal {
         }
         return null;
     }
+    /** Find first material with exact name match */
     static getMaterialByName(object, name) {
         if (object instanceof Mesh) {
             if (Array.isArray(object.material)) {
@@ -273,6 +226,7 @@ class SceneTraversal {
         }
         return null;
     }
+    /** Process all objects of a specific type */
     static enumerateObjectsByType(object, type, callback) {
         if (object instanceof type) {
             callback(object);
@@ -281,6 +235,7 @@ class SceneTraversal {
             SceneTraversal.enumerateObjectsByType(child, type, callback);
         }
     }
+    /** Process all materials in meshes */
     static enumerateMaterials(object, callback) {
         if (object instanceof Mesh) {
             if (Array.isArray(object.material)) {
@@ -296,6 +251,7 @@ class SceneTraversal {
             SceneTraversal.enumerateMaterials(child, callback);
         }
     }
+    /** Find all objects whose names match a pattern */
     static filterObjects(object, name) {
         let result = [];
         if (object.name && name.test(object.name)) {
@@ -306,6 +262,7 @@ class SceneTraversal {
         }
         return result;
     }
+    /** Find all materials whose names match a pattern */
     static filterMaterials(object, name) {
         let result = [];
         if (object instanceof Mesh) {
@@ -327,41 +284,58 @@ class SceneTraversal {
         }
         return result;
     }
-    static setShadowRecursive(object, castShadow = true, receiveShadow = true) {
+    /** 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);
+            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 {
-    static assemble(options) {
+    /**
+     * 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 instancedMeshes = [];
-        const tolerance = (_a = options.geometryTolerance) !== null && _a !== void 0 ? _a : 1e-6;
-        const geometryHashCache = new Map();
-        SceneTraversal.enumerateObjectsByType(options.container, Mesh, (child) => {
+        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 = geometryHashCache.get(child.geometry.uuid);
+                let geometryHash = geometryHashes.get(child.geometry.uuid);
                 if (!geometryHash) {
                     geometryHash = GeometryHasher.getGeometryHash(child.geometry, tolerance);
-                    geometryHashCache.set(child.geometry.uuid, geometryHash);
+                    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: materials,
+                    materials,
                     castShadow: false,
                     receiveShadow: false,
                 };
@@ -376,7 +350,7 @@ class InstanceAssembler {
             }
         });
         for (const descriptor of dictionary.values()) {
-            if (descriptor.meshes.length < 2) {
+            if (descriptor.meshes.length < MIN_INSTANCE_COUNT) {
                 continue;
             }
             const { meshes, materials, castShadow, receiveShadow } = descriptor;
@@ -393,63 +367,74 @@ class InstanceAssembler {
                 instancedMesh.userData[mesh.uuid] = mesh.userData;
             }
             instancedMesh.instanceMatrix.needsUpdate = true;
-            instancedMeshes.push(instancedMesh);
+            instances.push(instancedMesh);
             for (const mesh of sortedMeshes) {
                 (_b = mesh.parent) === null || _b === void 0 ? void 0 : _b.remove(mesh);
             }
         }
-        if (instancedMeshes.length > 0) {
-            options.container.add(...instancedMeshes);
+        if (instances.length > 0) {
+            container.add(...instances);
         }
     }
 }
 
+/** Post-processes a scene based on name patterns */
 class SceneProcessor {
-    static process(options) {
-        const container = options.asset.clone();
-        InstanceAssembler.assemble({ container: container });
+    /**
+     * Process a scene to set up materials and shadows.
+     *
+     * @param asset - Scene to process
+     * @param options - How to process the scene
+     * @returns Processed scene root objects
+     */
+    static process(asset, options) {
+        const container = options.cloneAsset !== false ? asset.clone() : asset;
+        if (options.assembleInstances !== false) {
+            InstanceAssembler.assemble(container);
+        }
         SceneTraversal.enumerateMaterials(container, (material) => {
-            material.transparent = SceneProcessor.matchesAny(material.name, options.transparentMaterialNames);
-            material.depthWrite = !SceneProcessor.matchesAny(material.name, options.noDepthWriteMaterialNames);
+            material.transparent = SceneProcessor.matchesAny(material.name, options.transparentMaterialExpressions);
+            material.depthWrite = !SceneProcessor.matchesAny(material.name, options.noDepthWriteMaterialExpressions);
             material.side = FrontSide;
             material.forceSinglePass = true;
             material.depthTest = true;
         });
         SceneTraversal.enumerateObjectsByType(container, Mesh, (child) => {
-            child.castShadow = SceneProcessor.matchesAny(child.name, options.castShadowMeshNames);
-            child.receiveShadow = SceneProcessor.matchesAny(child.name, options.receiveShadowMeshNames);
+            child.castShadow = SceneProcessor.matchesAny(child.name, options.castShadowExpressions);
+            child.receiveShadow = SceneProcessor.matchesAny(child.name, options.receiveShadwoExpressions);
         });
         return container.children;
     }
-    static matchesAny(value, patterns = []) {
-        return patterns.some((p) => typeof p === "string" ? value === p : p.test(value));
+    /** Does the string match any of the patterns? */
+    static matchesAny(value, expressions = []) {
+        return expressions.some((p) => p.test(value));
     }
 }
 
-/**
- * Utilities for baking poses and animations from SkinnedMesh into a regular static Mesh.
- */
+/** Number of components per vertex */
+const COMPONENT_COUNT = 3;
+/** Convert skinned meshes to regular static meshes */
 class SkinnedMeshBaker {
     /**
-     * Bakes the current pose of a SkinnedMesh into a regular geometry.
-     * Transforms all vertices according to the current skeleton state.
+     * Convert a skinned mesh to a regular mesh in its current pose.
+     * The resulting mesh will have no bones but look identical.
      *
-     * @param skinnedMesh - SkinnedMesh from which to bake the geometry
-     * @returns A new Mesh with positions corresponding to the current bone positions
+     * @param skinnedMesh - Mesh to convert
+     * @returns Static mesh with baked vertex positions
      */
     static bakePose(skinnedMesh) {
         const bakedGeometry = skinnedMesh.geometry.clone();
         const position = bakedGeometry.attributes["position"];
-        const newPositions = new Float32Array(position.count * 3);
+        const newPositions = new Float32Array(position.count * COMPONENT_COUNT);
         const target = new Vector3();
         for (let i = 0; i < position.count; i++) {
             target.fromBufferAttribute(position, i);
             skinnedMesh.applyBoneTransform(i, target);
-            newPositions[i * 3 + 0] = target.x;
-            newPositions[i * 3 + 1] = target.y;
-            newPositions[i * 3 + 2] = target.z;
+            newPositions[i * COMPONENT_COUNT + 0] = target.x;
+            newPositions[i * COMPONENT_COUNT + 1] = target.y;
+            newPositions[i * COMPONENT_COUNT + 2] = target.z;
         }
-        bakedGeometry.setAttribute("position", new BufferAttribute(newPositions, 3));
+        bakedGeometry.setAttribute("position", new BufferAttribute(newPositions, COMPONENT_COUNT));
         bakedGeometry.computeVertexNormals();
         bakedGeometry.deleteAttribute("skinIndex");
         bakedGeometry.deleteAttribute("skinWeight");
@@ -458,13 +443,13 @@ class SkinnedMeshBaker {
         return mesh;
     }
     /**
-     * Bakes a SkinnedMesh in a specific pose derived from an AnimationClip at the given timestamp.
+     * Bake a single frame from an animation into a static mesh.
      *
-     * @param armature - The parent object (typically an armature from GLTF) containing the bones
-     * @param skinnedMesh - The SkinnedMesh to be baked
-     * @param timeOffset - The animation time in seconds to set
-     * @param clip - The animation clip
-     * @returns A new Mesh with geometry matching the specified animation frame
+     * @param armature - Root object with bones (usually from GLTF)
+     * @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
      */
     static bakeAnimationFrame(armature, skinnedMesh, timeOffset, clip) {
         const mixer = new AnimationMixer(armature);
@@ -477,22 +462,16 @@ class SkinnedMeshBaker {
     }
 }
 
-/**
- * Sun extends Three.js DirectionalLight to provide a specialized light source that simulates
- * sunlight with advanced positioning and shadow controls.
- *
- * Features:
- * - Spherical coordinate control (distance, elevation, azimuth)
- * - Automatic shadow map configuration based on bounding boxes
- * - HDR environment map-based positioning
- * - Efficient temporary vector management for calculations
- *
- * @extends DirectionalLight
- */
+const RGBA_CHANNEL_COUNT = 4;
+const RGB_CHANNEL_COUNT = 3;
+const LUMINANCE_R = 0.2126;
+const LUMINANCE_G = 0.7152;
+const LUMINANCE_B = 0.0722;
+/** A directional light with spherical positioning controls */
 class Sun extends DirectionalLight {
     constructor() {
         super(...arguments);
-        // Temporary vectors for calculations to avoid garbage collection
+        /** Internal vectors to avoid garbage collection */
         this.tempVector3D0 = new Vector3();
         this.tempVector3D1 = new Vector3();
         this.tempVector3D2 = new Vector3();
@@ -504,57 +483,34 @@ class Sun extends DirectionalLight {
         this.tempBox3 = new Box3();
         this.tempSpherical = new Spherical();
     }
-    /**
-     * Gets the distance of the sun from its target (radius in spherical coordinates)
-     * @returns The distance in world units
-     */
+    /** Distance from the light to its target */
     get distance() {
         return this.position.length();
     }
-    /**
-     * Gets the elevation angle of the sun (phi in spherical coordinates)
-     * @returns The elevation in radians
-     */
+    /** Vertical angle from the ground in radians */
     get elevation() {
         return this.tempSpherical.setFromVector3(this.position).phi;
     }
-    /**
-     * Gets the azimuth angle of the sun (theta in spherical coordinates)
-     * @returns The azimuth in radians
-     */
+    /** Horizontal angle around the target in radians */
     get azimuth() {
         return this.tempSpherical.setFromVector3(this.position).theta;
     }
-    /**
-     * Sets the distance of the sun from its target while maintaining current angles
-     * @param value - The new distance in world units
-     */
+    /** Set distance while keeping current angles */
     set distance(value) {
         this.tempSpherical.setFromVector3(this.position);
         this.position.setFromSphericalCoords(value, this.tempSpherical.phi, this.tempSpherical.theta);
     }
-    /**
-     * Sets the elevation angle of the sun while maintaining current distance and azimuth
-     * @param value - The new elevation in radians
-     */
+    /** Set elevation while keeping current distance and azimuth */
     set elevation(value) {
         this.tempSpherical.setFromVector3(this.position);
         this.position.setFromSphericalCoords(this.tempSpherical.radius, value, this.tempSpherical.theta);
     }
-    /**
-     * Sets the azimuth angle of the sun while maintaining current distance and elevation
-     * @param value - The new azimuth in radians
-     */
+    /** Set azimuth while keeping current distance and elevation */
     set azimuth(value) {
         this.tempSpherical.setFromVector3(this.position);
         this.position.setFromSphericalCoords(this.tempSpherical.radius, this.tempSpherical.phi, value);
     }
-    /**
-     * Configures the shadow camera's frustum to encompass the given bounding box
-     * This ensures that shadows are cast correctly for objects within the box
-     *
-     * @param box3 - The bounding box to configure shadows for
-     */
+    /** Configure shadows to cover all corners of a bounding box */
     setShadowMapFromBox3(box3) {
         const camera = this.shadow.camera;
         this.target.updateWorldMatrix(true, false);
@@ -584,33 +540,26 @@ class Sun extends DirectionalLight {
         camera.updateWorldMatrix(true, false);
         camera.updateProjectionMatrix();
     }
-    /**
-     * Sets the sun's direction based on the brightest point in an HDR texture
-     * This is useful for matching the sun's position to an environment map
-     *
-     * @param texture - The HDR texture to analyze (must be loaded and have valid image data)
-     * @param distance - Optional distance to position the sun from its target (default: 1)
-     */
+    /** Set light direction based on brightest point in an HDR texture */
     setDirectionFromHDR(texture, distance = 1) {
         const data = texture.image.data;
         const width = texture.image.width;
         const height = texture.image.height;
         let maxLuminance = 0;
         let maxIndex = 0;
-        // Find the brightest pixel in the HDR texture
-        const step = texture.format === RGBAFormat ? 4 : 3;
+        // Find brightest pixel
+        const step = texture.format === RGBAFormat ? RGBA_CHANNEL_COUNT : RGB_CHANNEL_COUNT;
         for (let i = 0; i < data.length; i += step) {
             const r = data[i];
             const g = data[i + 1];
             const b = data[i + 2];
-            // Calculate luminance using the Rec. 709 coefficients
-            const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+            const luminance = LUMINANCE_R * r + LUMINANCE_G * g + LUMINANCE_B * b;
             if (luminance > maxLuminance) {
                 maxLuminance = luminance;
                 maxIndex = i;
             }
         }
-        // Convert pixel coordinates to spherical coordinates
+        // Convert to spherical coordinates
         const pixelIndex = maxIndex / step;
         const x = pixelIndex % width;
         const y = Math.floor(pixelIndex / width);