three-zoo 0.4.1 → 0.4.3

package/dist/index.js

@@ -1,60 +1,217 @@
-import { Box3, Vector3, PerspectiveCamera, MathUtils, Mesh, InstancedMesh, FrontSide, BufferAttribute, AnimationMixer, DirectionalLight, Spherical, RGBAFormat } from 'three';
+import { PerspectiveCamera, MathUtils, Box3, Vector3, Mesh, InstancedMesh, FrontSide, BufferAttribute, AnimationMixer, DirectionalLight, Spherical, RGBAFormat } from 'three';
 
+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;
+/**
+ * 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 {
+    /**
+     * @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);
+        this.horizontalFovInternal = horizontalFov;
+        this.verticalFovInternal = verticalFov;
+        this.updateProjectionMatrix();
+    }
+    /** Current horizontal FOV in degrees */
+    get horizontalFov() {
+        return this.horizontalFovInternal;
+    }
+    /** Current vertical FOV in degrees */
+    get verticalFov() {
+        return this.verticalFovInternal;
+    }
+    /** Set horizontal FOV in degrees (clamped between 1° and 179°) */
+    set horizontalFov(value) {
+        this.horizontalFovInternal = MathUtils.clamp(value, MIN_FOV, MAX_FOV);
+        this.updateProjectionMatrix();
+    }
+    /** Set vertical FOV in degrees (clamped between 1° and 179°) */
+    set verticalFov(value) {
+        this.verticalFovInternal = MathUtils.clamp(value, MIN_FOV, MAX_FOV);
+        this.updateProjectionMatrix();
+    }
+    /**
+     * Update both horizontal and vertical FOV
+     * @param horizontal - Horizontal FOV in degrees
+     * @param vertical - Vertical FOV in degrees
+     */
+    setFov(horizontal, vertical) {
+        this.horizontalFovInternal = MathUtils.clamp(horizontal, MIN_FOV, MAX_FOV);
+        this.verticalFovInternal = MathUtils.clamp(vertical, MIN_FOV, MAX_FOV);
+        this.updateProjectionMatrix();
+    }
+    /**
+     * Copy FOV settings from another BiFovCamera
+     * @param source - Camera to copy from
+     */
+    copyFovSettings(source) {
+        this.horizontalFovInternal = source.horizontalFov;
+        this.verticalFovInternal = source.verticalFov;
+        this.updateProjectionMatrix();
+    }
+    /**
+     * Updates the projection matrix based on FOV settings and aspect ratio.
+     * In landscape: preserves horizontal FOV
+     * In portrait: preserves vertical FOV
+     */
+    updateProjectionMatrix() {
+        if (this.aspect >= 1) {
+            // Landscape orientation: preserve horizontal FOV
+            const radians = MathUtils.degToRad(this.horizontalFovInternal);
+            this.fov = MathUtils.radToDeg(Math.atan(Math.tan(radians / 2) / this.aspect) * 2);
+        }
+        else {
+            // Portrait orientation: preserve vertical FOV
+            this.fov = this.verticalFovInternal;
+        }
+        super.updateProjectionMatrix();
+    }
+    /** Get actual horizontal FOV after aspect ratio adjustments */
+    getEffectiveHorizontalFov() {
+        if (this.aspect >= 1) {
+            return this.horizontalFovInternal;
+        }
+        const verticalRadians = MathUtils.degToRad(this.verticalFovInternal);
+        return MathUtils.radToDeg(Math.atan(Math.tan(verticalRadians / 2) * this.aspect) * 2);
+    }
+    /** Get actual vertical FOV after aspect ratio adjustments */
+    getEffectiveVerticalFov() {
+        if (this.aspect < 1) {
+            return this.verticalFovInternal;
+        }
+        const horizontalRadians = MathUtils.degToRad(this.horizontalFovInternal);
+        return MathUtils.radToDeg(Math.atan(Math.tan(horizontalRadians / 2) / this.aspect) * 2);
+    }
+    /** 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);
+        return camera;
+    }
+}
+
+/**
+ * Box3 with additional convenience methods for width, height, depth, etc.
+ */
 class Bounds extends Box3 {
-    constructor() {
-        super(...arguments);
-        this.tempVector3 = new Vector3();
+    constructor(object) {
+        super();
+        /** Temporary vector for calculations */
+        this.tempVector3A = new Vector3();
+        if (object) {
+            this.setFromObject(object);
+        }
     }
+    /** Width (x-axis length) */
     get width() {
         return this.max.x - this.min.x;
     }
+    /** Height (y-axis length) */
     get height() {
         return this.max.y - this.min.y;
     }
+    /** Depth (z-axis length) */
     get depth() {
         return this.max.z - this.min.z;
     }
+    /** Length of the box's diagonal */
     get diagonal() {
-        this.tempVector3.subVectors(this.max, this.min);
-        return this.tempVector3.length();
+        return this.tempVector3A.subVectors(this.max, this.min).length();
+    }
+    /** Volume (width * height * depth) */
+    getVolume() {
+        return this.width * this.height * this.depth;
+    }
+    /** Surface area (sum of all six faces) */
+    getSurfaceArea() {
+        const w = this.width;
+        const h = this.height;
+        const d = this.depth;
+        return 2 * (w * h + h * d + d * w);
     }
 }
 
-class DoubleFOVCamera extends PerspectiveCamera {
-    constructor(horizontalFov = 90, verticalFov = 90, aspect = 1, near = 1, far = 1000) {
-        super(verticalFov, aspect, near, far);
-        this.horizontalFov = horizontalFov;
-        this.verticalFov = verticalFov;
-    }
-    updateProjectionMatrix() {
-        if (this.aspect >= 1) {
-            const radians = MathUtils.degToRad(this.horizontalFov);
-            this.fov = MathUtils.radToDeg(Math.atan(Math.tan(radians / 2) / this.aspect) * 2);
+const POSITION_COMPONENT_COUNT = 3;
+const NORMAL_COMPONENT_COUNT = 3;
+/**
+ * Internal utility to identify identical geometries.
+ * @internal
+ */
+class GeometryHasher {
+    /**
+     * Creates a hash for a geometry based on its vertex data.
+     * Vertices that differ by less than tolerance are considered the same.
+     *
+     * @param geometry - Geometry to hash
+     * @param tolerance - How close vertices need to be to count as identical
+     * @returns Hash string that's the same for matching geometries
+     * @internal
+     */
+    static getGeometryHash(geometry, tolerance) {
+        const position = geometry.attributes["position"];
+        const positionArray = position.array;
+        const positionHashParts = [];
+        // Sample vertex positions with tolerance
+        for (let i = 0; i < positionArray.length; i += POSITION_COMPONENT_COUNT) {
+            const x = Math.round(positionArray[i] / tolerance);
+            const y = Math.round(positionArray[i + 1] / tolerance);
+            const z = Math.round(positionArray[i + 2] / tolerance);
+            positionHashParts.push(`${x},${y},${z}`);
         }
-        else {
-            this.fov = this.verticalFov;
+        // 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}`);
         }
-        super.updateProjectionMatrix();
+        // Combine position and normal hashes
+        const positionHash = positionHashParts.join("|");
+        const normalHash = normalHashParts.join("|");
+        return `${positionHash}#${normalHash}`;
     }
 }
 
-class Enumerator {
+/** 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)
+        if (object.name === name) {
             return object;
+        }
         for (const child of object.children) {
-            const result = Enumerator.getObjectByName(child, name);
-            if (result)
+            const result = SceneTraversal.getObjectByName(child, name);
+            if (result) {
                 return result;
+            }
         }
         return null;
     }
+    /** Find first material with exact name match */
     static getMaterialByName(object, name) {
         if (object instanceof Mesh) {
             if (Array.isArray(object.material)) {
                 for (const material of object.material) {
-                    if (material.name === name)
+                    if (material.name === name) {
                         return material;
+                    }
                 }
             }
             else if (object.material.name === name) {
@@ -62,20 +219,23 @@ class Enumerator {
             }
         }
         for (const child of object.children) {
-            const material = Enumerator.getMaterialByName(child, name);
-            if (material)
+            const material = SceneTraversal.getMaterialByName(child, name);
+            if (material) {
                 return material;
+            }
         }
         return null;
     }
+    /** Process all objects of a specific type */
     static enumerateObjectsByType(object, type, callback) {
         if (object instanceof type) {
             callback(object);
         }
         for (const child of object.children) {
-            Enumerator.enumerateObjectsByType(child, type, callback);
+            SceneTraversal.enumerateObjectsByType(child, type, callback);
         }
     }
+    /** Process all materials in meshes */
     static enumerateMaterials(object, callback) {
         if (object instanceof Mesh) {
             if (Array.isArray(object.material)) {
@@ -88,19 +248,21 @@ class Enumerator {
             }
         }
         for (const child of object.children) {
-            Enumerator.enumerateMaterials(child, callback);
+            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)) {
             result.push(object);
         }
         for (const child of object.children) {
-            result = result.concat(Enumerator.filterObjects(child, name));
+            result = result.concat(SceneTraversal.filterObjects(child, name));
         }
         return result;
     }
+    /** Find all materials whose names match a pattern */
     static filterMaterials(object, name) {
         let result = [];
         if (object instanceof Mesh) {
@@ -118,224 +280,79 @@ class Enumerator {
             }
         }
         for (const child of object.children) {
-            result = result.concat(Enumerator.filterMaterials(child, name));
+            result = result.concat(SceneTraversal.filterMaterials(child, name));
         }
         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) {
-            Enumerator.setShadowRecursive(child, castShadow, receiveShadow);
+            SceneTraversal.setShadowRecursive(child, castShadow, receiveShadow, filter);
         }
     }
 }
 
+const MIN_INSTANCE_COUNT = 2;
+const DEFAULT_TOLERANCE = 1e-6;
 /**
- * Utility class for comparing and hashing BufferGeometry instances with tolerance support.
+ * Combines identical meshes into instanced versions for better performance.
+ * Meshes are considered identical if they share the same geometry and materials.
  */
-class GeometryComparator {
+class InstanceAssembler {
     /**
-     * Generates a consistent hash for a BufferGeometry based on its contents and tolerance.
+     * 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 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).
-     */
-    static compare(firstGeometry, secondGeometry, tolerance = 1e-6) {
-        if (firstGeometry.uuid === secondGeometry.uuid) {
-            return true;
-        }
-        // Use hash comparison for consistent results
-        return (this.getGeometryHash(firstGeometry, tolerance) ===
-            this.getGeometryHash(secondGeometry, tolerance));
-    }
-    /**
-     * Generates a hash for a buffer attribute with tolerance.
+     * @param container - Object containing meshes to process
+     * @param options - Optional settings
      */
-    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(","));
-        }
-        return hashParts.join(";");
-    }
-    /**
-     * Compares two buffer attributes with tolerance.
-     */
-    static compareBufferAttributes(firstAttribute, secondAttribute, tolerance) {
-        return (this.getAttributeHash(firstAttribute, tolerance) ===
-            this.getAttributeHash(secondAttribute, tolerance));
-    }
-}
-// import {
-//   BufferAttribute,
-//   BufferGeometry,
-//   InterleavedBufferAttribute,
-// } from "three";
-// type AnySuitableAttribute = BufferAttribute | InterleavedBufferAttribute;
-// /**
-//  * Utility class for comparing two BufferGeometry instances with tolerance support.
-//  * Checks geometry attributes (positions, normals, UVs, etc.) and indices (if present).
-//  */
-// export class GeometryComparator {
-//   /**
-//    * Compares two BufferGeometry instances for approximate equality.
-//    * Early exit if UUIDs match (same object or cloned geometry).
-//    *
-//    * @param firstGeometry - The first geometry to compare.
-//    * @param secondGeometry - The second geometry to compare.
-//    * @param tolerance - Maximum allowed difference between numeric values (default: 1e-6).
-//    * @returns `true` if geometries are equivalent within tolerance, otherwise `false`.
-//    */
-//   public static compare(
-//     firstGeometry: BufferGeometry,
-//     secondGeometry: BufferGeometry,
-//     tolerance = 1e-6,
-//   ): boolean {
-//     if (firstGeometry.uuid === secondGeometry.uuid) {
-//       return true;
-//     }
-//     const firstAttributes = firstGeometry.attributes;
-//     const secondAttributes = secondGeometry.attributes;
-//     const firstAttributeNames = Object.keys(firstAttributes);
-//     const secondAttributeNames = Object.keys(secondAttributes);
-//     if (firstAttributeNames.length !== secondAttributeNames.length) {
-//       return false;
-//     }
-//     for (const attributeName of firstAttributeNames) {
-//       if (!secondAttributes[attributeName]) {
-//         return false;
-//       }
-//       const firstAttribute = firstAttributes[
-//         attributeName
-//       ] as AnySuitableAttribute;
-//       const secondAttribute = secondAttributes[
-//         attributeName
-//       ] as AnySuitableAttribute;
-//       if (
-//         firstAttribute.count !== secondAttribute.count ||
-//         firstAttribute.itemSize !== secondAttribute.itemSize ||
-//         !this.compareBufferAttributes(
-//           firstAttribute,
-//           secondAttribute,
-//           tolerance,
-//         )
-//       ) {
-//         return false;
-//       }
-//     }
-//     if (firstGeometry.index || secondGeometry.index) {
-//       if (!firstGeometry.index || !secondGeometry.index) {
-//         return false;
-//       }
-//       if (
-//         !this.compareBufferAttributes(
-//           firstGeometry.index,
-//           secondGeometry.index,
-//           tolerance,
-//         )
-//       ) {
-//         return false;
-//       }
-//     }
-//     return true;
-//   }
-//   /**
-//    * Compares two buffer attributes (or index buffers) with tolerance.
-//    *
-//    * @param firstAttribute - First attribute/indices to compare.
-//    * @param secondAttribute - Second attribute/indices to compare.
-//    * @param tolerance - Maximum allowed difference between array elements.
-//    * @returns `true` if arrays are equal within tolerance, otherwise `false`.
-//    */
-//   private static compareBufferAttributes(
-//     firstAttribute: AnySuitableAttribute,
-//     secondAttribute: AnySuitableAttribute,
-//     tolerance: number,
-//   ): boolean {
-//     const firstArray = firstAttribute.array;
-//     const secondArray = secondAttribute.array;
-//     if (firstArray.length !== secondArray.length) {
-//       return false;
-//     }
-//     for (let index = 0; index < firstArray.length; index++) {
-//       if (Math.abs(firstArray[index] - secondArray[index]) > tolerance) {
-//         return false;
-//       }
-//     }
-//     return true;
-//   }
-// }
-
-class InstanceAssembler {
-    static assemble(options) {
+    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();
-        Enumerator.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 = GeometryComparator.getGeometryHash(child.geometry, tolerance);
-                    geometryHashCache.set(child.geometry.uuid, geometryHash);
+                    geometryHash = GeometryHasher.getGeometryHash(child.geometry, tolerance);
+                    geometryHashes.set(child.geometry.uuid, geometryHash);
                 }
                 const materialKey = materials.map((m) => m.uuid).join(",");
                 const compositeKey = `${geometryHash}|${materialKey}`;
                 const entry = (_a = dictionary.get(compositeKey)) !== null && _a !== void 0 ? _a : {
                     meshes: [],
-                    materials: materials,
+                    materials,
                     castShadow: false,
                     receiveShadow: false,
                 };
-                if (child.castShadow)
+                if (child.castShadow) {
                     entry.castShadow = true;
-                if (child.receiveShadow)
+                }
+                if (child.receiveShadow) {
                     entry.receiveShadow = true;
+                }
                 entry.meshes.push(child);
                 dictionary.set(compositeKey, entry);
             }
         });
         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;
             const sortedMeshes = meshes.sort((a, b) => a.name.localeCompare(b.name));
             const defaultMesh = sortedMeshes[0];
@@ -350,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 });
-        Enumerator.enumerateMaterials(container, (material) => {
-            material.transparent = SceneProcessor.matchesAny(material.name, options.transparentMaterialNames);
-            material.depthWrite = !SceneProcessor.matchesAny(material.name, options.noDepthWriteMaterialNames);
+    /**
+     * 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.transparentMaterialExpressions);
+            material.depthWrite = !SceneProcessor.matchesAny(material.name, options.noDepthWriteMaterialExpressions);
             material.side = FrontSide;
             material.forceSinglePass = true;
             material.depthTest = true;
         });
-        Enumerator.enumerateObjectsByType(container, Mesh, (child) => {
-            child.castShadow = SceneProcessor.matchesAny(child.name, options.castShadowMeshNames);
-            child.receiveShadow = SceneProcessor.matchesAny(child.name, options.receiveShadowMeshNames);
+        SceneTraversal.enumerateObjectsByType(container, Mesh, (child) => {
+            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");
@@ -415,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);
@@ -434,9 +462,16 @@ class SkinnedMeshBaker {
     }
 }
 
+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);
+        /** Internal vectors to avoid garbage collection */
         this.tempVector3D0 = new Vector3();
         this.tempVector3D1 = new Vector3();
         this.tempVector3D2 = new Vector3();
@@ -448,27 +483,34 @@ class Sun extends DirectionalLight {
         this.tempBox3 = new Box3();
         this.tempSpherical = new Spherical();
     }
+    /** Distance from the light to its target */
     get distance() {
         return this.position.length();
     }
+    /** Vertical angle from the ground in radians */
     get elevation() {
         return this.tempSpherical.setFromVector3(this.position).phi;
     }
+    /** Horizontal angle around the target in radians */
     get azimuth() {
         return this.tempSpherical.setFromVector3(this.position).theta;
     }
+    /** Set distance while keeping current angles */
     set distance(value) {
         this.tempSpherical.setFromVector3(this.position);
         this.position.setFromSphericalCoords(value, this.tempSpherical.phi, this.tempSpherical.theta);
     }
+    /** 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);
     }
+    /** 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);
     }
+    /** Configure shadows to cover all corners of a bounding box */
     setShadowMapFromBox3(box3) {
         const camera = this.shadow.camera;
         this.target.updateWorldMatrix(true, false);
@@ -498,23 +540,26 @@ class Sun extends DirectionalLight {
         camera.updateWorldMatrix(true, false);
         camera.updateProjectionMatrix();
     }
+    /** Set light direction based on brightest point in an HDR texture */
     setDirectionFromHDR(texture, distance = 1) {
         const data = texture.image.data;
         const width = texture.image.width;
         const height = texture.image.height;
         let maxLuminance = 0;
         let maxIndex = 0;
-        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];
-            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 to spherical coordinates
         const pixelIndex = maxIndex / step;
         const x = pixelIndex % width;
         const y = Math.floor(pixelIndex / width);
@@ -526,5 +571,5 @@ class Sun extends DirectionalLight {
     }
 }
 
-export { Bounds, DoubleFOVCamera, Enumerator, InstanceAssembler, SceneProcessor, SkinnedMeshBaker, Sun };
+export { BiFovCamera, Bounds, InstanceAssembler, SceneProcessor, SceneTraversal, SkinnedMeshBaker, Sun };
 //# sourceMappingURL=index.js.map