three-zoo 0.5.3 → 0.5.5

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <h1 align="center">🦁 three-zoo</h1>
   <p align="center">
-    A modest collection of Three.js utilities designed to simplify common 3D development tasks.
+    A small collection of Three.js utilities I use in my daily work with 3D development.
   </p>
 </p>
 
@@ -13,12 +13,14 @@
 <a href="https://threejs.org/"><img src="https://img.shields.io/badge/Three.js-%5E0.175.0-green" alt="Three.js"></a>
 </p>
 
-## Features
+## What's included
 
-- 📷 **DualFovCamera** - Independent horizontal and vertical FOV control with auto-fitting
-- ☀️ **Sun** - Intuitive spherical positioning for directional lights with HDR integration
-- 🔍 **SceneTraversal** - Find and manipulate objects and materials in scene graphs
-- 🎭 **SkinnedMeshBaker** - Convert animated meshes to static geometry
+- 📷 **DualFovCamera** - Camera with separate horizontal and vertical FOV controls
+- ☀️ **Sun** - Directional light with spherical positioning
+- 🔍 **SceneTraversal** - Helper functions for finding objects and materials in scenes
+- 🎭 **SkinnedMeshBaker** - Converts animated meshes to static geometry
+- 🎨 **StandardToLambertConverter** - Converts PBR materials to Lambert materials
+- ✨ **StandardToBasicConverter** - Converts PBR materials to Basic materials
 
 ## Installation
 
@@ -28,60 +30,60 @@ npm install three-zoo
 
 ## DualFovCamera
 
-Advanced camera with independent horizontal and vertical field of view:
+A camera that lets you control horizontal and vertical field of view separately:
 
 ```typescript
 const camera = new DualFovCamera(90, 60);
 
-// Independent FOV control
+// Set FOV values independently
 camera.horizontalFov = 100;
 camera.verticalFov = 70;
 
-// Auto-fit objects in view
+// Fit objects in view
 camera.fitVerticalFovToPoints(vertices);
 camera.fitVerticalFovToBox(boundingBox);
 camera.fitVerticalFovToMesh(skinnedMesh);
 
-// Smart camera positioning
+// Position camera based on mesh center
 camera.lookAtMeshCenterOfMass(skinnedMesh);
 ```
 
 ## Sun
 
-Directional light with spherical positioning:
+A directional light with spherical positioning:
 
 ```typescript
 const sun = new Sun();
 
-// Spherical coordinates
+// Position using spherical coordinates
 sun.elevation = Math.PI / 4;  // 45° above horizon
 sun.azimuth = Math.PI / 2;    // 90° rotation
 sun.distance = 100;           // Distance from origin
 
-// Automatic shadow configuration
+// Set up shadows for a bounding box
 sun.configureShadowsForBoundingBox(sceneBounds);
 
-// Position from HDR environment map
+// Position based on HDR environment map
 sun.setDirectionFromHDRTexture(hdrTexture, 50);
 ```
 
 ## SceneTraversal
 
-Navigate and manipulate Three.js scene graphs:
+Functions for working with Three.js scene graphs:
 
 ```typescript
 // Find by name
 const player = SceneTraversal.getObjectByName(scene, 'Player');
 const metal = SceneTraversal.getMaterialByName(scene, 'MetalMaterial');
 
-// Filter with patterns
+// Find with patterns
 const enemies = SceneTraversal.filterObjects(scene, /^enemy_/);
 const glassMats = SceneTraversal.filterMaterials(scene, /glass/i);
 
-// Find material users
+// Find objects using specific materials
 const glassObjects = SceneTraversal.findMaterialUsers(scene, /glass/i);
 
-// Batch operations
+// Process all materials in a scene
 SceneTraversal.enumerateMaterials(scene, (material) => {
   if ('roughness' in material) material.roughness = 0.8;
 });
@@ -104,6 +106,39 @@ const frameMesh = SkinnedMeshBaker.bakeAnimationFrame(
 );
 ```
 
+## Material Converters
+
+Convert PBR materials to simpler types. Useful for performance optimization:
+
+### StandardToLambertConverter
+
+```typescript
+// Basic conversion
+const lambertMaterial = StandardToLambertConverter.convert(standardMaterial);
+
+// With options
+const lambertMaterial = StandardToLambertConverter.convert(standardMaterial, {
+  preserveName: true,
+  roughnessColorFactor: 0.9,
+  disposeOriginal: true
+});
+```
+
+### StandardToBasicConverter
+
+```typescript
+// Convert to unlit material
+const basicMaterial = StandardToBasicConverter.convert(standardMaterial);
+
+// With brightness adjustment
+const basicMaterial = StandardToBasicConverter.convert(standardMaterial, {
+  brightnessFactor: 1.5,
+  combineEmissive: true,
+  preserveName: true,
+  disposeOriginal: false
+});
+```
+
 ## Requirements
 
 - Three.js ^0.175.0 (peer dependency)
@@ -111,7 +146,7 @@ const frameMesh = SkinnedMeshBaker.bakeAnimationFrame(
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit issues and pull requests.
+Feel free to submit issues and pull requests if you find these utilities helpful.
 
 ## License
 

package/dist/DualFovCamera.d.ts

@@ -11,50 +11,50 @@ export declare class DualFovCamera extends PerspectiveCamera {
     /** Internal storage for vertical field of view in degrees */
     private verticalFovInternal;
     /**
-     * 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?: number, verticalFov?: number, aspect?: number, near?: number, far?: number);
     /**
-     * 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(): number;
     /**
-     * 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(): number;
     /**
      * 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: number);
     /**
      * 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: number);
     /**
-     * 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: number, vertical: number): void;
     /**
-     * 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: DualFovCamera): void;
     /**
@@ -64,78 +64,77 @@ export declare 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
      */
     updateProjectionMatrix(): void;
     /**
-     * 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(): number;
     /**
-     * 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(): number;
     /**
-     * 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: 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
+     * 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: 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.
+     * 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): 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
+     * 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): void;
     /**
-     * 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(): this;

package/dist/SceneTraversal.d.ts

@@ -1,10 +1,10 @@
 import type { Material, Object3D } from "three";
 import { Mesh } from "three";
 /**
- * Constructor type for type-safe scene traversal operations.
+ * Constructor type for 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.
+ * Represents a constructor function that creates instances of type T.
+ * Used for runtime type checking when filtering objects by constructor type.
  *
  * @template T - The type that the constructor creates
  */
@@ -12,99 +12,89 @@ export type Constructor<T> = abstract new (...args: never[]) => T;
 /**
  * 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.
  */
 export declare 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: Object3D, name: string): Object3D | null;
     /**
      * 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: Object3D, name: string): Material | null;
     /**
      * 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<T>(object: Object3D, type: Constructor<T>, callback: (instance: T) => void): void;
     /**
      * 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: Object3D, callback: (material: Material) => void): void;
     /**
-     * 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: Object3D, filter: RegExp | ((object: Object3D) => boolean)): Object3D[];
     /**
-     * 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: Object3D, name: RegExp): Material[];
     /**
-     * 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

package/dist/SkinnedMeshBaker.d.ts

@@ -1,19 +1,19 @@
 import type { AnimationClip, Object3D, SkinnedMesh } from "three";
 import { Mesh } from "three";
-/** Convert skinned meshes to regular static meshes */
+/** Converts skinned meshes to static meshes */
 export declare 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
      */
     static bakePose(skinnedMesh: SkinnedMesh): 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

package/dist/StandardToBasicConverter.d.ts

@@ -0,0 +1,68 @@
+import type { MeshStandardMaterial } from "three";
+import { MeshBasicMaterial } from "three";
+/**
+ * Configuration options for the StandardToBasicConverter.
+ */
+export interface StandardToBasicConverterOptions {
+    /**
+     * Whether to preserve the original material's name
+     * @defaultValue true
+     */
+    preserveName: boolean;
+    /**
+     * Whether to copy user data from the original material
+     * @defaultValue true
+     */
+    copyUserData: boolean;
+    /**
+     * Whether to dispose the original material after conversion
+     * @defaultValue false
+     */
+    disposeOriginal: boolean;
+    /**
+     * Whether to apply emissive color to the base color for brightness compensation
+     * @defaultValue true
+     */
+    combineEmissive: boolean;
+    /**
+     * Factor for brightness adjustment to compensate for loss of lighting
+     * @defaultValue 1.3
+     */
+    brightnessFactor: number;
+}
+/**
+ * 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.
+ */
+export declare 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: MeshStandardMaterial, options?: Partial<StandardToBasicConverterOptions>): MeshBasicMaterial;
+}
+export default StandardToBasicConverter;

package/dist/StandardToLambertConverter.d.ts

@@ -0,0 +1,58 @@
+import type { MeshStandardMaterial } from "three";
+import { MeshLambertMaterial } from "three";
+/**
+ * Configuration options for the StandardToLambertConverter.
+ */
+export interface StandardToLambertConverterOptions {
+    /**
+     * Whether to preserve the original material's name
+     * @defaultValue true
+     */
+    preserveName: boolean;
+    /**
+     * Whether to copy user data from the original material
+     * @defaultValue true
+     */
+    copyUserData: boolean;
+    /**
+     * Whether to dispose the original material after conversion
+     * @defaultValue false
+     */
+    disposeOriginal: boolean;
+    /**
+     * Custom color adjustment factor for roughness compensation
+     * @defaultValue 0.8
+     */
+    roughnessColorFactor: number;
+}
+/**
+ * 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.
+ */
+export declare 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: MeshStandardMaterial, options?: Partial<StandardToLambertConverterOptions>): MeshLambertMaterial;
+}