three-zoo 0.4.6 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # three-zoo
 
-A few Three.js utilities to handle common 3D tasks.
+A modest collection of Three.js utilities designed to simplify common 3D development tasks.
 
 ## Install
 
@@ -8,102 +8,108 @@ A few Three.js utilities to handle common 3D tasks.
 npm install three-zoo
 ```
 
+## Overview
+
+**three-zoo** provides focused solutions for recurring challenges in 3D web development:
+
+- **Advanced camera controls** with independent FOV management and auto-fitting
+- **Intuitive lighting** with spherical positioning and HDR integration
+- **Scene graph utilities** for finding and manipulating objects and materials
+- **Animation baking** to convert skinned meshes to static geometry
+
+Each utility is designed to work seamlessly with existing Three.js workflows without imposing architectural constraints.
+
 ## Tools
 
-### BiFovCamera
+### DualFovCamera
 
-Camera with separate horizontal and vertical FOV control:
+Camera with independent horizontal and vertical field of view control, plus advanced fitting capabilities:
 
 ```typescript
-const camera = new BiFovCamera(90, 60); // hFov, vFov
+const camera = new DualFovCamera(90, 60); // hFov, vFov
 camera.horizontalFov = 100; // Change horizontal FOV
 camera.verticalFov = 70;    // Change vertical FOV
-```
 
-### Bounds
+// Automatically adjust FOV to fit objects
+camera.fitVerticalFovToPoints(vertices);
+camera.fitVerticalFovToBox(boundingBox);
+camera.fitVerticalFovToMesh(skinnedMesh);
 
-Extra bounding box calculations:
+// Point camera at mesh center of mass
+camera.lookAtMeshCenterOfMass(skinnedMesh);
 
-```typescript
-const bounds = new Bounds(mesh);
-console.log(bounds.width);         // x-axis length
-console.log(bounds.depth);         // z-axis length
-console.log(bounds.getVolume());   // volume
+// Get actual FOV after aspect ratio calculations
+const actualHFov = camera.getActualHorizontalFov();
+const actualVFov = camera.getActualVerticalFov();
 ```
 
-### InstanceAssembler
+### Sun
 
-Combines identical meshes into instances:
+Directional light with intuitive spherical positioning and automatic shadow configuration:
 
 ```typescript
-// Basic - combine all identical meshes
-InstanceAssembler.assemble(scene);
-
-// Custom - only specific meshes
-InstanceAssembler.assemble(scene, {
-  filter: mesh => mesh.name.startsWith('Tree_'),
-  geometryTolerance: 0.001
-});
-```
+const sun = new Sun();
 
-### SceneProcessor
+// Spherical positioning
+sun.elevation = Math.PI / 4;  // 45° above horizon
+sun.azimuth = Math.PI / 2;    // 90° rotation
+sun.distance = 100;           // Distance from origin
 
-Sets up materials and shadows based on naming patterns:
+// Automatically configure shadows for optimal coverage
+sun.configureShadowsForBoundingBox(sceneBounds);
 
-```typescript
-SceneProcessor.process(scene, {
-  castShadowExpressions: [/^Tree_.*/],
-  receiveShadwoExpressions: [/Ground/],
-  transparentMaterialExpressions: [/Glass/],
-});
+// Position sun based on brightest point in HDR environment map
+sun.setDirectionFromHDRTexture(hdrTexture, 50);
 ```
 
 ### SceneTraversal
 
-Scene graph utilities:
+Scene graph navigation and batch operations for finding and manipulating objects:
 
 ```typescript
-// Find objects
+// Find objects and materials by name
 const obj = SceneTraversal.getObjectByName(scene, 'player');
-const objects = SceneTraversal.filterObjects(scene, /^enemy_/);
+const material = SceneTraversal.getMaterialByName(scene, 'metal');
 
-// Configure shadows
-SceneTraversal.setShadowRecursive(scene, true, true);
+// Filter with patterns or custom functions
+const enemies = SceneTraversal.filterObjects(scene, /^enemy_/);
+const glassMaterials = SceneTraversal.filterMaterials(scene, /glass/i);
+
+// Find objects that use specific materials
+const meshesWithGlass = SceneTraversal.findMaterialUsers(scene, /glass/i);
+
+// Batch operations on specific object types
+SceneTraversal.enumerateObjectsByType(scene, Mesh, (mesh) => {
+  mesh.castShadow = true;
+});
+
+// Process all materials in the scene
+SceneTraversal.enumerateMaterials(scene, (material) => {
+  if ('roughness' in material) material.roughness = 0.8;
+});
 ```
 
 ### SkinnedMeshBaker
 
-Converts skinned meshes to static geometry:
+Converts animated skinned meshes to static geometry:
 
 ```typescript
-// Bake current pose
+// Bake current pose to static mesh
 const staticMesh = SkinnedMeshBaker.bakePose(skinnedMesh);
 
-// Bake animation frame
+// Bake specific animation frame
 const frameMesh = SkinnedMeshBaker.bakeAnimationFrame(
-  armature,
-  skinnedMesh,
-  1.5,  // time
-  clip   // animation
+  armature,        // Root object with bones
+  skinnedMesh,     // Mesh to bake
+  1.5,             // Time in seconds
+  animationClip    // Animation to sample
 );
 ```
 
-### Sun
-
-Directional light with spherical positioning:
-
-```typescript
-const sun = new Sun();
-sun.elevation = Math.PI / 4;  // 45°
-sun.azimuth = Math.PI / 2;    // 90°
-
-// Set up shadows
-sun.setShadowMapFromBox3(new Bounds().setFromObject(scene));
-```
-
 ## Requirements
 
-- three >= 0.150.0
+- Three.js >= 0.150.0
+- TypeScript support included
 
 ## License
 

package/dist/DualFovCamera.d.ts

@@ -0,0 +1,142 @@
+import type { Box3, SkinnedMesh } from "three";
+import { PerspectiveCamera, Vector3 } from "three";
+/**
+ * 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.
+ */
+export declare class DualFovCamera extends PerspectiveCamera {
+    /** Internal storage for horizontal field of view in degrees */
+    private horizontalFovInternal;
+    /** Internal storage for vertical field of view in degrees */
+    private verticalFovInternal;
+    /**
+     * Creates a new DualFovCamera instance with independent horizontal and vertical FOV control.
+     *
+     * @param horizontalFov - Horizontal field of view in degrees. Must be between 1° and 179°. Defaults to 90°.
+     * @param verticalFov - Vertical field of view in degrees. Must be between 1° and 179°. Defaults to 90°.
+     * @param aspect - Camera aspect ratio (width/height). Defaults to 1.
+     * @param near - Near clipping plane distance. Must be greater than 0. Defaults to 1.
+     * @param far - Far clipping plane distance. Must be greater than near plane. Defaults to 1000.
+     */
+    constructor(horizontalFov?: number, verticalFov?: number, aspect?: number, near?: number, far?: number);
+    /**
+     * Gets the current horizontal field of view in degrees.
+     *
+     * @returns The horizontal FOV value between 1° and 179°
+     */
+    get horizontalFov(): number;
+    /**
+     * Gets the current vertical field of view in degrees.
+     *
+     * @returns The vertical FOV value between 1° and 179°
+     */
+    get verticalFov(): number;
+    /**
+     * Sets the horizontal field of view in degrees.
+     *
+     * @param value - The horizontal FOV value in degrees. Will be clamped between 1° and 179°.
+     */
+    set horizontalFov(value: number);
+    /**
+     * Sets the vertical field of view in degrees.
+     *
+     * @param value - The vertical FOV value in degrees. Will be clamped between 1° and 179°.
+     */
+    set verticalFov(value: number);
+    /**
+     * Updates both horizontal and vertical field of view values simultaneously.
+     *
+     * @param horizontal - Horizontal FOV in degrees. Will be clamped between 1° and 179°.
+     * @param vertical - Vertical FOV in degrees. Will be clamped between 1° and 179°.
+     */
+    setFov(horizontal: number, vertical: number): void;
+    /**
+     * Copies the field of view settings from another DualFovCamera instance.
+     *
+     * @param source - The DualFovCamera instance to copy FOV settings from.
+     */
+    copyFovSettings(source: DualFovCamera): void;
+    /**
+     * Updates the projection matrix based on current FOV settings and aspect ratio.
+     *
+     * The behavior differs based on orientation:
+     * - **Landscape mode (aspect > 1)**: Preserves horizontal FOV, calculates vertical FOV
+     * - **Portrait mode (aspect ≤ 1)**: Preserves vertical FOV, calculates horizontal FOV
+     *
+     * This method is automatically called when FOV values or aspect ratio changes.
+     *
+     * @override
+     */
+    updateProjectionMatrix(): void;
+    /**
+     * Gets the actual horizontal field of view after aspect ratio adjustments.
+     *
+     * In landscape mode, this returns the set horizontal FOV.
+     * In portrait mode, this calculates the actual horizontal FOV based on the vertical FOV and aspect ratio.
+     *
+     * @returns The actual horizontal FOV in degrees
+     */
+    getActualHorizontalFov(): number;
+    /**
+     * Gets the actual vertical field of view after aspect ratio adjustments.
+     *
+     * In portrait mode, this returns the set vertical FOV.
+     * In landscape mode, this calculates the actual vertical FOV based on the horizontal FOV and aspect ratio.
+     *
+     * @returns The actual vertical FOV in degrees
+     */
+    getActualVerticalFov(): number;
+    /**
+     * Adjusts the vertical field of view to fit all specified points within the camera's view.
+     *
+     * This method calculates the required vertical FOV to ensure all provided vertices
+     * are visible within the vertical bounds of the camera's frustum.
+     *
+     * @param vertices - Array of 3D points (in world coordinates) that should fit within the camera's vertical view
+     */
+    fitVerticalFovToPoints(vertices: Vector3[]): void;
+    /**
+     * Adjusts the vertical field of view to fit a bounding box within the camera's view.
+     *
+     * This method calculates the required vertical FOV to ensure the entire bounding box
+     * is visible within the vertical bounds of the camera's frustum.
+     *
+     * @param box - The 3D bounding box (in world coordinates) that should fit within the camera's vertical view
+     */
+    fitVerticalFovToBox(box: Box3): void;
+    /**
+     * Adjusts the vertical field of view to fit a skinned mesh within the camera's view.
+     *
+     * This method updates the mesh's skeleton, applies bone transformations to all vertices,
+     * and then calculates the required vertical FOV to ensure the entire deformed mesh
+     * is visible within the vertical bounds of the camera's frustum.
+     *
+     * @param skinnedMesh - The skinned mesh (with active skeleton) that should fit within the camera's vertical view
+     */
+    fitVerticalFovToMesh(skinnedMesh: SkinnedMesh): void;
+    /**
+     * Points the camera to look at the center of mass of a skinned mesh.
+     *
+     * This method updates the mesh's skeleton, applies bone transformations to all vertices,
+     * calculates the center of mass using a clustering algorithm, and then orients the camera
+     * to look at that point.
+     *
+     * The center of mass calculation uses an iterative clustering approach to find the
+     * main concentration of vertices, which provides better results than a simple average
+     * for complex meshes.
+     *
+     * @param skinnedMesh - The skinned mesh (with active skeleton) whose center of mass should be the camera's target
+     */
+    lookAtMeshCenterOfMass(skinnedMesh: SkinnedMesh): void;
+    /**
+     * Creates a deep copy of this DualFovCamera instance.
+     *
+     * The cloned camera will have identical FOV settings, position, rotation,
+     * and all other camera properties.
+     *
+     * @returns A new DualFovCamera instance that is an exact copy of this one
+     * @override
+     */
+    clone(): this;
+}

package/dist/GeometryHasher.d.ts

@@ -1,17 +1 @@
-import type { BufferGeometry } from "three";
-/**
- * Internal utility to identify identical geometries.
- * @internal
- */
-export declare 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: BufferGeometry, tolerance: number): string;
-}
+export {};

package/dist/SceneTraversal.d.ts

@@ -1,20 +1,114 @@
 import type { Material, Object3D } from "three";
-/** Constructor type for type-safe scene traversal */
+import { Mesh } from "three";
+/**
+ * Constructor type for type-safe scene traversal operations.
+ *
+ * This type represents any constructor function that can be used to create instances of type T.
+ * It's used for runtime type checking when filtering objects by their constructor type.
+ *
+ * @template T - The type that the constructor creates
+ */
 export type Constructor<T> = abstract new (...args: never[]) => T;
-/** Find and modify objects in a Three.js scene */
+/**
+ * Utility class for finding and modifying objects in a Three.js scene graph.
+ *
+ * This class provides static methods for traversing Three.js scene hierarchies,
+ * searching for specific objects or materials, and performing batch operations
+ * on collections of scene objects.
+ *
+ * All methods perform depth-first traversal of the scene graph starting from
+ * the provided root object and recursively processing all children.
+ */
 export declare class SceneTraversal {
-    /** Find first object with exact name match */
+    /**
+     * Finds the first object in the scene hierarchy with an exact name match.
+     *
+     * Performs a depth-first search through the scene graph starting from the provided
+     * root object. Returns the first object encountered whose name property exactly
+     * matches the search string.
+     *
+     * @param object - The root Object3D to start searching from
+     * @param name - The exact name to search for (case-sensitive)
+     * @returns The first matching Object3D, or null if no match is found
+  
+     */
     static getObjectByName(object: Object3D, name: string): Object3D | null;
-    /** Find first material with exact name match */
+    /**
+     * Finds the first material in the scene hierarchy with an exact name match.
+     *
+     * Performs a depth-first search through the scene graph, examining materials
+     * attached to Mesh objects. Handles both single materials and material arrays.
+     * Returns the first material encountered whose name property exactly matches
+     * the search string.
+     *
+     * @param object - The root Object3D to start searching from
+     * @param name - The exact material name to search for (case-sensitive)
+     * @returns The first matching Material, or null if no match is found
+  
+     */
     static getMaterialByName(object: Object3D, name: string): Material | null;
-    /** Process all objects of a specific type */
+    /**
+     * Processes all objects of a specific type in the scene hierarchy.
+     *
+     * Performs a depth-first traversal and executes the provided callback function
+     * for every object that is an instance of the specified type. This is useful
+     * for batch operations on specific object types (e.g., all lights, all meshes, etc.).
+     *
+     * @template T - The type of objects to process
+     * @param object - The root Object3D to start searching from
+     * @param type - The constructor/class to filter by (e.g., DirectionalLight, Mesh)
+     * @param callback - Function to execute for each matching object instance
+  
+     */
     static enumerateObjectsByType<T>(object: Object3D, type: Constructor<T>, callback: (instance: T) => void): void;
-    /** Process all materials in meshes */
+    /**
+     * Processes all materials found in mesh objects within the scene hierarchy.
+     *
+     * Performs a depth-first traversal, finding all Mesh objects and executing
+     * the provided callback function for each material. Handles both single
+     * materials and material arrays properly.
+     *
+     * @param object - The root Object3D to start searching from
+     * @param callback - Function to execute for each material found
+  
+     */
     static enumerateMaterials(object: Object3D, callback: (material: Material) => void): void;
-    /** Find all objects whose names match a pattern */
+    /**
+     * Finds all objects in the scene hierarchy that match the specified filter criteria.
+     *
+     * Performs a depth-first search and collects all objects that either match
+     * a regular expression pattern (applied to the object's name) or satisfy
+     * a custom predicate function.
+     *
+     * @param object - The root Object3D to start searching from
+     * @param filter - Either a RegExp to test against object names, or a predicate function
+     * @returns Array of all matching Object3D instances
+  
+     */
     static filterObjects(object: Object3D, filter: RegExp | ((object: Object3D) => boolean)): Object3D[];
-    /** Find all materials whose names match a pattern */
+    /**
+     * Finds all materials in the scene hierarchy whose names match a regular expression pattern.
+     *
+     * Performs a depth-first search through all Mesh objects and collects materials
+     * whose name property matches the provided regular expression. Handles both
+     * single materials and material arrays properly.
+     *
+     * @param object - The root Object3D to start searching from
+     * @param name - Regular expression pattern to test against material names
+     * @returns Array of all matching Material instances
+  
+     */
     static filterMaterials(object: Object3D, name: RegExp): Material[];
-    /** Set shadow properties on meshes */
-    static setShadowRecursive(object: Object3D, castShadow?: boolean, receiveShadow?: boolean, filter?: (object: Object3D) => boolean): void;
+    /**
+     * Finds all objects (mesh users) that use materials with names matching a regular expression pattern.
+     *
+     * Performs a depth-first search through all Mesh objects and collects the mesh objects
+     * whose materials have names that match the provided regular expression. This is useful
+     * for finding all objects that use specific material types or naming patterns.
+     *
+     * @param object - The root Object3D to start searching from
+     * @param materialName - Regular expression pattern to test against material names
+     * @returns Array of all Mesh objects that use materials with matching names
+     */
+    static findMaterialUsers(object: Object3D, materialName: RegExp): Mesh[];
 }

package/dist/Sun.d.ts

@@ -1,8 +1,14 @@
 import type { Texture } from "three";
 import { Box3, DirectionalLight } from "three";
-/** A directional light with spherical positioning controls */
+/**
+ * A directional light with spherical positioning controls and advanced shadow mapping.
+ *
+ * Extends Three.js DirectionalLight to provide intuitive spherical coordinate control
+ * (distance, elevation, azimuth) and automatic shadow map configuration for bounding boxes.
+ * Also supports automatic sun direction calculation from HDR environment maps.
+ */
 export declare class Sun extends DirectionalLight {
-    /** Internal vectors to avoid garbage collection */
+    /** Internal vectors to avoid garbage collection during calculations */
     private readonly tempVector3D0;
     private readonly tempVector3D1;
     private readonly tempVector3D2;
@@ -13,20 +19,61 @@ export declare class Sun extends DirectionalLight {
     private readonly tempVector3D7;
     private readonly tempBox3;
     private readonly tempSpherical;
-    /** Distance from the light to its target */
+    /**
+     * Gets the distance from the light to its target (origin).
+     *
+     * @returns The distance in world units
+     */
     get distance(): number;
-    /** Vertical angle from the ground in radians */
+    /**
+     * Gets the elevation angle (vertical angle from the horizontal plane).
+     *
+     * @returns The elevation angle in radians (0 = horizontal, π/2 = directly above)
+     */
     get elevation(): number;
-    /** Horizontal angle around the target in radians */
+    /**
+     * Gets the azimuth angle (horizontal rotation around the target).
+     *
+     * @returns The azimuth angle in radians (0 = positive X axis, π/2 = positive Z axis)
+     */
     get azimuth(): number;
-    /** Set distance while keeping current angles */
+    /**
+     * Sets the distance while preserving current elevation and azimuth angles.
+     *
+     * @param value - The new distance in world units
+     */
     set distance(value: number);
-    /** Set elevation while keeping current distance and azimuth */
+    /**
+     * Sets the elevation angle while preserving current distance and azimuth.
+     *
+     * @param value - The new elevation angle in radians (0 = horizontal, π/2 = directly above)
+     */
     set elevation(value: number);
-    /** Set azimuth while keeping current distance and elevation */
+    /**
+     * Sets the azimuth angle while preserving current distance and elevation.
+     *
+     * @param value - The new azimuth angle in radians (0 = positive X axis, π/2 = positive Z axis)
+     */
     set azimuth(value: number);
-    /** Configure shadows to cover all corners of a bounding box */
-    setShadowMapFromBox3(box3: Box3): void;
-    /** Set light direction based on brightest point in an HDR texture */
-    setDirectionFromHDR(texture: Texture, distance?: number): void;
+    /**
+     * Configures the shadow camera to optimally cover a bounding box.
+     *
+     * This method automatically adjusts the directional light's shadow camera frustum
+     * to perfectly encompass the provided bounding box, ensuring efficient shadow map
+     * usage and eliminating shadow clipping issues.
+     *
+     * @param box3 - The 3D bounding box to cover with shadows
+     */
+    configureShadowsForBoundingBox(box3: Box3): void;
+    /**
+     * Sets the sun's direction based on the brightest point in an HDR environment map.
+     *
+     * This method analyzes an HDR texture to find the pixel with the highest luminance
+     * value and positions the sun to shine from that direction. This is useful for
+     * creating realistic lighting that matches HDR environment maps.
+     *
+     * @param texture - The HDR texture to analyze (must have image data available)
+     * @param distance - The distance to place the sun from the origin (defaults to 1)
+     */
+    setDirectionFromHDRTexture(texture: Texture, distance?: number): void;
 }

package/dist/index.d.ts

@@ -1,7 +1,4 @@
-export * from "./BiFovCamera";
-export * from "./Bounds";
-export * from "./InstanceAssembler";
-export * from "./SceneProcessor";
+export * from "./DualFovCamera";
 export * from "./SceneTraversal";
 export * from "./SkinnedMeshBaker";
 export * from "./Sun";