three-zoo 0.4.2 → 0.4.3

package/README.md

@@ -0,0 +1,110 @@
+# three-zoo
+
+A few Three.js utilities to handle common 3D tasks.
+
+## Install
+
+```bash
+npm install three-zoo
+```
+
+## Tools
+
+### BiFovCamera
+
+Camera with separate horizontal and vertical FOV control:
+
+```typescript
+const camera = new BiFovCamera(90, 60); // hFov, vFov
+camera.horizontalFov = 100; // Change horizontal FOV
+camera.verticalFov = 70;    // Change vertical FOV
+```
+
+### Bounds
+
+Extra bounding box calculations:
+
+```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
+```
+
+### InstanceAssembler
+
+Combines identical meshes into instances:
+
+```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
+});
+```
+
+### SceneProcessor
+
+Sets up materials and shadows based on naming patterns:
+
+```typescript
+SceneProcessor.process(scene, {
+  castShadowExpressions: [/^Tree_.*/],
+  receiveShadwoExpressions: [/Ground/],
+  transparentMaterialExpressions: [/Glass/],
+});
+```
+
+### SceneTraversal
+
+Scene graph utilities:
+
+```typescript
+// Find objects
+const obj = SceneTraversal.getObjectByName(scene, 'player');
+const objects = SceneTraversal.filterObjects(scene, /^enemy_/);
+
+// Configure shadows
+SceneTraversal.setShadowRecursive(scene, true, true);
+```
+
+### SkinnedMeshBaker
+
+Converts skinned meshes to static geometry:
+
+```typescript
+// Bake current pose
+const staticMesh = SkinnedMeshBaker.bakePose(skinnedMesh);
+
+// Bake animation frame
+const frameMesh = SkinnedMeshBaker.bakeAnimationFrame(
+  armature,
+  skinnedMesh,
+  1.5,  // time
+  clip   // animation
+);
+```
+
+### 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
+
+## License
+
+MIT

package/dist/BiFovCamera.d.ts

@@ -1,71 +1,49 @@
 import { PerspectiveCamera } from "three";
 /**
- * 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.
  */
 export declare class BiFovCamera extends PerspectiveCamera {
     private horizontalFovInternal;
     private verticalFovInternal;
     /**
-     * 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?: number, verticalFov?: number, aspect?: number, near?: number, far?: number);
-    /**
-     * Gets the horizontal field of view in degrees
-     */
+    /** Current horizontal FOV in degrees */
     get horizontalFov(): number;
-    /**
-     * Gets the vertical field of view in degrees
-     */
+    /** Current vertical FOV in degrees */
     get verticalFov(): number;
-    /**
-     * 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: number);
-    /**
-     * 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: number);
     /**
-     * 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: number, vertical: number): void;
     /**
-     * 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: BiFovCamera): void;
     /**
-     * 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(): void;
-    /**
-     * Returns the actual horizontal FOV after aspect ratio adjustments
-     */
+    /** Get actual horizontal FOV after aspect ratio adjustments */
     getEffectiveHorizontalFov(): number;
-    /**
-     * Returns the actual vertical FOV after aspect ratio adjustments
-     */
+    /** Get actual vertical FOV after aspect ratio adjustments */
     getEffectiveVerticalFov(): number;
-    /**
-     * Creates a clone of this camera with the same properties
-     */
+    /** Create a clone of this camera */
     clone(): this;
 }

package/dist/Bounds.d.ts

@@ -1,28 +1,22 @@
+import type { Object3D } from "three";
 import { Box3 } from "three";
+/**
+ * Box3 with additional convenience methods for width, height, depth, etc.
+ */
 export declare class Bounds extends Box3 {
+    /** Temporary vector for calculations */
     private readonly tempVector3A;
-    /**
-     * Gets the width (x-axis length) of the bounding box
-     */
+    constructor(object?: Object3D);
+    /** Width (x-axis length) */
     get width(): number;
-    /**
-     * Gets the height (y-axis length) of the bounding box
-     */
+    /** Height (y-axis length) */
     get height(): number;
-    /**
-     * Gets the depth (z-axis length) of the bounding box
-     */
+    /** Depth (z-axis length) */
     get depth(): number;
-    /**
-     * Gets the length of the box's diagonal
-     */
+    /** Length of the box's diagonal */
     get diagonal(): number;
-    /**
-     * Gets the volume of the bounding box
-     */
+    /** Volume (width * height * depth) */
     getVolume(): number;
-    /**
-     * Gets the surface area of the bounding box
-     */
+    /** Surface area (sum of all six faces) */
     getSurfaceArea(): number;
 }

package/dist/GeometryHasher.d.ts

@@ -1,27 +1,17 @@
 import type { BufferGeometry } from "three";
 /**
- * Utility class for comparing and hashing BufferGeometry instances with tolerance support.
+ * Internal utility to identify identical geometries.
+ * @internal
  */
 export declare 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
+     * @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;
-    /**
-     * Compares two BufferGeometry instances for approximate equality.
-     * Early exit if UUIDs match (same object or cloned geometry).
-     */
-    static compare(firstGeometry: BufferGeometry, secondGeometry: BufferGeometry, tolerance?: number): boolean;
-    /**
-     * Generates a hash for a buffer attribute with tolerance.
-     */
-    private static getAttributeHash;
-    /**
-     * Compares two buffer attributes with tolerance.
-     */
-    private static compareBufferAttributes;
+    static getGeometryHash(geometry: BufferGeometry, tolerance: number): string;
 }

package/dist/InstanceAssembler.d.ts

@@ -1,11 +1,26 @@
 import type { Object3D } from "three";
 import { Mesh } from "three";
-interface IOptions {
-    container: Object3D;
-    filter?: (child: Mesh) => boolean;
-    geometryTolerance?: number;
+/** Configuration for instance assembly */
+export interface InstanceAssemblerOptions {
+    /** Filter which meshes to include */
+    filter: (child: Mesh) => boolean;
+    /** How close vertices need to be to count as identical */
+    geometryTolerance: number;
 }
+/**
+ * Combines identical meshes into instanced versions for better performance.
+ * Meshes are considered identical if they share the same geometry and materials.
+ */
 export declare class InstanceAssembler {
-    static assemble(options: IOptions): void;
+    /**
+     * 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: Object3D, options?: Partial<InstanceAssemblerOptions>): void;
 }
-export {};

package/dist/SceneProcessor.d.ts

@@ -1,14 +1,29 @@
 import type { Object3D } from "three";
-type IPattern = string | RegExp;
-interface IOptions {
-    asset: Object3D;
-    castShadowMeshNames?: IPattern[];
-    receiveShadowMeshNames?: IPattern[];
-    transparentMaterialNames?: IPattern[];
-    noDepthWriteMaterialNames?: IPattern[];
+/** Options for scene post-processing */
+export interface SceneProcessorOptions {
+    /** Clone the input asset before processing? */
+    cloneAsset: boolean;
+    /** Combine identical meshes into instances? */
+    assembleInstances: boolean;
+    /** Names matching these patterns will cast shadows */
+    castShadowExpressions: RegExp[];
+    /** Names matching these patterns will receive shadows */
+    receiveShadwoExpressions: RegExp[];
+    /** Names matching these patterns will be transparent */
+    transparentMaterialExpressions: RegExp[];
+    /** Names matching these patterns won't write to depth buffer */
+    noDepthWriteMaterialExpressions: RegExp[];
 }
+/** Post-processes a scene based on name patterns */
 export declare class SceneProcessor {
-    static process(options: IOptions): Object3D[];
+    /**
+     * 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: Object3D, options: Partial<SceneProcessorOptions>): Object3D[];
+    /** Does the string match any of the patterns? */
     private static matchesAny;
 }
-export {};

package/dist/SceneTraversal.d.ts

@@ -1,12 +1,20 @@
 import type { Material, Object3D } from "three";
-type Constructor<T> = abstract new (...args: never[]) => T;
+/** Constructor type for type-safe scene traversal */
+export type Constructor<T> = abstract new (...args: never[]) => T;
+/** Find and modify objects in a Three.js scene */
 export declare class SceneTraversal {
+    /** Find first object with exact name match */
     static getObjectByName(object: Object3D, name: string): Object3D | null;
+    /** Find first material with exact name match */
     static getMaterialByName(object: Object3D, name: string): Material | null;
+    /** Process all objects of a specific type */
     static enumerateObjectsByType<T>(object: Object3D, type: Constructor<T>, callback: (instance: T) => void): void;
+    /** Process all materials in meshes */
     static enumerateMaterials(object: Object3D, callback: (material: Material) => void): void;
+    /** Find all objects whose names match a pattern */
     static filterObjects(object: Object3D, name: RegExp): Object3D[];
+    /** Find all materials whose names match a pattern */
     static filterMaterials(object: Object3D, name: RegExp): Material[];
-    static setShadowRecursive(object: Object3D, castShadow?: boolean, receiveShadow?: boolean): void;
+    /** Set shadow properties on meshes */
+    static setShadowRecursive(object: Object3D, castShadow?: boolean, receiveShadow?: boolean, filter?: (object: Object3D) => boolean): void;
 }
-export {};

package/dist/SkinnedMeshBaker.d.ts

@@ -1,25 +1,23 @@
 import type { AnimationClip, Object3D, SkinnedMesh } from "three";
 import { Mesh } from "three";
-/**
- * Utilities for baking poses and animations from SkinnedMesh into a regular static Mesh.
- */
+/** Convert skinned meshes to regular static meshes */
 export declare 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: SkinnedMesh): 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: Object3D, skinnedMesh: SkinnedMesh, timeOffset: number, clip: AnimationClip): Mesh;
 }

package/dist/Sun.d.ts

@@ -1,18 +1,8 @@
 import type { Texture } from "three";
 import { Box3, DirectionalLight } from "three";
-/**
- * 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
- */
+/** A directional light with spherical positioning controls */
 export declare class Sun extends DirectionalLight {
+    /** Internal vectors to avoid garbage collection */
     private readonly tempVector3D0;
     private readonly tempVector3D1;
     private readonly tempVector3D2;
@@ -23,49 +13,20 @@ export declare class Sun extends DirectionalLight {
     private readonly tempVector3D7;
     private readonly tempBox3;
     private readonly tempSpherical;
-    /**
-     * 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(): number;
-    /**
-     * 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(): number;
-    /**
-     * 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(): number;
-    /**
-     * 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: number);
-    /**
-     * 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: number);
-    /**
-     * 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: number);
-    /**
-     * 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: Box3): void;
-    /**
-     * 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: Texture, distance?: number): void;
 }