three-zoo 0.5.2 → 0.5.4

package/README.md

@@ -16,9 +16,11 @@
 ## Features
 
 - 📷 **DualFovCamera** - Independent horizontal and vertical FOV control with auto-fitting
-- 🔍 **SceneTraversal** - Find and manipulate objects and materials in scene graphs
-- 🎭 **SkinnedMeshBaker** - Convert animated meshes to static geometry for optimization
 - ☀️ **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
+- 🎨 **StandardToLambertConverter** - Convert PBR materials to Lambert with visual compensation
+- ✨ **StandardToBasicConverter** - Convert PBR materials to unlit Basic materials
 
 ## Installation
 
@@ -26,27 +28,6 @@
 npm install three-zoo
 ```
 
-## Quick Start
-
-```typescript
-import { DualFovCamera, SceneTraversal, Sun } from 'three-zoo';
-
-// Camera with independent FOV control
-const camera = new DualFovCamera(90, 60);
-camera.fitVerticalFovToMesh(characterMesh);
-camera.lookAtMeshCenterOfMass(characterMesh);
-
-// Scene traversal and manipulation
-const enemies = SceneTraversal.filterObjects(scene, /^enemy_/);
-const glassMaterials = SceneTraversal.filterMaterials(scene, /glass/i);
-
-// Intuitive sun positioning
-const sun = new Sun();
-sun.elevation = Math.PI / 4;
-sun.azimuth = Math.PI / 2;
-sun.configureShadowsForBoundingBox(sceneBounds);
-```
-
 ## DualFovCamera
 
 Advanced camera with independent horizontal and vertical field of view:
@@ -67,6 +48,25 @@ camera.fitVerticalFovToMesh(skinnedMesh);
 camera.lookAtMeshCenterOfMass(skinnedMesh);
 ```
 
+## Sun
+
+Directional light with spherical positioning:
+
+```typescript
+const sun = new Sun();
+
+// 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
+sun.configureShadowsForBoundingBox(sceneBounds);
+
+// Position from HDR environment map
+sun.setDirectionFromHDRTexture(hdrTexture, 50);
+```
+
 ## SceneTraversal
 
 Navigate and manipulate Three.js scene graphs:
@@ -106,23 +106,37 @@ const frameMesh = SkinnedMeshBaker.bakeAnimationFrame(
 );
 ```
 
-## Sun
+## Material Converters
 
-Directional light with spherical positioning:
+Convert PBR StandardMaterials to simpler material types while preserving visual appearance:
 
-```typescript
-const sun = new Sun();
+### StandardToLambertConverter
 
-// Spherical coordinates
-sun.elevation = Math.PI / 4;  // 45° above horizon
-sun.azimuth = Math.PI / 2;    // 90° rotation
-sun.distance = 100;           // Distance from origin
+```typescript
+// Basic conversion
+const lambertMaterial = StandardToLambertConverter.convert(standardMaterial);
+
+// With custom options
+const lambertMaterial = StandardToLambertConverter.convert(standardMaterial, {
+  preserveName: true,
+  roughnessColorFactor: 0.9,
+  disposeOriginal: true
+});
+```
 
-// Automatic shadow configuration
-sun.configureShadowsForBoundingBox(sceneBounds);
+### StandardToBasicConverter
 
-// Position from HDR environment map
-sun.setDirectionFromHDRTexture(hdrTexture, 50);
+```typescript
+// Convert to unlit material
+const basicMaterial = StandardToBasicConverter.convert(standardMaterial);
+
+// With brightness compensation
+const basicMaterial = StandardToBasicConverter.convert(standardMaterial, {
+  brightnessFactor: 1.5,
+  combineEmissive: true,
+  preserveName: true,
+  disposeOriginal: false
+});
 ```
 
 ## Requirements

package/dist/StandardToBasicConverter.d.ts

@@ -0,0 +1,74 @@
+import type { MeshStandardMaterial } from "three";
+import { MeshBasicMaterial } from "three";
+/**
+ * Configuration options for the StandardToBasicConverter
+ *
+ * @interface StandardToBasicConverterOptions
+ */
+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
+ *
+ * This converter handles the translation from PBR (Physically Based Rendering)
+ * StandardMaterial to the unlit BasicMaterial. Since BasicMaterial doesn't respond
+ * to lighting, this converter applies various compensation techniques to maintain
+ * visual similarity, including brightness adjustments and emissive color combination.
+ */
+export declare class StandardToBasicConverter {
+    /**
+     * Converts a MeshStandardMaterial to MeshBasicMaterial
+     *
+     * This method performs a comprehensive conversion from PBR StandardMaterial to
+     * unlit BasicMaterial while attempting to preserve visual similarity through
+     * brightness compensation and intelligent 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
+     * });
+     * ```
+     *
+     * @see {@link StandardToBasicConverterOptions} for available configuration options
+     */
+    static convert(standardMaterial: MeshStandardMaterial, options?: Partial<StandardToBasicConverterOptions>): MeshBasicMaterial;
+}
+export default StandardToBasicConverter;

package/dist/StandardToLambertConverter.d.ts

@@ -0,0 +1,64 @@
+import type { MeshStandardMaterial } from "three";
+import { MeshLambertMaterial } from "three";
+/**
+ * Configuration options for the StandardToLambertConverter
+ *
+ * @interface StandardToLambertConverterOptions
+ */
+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
+ *
+ * This converter handles the translation between PBR (Physically Based Rendering)
+ * properties of StandardMaterial and the simpler Lambertian reflectance model
+ * used by LambertMaterial. The conversion preserves visual similarity by applying
+ * color compensation based on metalness and roughness values.
+ */
+export declare class StandardToLambertConverter {
+    /**
+     * Converts a MeshStandardMaterial to MeshLambertMaterial
+     *
+     * This method performs a comprehensive conversion from PBR StandardMaterial to
+     * the simpler Lambert lighting model while attempting to preserve visual similarity
+     * through intelligent color compensation.
+     *
+     * @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);
+     * ```
+     *
+     * @see {@link StandardToLambertConverterOptions} for available configuration options
+     */
+    static convert(material: MeshStandardMaterial, options?: Partial<StandardToLambertConverterOptions>): MeshLambertMaterial;
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./DualFovCamera";
 export * from "./SceneTraversal";
 export * from "./SkinnedMeshBaker";
+export * from "./StandardToBasicConverter";
+export * from "./StandardToLambertConverter";
 export * from "./Sun";

package/dist/index.js

@@ -1,4 +1,4 @@
-import { PerspectiveCamera, MathUtils, Vector3, Mesh, BufferAttribute, AnimationMixer, DirectionalLight, Box3, Spherical, RGBAFormat } from 'three';
+import { PerspectiveCamera, MathUtils, Vector3, Mesh, BufferAttribute, AnimationMixer, MeshBasicMaterial, MeshLambertMaterial, DirectionalLight, Box3, Spherical, RGBAFormat } from 'three';
 
 /** Default horizontal field of view in degrees */
 const DEFAULT_HORIZONTAL_FOV = 90;
@@ -550,6 +550,411 @@ class SkinnedMeshBaker {
     }
 }
 
+/**
+ * Converts Three.js MeshStandardMaterial to MeshBasicMaterial
+ *
+ * This converter handles the translation from PBR (Physically Based Rendering)
+ * StandardMaterial to the unlit BasicMaterial. Since BasicMaterial doesn't respond
+ * to lighting, this converter applies various compensation techniques to maintain
+ * visual similarity, including brightness adjustments and emissive color combination.
+ */
+class StandardToBasicConverter {
+    /**
+     * Converts a MeshStandardMaterial to MeshBasicMaterial
+     *
+     * This method performs a comprehensive conversion from PBR StandardMaterial to
+     * unlit BasicMaterial while attempting to preserve visual similarity through
+     * brightness compensation and intelligent 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
+     * });
+     * ```
+     *
+     * @see {@link StandardToBasicConverterOptions} for available configuration options
+     */
+    static convert(standardMaterial, options = {}) {
+        const config = {
+            preserveName: true,
+            copyUserData: true,
+            disposeOriginal: false,
+            combineEmissive: true,
+            brightnessFactor: 1.3,
+            ...options,
+        };
+        // Create new Basic material
+        const basicMaterial = new MeshBasicMaterial();
+        // Copy basic material properties
+        this.copyBasicProperties(standardMaterial, basicMaterial, config);
+        // Handle color properties with lighting compensation
+        this.convertColorProperties(standardMaterial, basicMaterial, config);
+        // Handle texture maps
+        this.convertTextureMaps(standardMaterial, basicMaterial);
+        // Handle transparency and alpha
+        this.convertTransparencyProperties(standardMaterial, basicMaterial);
+        // Cleanup if requested
+        if (config.disposeOriginal) {
+            standardMaterial.dispose();
+        }
+        basicMaterial.needsUpdate = true;
+        return basicMaterial;
+    }
+    /**
+     * Copies basic material properties from source to target material
+     *
+     * Transfers common material properties including rendering settings,
+     * visibility, fog interaction, wireframe settings, and user data.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshBasicMaterial
+     * @param config - The resolved configuration options
+     * @internal
+     */
+    static copyBasicProperties(source, target, config) {
+        if (config.preserveName) {
+            target.name = source.name;
+        }
+        target.side = source.side;
+        target.visible = source.visible;
+        target.fog = source.fog;
+        target.wireframe = source.wireframe;
+        target.wireframeLinewidth = source.wireframeLinewidth;
+        target.vertexColors = source.vertexColors;
+        if (config.copyUserData) {
+            target.userData = { ...source.userData };
+        }
+    }
+    /**
+     * Converts color-related properties with lighting compensation
+     *
+     * Applies brightness compensation and optional emissive color combination
+     * to account for BasicMaterial's lack of lighting response. Metallic materials
+     * receive additional brightness adjustment, and colors are clamped to valid ranges.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshBasicMaterial
+     * @param config - The resolved configuration options
+     * @internal
+     */
+    static convertColorProperties(source, target, config) {
+        // Base color conversion with brightness compensation
+        target.color = source.color.clone();
+        // Apply brightness compensation since BasicMaterial doesn't respond to lighting
+        target.color.multiplyScalar(config.brightnessFactor);
+        // Adjust for metalness - metallic materials tend to be darker without lighting
+        if (source.metalness > 0) {
+            const metalnessBrightness = 1 + source.metalness * 0.3;
+            target.color.multiplyScalar(metalnessBrightness);
+        }
+        // Combine emissive color if requested
+        if (config.combineEmissive) {
+            const emissiveContribution = source.emissive
+                .clone()
+                .multiplyScalar(source.emissiveIntensity * 0.5);
+            target.color.add(emissiveContribution);
+        }
+        // Ensure color doesn't exceed valid range
+        target.color.r = Math.min(target.color.r, 1.0);
+        target.color.g = Math.min(target.color.g, 1.0);
+        target.color.b = Math.min(target.color.b, 1.0);
+    }
+    /**
+     * Converts and maps texture properties from Standard to Basic material
+     *
+     * Handles the transfer of compatible texture maps including diffuse, alpha,
+     * environment, light, and AO maps. The metalness map is repurposed as a
+     * specular map for some reflective effect, and environment map reflectivity
+     * is set based on the original material's metalness value.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshBasicMaterial
+     * @internal
+     */
+    static convertTextureMaps(source, target) {
+        // Main diffuse/albedo map
+        if (source.map) {
+            target.map = source.map;
+        }
+        // Alpha map
+        if (source.alphaMap) {
+            target.alphaMap = source.alphaMap;
+        }
+        // Environment map (BasicMaterial supports this for reflections)
+        if (source.envMap) {
+            target.envMap = source.envMap;
+            // Use metalness to determine reflectivity
+            target.reflectivity = source.metalness;
+        }
+        // Light map (BasicMaterial supports this)
+        if (source.lightMap) {
+            target.lightMap = source.lightMap;
+            target.lightMapIntensity = source.lightMapIntensity;
+        }
+        // AO map (BasicMaterial supports this)
+        if (source.aoMap) {
+            target.aoMap = source.aoMap;
+            target.aoMapIntensity = source.aoMapIntensity;
+        }
+        // Specular map (BasicMaterial supports this)
+        if (source.metalnessMap) {
+            // Use metalness map as specular map for some reflective effect
+            target.specularMap = source.metalnessMap;
+        }
+        // Copy UV transforms
+        this.copyUVTransforms(source, target);
+    }
+    /**
+     * Copies UV transformation properties for texture maps
+     *
+     * Transfers UV offset, repeat, rotation, and center properties from the
+     * source material's main texture map to the target material's map.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshBasicMaterial
+     * @internal
+     */
+    static copyUVTransforms(source, target) {
+        // Main texture UV transform
+        if (source.map && target.map) {
+            target.map.offset.copy(source.map.offset);
+            target.map.repeat.copy(source.map.repeat);
+            target.map.rotation = source.map.rotation;
+            target.map.center.copy(source.map.center);
+        }
+    }
+    /**
+     * Converts transparency and rendering properties
+     *
+     * Transfers transparency, opacity, alpha testing, depth testing,
+     * depth writing, and blending mode settings from source to target.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshBasicMaterial
+     * @internal
+     */
+    static convertTransparencyProperties(source, target) {
+        target.transparent = source.transparent;
+        target.opacity = source.opacity;
+        target.alphaTest = source.alphaTest;
+        target.depthTest = source.depthTest;
+        target.depthWrite = source.depthWrite;
+        target.blending = source.blending;
+    }
+}
+
+/**
+ * Converts Three.js MeshStandardMaterial to MeshLambertMaterial
+ *
+ * This converter handles the translation between PBR (Physically Based Rendering)
+ * properties of StandardMaterial and the simpler Lambertian reflectance model
+ * used by LambertMaterial. The conversion preserves visual similarity by applying
+ * color compensation based on metalness and roughness values.
+ */
+class StandardToLambertConverter {
+    /**
+     * Converts a MeshStandardMaterial to MeshLambertMaterial
+     *
+     * This method performs a comprehensive conversion from PBR StandardMaterial to
+     * the simpler Lambert lighting model while attempting to preserve visual similarity
+     * through intelligent color compensation.
+     *
+     * @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);
+     * ```
+     *
+     * @see {@link StandardToLambertConverterOptions} for available configuration options
+     */
+    static convert(material, options = {}) {
+        const config = {
+            preserveName: true,
+            copyUserData: true,
+            disposeOriginal: false,
+            roughnessColorFactor: 0.8,
+            ...options,
+        };
+        // Create new Lambert material
+        const lambertMaterial = new MeshLambertMaterial();
+        // Copy basic material properties
+        this.copyBasicProperties(material, lambertMaterial, config);
+        // Handle color properties with roughness compensation
+        this.convertColorProperties(material, lambertMaterial, config);
+        // Handle texture maps
+        this.convertTextureMaps(material, lambertMaterial);
+        // Handle transparency and alpha
+        this.convertTransparencyProperties(material, lambertMaterial);
+        // Cleanup if requested
+        if (config.disposeOriginal) {
+            material.dispose();
+        }
+        lambertMaterial.needsUpdate = true;
+        return lambertMaterial;
+    }
+    /**
+     * Copies basic material properties from source to target material
+     *
+     * Transfers common material properties including rendering settings,
+     * visibility, fog interaction, wireframe settings, and user data.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshLambertMaterial
+     * @param config - The resolved configuration options
+     * @internal
+     */
+    static copyBasicProperties(source, target, config) {
+        if (config.preserveName) {
+            target.name = source.name;
+        }
+        target.side = source.side;
+        target.visible = source.visible;
+        target.fog = source.fog;
+        target.wireframe = source.wireframe;
+        target.wireframeLinewidth = source.wireframeLinewidth;
+        target.vertexColors = source.vertexColors;
+        target.flatShading = source.flatShading;
+        if (config.copyUserData) {
+            target.userData = { ...source.userData };
+        }
+    }
+    /**
+     * Converts color-related properties with PBR compensation
+     *
+     * Applies intelligent color adjustments to compensate for the loss of
+     * metalness and roughness information when converting to Lambert material.
+     * Metallic materials are darkened and rough materials receive additional
+     * darkening based on the roughnessColorFactor.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshLambertMaterial
+     * @param config - The resolved configuration options
+     * @internal
+     */
+    static convertColorProperties(source, target, config) {
+        target.color = source.color.clone();
+        // Adjust color based on metalness and roughness for better visual match
+        if (source.metalness > 0) {
+            // Metallic materials tend to be darker in Lambert shading
+            const metalnessFactor = 1 - source.metalness * 0.3;
+            target.color.multiplyScalar(metalnessFactor);
+        }
+        if (source.roughness > 0.5) {
+            // Rough materials appear slightly darker
+            const roughnessFactor = config.roughnessColorFactor + source.roughness * 0.2;
+            target.color.multiplyScalar(roughnessFactor);
+        }
+        target.emissive = source.emissive.clone();
+        target.emissiveIntensity = source.emissiveIntensity;
+    }
+    /**
+     * Converts and maps texture properties from Standard to Lambert material
+     *
+     * Handles the transfer of compatible texture maps including diffuse, normal,
+     * emissive, AO, light maps, and environment maps. The environment map
+     * reflectivity is set based on the original material's metalness value.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshLambertMaterial
+     * @internal
+     */
+    static convertTextureMaps(source, target) {
+        // Diffuse/Albedo map
+        if (source.map) {
+            target.map = source.map;
+        }
+        // Emissive map
+        if (source.emissiveMap) {
+            target.emissiveMap = source.emissiveMap;
+        }
+        // Normal map (Lambert materials support normal mapping)
+        if (source.normalMap) {
+            target.normalMap = source.normalMap;
+            target.normalScale = source.normalScale.clone();
+        }
+        // Light map
+        if (source.lightMap) {
+            target.lightMap = source.lightMap;
+            target.lightMapIntensity = source.lightMapIntensity;
+        }
+        // AO map
+        if (source.aoMap) {
+            target.aoMap = source.aoMap;
+            target.aoMapIntensity = source.aoMapIntensity;
+        }
+        // Environment map (for reflections)
+        if (source.envMap) {
+            target.envMap = source.envMap;
+            target.reflectivity = Math.min(source.metalness + 0.1, 1.0);
+        }
+        // Alpha map
+        if (source.alphaMap) {
+            target.alphaMap = source.alphaMap;
+        }
+        // Copy UV transforms
+        this.copyUVTransforms(source, target);
+    }
+    /**
+     * Copies UV transformation properties for texture maps
+     *
+     * Transfers UV offset, repeat, rotation, and center properties from the
+     * source material's main texture map to the target material's map.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshLambertMaterial
+     * @internal
+     */
+    static copyUVTransforms(source, target) {
+        // Main texture UV transform
+        if (source.map && target.map) {
+            target.map.offset.copy(source.map.offset);
+            target.map.repeat.copy(source.map.repeat);
+            target.map.rotation = source.map.rotation;
+            target.map.center.copy(source.map.center);
+        }
+    }
+    /**
+     * Converts transparency and rendering properties
+     *
+     * Transfers transparency, opacity, alpha testing, depth testing,
+     * depth writing, and blending mode settings from source to target.
+     *
+     * @param source - The source MeshStandardMaterial
+     * @param target - The target MeshLambertMaterial
+     * @internal
+     */
+    static convertTransparencyProperties(source, target) {
+        target.transparent = source.transparent;
+        target.opacity = source.opacity;
+        target.alphaTest = source.alphaTest;
+        target.depthTest = source.depthTest;
+        target.depthWrite = source.depthWrite;
+        target.blending = source.blending;
+    }
+}
+
 /** Number of color channels in RGBA format */
 const RGBA_CHANNEL_COUNT = 4;
 /** Number of color channels in RGB format */
@@ -711,5 +1116,5 @@ class Sun extends DirectionalLight {
     }
 }
 
-export { DualFovCamera, SceneTraversal, SkinnedMeshBaker, Sun };
+export { DualFovCamera, SceneTraversal, SkinnedMeshBaker, StandardToBasicConverter, StandardToLambertConverter, Sun };
 //# sourceMappingURL=index.js.map