three-zoo 0.4.1 → 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

@@ -0,0 +1,49 @@
+import { PerspectiveCamera } 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 BiFovCamera extends PerspectiveCamera {
+    private horizontalFovInternal;
+    private verticalFovInternal;
+    /**
+     * @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);
+    /** Current horizontal FOV in degrees */
+    get horizontalFov(): number;
+    /** Current vertical FOV in degrees */
+    get verticalFov(): number;
+    /** Set horizontal FOV in degrees (clamped between 1° and 179°) */
+    set horizontalFov(value: number);
+    /** Set vertical FOV in degrees (clamped between 1° and 179°) */
+    set verticalFov(value: number);
+    /**
+     * Update both horizontal and vertical FOV
+     * @param horizontal - Horizontal FOV in degrees
+     * @param vertical - Vertical FOV in degrees
+     */
+    setFov(horizontal: number, vertical: number): void;
+    /**
+     * Copy FOV settings from another BiFovCamera
+     * @param source - Camera to copy from
+     */
+    copyFovSettings(source: BiFovCamera): void;
+    /**
+     * Updates the projection matrix based on FOV settings and aspect ratio.
+     * In landscape: preserves horizontal FOV
+     * In portrait: preserves vertical FOV
+     */
+    updateProjectionMatrix(): void;
+    /** Get actual horizontal FOV after aspect ratio adjustments */
+    getEffectiveHorizontalFov(): number;
+    /** Get actual vertical FOV after aspect ratio adjustments */
+    getEffectiveVerticalFov(): number;
+    /** Create a clone of this camera */
+    clone(): this;
+}

package/dist/Bounds.d.ts

@@ -1,8 +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 {
-    private readonly tempVector3;
+    /** Temporary vector for calculations */
+    private readonly tempVector3A;
+    constructor(object?: Object3D);
+    /** Width (x-axis length) */
     get width(): number;
+    /** Height (y-axis length) */
     get height(): number;
+    /** Depth (z-axis length) */
     get depth(): number;
+    /** Length of the box's diagonal */
     get diagonal(): number;
+    /** Volume (width * height * depth) */
+    getVolume(): number;
+    /** Surface area (sum of all six faces) */
+    getSurfaceArea(): number;
 }

package/dist/GeometryHasher.d.ts

@@ -0,0 +1,17 @@
+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;
+}

package/dist/InstanceAssembler.d.ts

@@ -1,10 +1,26 @@
-import { Mesh, Object3D } from "three";
-interface IOptions {
-    container: Object3D;
-    filter?: (child: Mesh) => boolean;
-    geometryTolerance?: number;
+import type { Object3D } from "three";
+import { Mesh } from "three";
+/** 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 { Object3D } from "three";
-type IPattern = string | RegExp;
-interface IOptions {
-    asset: Object3D;
-    castShadowMeshNames?: IPattern[];
-    receiveShadowMeshNames?: IPattern[];
-    transparentMaterialNames?: IPattern[];
-    noDepthWriteMaterialNames?: IPattern[];
+import type { Object3D } from "three";
+/** 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

@@ -0,0 +1,20 @@
+import type { Material, Object3D } from "three";
+/** 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[];
+    /** Set shadow properties on meshes */
+    static setShadowRecursive(object: Object3D, castShadow?: boolean, receiveShadow?: boolean, filter?: (object: Object3D) => boolean): void;
+}

package/dist/SkinnedMeshBaker.d.ts

@@ -1,24 +1,23 @@
-import { AnimationClip, Mesh, Object3D, SkinnedMesh } from "three";
-/**
- * Utilities for baking poses and animations from SkinnedMesh into a regular static Mesh.
- */
+import type { AnimationClip, Object3D, SkinnedMesh } from "three";
+import { Mesh } from "three";
+/** 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,21 +1,32 @@
-import { Box3, DirectionalLight, Texture } from "three";
+import type { Texture } from "three";
+import { Box3, DirectionalLight } from "three";
+/** A directional light with spherical positioning controls */
 export declare class Sun extends DirectionalLight {
-    private tempVector3D0;
-    private tempVector3D1;
-    private tempVector3D2;
-    private tempVector3D3;
-    private tempVector3D4;
-    private tempVector3D5;
-    private tempVector3D6;
-    private tempVector3D7;
-    private tempBox3;
-    private tempSpherical;
+    /** Internal vectors to avoid garbage collection */
+    private readonly tempVector3D0;
+    private readonly tempVector3D1;
+    private readonly tempVector3D2;
+    private readonly tempVector3D3;
+    private readonly tempVector3D4;
+    private readonly tempVector3D5;
+    private readonly tempVector3D6;
+    private readonly tempVector3D7;
+    private readonly tempBox3;
+    private readonly tempSpherical;
+    /** Distance from the light to its target */
     get distance(): number;
+    /** Vertical angle from the ground in radians */
     get elevation(): number;
+    /** Horizontal angle around the target in radians */
     get azimuth(): number;
+    /** Set distance while keeping current angles */
     set distance(value: number);
+    /** Set elevation while keeping current distance and azimuth */
     set elevation(value: number);
+    /** Set azimuth while keeping current distance and elevation */
     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;
 }

package/dist/index.d.ts

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