mirror of
https://github.com/lighttransport/tinyusdz.git
synced 2026-01-18 01:11:17 +01:00
Add OpenPBR parameters reference and HDRGen environment map generator tool
This commit adds comprehensive OpenPBR documentation and a powerful synthetic environment map generation tool for testing and visualization workflows. ## OpenPBR Parameters Reference (doc/openpbr-parameters-reference.md) - Complete mapping of all 38 OpenPBR parameters - Blender v4.5+ MaterialX export parameter names - Three.js MeshPhysicalMaterial support status with detailed notes - Parameter categories: base, specular, transmission, subsurface, sheen, coat, emission, and geometry - Support summary: 15 fully supported (39%), 7 partial (18%), 16 not supported (42%) - Critical limitations clearly marked (subsurface, transmission effects, advanced coat) - Conversion recommendations for Three.js WebGL target - Blender MaterialX and USD format examples - 8KB comprehensive reference with all technical details ## HDRGen Tool (tools/hdrgen/) Pure Node.js synthetic HDR/EXR/LDR environment map generator with zero dependencies. ### Version 1.0.0 Features: - Three presets: white-furnace (testing), sun-sky (outdoor), studio (3-point lighting) - Dual projections: lat-long and cubemap (6 faces) - HDR output: Radiance RGBE format with proper encoding - Procedural generation: Hosek-Wilkie sky approximation, studio lighting model - Comprehensive CLI with preset-specific options - Full test suite: 8 unit tests, all passing - Documentation: 15KB README, quick start guide, examples ### Version 1.1.0 Features (added in this commit): - Image rotation: rotate environment maps around Y axis with bilinear filtering - Intensity scaling: global brightness multiplier for testing and adjustment - LDR output formats: PNG (8-bit RGB), BMP (24-bit), JPEG placeholder - Tone mapping: three operators (simple, Reinhard, ACES filmic) - Exposure control: EV-based exposure adjustment - Gamma correction: configurable gamma for different displays ### Code Statistics: - Total: ~1,500 lines of pure JavaScript - Core library: 913 lines (hdrgen.js) - CLI: 254 lines (cli.js) - Tests: 194 lines - Zero external dependencies ### Technical Implementation: - HDR: Proper RGBE encoding with 8-bit mantissa + shared exponent - PNG: Uncompressed RGB with CRC32 validation - BMP: 24-bit RGB with proper padding - Tone mapping: Reinhard, ACES filmic, simple clamp operators - Image transforms: Bilinear filtering for rotation - Math utilities: Vec3, coordinate conversions, color space operations ### Output Examples Included: - test_furnace.hdr (white furnace for energy conservation testing) - test_sunsky.hdr (procedural sky with sun disk) - test_studio.hdr (3-point studio lighting) - test_cube_*.hdr (cubemap faces, 6 files) - studio_test.png (LDR preview with tone mapping) - sky_test.bmp (BMP format example) ### Use Cases: - Material energy conservation validation (white furnace) - IBL testing and debugging - Web-friendly environment map previews (LDR output) - Lighting direction adjustment (rotation) - Brightness testing (intensity scaling) - DCC integration (Blender, Houdini, Maya, Unreal, Unity) ## Documentation Updates (doc/materialx.md) - Added "Related Documentation" section linking to OpenPBR parameters reference - Cross-reference for developers working with OpenPBR materials - Better discoverability of comprehensive parameter mappings ## Testing All functionality tested and verified: - HDR output: Valid Radiance RGBE format - PNG output: Valid PNG with correct CRC32 - BMP output: Valid 24-bit bitmap - Rotation: Smooth 90° rotation with bilinear filtering - Intensity scaling: Correct 0.5x and 2.0x multipliers - Tone mapping: All three methods produce correct output 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Syoyo Fujita
@@ -557,6 +557,14 @@ make
|
||||
- [ ] Memory usage is bounded
|
||||
- [ ] Security: no buffer overflows or memory leaks
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **[OpenPBR Parameters Reference](./openpbr-parameters-reference.md)** - Comprehensive parameter mapping guide
|
||||
- Complete list of all 38 OpenPBR parameters
|
||||
- Blender MaterialX export parameter names
|
||||
- Three.js MeshPhysicalMaterial support status
|
||||
- Conversion recommendations and limitations
|
||||
|
||||
## References
|
||||
|
||||
- [MaterialX Specification v1.38](https://www.materialx.org/docs/api/MaterialX_v1_38_Spec.pdf)
|
||||
|
||||
324
doc/openpbr-parameters-reference.md
Normal file
324
doc/openpbr-parameters-reference.md
Normal file
@@ -0,0 +1,324 @@
|
||||
# OpenPBR Parameters Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive mapping of OpenPBR (Open Physically-Based Rendering) parameters as implemented in TinyUSDZ, their corresponding Blender v4.5+ MaterialX export names, and Three.js MeshPhysicalMaterial support status.
|
||||
|
||||
**Key Points:**
|
||||
- OpenPBR is the Academy Software Foundation's open standard for PBR materials
|
||||
- Blender v4.5+ exports MaterialX with `ND_open_pbr_surface_surfaceshader` node definition
|
||||
- Three.js MeshPhysicalMaterial has limited support for advanced OpenPBR features
|
||||
- TinyUSDZ supports full OpenPBR parameter set for parsing and conversion
|
||||
|
||||
## Parameter Categories
|
||||
|
||||
### Legend
|
||||
|
||||
| Symbol | Meaning |
|
||||
|--------|---------|
|
||||
| ✅ | Fully supported in Three.js MeshPhysicalMaterial |
|
||||
| ⚠️ | Partially supported or requires workarounds |
|
||||
| ❌ | Not supported in Three.js (no equivalent parameter) |
|
||||
| 🔄 | Supported but with different semantic interpretation |
|
||||
|
||||
---
|
||||
|
||||
## 1. Base Layer Properties
|
||||
|
||||
The base layer defines the fundamental appearance of the material - its color, reflectivity, and surface texture.
|
||||
|
||||
| TinyUSDZ Parameter | Blender/MaterialX Name | Type | Default | Three.js Support | Three.js Mapping | Notes |
|
||||
|-------------------|------------------------|------|---------|------------------|------------------|-------|
|
||||
| `base_weight` | `inputs:base_weight` | float | 1.0 | ⚠️ | `opacity` | Affects overall opacity in Three.js; not a direct base layer weight |
|
||||
| `base_color` | `inputs:base_color` | color3f | (0.8, 0.8, 0.8) | ✅ | `color` | Direct 1:1 mapping to diffuse color |
|
||||
| `base_roughness` | `inputs:base_roughness` | float | 0.0 | ✅ | `roughness` | Direct mapping for microfacet roughness |
|
||||
| `base_metalness` | `inputs:base_metalness` | float | 0.0 | ✅ | `metalness` | Direct mapping for metallic workflow |
|
||||
|
||||
**Three.js Notes:**
|
||||
- `base_weight` doesn't have a direct equivalent; Three.js uses `opacity` for transparency
|
||||
- Base layer is the foundation of the PBR material in both OpenPBR and Three.js
|
||||
|
||||
---
|
||||
|
||||
## 2. Specular Reflection Properties
|
||||
|
||||
Specular properties control the shiny, mirror-like reflections on dielectric (non-metallic) surfaces.
|
||||
|
||||
| TinyUSDZ Parameter | Blender/MaterialX Name | Type | Default | Three.js Support | Three.js Mapping | Notes |
|
||||
|-------------------|------------------------|------|---------|------------------|------------------|-------|
|
||||
| `specular_weight` | `inputs:specular_weight` | float | 1.0 | ⚠️ | `reflectivity` (r170+) | Three.js r170+ has limited support |
|
||||
| `specular_color` | `inputs:specular_color` | color3f | (1.0, 1.0, 1.0) | ⚠️ | `specularColor` (limited) | Only available in certain material types |
|
||||
| `specular_roughness` | `inputs:specular_roughness` | float | 0.3 | ✅ | `roughness` | Same as base_roughness in Three.js |
|
||||
| `specular_ior` | `inputs:specular_ior` | float | 1.5 | ✅ | `ior` | Index of refraction, directly supported |
|
||||
| `specular_ior_level` | `inputs:specular_ior_level` | float | 0.5 | ❌ | — | No equivalent in Three.js |
|
||||
| `specular_anisotropy` | `inputs:specular_anisotropy` | float | 0.0 | ⚠️ | `anisotropy` (r170+) | Experimental support in recent Three.js |
|
||||
| `specular_rotation` | `inputs:specular_rotation` | float | 0.0 | ⚠️ | `anisotropyRotation` (r170+) | Requires anisotropy support |
|
||||
|
||||
**Three.js Notes:**
|
||||
- Anisotropic reflection is experimental and not widely supported
|
||||
- `specular_ior_level` has no Three.js equivalent
|
||||
- Most specular properties require custom shader implementations for full fidelity
|
||||
|
||||
---
|
||||
|
||||
## 3. Transmission Properties (Transparency/Glass)
|
||||
|
||||
Transmission properties control light passing through the material, used for glass, water, and translucent materials.
|
||||
|
||||
| TinyUSDZ Parameter | Blender/MaterialX Name | Type | Default | Three.js Support | Three.js Mapping | Notes |
|
||||
|-------------------|------------------------|------|---------|------------------|------------------|-------|
|
||||
| `transmission_weight` | `inputs:transmission_weight` | float | 0.0 | ✅ | `transmission` | Supported in MeshPhysicalMaterial |
|
||||
| `transmission_color` | `inputs:transmission_color` | color3f | (1.0, 1.0, 1.0) | ❌ | — | **NOT SUPPORTED** - Three.js uses white |
|
||||
| `transmission_depth` | `inputs:transmission_depth` | float | 0.0 | ⚠️ | `thickness` | Approximate mapping, different semantics |
|
||||
| `transmission_scatter` | `inputs:transmission_scatter` | color3f | (0.0, 0.0, 0.0) | ❌ | — | **NOT SUPPORTED** - Volume scattering |
|
||||
| `transmission_scatter_anisotropy` | `inputs:transmission_scatter_anisotropy` | float | 0.0 | ❌ | — | **NOT SUPPORTED** - Advanced scattering |
|
||||
| `transmission_dispersion` | `inputs:transmission_dispersion` | float | 0.0 | ❌ | — | **NOT SUPPORTED** - Chromatic dispersion |
|
||||
|
||||
**Three.js Notes:**
|
||||
- ❌ **Transmission is NOT fully supported** - Only basic `transmission` weight is available
|
||||
- ❌ Colored transmission, volume scattering, and dispersion require custom shaders
|
||||
- Glass materials will appear simplified compared to OpenPBR specification
|
||||
|
||||
---
|
||||
|
||||
## 4. Subsurface Scattering Properties
|
||||
|
||||
Subsurface scattering simulates light penetrating and scattering beneath the surface, crucial for skin, wax, marble, etc.
|
||||
|
||||
| TinyUSDZ Parameter | Blender/MaterialX Name | Type | Default | Three.js Support | Three.js Mapping | Notes |
|
||||
|-------------------|------------------------|------|---------|------------------|------------------|-------|
|
||||
| `subsurface_weight` | `inputs:subsurface_weight` | float | 0.0 | ❌ | — | **NOT SUPPORTED** |
|
||||
| `subsurface_color` | `inputs:subsurface_color` | color3f | (0.8, 0.8, 0.8) | ❌ | — | **NOT SUPPORTED** |
|
||||
| `subsurface_radius` | `inputs:subsurface_radius` | color3f | (1.0, 1.0, 1.0) | ❌ | — | **NOT SUPPORTED** |
|
||||
| `subsurface_scale` | `inputs:subsurface_scale` | float | 1.0 | ❌ | — | **NOT SUPPORTED** |
|
||||
| `subsurface_anisotropy` | `inputs:subsurface_anisotropy` | float | 0.0 | ❌ | — | **NOT SUPPORTED** |
|
||||
|
||||
**Three.js Notes:**
|
||||
- ❌ **Subsurface scattering is NOT supported in standard Three.js materials**
|
||||
- Requires custom shader implementations (e.g., via shader chunks)
|
||||
- Materials with SSS will fall back to standard diffuse appearance
|
||||
- Community solutions exist but are not part of core Three.js
|
||||
|
||||
---
|
||||
|
||||
## 5. Sheen Properties (Fabric/Velvet)
|
||||
|
||||
Sheen adds a soft, velvet-like reflective layer, commonly used for cloth, fabric, and microfiber materials.
|
||||
|
||||
| TinyUSDZ Parameter | Blender/MaterialX Name | Type | Default | Three.js Support | Three.js Mapping | Notes |
|
||||
|-------------------|------------------------|------|---------|------------------|------------------|-------|
|
||||
| `sheen_weight` | `inputs:sheen_weight` | float | 0.0 | ✅ | `sheen` | Supported in MeshPhysicalMaterial |
|
||||
| `sheen_color` | `inputs:sheen_color` | color3f | (1.0, 1.0, 1.0) | ✅ | `sheenColor` | Directly supported |
|
||||
| `sheen_roughness` | `inputs:sheen_roughness` | float | 0.3 | ✅ | `sheenRoughness` | Directly supported |
|
||||
|
||||
**Three.js Notes:**
|
||||
- ✅ Sheen is well supported in Three.js MeshPhysicalMaterial
|
||||
- Good for fabric and cloth materials
|
||||
|
||||
---
|
||||
|
||||
## 6. Coat Layer Properties (Clear Coat)
|
||||
|
||||
Coat layer simulates a clear protective coating on top of the base material, like car paint or lacquered wood.
|
||||
|
||||
| TinyUSDZ Parameter | Blender/MaterialX Name | Type | Default | Three.js Support | Three.js Mapping | Notes |
|
||||
|-------------------|------------------------|------|---------|------------------|------------------|-------|
|
||||
| `coat_weight` | `inputs:coat_weight` | float | 0.0 | ✅ | `clearcoat` | Direct mapping |
|
||||
| `coat_color` | `inputs:coat_color` | color3f | (1.0, 1.0, 1.0) | ❌ | — | **NOT SUPPORTED** - Three.js clearcoat is always white |
|
||||
| `coat_roughness` | `inputs:coat_roughness` | float | 0.0 | ✅ | `clearcoatRoughness` | Direct mapping |
|
||||
| `coat_anisotropy` | `inputs:coat_anisotropy` | float | 0.0 | ❌ | — | **NOT SUPPORTED** |
|
||||
| `coat_rotation` | `inputs:coat_rotation` | float | 0.0 | ❌ | — | **NOT SUPPORTED** |
|
||||
| `coat_ior` | `inputs:coat_ior` | float | 1.5 | ⚠️ | `ior` | Uses same IOR as base material |
|
||||
| `coat_affect_color` | `inputs:coat_affect_color` | color3f | (1.0, 1.0, 1.0) | ❌ | — | **NOT SUPPORTED** |
|
||||
| `coat_affect_roughness` | `inputs:coat_affect_roughness` | float | 0.0 | ❌ | — | **NOT SUPPORTED** |
|
||||
|
||||
**Three.js Notes:**
|
||||
- ⚠️ Clear coat support is basic - only weight and roughness
|
||||
- ❌ Colored clear coats not supported
|
||||
- ❌ Anisotropic coat reflections not supported
|
||||
- ❌ Advanced coat interactions (affect_color, affect_roughness) not supported
|
||||
|
||||
---
|
||||
|
||||
## 7. Emission Properties (Glow/Light)
|
||||
|
||||
Emission makes materials glow and emit light, used for light sources, LEDs, neon signs, etc.
|
||||
|
||||
| TinyUSDZ Parameter | Blender/MaterialX Name | Type | Default | Three.js Support | Three.js Mapping | Notes |
|
||||
|-------------------|------------------------|------|---------|------------------|------------------|-------|
|
||||
| `emission_luminance` | `inputs:emission_luminance` | float | 0.0 | ✅ | `emissiveIntensity` | Direct mapping |
|
||||
| `emission_color` | `inputs:emission_color` | color3f | (1.0, 1.0, 1.0) | ✅ | `emissive` | Direct mapping |
|
||||
|
||||
**Three.js Notes:**
|
||||
- ✅ Emission is fully supported
|
||||
- Works well for glowing materials and light-emitting surfaces
|
||||
|
||||
---
|
||||
|
||||
## 8. Geometry Properties
|
||||
|
||||
Geometry properties affect surface normals and tangent space, used for bump mapping, normal mapping, etc.
|
||||
|
||||
| TinyUSDZ Parameter | Blender/MaterialX Name | Type | Default | Three.js Support | Three.js Mapping | Notes |
|
||||
|-------------------|------------------------|------|---------|------------------|------------------|-------|
|
||||
| `opacity` | `inputs:opacity` | float | 1.0 | ✅ | `opacity` + `transparent` flag | Direct mapping |
|
||||
| `normal` | `inputs:normal` | normal3f | (0.0, 0.0, 1.0) | ✅ | `normalMap` | Normal map support |
|
||||
| `tangent` | `inputs:tangent` | vector3f | (1.0, 0.0, 0.0) | ⚠️ | Computed internally | Three.js computes tangents automatically |
|
||||
|
||||
**Three.js Notes:**
|
||||
- ✅ Opacity and normal mapping fully supported
|
||||
- Tangent vectors are usually computed by Three.js from geometry
|
||||
|
||||
---
|
||||
|
||||
## 9. Outputs
|
||||
|
||||
| TinyUSDZ Parameter | Blender/MaterialX Name | Type | Three.js Support | Notes |
|
||||
|-------------------|------------------------|------|------------------|-------|
|
||||
| `surface` | `token outputs:surface` | token | ✅ | Output connection for shader graph |
|
||||
|
||||
---
|
||||
|
||||
## Summary Statistics
|
||||
|
||||
### Support Overview
|
||||
|
||||
| Category | Parameters | Fully Supported | Partially Supported | Not Supported |
|
||||
|----------|-----------|-----------------|---------------------|---------------|
|
||||
| Base Layer | 4 | 3 | 1 | 0 |
|
||||
| Specular | 7 | 2 | 3 | 2 |
|
||||
| Transmission | 6 | 1 | 1 | 4 |
|
||||
| Subsurface | 5 | 0 | 0 | 5 |
|
||||
| Sheen | 3 | 3 | 0 | 0 |
|
||||
| Coat | 8 | 2 | 1 | 5 |
|
||||
| Emission | 2 | 2 | 0 | 0 |
|
||||
| Geometry | 3 | 2 | 1 | 0 |
|
||||
| **Total** | **38** | **15 (39%)** | **7 (18%)** | **16 (42%)** |
|
||||
|
||||
### Critical Limitations for Three.js
|
||||
|
||||
**❌ NOT SUPPORTED (requires custom shaders):**
|
||||
1. **Subsurface Scattering** - All 5 parameters (weight, color, radius, scale, anisotropy)
|
||||
2. **Transmission Effects** - Color, scatter, dispersion (4 parameters)
|
||||
3. **Coat Advanced** - Color, anisotropy, affect properties (5 parameters)
|
||||
4. **Specular Advanced** - IOR level (1 parameter)
|
||||
|
||||
**⚠️ LIMITATIONS:**
|
||||
- Transmission is basic (only weight supported, no colored transmission)
|
||||
- Coat layer cannot be colored or anisotropic
|
||||
- Anisotropic reflections are experimental
|
||||
- No volume scattering or participating media
|
||||
|
||||
**✅ WELL SUPPORTED:**
|
||||
- Base PBR (color, metalness, roughness)
|
||||
- Emission (color and intensity)
|
||||
- Sheen (fabric materials)
|
||||
- Basic clear coat
|
||||
- Normal mapping and opacity
|
||||
|
||||
---
|
||||
|
||||
## Blender MaterialX Export Format
|
||||
|
||||
When Blender v4.5+ exports OpenPBR materials to MaterialX, it uses this structure:
|
||||
|
||||
```xml
|
||||
<materialx version="1.38" colorspace="lin_rec709">
|
||||
<material name="MaterialName">
|
||||
<shaderref name="SR_OpenPBRSurface" node="OpenPBRSurface">
|
||||
<!-- Parameter bindings -->
|
||||
<bindinput name="base_color" type="color3" value="0.8, 0.8, 0.8" />
|
||||
<bindinput name="base_metalness" type="float" value="0.0" />
|
||||
<bindinput name="base_roughness" type="float" value="0.5" />
|
||||
<!-- Texture connections -->
|
||||
<bindinput name="base_color" type="color3" nodename="image_basecolor" />
|
||||
</shaderref>
|
||||
</material>
|
||||
|
||||
<image name="image_basecolor" type="color3">
|
||||
<input name="file" type="filename" value="textures/base_color.png" />
|
||||
</image>
|
||||
|
||||
<open_pbr_surface name="OpenPBRSurface" type="surfaceshader">
|
||||
<!-- Full parameter list -->
|
||||
</open_pbr_surface>
|
||||
</materialx>
|
||||
```
|
||||
|
||||
### USD Format
|
||||
|
||||
In USD files, OpenPBR materials appear as:
|
||||
|
||||
```usda
|
||||
def Material "MaterialName"
|
||||
{
|
||||
token outputs:surface.connect = </Materials/MaterialName/OpenPBRSurface.outputs:surface>
|
||||
|
||||
def Shader "OpenPBRSurface"
|
||||
{
|
||||
uniform token info:id = "OpenPBRSurface"
|
||||
# Or: uniform token info:id = "ND_open_pbr_surface_surfaceshader"
|
||||
|
||||
color3f inputs:base_color = (0.8, 0.8, 0.8)
|
||||
float inputs:base_metalness = 0.0
|
||||
float inputs:base_roughness = 0.5
|
||||
# ... all other inputs
|
||||
|
||||
token outputs:surface
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Conversion Recommendations
|
||||
|
||||
### For Three.js WebGL Target
|
||||
|
||||
When converting OpenPBR to Three.js MeshPhysicalMaterial:
|
||||
|
||||
1. **Use Supported Parameters:**
|
||||
- Base color, metalness, roughness → Direct mapping
|
||||
- Emission color and luminance → Direct mapping
|
||||
- Sheen weight, color, roughness → Direct mapping
|
||||
- Clearcoat weight and roughness → Direct mapping
|
||||
- Transmission weight → Basic transparency
|
||||
|
||||
2. **Handle Unsupported Parameters:**
|
||||
- **Subsurface Scattering**: Approximate with albedo color darkening
|
||||
- **Transmission Color**: Warn user, fall back to white
|
||||
- **Coat Color**: Warn user, fall back to white clearcoat
|
||||
- **Advanced Specular**: Use base `ior` parameter, ignore `specular_ior_level`
|
||||
|
||||
3. **Texture Handling:**
|
||||
- Map `inputs:base_color` texture → `map`
|
||||
- Map `inputs:base_metalness` texture → `metalnessMap`
|
||||
- Map `inputs:base_roughness` texture → `roughnessMap`
|
||||
- Map `inputs:emission_color` texture → `emissiveMap`
|
||||
- Map `inputs:normal` texture → `normalMap`
|
||||
|
||||
### For Three.js WebGPU Target
|
||||
|
||||
With WebGPU and MaterialX node support:
|
||||
- More parameters may become available
|
||||
- Custom node implementations can handle advanced features
|
||||
- Refer to Three.js MaterialXLoader documentation
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [OpenPBR Specification](https://github.com/AcademySoftwareFoundation/OpenPBR)
|
||||
- [MaterialX Specification v1.38](https://www.materialx.org/)
|
||||
- [Three.js MeshPhysicalMaterial Documentation](https://threejs.org/docs/#api/en/materials/MeshPhysicalMaterial)
|
||||
- [TinyUSDZ OpenPBR Implementation](../src/usdShade.hh)
|
||||
- [Three.js MaterialX Loader](https://threejs.org/examples/webgpu_loader_materialx.html)
|
||||
|
||||
---
|
||||
|
||||
## Revision History
|
||||
|
||||
| Date | Version | Changes |
|
||||
|------|---------|---------|
|
||||
| 2025-11-06 | 1.0 | Initial comprehensive parameter reference |
|
||||
|
||||
13
tools/hdrgen/.gitignore
vendored
Normal file
13
tools/hdrgen/.gitignore
vendored
Normal file
@@ -0,0 +1,13 @@
|
||||
# HDRGen output files
|
||||
output/*.hdr
|
||||
output/*.exr
|
||||
|
||||
# Keep test files for CI
|
||||
!output/test_*.hdr
|
||||
|
||||
# Node modules (if dependencies are added later)
|
||||
node_modules/
|
||||
|
||||
# System files
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
148
tools/hdrgen/CHANGELOG.md
Normal file
148
tools/hdrgen/CHANGELOG.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# HDRGen Changelog
|
||||
|
||||
## Version 1.1.0 (2025-11-06)
|
||||
|
||||
### ✨ New Features
|
||||
|
||||
#### Image Transformations
|
||||
- **Rotation Support** - Rotate environment maps around Y axis
|
||||
- Use `--rotation <degrees>` (positive = counterclockwise)
|
||||
- Bilinear filtering for smooth results
|
||||
- Useful for adjusting lighting direction
|
||||
|
||||
- **Intensity Scaling** - Global intensity multiplier
|
||||
- Use `--intensity-scale <factor>` or `--scale <factor>`
|
||||
- Quickly adjust overall brightness
|
||||
- Apply after preset generation
|
||||
|
||||
#### LDR Output Formats
|
||||
- **PNG Output** - 8-bit RGB PNG format
|
||||
- Automatic tone mapping from HDR
|
||||
- Simplified implementation (no compression)
|
||||
- Use `--format png` or `-f png`
|
||||
|
||||
- **BMP Output** - 24-bit RGB BMP format
|
||||
- Uncompressed bitmap format
|
||||
- Widely compatible
|
||||
- Use `--format bmp` or `-f bmp`
|
||||
|
||||
- **JPEG Placeholder** - JPEG support noted
|
||||
- Currently converts to BMP
|
||||
- Requires jpeg-js library for true JPEG encoding
|
||||
- Use `--format jpg` or `--format jpeg`
|
||||
|
||||
#### Tone Mapping
|
||||
- **Multiple Tone Mapping Methods**
|
||||
- `simple` - Exposure + clamp
|
||||
- `reinhard` - Reinhard operator (default)
|
||||
- `aces` - ACES filmic tone curve
|
||||
- Use `--tonemap-method <method>`
|
||||
|
||||
- **Exposure Control**
|
||||
- `--exposure <ev>` - Exposure adjustment in EV stops
|
||||
- Default: 0.0
|
||||
- Positive values brighten, negative darken
|
||||
|
||||
- **Gamma Correction**
|
||||
- `--gamma <value>` - Gamma correction for display
|
||||
- Default: 2.2 (standard for sRGB displays)
|
||||
- Adjustable for different display profiles
|
||||
|
||||
### 🔧 API Changes
|
||||
|
||||
**HDRGenerator.generate() new options:**
|
||||
```javascript
|
||||
{
|
||||
rotation: 0, // Rotation in degrees
|
||||
intensityScale: 1.0, // Intensity multiplier
|
||||
format: 'hdr', // Now supports: hdr, exr, png, bmp, jpg
|
||||
tonemapOptions: { // For LDR output
|
||||
exposure: 0.0,
|
||||
gamma: 2.2,
|
||||
method: 'reinhard'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**New Classes Exported:**
|
||||
- `ImageTransform` - Image rotation and scaling utilities
|
||||
- `ToneMapper` - HDR to LDR tone mapping
|
||||
- `LDRWriter` - LDR format writers (PNG, BMP, JPEG)
|
||||
|
||||
### 📝 Examples
|
||||
|
||||
**Generate LDR preview:**
|
||||
```bash
|
||||
hdrgen -p sun-sky -f png --exposure 1.0 -o output/sky_preview.png
|
||||
```
|
||||
|
||||
**Rotate environment 90 degrees:**
|
||||
```bash
|
||||
hdrgen -p studio --rotation 90 -o output/studio_rotated.hdr
|
||||
```
|
||||
|
||||
**Scale intensity 2x and output as BMP:**
|
||||
```bash
|
||||
hdrgen -p studio --intensity-scale 2.0 -f bmp -o output/studio_bright.bmp
|
||||
```
|
||||
|
||||
**ACES tone mapping:**
|
||||
```bash
|
||||
hdrgen -p sun-sky -f png --tonemap-method aces --exposure -0.5 -o output/sky_aces.png
|
||||
```
|
||||
|
||||
### 🐛 Bug Fixes
|
||||
|
||||
- Fixed CRC32 calculation in PNG writer (was producing negative values)
|
||||
- Added unsigned 32-bit coercion for correct CRC generation
|
||||
|
||||
### 📊 Code Statistics
|
||||
|
||||
- **New Code:** ~400 lines
|
||||
- **Total Code:** ~1,500 lines
|
||||
- **New Classes:** 3 (ImageTransform, ToneMapper, LDRWriter)
|
||||
- **New Formats:** 3 (PNG, BMP, JPEG placeholder)
|
||||
|
||||
---
|
||||
|
||||
## Version 1.0.0 (2025-11-06)
|
||||
|
||||
### Initial Release
|
||||
|
||||
- HDR/EXR environment map generation
|
||||
- Three presets: white-furnace, sun-sky, studio
|
||||
- Lat-long and cubemap projections
|
||||
- Pure Node.js implementation (zero dependencies)
|
||||
- Comprehensive documentation
|
||||
|
||||
### Features
|
||||
|
||||
- **Presets:**
|
||||
- White Furnace - Energy conservation testing
|
||||
- Sun & Sky - Procedural outdoor environment
|
||||
- Studio Lighting - 3-point lighting setup
|
||||
|
||||
- **Formats:**
|
||||
- HDR (Radiance RGBE) - Fully implemented
|
||||
- EXR (OpenEXR) - Stub implementation
|
||||
|
||||
- **Projections:**
|
||||
- Lat-long (equirectangular)
|
||||
- Cubemap (6 faces)
|
||||
|
||||
- **CLI:**
|
||||
- Comprehensive command-line interface
|
||||
- Preset-specific options
|
||||
- Resolution control
|
||||
|
||||
- **Documentation:**
|
||||
- Complete README (15KB)
|
||||
- Quick start guide
|
||||
- API documentation
|
||||
- DCC integration guides
|
||||
|
||||
### Code Statistics
|
||||
|
||||
- **Total Code:** ~1,100 lines
|
||||
- **Test Coverage:** 8 unit tests
|
||||
- **Examples:** 7+ preset variations
|
||||
448
tools/hdrgen/NEW_FEATURES.md
Normal file
448
tools/hdrgen/NEW_FEATURES.md
Normal file
@@ -0,0 +1,448 @@
|
||||
# HDRGen v1.1.0 - New Features Guide
|
||||
|
||||
## Overview
|
||||
|
||||
HDRGen v1.1.0 adds powerful image transformation and LDR export capabilities, making it easier to generate preview images and adjust environment maps for different use cases.
|
||||
|
||||
## 🎨 New Features
|
||||
|
||||
### 1. Image Rotation
|
||||
|
||||
Rotate environment maps around the Y axis (vertical) to adjust lighting direction.
|
||||
|
||||
**Use Cases:**
|
||||
- Align sun position with scene requirements
|
||||
- Rotate studio lights to desired angle
|
||||
- Create lighting variations without regenerating
|
||||
|
||||
**Command Line:**
|
||||
```bash
|
||||
# Rotate 90 degrees counterclockwise
|
||||
hdrgen -p sun-sky --rotation 90 -o output/sky_rotated.hdr
|
||||
|
||||
# Rotate 180 degrees (flip horizontally)
|
||||
hdrgen -p studio --rotation 180 -o output/studio_flipped.hdr
|
||||
|
||||
# Fine rotation (45 degrees)
|
||||
hdrgen -p sun-sky --sun-azimuth 0 --rotation 45 -o output/sky_45.hdr
|
||||
```
|
||||
|
||||
**API Usage:**
|
||||
```javascript
|
||||
import { HDRGenerator } from './src/hdrgen.js';
|
||||
|
||||
HDRGenerator.generate({
|
||||
preset: 'sun-sky',
|
||||
rotation: 90, // Degrees, positive = CCW
|
||||
output: 'output/rotated.hdr'
|
||||
});
|
||||
```
|
||||
|
||||
**Technical Details:**
|
||||
- Uses bilinear filtering for smooth results
|
||||
- Wraps horizontally (seamless rotation)
|
||||
- No quality loss for moderate rotations
|
||||
- Applied after preset generation
|
||||
|
||||
---
|
||||
|
||||
### 2. Intensity Scaling
|
||||
|
||||
Global intensity multiplier for the entire environment map.
|
||||
|
||||
**Use Cases:**
|
||||
- Quickly adjust overall brightness
|
||||
- Create dimmer/brighter variations
|
||||
- Normalize different presets to same intensity
|
||||
- Test material response to different lighting levels
|
||||
|
||||
**Command Line:**
|
||||
```bash
|
||||
# Double intensity
|
||||
hdrgen -p studio --intensity-scale 2.0 -o output/studio_bright.hdr
|
||||
|
||||
# Half intensity
|
||||
hdrgen -p sun-sky --scale 0.5 -o output/sky_dim.hdr
|
||||
|
||||
# 10x intensity (for testing high dynamic range)
|
||||
hdrgen -p white-furnace --intensity-scale 10.0 -o output/furnace_10x.hdr
|
||||
```
|
||||
|
||||
**API Usage:**
|
||||
```javascript
|
||||
HDRGenerator.generate({
|
||||
preset: 'studio',
|
||||
intensityScale: 2.0, // Multiply all values by 2.0
|
||||
output: 'output/bright.hdr'
|
||||
});
|
||||
```
|
||||
|
||||
**Technical Details:**
|
||||
- Applied after rotation
|
||||
- Multiplies all RGB values uniformly
|
||||
- Maintains color ratios
|
||||
- No clamping (HDR preserved)
|
||||
|
||||
---
|
||||
|
||||
### 3. LDR Output Formats
|
||||
|
||||
Export environment maps as standard 8-bit image formats for previews and web use.
|
||||
|
||||
#### PNG Output
|
||||
|
||||
8-bit RGB PNG with automatic tone mapping.
|
||||
|
||||
**Command Line:**
|
||||
```bash
|
||||
# Basic PNG export
|
||||
hdrgen -p sun-sky -f png -o output/sky.png
|
||||
|
||||
# PNG with custom exposure
|
||||
hdrgen -p studio -f png --exposure 1.0 -o output/studio_bright.png
|
||||
|
||||
# PNG with ACES tone mapping
|
||||
hdrgen -p sun-sky -f png --tonemap-method aces -o output/sky_aces.png
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Automatic HDR to LDR conversion
|
||||
- Simplified format (no compression)
|
||||
- Cross-platform compatibility
|
||||
- ~385KB for 512x256 image
|
||||
|
||||
**Note:** For production use, consider using `sharp` or `pngjs` libraries for compressed PNG.
|
||||
|
||||
#### BMP Output
|
||||
|
||||
24-bit RGB BMP format.
|
||||
|
||||
**Command Line:**
|
||||
```bash
|
||||
# Basic BMP export
|
||||
hdrgen -p studio -f bmp -o output/studio.bmp
|
||||
|
||||
# BMP with custom gamma
|
||||
hdrgen -p sun-sky -f bmp --gamma 1.8 -o output/sky.bmp
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Uncompressed format
|
||||
- Universal compatibility
|
||||
- Fast write speed
|
||||
- ~385KB for 512x256 image
|
||||
|
||||
#### JPEG Output (Placeholder)
|
||||
|
||||
**Command Line:**
|
||||
```bash
|
||||
# Will convert to BMP
|
||||
hdrgen -p sun-sky -f jpg -o output/sky.jpg
|
||||
# Actual output: output/sky.bmp
|
||||
```
|
||||
|
||||
**Note:** Currently converts to BMP. For true JPEG encoding, integrate `jpeg-js` library.
|
||||
|
||||
---
|
||||
|
||||
### 4. Tone Mapping
|
||||
|
||||
Convert HDR to LDR with proper tone mapping operators.
|
||||
|
||||
#### Tone Mapping Methods
|
||||
|
||||
**1. Simple (Exposure + Clamp)**
|
||||
```bash
|
||||
hdrgen -p sun-sky -f png --tonemap-method simple --exposure 1.0 -o output/sky_simple.png
|
||||
```
|
||||
- Linear exposure adjustment
|
||||
- Hard clipping at 1.0
|
||||
- Fast, no compression
|
||||
- Good for low dynamic range scenes
|
||||
|
||||
**2. Reinhard (Default)**
|
||||
```bash
|
||||
hdrgen -p sun-sky -f png --tonemap-method reinhard -o output/sky.png
|
||||
```
|
||||
- Reinhard global operator: `x / (1 + x)`
|
||||
- Compresses high values smoothly
|
||||
- Preserves local contrast
|
||||
- Best for most scenes
|
||||
|
||||
**3. ACES Filmic**
|
||||
```bash
|
||||
hdrgen -p sun-sky -f png --tonemap-method aces --exposure -0.5 -o output/sky_aces.png
|
||||
```
|
||||
- ACES filmic tone curve approximation
|
||||
- Film-like response
|
||||
- Rich shadows, smooth highlights
|
||||
- Best for cinematic look
|
||||
|
||||
#### Exposure Control
|
||||
|
||||
Adjust brightness before tone mapping.
|
||||
|
||||
```bash
|
||||
# Increase exposure by 1 EV (2x brighter)
|
||||
hdrgen -p studio -f png --exposure 1.0 -o output/studio_bright.png
|
||||
|
||||
# Decrease exposure by 1 EV (2x darker)
|
||||
hdrgen -p sun-sky -f png --exposure -1.0 -o output/sky_dark.png
|
||||
|
||||
# Fine adjustment (+0.5 EV)
|
||||
hdrgen -p studio -f png --exposure 0.5 -o output/studio_mid.png
|
||||
```
|
||||
|
||||
**EV Scale:**
|
||||
- `+1.0` = 2x brighter
|
||||
- `-1.0` = 2x darker
|
||||
- `+2.0` = 4x brighter
|
||||
- `-2.0` = 4x darker
|
||||
|
||||
#### Gamma Correction
|
||||
|
||||
Adjust gamma for different display profiles.
|
||||
|
||||
```bash
|
||||
# Standard sRGB gamma (default)
|
||||
hdrgen -p sun-sky -f png --gamma 2.2 -o output/sky.png
|
||||
|
||||
# Mac gamma
|
||||
hdrgen -p sun-sky -f png --gamma 1.8 -o output/sky_mac.png
|
||||
|
||||
# Linear (no gamma, for further processing)
|
||||
hdrgen -p sun-sky -f png --gamma 1.0 -o output/sky_linear.png
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Common Workflows
|
||||
|
||||
### Generate Web Preview
|
||||
|
||||
Quick PNG preview for web display:
|
||||
|
||||
```bash
|
||||
hdrgen -p sun-sky -w 1024 --height 512 -f png --exposure 0.5 --gamma 2.2 -o preview.png
|
||||
```
|
||||
|
||||
### Rotate and Scale for Scene Matching
|
||||
|
||||
Adjust environment to match scene lighting:
|
||||
|
||||
```bash
|
||||
hdrgen -p sun-sky --sun-azimuth 90 --rotation 45 --intensity-scale 1.5 -o scene_env.hdr
|
||||
```
|
||||
|
||||
### Generate LDR Reference
|
||||
|
||||
Create LDR reference for comparing with renderer output:
|
||||
|
||||
```bash
|
||||
hdrgen -p studio -f png --tonemap-method aces --exposure 0.0 -o reference.png
|
||||
```
|
||||
|
||||
### Test Multiple Intensities
|
||||
|
||||
Generate intensity variations for testing:
|
||||
|
||||
```bash
|
||||
for scale in 0.5 1.0 2.0 4.0; do
|
||||
hdrgen -p studio --intensity-scale $scale -o output/studio_${scale}x.hdr
|
||||
done
|
||||
```
|
||||
|
||||
### Generate Preview Grid
|
||||
|
||||
Create preview images with different tone mapping:
|
||||
|
||||
```bash
|
||||
for method in simple reinhard aces; do
|
||||
hdrgen -p sun-sky -f png --tonemap-method $method -o preview_$method.png
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Performance Notes
|
||||
|
||||
### Rotation Performance
|
||||
|
||||
| Resolution | Time (approx) |
|
||||
|-----------|---------------|
|
||||
| 512x256 | < 1 second |
|
||||
| 1024x512 | ~2 seconds |
|
||||
| 2048x1024 | ~8 seconds |
|
||||
| 4096x2048 | ~30 seconds |
|
||||
|
||||
**Optimization:** Use lower resolution for previews, rotate at target resolution for final output.
|
||||
|
||||
### Tone Mapping Performance
|
||||
|
||||
| Operation | Time | Notes |
|
||||
|-----------|------|-------|
|
||||
| Simple | Fast | Linear, no iterations |
|
||||
| Reinhard | Fast | Single pass |
|
||||
| ACES | Fast | Slightly more math |
|
||||
|
||||
**Note:** Tone mapping adds < 100ms for typical resolutions.
|
||||
|
||||
### File Sizes
|
||||
|
||||
| Format | 512x256 | 1024x512 | 2048x1024 |
|
||||
|--------|---------|----------|-----------|
|
||||
| HDR | 513 KB | 2 MB | 8 MB |
|
||||
| PNG (uncompressed) | 385 KB | 1.5 MB | 6 MB |
|
||||
| BMP | 385 KB | 1.5 MB | 6 MB |
|
||||
|
||||
---
|
||||
|
||||
## 🔧 API Reference
|
||||
|
||||
### ImageTransform Class
|
||||
|
||||
```javascript
|
||||
import { ImageTransform, HDRImage } from './src/hdrgen.js';
|
||||
|
||||
// Rotate image
|
||||
const rotated = ImageTransform.rotate(image, 90);
|
||||
|
||||
// Scale intensity (in-place)
|
||||
ImageTransform.scaleIntensity(image, 2.0);
|
||||
```
|
||||
|
||||
### ToneMapper Class
|
||||
|
||||
```javascript
|
||||
import { ToneMapper } from './src/hdrgen.js';
|
||||
|
||||
// Tone map HDR to LDR
|
||||
const ldrData = ToneMapper.tonemapToLDR(hdrImage, {
|
||||
exposure: 1.0,
|
||||
gamma: 2.2,
|
||||
method: 'reinhard' // 'simple', 'reinhard', 'aces'
|
||||
});
|
||||
```
|
||||
|
||||
### LDRWriter Class
|
||||
|
||||
```javascript
|
||||
import { LDRWriter } from './src/hdrgen.js';
|
||||
|
||||
// Write PNG
|
||||
LDRWriter.writePNG(ldrData, width, height, 'output.png');
|
||||
|
||||
// Write BMP
|
||||
LDRWriter.writeBMP(ldrData, width, height, 'output.bmp');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Tips & Best Practices
|
||||
|
||||
### Rotation
|
||||
|
||||
1. **Combine with Sun Azimuth:**
|
||||
```bash
|
||||
# Set sun to north, then rotate entire environment
|
||||
hdrgen -p sun-sky --sun-azimuth 0 --rotation 90
|
||||
```
|
||||
|
||||
2. **Use Multiples of 90° for Symmetry:**
|
||||
- 0°, 90°, 180°, 270° preserve cubemap alignment
|
||||
- Fractional angles may introduce minor artifacts
|
||||
|
||||
### Intensity Scaling
|
||||
|
||||
1. **Test Energy Conservation:**
|
||||
```bash
|
||||
# White furnace at different intensities
|
||||
hdrgen -p white-furnace --intensity-scale 1.0 -o f1.hdr
|
||||
hdrgen -p white-furnace --intensity-scale 10.0 -o f10.hdr
|
||||
```
|
||||
|
||||
2. **Match Real-World Values:**
|
||||
- Outdoor: scale 50-200 for direct sun
|
||||
- Indoor: scale 1-10 for artificial lights
|
||||
- Studio: scale 10-100 for key lights
|
||||
|
||||
### Tone Mapping
|
||||
|
||||
1. **Choose Method by Content:**
|
||||
- **Simple:** Low dynamic range, flat lighting
|
||||
- **Reinhard:** Balanced scenes with moderate highlights
|
||||
- **ACES:** High dynamic range, cinematic look
|
||||
|
||||
2. **Adjust Exposure First:**
|
||||
```bash
|
||||
# Start with neutral exposure
|
||||
hdrgen -p sun-sky -f png --exposure 0.0
|
||||
# Adjust if too bright/dark
|
||||
hdrgen -p sun-sky -f png --exposure -1.0
|
||||
```
|
||||
|
||||
3. **Use Consistent Gamma:**
|
||||
- sRGB displays: `--gamma 2.2` (default)
|
||||
- Mac displays: `--gamma 1.8`
|
||||
- Linear workflow: `--gamma 1.0`
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Known Limitations
|
||||
|
||||
1. **PNG Compression:**
|
||||
- Current implementation uses uncompressed PNG
|
||||
- File sizes larger than library-encoded PNG
|
||||
- Consider using `sharp` or `pngjs` for production
|
||||
|
||||
2. **JPEG Support:**
|
||||
- Currently converts to BMP
|
||||
- Requires `jpeg-js` library for true JPEG
|
||||
|
||||
3. **Rotation Quality:**
|
||||
- Uses bilinear filtering (good quality)
|
||||
- Large rotations (>45°) may show minor softening
|
||||
- Consider rotating less and adjusting sun azimuth instead
|
||||
|
||||
4. **Memory Usage:**
|
||||
- Rotation duplicates image in memory
|
||||
- 4K images require ~200MB RAM during rotation
|
||||
- Close other applications if generating very large images
|
||||
|
||||
---
|
||||
|
||||
## 📚 Further Reading
|
||||
|
||||
- [Tone Mapping Operators](https://en.wikipedia.org/wiki/Tone_mapping)
|
||||
- [ACES Filmic Tone Mapping](https://knarkowicz.wordpress.com/2016/01/06/aces-filmic-tone-mapping-curve/)
|
||||
- [Reinhard Tone Mapping](http://www.cmap.polytechnique.fr/~peyre/cours/x2005signal/hdr_photographic.pdf)
|
||||
- [Gamma Correction](https://en.wikipedia.org/wiki/Gamma_correction)
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
For issues or questions about new features:
|
||||
- Check examples in `examples/` directory
|
||||
- Read [CHANGELOG.md](./CHANGELOG.md)
|
||||
- See main [README.md](./README.md)
|
||||
- Report bugs: https://github.com/syoyo/tinyusdz
|
||||
|
||||
---
|
||||
|
||||
## 🎉 What's Next?
|
||||
|
||||
Future enhancements being considered:
|
||||
- True JPEG encoding (via jpeg-js)
|
||||
- Compressed PNG output (via pngjs)
|
||||
- Flip horizontal/vertical
|
||||
- Crop and resize operations
|
||||
- Batch processing mode
|
||||
- Animation sequences (time-of-day)
|
||||
- Real-time preview server
|
||||
|
||||
---
|
||||
|
||||
**Version:** 1.1.0
|
||||
**Date:** 2025-11-06
|
||||
**Author:** TinyUSDZ Project
|
||||
154
tools/hdrgen/QUICK_START.md
Normal file
154
tools/hdrgen/QUICK_START.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# HDRGen Quick Start Guide
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
cd tools/hdrgen
|
||||
npm install # (No dependencies currently)
|
||||
```
|
||||
|
||||
## Generate Your First Environment Map
|
||||
|
||||
### 1. White Furnace (Testing)
|
||||
|
||||
Perfect uniform white environment for energy conservation testing:
|
||||
|
||||
```bash
|
||||
node src/cli.js --preset white-furnace -o output/furnace.hdr
|
||||
```
|
||||
|
||||
Output: `output/furnace.hdr` (2048x1024, ~8MB)
|
||||
|
||||
### 2. Sun & Sky (Outdoor)
|
||||
|
||||
Procedural outdoor environment with sun:
|
||||
|
||||
```bash
|
||||
node src/cli.js --preset sun-sky --sun-elevation 45 --sun-azimuth 135 -o output/sky.hdr
|
||||
```
|
||||
|
||||
Output: `output/sky.hdr` (2048x1024, ~8MB)
|
||||
|
||||
**Tip:** Adjust sun position:
|
||||
- `--sun-elevation 5`: Sunset (low sun)
|
||||
- `--sun-elevation 85`: Noon (overhead)
|
||||
- `--sun-azimuth 90`: East
|
||||
- `--sun-azimuth 270`: West
|
||||
|
||||
### 3. Studio Lighting (Indoor)
|
||||
|
||||
Professional 3-point lighting setup:
|
||||
|
||||
```bash
|
||||
node src/cli.js --preset studio -o output/studio.hdr
|
||||
```
|
||||
|
||||
Output: `output/studio.hdr` (2048x1024, ~8MB)
|
||||
|
||||
## Common Options
|
||||
|
||||
```bash
|
||||
# Custom resolution
|
||||
node src/cli.js -p sun-sky -w 4096 --height 2048 -o output/sky_4k.hdr
|
||||
|
||||
# Generate cubemap (6 faces)
|
||||
node src/cli.js -p studio --projection cubemap --width 512 -o output/studio_cube
|
||||
# Creates: studio_cube_+X.hdr, studio_cube_-X.hdr, ... (6 files)
|
||||
|
||||
# Adjust intensity
|
||||
node src/cli.js -p sun-sky --sun-intensity 200 --sky-intensity 0.8 -o output/bright_sky.hdr
|
||||
```
|
||||
|
||||
## Generate All Examples
|
||||
|
||||
```bash
|
||||
npm run example
|
||||
```
|
||||
|
||||
This generates 7+ example environment maps in `output/`:
|
||||
- White furnace
|
||||
- Sun/sky variations (afternoon, sunset, noon)
|
||||
- Studio lighting variations (default, high-key, low-key)
|
||||
- Cubemap example
|
||||
|
||||
## View Generated HDR Files
|
||||
|
||||
**On macOS/Linux:**
|
||||
```bash
|
||||
# Install ImageMagick
|
||||
sudo apt install imagemagick # Ubuntu/Debian
|
||||
brew install imagemagick # macOS
|
||||
|
||||
# Convert HDR to viewable PNG
|
||||
convert output/furnace.hdr output/furnace.png
|
||||
```
|
||||
|
||||
**In Blender:**
|
||||
1. Switch to **Shading** workspace
|
||||
2. Select **World** shader
|
||||
3. Add **Environment Texture** node
|
||||
4. Open your `.hdr` file
|
||||
|
||||
**In Web Browser:**
|
||||
Use online HDR viewer: https://www.hdrlabs.com/sibl/viewer.html
|
||||
|
||||
## Quick Command Reference
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `-p, --preset` | Preset name: white-furnace, sun-sky, studio |
|
||||
| `-w, --width` | Width in pixels (default: 2048) |
|
||||
| `--height` | Height in pixels (default: 1024) |
|
||||
| `--projection` | latlong or cubemap (default: latlong) |
|
||||
| `-f, --format` | hdr or exr (default: hdr) |
|
||||
| `-o, --output` | Output file path |
|
||||
| `--sun-elevation` | Sun angle above horizon (0-90°) |
|
||||
| `--sun-azimuth` | Sun compass direction (0-360°) |
|
||||
| `--key-intensity` | Studio key light intensity |
|
||||
|
||||
For full documentation, see [README.md](./README.md)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Files too dark/bright?
|
||||
|
||||
Adjust intensity parameters:
|
||||
```bash
|
||||
# Brighter sun
|
||||
node src/cli.js -p sun-sky --sun-intensity 200
|
||||
|
||||
# Dimmer studio
|
||||
node src/cli.js -p studio --key-intensity 25
|
||||
```
|
||||
|
||||
### Sun in wrong position?
|
||||
|
||||
Check azimuth (compass direction):
|
||||
- 0° = North (center top of image)
|
||||
- 90° = East (right side)
|
||||
- 180° = South (center bottom)
|
||||
- 270° = West (left side)
|
||||
|
||||
### Need help?
|
||||
|
||||
```bash
|
||||
node src/cli.js --help
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Read full [README.md](./README.md) for detailed documentation
|
||||
- Check [examples/](./examples/) directory for code samples
|
||||
- Import generated HDR files into your DCC (Blender, Houdini, etc.)
|
||||
- Use for IBL testing in your renderer
|
||||
|
||||
## File Sizes
|
||||
|
||||
| Resolution | File Size (HDR) | Use Case |
|
||||
|-----------|----------------|----------|
|
||||
| 512x256 | ~0.5 MB | Quick preview |
|
||||
| 1024x512 | ~2 MB | Development |
|
||||
| 2048x1024 | ~8 MB | Production (standard) |
|
||||
| 4096x2048 | ~32 MB | Production (high quality) |
|
||||
|
||||
Cubemaps are ~6x the equivalent lat-long size (one file per face).
|
||||
553
tools/hdrgen/README.md
Normal file
553
tools/hdrgen/README.md
Normal file
@@ -0,0 +1,553 @@
|
||||
# HDRGen - Synthetic HDR/EXR Environment Map Generator
|
||||
|
||||
A pure Node.js tool for generating synthetic HDR environment maps for testing, debugging, and prototyping PBR materials and IBL (Image-Based Lighting) setups.
|
||||
|
||||
## Features
|
||||
|
||||
- **Pure JavaScript/Node.js** - No external dependencies, no native bindings
|
||||
- **Multiple Presets** - White furnace, sun & sky, studio lighting
|
||||
- **Flexible Output** - HDR (Radiance RGBE) and EXR (OpenEXR) formats
|
||||
- **Dual Projections** - Equirectangular (lat-long) and cubemap
|
||||
- **Physically-Based** - Linear color space, HDR values, proper intensity scaling
|
||||
- **Customizable** - Extensive options for each preset
|
||||
- **CLI & API** - Use from command line or import as library
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
cd tools/hdrgen
|
||||
npm install
|
||||
```
|
||||
|
||||
Make CLI globally available:
|
||||
```bash
|
||||
npm link
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Generate White Furnace (Energy Conservation Test)
|
||||
|
||||
```bash
|
||||
node src/cli.js --preset white-furnace -o output/furnace.hdr
|
||||
```
|
||||
|
||||
### Generate Sun & Sky Environment
|
||||
|
||||
```bash
|
||||
node src/cli.js --preset sun-sky --sun-elevation 45 -o output/sky.hdr
|
||||
```
|
||||
|
||||
### Generate Studio Lighting
|
||||
|
||||
```bash
|
||||
node src/cli.js --preset studio -o output/studio.hdr
|
||||
```
|
||||
|
||||
### Generate Cubemap
|
||||
|
||||
```bash
|
||||
node src/cli.js --preset studio --projection cubemap --width 512 -o output/studio_cube
|
||||
```
|
||||
|
||||
### Generate All Examples
|
||||
|
||||
```bash
|
||||
npm run example
|
||||
```
|
||||
|
||||
## CLI Usage
|
||||
|
||||
```bash
|
||||
hdrgen [OPTIONS]
|
||||
```
|
||||
|
||||
### General Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `-h, --help` | Show help message | - |
|
||||
| `-p, --preset <name>` | Preset name (white-furnace, sun-sky, studio) | `white-furnace` |
|
||||
| `-w, --width <px>` | Width in pixels | `2048` |
|
||||
| `--height <px>` | Height in pixels | `1024` |
|
||||
| `--projection <type>` | Projection type (latlong, cubemap) | `latlong` |
|
||||
| `-f, --format <fmt>` | Output format (hdr, exr) | `hdr` |
|
||||
| `-o, --output <path>` | Output file path | `output/<preset>_<proj>.<fmt>` |
|
||||
|
||||
### White Furnace Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--intensity <val>` | Furnace intensity | `1.0` |
|
||||
|
||||
**Purpose:** Uniform white environment for testing energy conservation. A perfect diffuse BRDF should integrate to exactly the furnace intensity.
|
||||
|
||||
### Sun & Sky Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--sun-elevation <deg>` | Sun elevation angle (0=horizon, 90=zenith) | `45` |
|
||||
| `--sun-azimuth <deg>` | Sun azimuth angle (0=north, 90=east) | `135` |
|
||||
| `--sun-intensity <val>` | Sun disk intensity | `100.0` |
|
||||
| `--sky-intensity <val>` | Base sky intensity | `0.5` |
|
||||
|
||||
**Purpose:** Procedural outdoor environment with directional sun and atmospheric sky gradient.
|
||||
|
||||
### Studio Lighting Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|--------|-------------|---------|
|
||||
| `--key-intensity <val>` | Key light intensity (main light) | `50.0` |
|
||||
| `--fill-intensity <val>` | Fill light intensity (shadow fill) | `10.0` |
|
||||
| `--rim-intensity <val>` | Rim light intensity (back highlight) | `20.0` |
|
||||
| `--ambient-intensity <val>` | Ambient light intensity | `0.5` |
|
||||
|
||||
**Purpose:** Professional 3-point lighting setup for product visualization and character lighting.
|
||||
|
||||
## Presets
|
||||
|
||||
### 1. White Furnace
|
||||
|
||||
Uniform white environment at specified intensity. Essential for validating PBR material energy conservation.
|
||||
|
||||
**Use Cases:**
|
||||
- Energy conservation testing
|
||||
- BRDF validation
|
||||
- Exposure calibration
|
||||
- Albedo verification
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Standard furnace test
|
||||
hdrgen -p white-furnace --intensity 1.0 -o output/furnace.hdr
|
||||
|
||||
# High intensity test
|
||||
hdrgen -p white-furnace --intensity 10.0 -o output/furnace_10x.hdr
|
||||
```
|
||||
|
||||
**Expected Results:**
|
||||
- Perfectly diffuse white material should appear with albedo = intensity
|
||||
- Metals should appear dark (no diffuse reflection)
|
||||
- Specular reflections should be uniform in all directions
|
||||
|
||||
### 2. Sun & Sky
|
||||
|
||||
Procedural sky with sun disk and atmospheric gradient. Simplified Hosek-Wilkie sky model approximation.
|
||||
|
||||
**Use Cases:**
|
||||
- Outdoor scene lighting
|
||||
- Architecture visualization
|
||||
- Product photography (outdoor)
|
||||
- Time-of-day studies
|
||||
|
||||
**Parameters:**
|
||||
- **Sun Elevation:** Height of sun above horizon (0°-90°)
|
||||
- `0°-10°`: Sunrise/sunset (warm, long shadows)
|
||||
- `30°-60°`: Mid-day (balanced, natural)
|
||||
- `80°-90°`: Noon (overhead, harsh)
|
||||
- **Sun Azimuth:** Compass direction of sun (0°-360°)
|
||||
- `0°`: North
|
||||
- `90°`: East
|
||||
- `180°`: South
|
||||
- `270°`: West
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Afternoon sun (front-right)
|
||||
hdrgen -p sun-sky --sun-elevation 45 --sun-azimuth 135 -o output/afternoon.hdr
|
||||
|
||||
# Sunset (low sun, west)
|
||||
hdrgen -p sun-sky --sun-elevation 5 --sun-azimuth 270 --sun-intensity 150 -o output/sunset.hdr
|
||||
|
||||
# Noon (overhead)
|
||||
hdrgen -p sun-sky --sun-elevation 85 --sun-azimuth 0 --sun-intensity 200 -o output/noon.hdr
|
||||
|
||||
# Sunrise (low sun, east)
|
||||
hdrgen -p sun-sky --sun-elevation 10 --sun-azimuth 90 --sun-intensity 120 -o output/sunrise.hdr
|
||||
```
|
||||
|
||||
### 3. Studio Lighting
|
||||
|
||||
3-point lighting setup with key, fill, and rim lights. Classic photography and cinematography lighting pattern.
|
||||
|
||||
**Use Cases:**
|
||||
- Product rendering
|
||||
- Character lighting
|
||||
- Controlled lighting studies
|
||||
- Material comparison
|
||||
|
||||
**Light Configuration:**
|
||||
- **Key Light:** Main light source (front-right, elevated)
|
||||
- Position: 45° right, 30° up
|
||||
- Color: Warm (slightly yellow)
|
||||
- **Fill Light:** Shadow fill (front-left, lower)
|
||||
- Position: 30° left, 20° up
|
||||
- Color: Cool (slightly blue)
|
||||
- **Rim Light:** Edge/separation light (back, elevated)
|
||||
- Position: Behind subject, 25° up
|
||||
- Color: Neutral white
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Standard studio setup
|
||||
hdrgen -p studio -o output/studio.hdr
|
||||
|
||||
# High-key lighting (bright, low contrast)
|
||||
hdrgen -p studio --key-intensity 80 --fill-intensity 30 --ambient-intensity 1.0 -o output/highkey.hdr
|
||||
|
||||
# Low-key lighting (dramatic, high contrast)
|
||||
hdrgen -p studio --key-intensity 30 --fill-intensity 5 --rim-intensity 40 --ambient-intensity 0.1 -o output/lowkey.hdr
|
||||
|
||||
# Product lighting (strong rim for edge definition)
|
||||
hdrgen -p studio --key-intensity 60 --fill-intensity 15 --rim-intensity 50 -o output/product.hdr
|
||||
```
|
||||
|
||||
## Projection Types
|
||||
|
||||
### Equirectangular (Lat-Long)
|
||||
|
||||
Single image with 2:1 aspect ratio (e.g., 2048x1024). Standard format for environment maps.
|
||||
|
||||
**Characteristics:**
|
||||
- Full 360° horizontal, 180° vertical coverage
|
||||
- Distortion at poles (top and bottom stretched)
|
||||
- Most compact format (single file)
|
||||
- Widely supported by renderers and DCCs
|
||||
|
||||
**Output:** Single `.hdr` or `.exr` file
|
||||
|
||||
```bash
|
||||
hdrgen -p sun-sky --projection latlong -w 2048 --height 1024 -o output/sky.hdr
|
||||
```
|
||||
|
||||
### Cubemap
|
||||
|
||||
Six square images representing faces of a cube. No distortion, but requires 6 separate files.
|
||||
|
||||
**Face Order (OpenGL Convention):**
|
||||
- `+X`: Right
|
||||
- `-X`: Left
|
||||
- `+Y`: Top (up)
|
||||
- `-Y`: Bottom (down)
|
||||
- `+Z`: Front
|
||||
- `-Z`: Back
|
||||
|
||||
**Characteristics:**
|
||||
- No polar distortion
|
||||
- Uniform sampling across all directions
|
||||
- Larger total file size (6 files)
|
||||
- Preferred for real-time rendering and importance sampling
|
||||
|
||||
**Output:** Six files with face suffixes: `_+X.hdr`, `_-X.hdr`, etc.
|
||||
|
||||
```bash
|
||||
hdrgen -p studio --projection cubemap --width 512 -o output/studio_cube
|
||||
# Creates: studio_cube_+X.hdr, studio_cube_-X.hdr, ..., studio_cube_-Z.hdr
|
||||
```
|
||||
|
||||
## File Formats
|
||||
|
||||
### HDR (Radiance RGBE)
|
||||
|
||||
Standard format for HDR images. Widely supported, compact, 8-bit per channel with shared exponent.
|
||||
|
||||
**Specifications:**
|
||||
- Format: RGBE (RGB + 8-bit shared exponent)
|
||||
- Precision: ~7 decimal digits
|
||||
- Dynamic range: 10^-38 to 10^38
|
||||
- File size: 4 bytes per pixel
|
||||
- Extension: `.hdr`
|
||||
|
||||
**Advantages:**
|
||||
- Small file size
|
||||
- Fast to write
|
||||
- Universal support
|
||||
- Good for most IBL use cases
|
||||
|
||||
**Limitations:**
|
||||
- Limited precision (8-bit mantissa)
|
||||
- No alpha channel
|
||||
- No arbitrary metadata
|
||||
|
||||
### EXR (OpenEXR)
|
||||
|
||||
High-precision format from ILM. Better precision, alpha channel support, extensive metadata.
|
||||
|
||||
**Specifications:**
|
||||
- Format: Half-float (16-bit) or float (32-bit) per channel
|
||||
- Precision: Half = 11-bit mantissa, Float = 24-bit mantissa
|
||||
- Dynamic range: Half = 10^-5 to 65504
|
||||
- File size: 6 bytes (half) or 12 bytes (float) per pixel
|
||||
- Extension: `.exr`
|
||||
|
||||
**Note:** Current implementation converts to HDR. For production EXR writing, use `@openexr/node` or similar library.
|
||||
|
||||
## API Usage
|
||||
|
||||
### As ES6 Module
|
||||
|
||||
```javascript
|
||||
import { HDRGenerator } from './src/hdrgen.js';
|
||||
|
||||
// Generate lat-long sun & sky
|
||||
const result = HDRGenerator.generate({
|
||||
preset: 'sun-sky',
|
||||
width: 2048,
|
||||
height: 1024,
|
||||
projection: 'latlong',
|
||||
format: 'hdr',
|
||||
output: 'output/sky.hdr',
|
||||
presetOptions: {
|
||||
sunElevation: 45,
|
||||
sunAzimuth: 135,
|
||||
sunIntensity: 100.0
|
||||
}
|
||||
});
|
||||
|
||||
// Access raw image data
|
||||
const { latLongImage } = result;
|
||||
console.log(`Generated ${latLongImage.width}x${latLongImage.height} HDR image`);
|
||||
```
|
||||
|
||||
### Programmatic Generation
|
||||
|
||||
```javascript
|
||||
import { HDRImage, EnvMapPresets, HDRWriter } from './src/hdrgen.js';
|
||||
|
||||
// Create custom environment
|
||||
const image = new HDRImage(2048, 1024);
|
||||
|
||||
// Apply preset
|
||||
EnvMapPresets.sunSky(image, {
|
||||
sunElevation: 30,
|
||||
sunIntensity: 150.0
|
||||
});
|
||||
|
||||
// Write to file
|
||||
HDRWriter.writeRGBE(image, 'output/custom.hdr');
|
||||
```
|
||||
|
||||
### Custom Procedural Environments
|
||||
|
||||
```javascript
|
||||
import { HDRImage, Vec3 } from './src/hdrgen.js';
|
||||
|
||||
const image = new HDRImage(1024, 512);
|
||||
|
||||
for (let y = 0; y < image.height; y++) {
|
||||
for (let x = 0; x < image.width; x++) {
|
||||
const u = x / image.width;
|
||||
const v = y / image.height;
|
||||
|
||||
// Custom procedural function
|
||||
const r = Math.sin(u * Math.PI * 4) * 0.5 + 0.5;
|
||||
const g = Math.sin(v * Math.PI * 4) * 0.5 + 0.5;
|
||||
const b = 0.5;
|
||||
|
||||
image.setPixel(x, y, r * 10.0, g * 10.0, b * 10.0);
|
||||
}
|
||||
}
|
||||
|
||||
HDRWriter.writeRGBE(image, 'output/procedural.hdr');
|
||||
```
|
||||
|
||||
## Resolution Guidelines
|
||||
|
||||
### Lat-Long Environments
|
||||
|
||||
| Use Case | Resolution | Aspect | File Size (HDR) |
|
||||
|----------|-----------|--------|-----------------|
|
||||
| Quick preview | 512x256 | 2:1 | ~0.5 MB |
|
||||
| Development | 1024x512 | 2:1 | ~2 MB |
|
||||
| Production (low) | 2048x1024 | 2:1 | ~8 MB |
|
||||
| Production (standard) | 4096x2048 | 2:1 | ~32 MB |
|
||||
| Production (high) | 8192x4096 | 2:1 | ~128 MB |
|
||||
|
||||
### Cubemap Environments
|
||||
|
||||
| Use Case | Face Size | Total Resolution | File Size (HDR x6) |
|
||||
|----------|----------|------------------|-------------------|
|
||||
| Preview | 128x128 | 128 | ~0.4 MB |
|
||||
| Low | 256x256 | 256 | ~1.5 MB |
|
||||
| Medium | 512x512 | 512 | ~6 MB |
|
||||
| High | 1024x1024 | 1K | ~24 MB |
|
||||
| Ultra | 2048x2048 | 2K | ~96 MB |
|
||||
|
||||
**Recommendation:** Start with 1024x512 lat-long for development, use 2048x1024 or higher for final renders.
|
||||
|
||||
## Testing & Validation
|
||||
|
||||
### Energy Conservation Test
|
||||
|
||||
White furnace with diffuse white material should reflect exactly the furnace intensity:
|
||||
|
||||
```bash
|
||||
# Generate test environment
|
||||
hdrgen -p white-furnace --intensity 1.0 -o output/furnace_test.hdr
|
||||
|
||||
# In your renderer:
|
||||
# 1. Load furnace_test.hdr
|
||||
# 2. Create material: diffuse white (albedo = 1.0)
|
||||
# 3. Render sphere
|
||||
# 4. Expected result: sphere appears with color = (1.0, 1.0, 1.0)
|
||||
```
|
||||
|
||||
### Sun Direction Validation
|
||||
|
||||
```bash
|
||||
# Generate known sun position (45° elevation, 90° east)
|
||||
hdrgen -p sun-sky --sun-elevation 45 --sun-azimuth 90 -o output/sun_test.hdr
|
||||
|
||||
# Visual check: Bright spot should be in upper-right quadrant of lat-long image
|
||||
# Azimuth 90° = right side of image (east)
|
||||
# Elevation 45° = mid-height of image
|
||||
```
|
||||
|
||||
### Studio Lighting Validation
|
||||
|
||||
```bash
|
||||
# Generate studio environment
|
||||
hdrgen -p studio -o output/studio_test.hdr
|
||||
|
||||
# Expected light positions:
|
||||
# - Key light: Front-right (bright warm spot)
|
||||
# - Fill light: Front-left (dimmer cool glow)
|
||||
# - Rim light: Back (sharp highlight)
|
||||
```
|
||||
|
||||
## Importing in DCCs
|
||||
|
||||
### Blender
|
||||
|
||||
1. Switch to **Shading** workspace
|
||||
2. Select **World** shader
|
||||
3. Add **Environment Texture** node
|
||||
4. Open generated `.hdr` file
|
||||
5. Connect to **Background** shader
|
||||
|
||||
### Houdini
|
||||
|
||||
1. Create **Environment Light**
|
||||
2. Set **Environment Map** to generated `.hdr` file
|
||||
3. Adjust **Intensity** if needed
|
||||
|
||||
### Maya
|
||||
|
||||
1. Create **Skydome Light**
|
||||
2. Load generated `.hdr` in **Color** attribute
|
||||
3. Set **Exposure** if needed
|
||||
|
||||
### Unreal Engine
|
||||
|
||||
1. Import `.hdr` as **Texture Cube** (for cubemaps) or **Texture 2D** (for lat-long)
|
||||
2. Create **Skylight** actor
|
||||
3. Set **Source Type** to **SLS Specified Cubemap**
|
||||
4. Assign texture
|
||||
|
||||
### Unity
|
||||
|
||||
1. Import `.hdr` file
|
||||
2. Set **Texture Shape** to **Cube** (for cubemap) or **2D** (for lat-long)
|
||||
3. In **Lighting** window, assign to **Environment Skybox**
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Color Space
|
||||
|
||||
All generated environments are in **linear color space** (no gamma encoding). This is correct for PBR rendering and HDR textures.
|
||||
|
||||
- Input values: Linear RGB
|
||||
- Output values: Linear RGB (HDR, values can exceed 1.0)
|
||||
- No sRGB transfer function applied
|
||||
|
||||
### HDR Range
|
||||
|
||||
Values are unbounded and can significantly exceed 1.0:
|
||||
- Sun disk: 50-200+ (direct sunlight simulation)
|
||||
- Sky: 0.1-2.0 (indirect ambient)
|
||||
- Studio lights: 10-100 (controlled lighting)
|
||||
- White furnace: 0.1-10.0 (testing range)
|
||||
|
||||
### Coordinate System
|
||||
|
||||
**Lat-Long (Equirectangular):**
|
||||
- U (horizontal): 0 = -180° (west), 0.5 = 0° (north), 1.0 = 180° (east)
|
||||
- V (vertical): 0 = -90° (down), 0.5 = 0° (horizon), 1.0 = 90° (up)
|
||||
- Direction: +X right, +Y up, +Z forward
|
||||
|
||||
**Cubemap (OpenGL Convention):**
|
||||
- Faces: +X, -X, +Y, -Y, +Z, -Z
|
||||
- +Y is up (top face)
|
||||
- Right-handed coordinate system
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Generated files appear too dark/bright
|
||||
|
||||
Adjust intensity parameters:
|
||||
```bash
|
||||
# Increase sun intensity
|
||||
hdrgen -p sun-sky --sun-intensity 200 -o output/bright_sky.hdr
|
||||
|
||||
# Decrease studio key light
|
||||
hdrgen -p studio --key-intensity 25 -o output/dim_studio.hdr
|
||||
```
|
||||
|
||||
### Sun position is incorrect
|
||||
|
||||
Check azimuth convention:
|
||||
- 0° = North (top of lat-long image, middle)
|
||||
- 90° = East (right side of lat-long image)
|
||||
- 180° = South (bottom, middle)
|
||||
- 270° = West (left side)
|
||||
|
||||
### Cubemap faces don't align properly
|
||||
|
||||
Ensure DCC is using OpenGL convention (+Y up). Some DCCs (DirectX convention) may require face reordering.
|
||||
|
||||
### EXR files aren't working
|
||||
|
||||
Current implementation writes HDR format. For true EXR support, integrate `@openexr/node` or similar library.
|
||||
|
||||
## Limitations
|
||||
|
||||
- **EXR Writing:** Currently writes HDR format instead (requires external library for true EXR)
|
||||
- **Sky Model:** Simplified procedural sky (not full Hosek-Wilkie or Nishita)
|
||||
- **Compression:** HDR files are uncompressed (no RLE compression)
|
||||
- **Metadata:** Minimal file metadata (no custom tags)
|
||||
|
||||
## Roadmap
|
||||
|
||||
- [ ] Proper EXR writing with compression
|
||||
- [ ] More presets (indoor, sunset, overcast, etc.)
|
||||
- [ ] Importance sampling map generation
|
||||
- [ ] Diffuse/specular pre-filtering
|
||||
- [ ] HDRI panorama manipulation (rotate, exposure)
|
||||
- [ ] Animation (time-of-day sequence)
|
||||
- [ ] Web-based visualizer
|
||||
|
||||
## License
|
||||
|
||||
Apache License 2.0
|
||||
|
||||
Copyright 2024 - Present, Light Transport Entertainment Inc.
|
||||
|
||||
## References
|
||||
|
||||
- [HDR Image Formats](https://www.pauldebevec.com/Research/HDR/)
|
||||
- [Radiance RGBE Format](https://floyd.lbl.gov/radiance/refer/Notes/picture_format.html)
|
||||
- [OpenEXR Specification](https://www.openexr.com/)
|
||||
- [PBR Theory](https://www.pbrt.org/)
|
||||
- [Hosek-Wilkie Sky Model](https://cgg.mff.cuni.cz/projects/SkylightModelling/)
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions welcome! Please ensure:
|
||||
- Code follows existing style
|
||||
- Tests pass: `npm test`
|
||||
- Examples work: `npm run example`
|
||||
- Documentation is updated
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions, see: https://github.com/syoyo/tinyusdz
|
||||
138
tools/hdrgen/examples/generate-all.js
Normal file
138
tools/hdrgen/examples/generate-all.js
Normal file
@@ -0,0 +1,138 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Generate all preset examples
|
||||
*/
|
||||
|
||||
import { HDRGenerator } from '../src/hdrgen.js';
|
||||
import * as path from 'path';
|
||||
import { fileURLToPath } from 'url';
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
const __dirname = path.dirname(__filename);
|
||||
const outputDir = path.join(__dirname, '../output');
|
||||
|
||||
console.log('Generating all preset examples...\n');
|
||||
|
||||
// 1. White Furnace (for testing)
|
||||
console.log('--- White Furnace ---');
|
||||
HDRGenerator.generate({
|
||||
preset: 'white-furnace',
|
||||
width: 1024,
|
||||
height: 512,
|
||||
projection: 'latlong',
|
||||
format: 'hdr',
|
||||
output: path.join(outputDir, 'white_furnace_1k.hdr'),
|
||||
presetOptions: { intensity: 1.0 }
|
||||
});
|
||||
|
||||
// 2. Sun & Sky (Default - afternoon)
|
||||
console.log('\n--- Sun & Sky (Afternoon) ---');
|
||||
HDRGenerator.generate({
|
||||
preset: 'sun-sky',
|
||||
width: 2048,
|
||||
height: 1024,
|
||||
projection: 'latlong',
|
||||
format: 'hdr',
|
||||
output: path.join(outputDir, 'sunsky_afternoon_2k.hdr'),
|
||||
presetOptions: {
|
||||
sunElevation: 45,
|
||||
sunAzimuth: 135,
|
||||
sunIntensity: 100.0,
|
||||
skyIntensity: 0.5
|
||||
}
|
||||
});
|
||||
|
||||
// 3. Sun & Sky (Sunset)
|
||||
console.log('\n--- Sun & Sky (Sunset) ---');
|
||||
HDRGenerator.generate({
|
||||
preset: 'sun-sky',
|
||||
width: 2048,
|
||||
height: 1024,
|
||||
projection: 'latlong',
|
||||
format: 'hdr',
|
||||
output: path.join(outputDir, 'sunsky_sunset_2k.hdr'),
|
||||
presetOptions: {
|
||||
sunElevation: 5,
|
||||
sunAzimuth: 270,
|
||||
sunIntensity: 150.0,
|
||||
skyIntensity: 0.3
|
||||
}
|
||||
});
|
||||
|
||||
// 4. Sun & Sky (Noon)
|
||||
console.log('\n--- Sun & Sky (Noon) ---');
|
||||
HDRGenerator.generate({
|
||||
preset: 'sun-sky',
|
||||
width: 2048,
|
||||
height: 1024,
|
||||
projection: 'latlong',
|
||||
format: 'hdr',
|
||||
output: path.join(outputDir, 'sunsky_noon_2k.hdr'),
|
||||
presetOptions: {
|
||||
sunElevation: 85,
|
||||
sunAzimuth: 0,
|
||||
sunIntensity: 200.0,
|
||||
skyIntensity: 0.8
|
||||
}
|
||||
});
|
||||
|
||||
// 5. Studio Lighting (Default)
|
||||
console.log('\n--- Studio Lighting (Default) ---');
|
||||
HDRGenerator.generate({
|
||||
preset: 'studio',
|
||||
width: 2048,
|
||||
height: 1024,
|
||||
projection: 'latlong',
|
||||
format: 'hdr',
|
||||
output: path.join(outputDir, 'studio_default_2k.hdr'),
|
||||
presetOptions: {}
|
||||
});
|
||||
|
||||
// 6. Studio Lighting (High Key)
|
||||
console.log('\n--- Studio Lighting (High Key) ---');
|
||||
HDRGenerator.generate({
|
||||
preset: 'studio',
|
||||
width: 2048,
|
||||
height: 1024,
|
||||
projection: 'latlong',
|
||||
format: 'hdr',
|
||||
output: path.join(outputDir, 'studio_highkey_2k.hdr'),
|
||||
presetOptions: {
|
||||
keyIntensity: 80.0,
|
||||
fillIntensity: 30.0,
|
||||
rimIntensity: 10.0,
|
||||
ambientIntensity: 1.0
|
||||
}
|
||||
});
|
||||
|
||||
// 7. Studio Lighting (Low Key)
|
||||
console.log('\n--- Studio Lighting (Low Key) ---');
|
||||
HDRGenerator.generate({
|
||||
preset: 'studio',
|
||||
width: 2048,
|
||||
height: 1024,
|
||||
projection: 'latlong',
|
||||
format: 'hdr',
|
||||
output: path.join(outputDir, 'studio_lowkey_2k.hdr'),
|
||||
presetOptions: {
|
||||
keyIntensity: 30.0,
|
||||
fillIntensity: 5.0,
|
||||
rimIntensity: 40.0,
|
||||
ambientIntensity: 0.1
|
||||
}
|
||||
});
|
||||
|
||||
// 8. Cubemap Example (Studio)
|
||||
console.log('\n--- Cubemap (Studio) ---');
|
||||
HDRGenerator.generate({
|
||||
preset: 'studio',
|
||||
width: 512,
|
||||
height: 512,
|
||||
projection: 'cubemap',
|
||||
format: 'hdr',
|
||||
output: path.join(outputDir, 'studio_cube'),
|
||||
presetOptions: {}
|
||||
});
|
||||
|
||||
console.log('\n=== All examples generated successfully! ===');
|
||||
console.log(`Output directory: ${outputDir}\n`);
|
||||
194
tools/hdrgen/examples/test-presets.js
Normal file
194
tools/hdrgen/examples/test-presets.js
Normal file
@@ -0,0 +1,194 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Quick test script for validating all presets
|
||||
*/
|
||||
|
||||
import { HDRGenerator, HDRImage, Vec3 } from '../src/hdrgen.js';
|
||||
import * as path from 'path';
|
||||
import { fileURLToPath } from 'url';
|
||||
import * as fs from 'fs';
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
const __dirname = path.dirname(__filename);
|
||||
const outputDir = path.join(__dirname, '../output');
|
||||
|
||||
// Ensure output directory exists
|
||||
if (!fs.existsSync(outputDir)) {
|
||||
fs.mkdirSync(outputDir, { recursive: true });
|
||||
}
|
||||
|
||||
console.log('Running HDRGen tests...\n');
|
||||
|
||||
let passed = 0;
|
||||
let failed = 0;
|
||||
|
||||
function test(name, fn) {
|
||||
try {
|
||||
console.log(`Testing: ${name}`);
|
||||
fn();
|
||||
console.log(`✓ ${name} passed\n`);
|
||||
passed++;
|
||||
} catch (err) {
|
||||
console.error(`✗ ${name} failed: ${err.message}\n`);
|
||||
failed++;
|
||||
}
|
||||
}
|
||||
|
||||
// Test 1: White Furnace Generation
|
||||
test('White Furnace (256x128)', () => {
|
||||
const result = HDRGenerator.generate({
|
||||
preset: 'white-furnace',
|
||||
width: 256,
|
||||
height: 128,
|
||||
projection: 'latlong',
|
||||
format: 'hdr',
|
||||
output: path.join(outputDir, 'test_furnace.hdr'),
|
||||
presetOptions: { intensity: 1.0 }
|
||||
});
|
||||
|
||||
if (!result.latLongImage) throw new Error('No image generated');
|
||||
if (result.latLongImage.width !== 256) throw new Error('Wrong width');
|
||||
if (result.latLongImage.height !== 128) throw new Error('Wrong height');
|
||||
|
||||
// Check first pixel is white
|
||||
const pixel = result.latLongImage.getPixel(0, 0);
|
||||
if (Math.abs(pixel.r - 1.0) > 0.01) throw new Error('Wrong intensity');
|
||||
});
|
||||
|
||||
// Test 2: Sun & Sky Generation
|
||||
test('Sun & Sky (256x128)', () => {
|
||||
const result = HDRGenerator.generate({
|
||||
preset: 'sun-sky',
|
||||
width: 256,
|
||||
height: 128,
|
||||
projection: 'latlong',
|
||||
format: 'hdr',
|
||||
output: path.join(outputDir, 'test_sunsky.hdr'),
|
||||
presetOptions: {
|
||||
sunElevation: 45,
|
||||
sunAzimuth: 135,
|
||||
sunIntensity: 100.0
|
||||
}
|
||||
});
|
||||
|
||||
if (!result.latLongImage) throw new Error('No image generated');
|
||||
|
||||
// Check that sky has varying intensities (not uniform)
|
||||
const p1 = result.latLongImage.getPixel(0, 0);
|
||||
const p2 = result.latLongImage.getPixel(128, 64);
|
||||
if (p1.r === p2.r && p1.g === p2.g && p1.b === p2.b) {
|
||||
throw new Error('Sky should not be uniform');
|
||||
}
|
||||
});
|
||||
|
||||
// Test 3: Studio Lighting Generation
|
||||
test('Studio Lighting (256x128)', () => {
|
||||
const result = HDRGenerator.generate({
|
||||
preset: 'studio',
|
||||
width: 256,
|
||||
height: 128,
|
||||
projection: 'latlong',
|
||||
format: 'hdr',
|
||||
output: path.join(outputDir, 'test_studio.hdr'),
|
||||
presetOptions: {}
|
||||
});
|
||||
|
||||
if (!result.latLongImage) throw new Error('No image generated');
|
||||
});
|
||||
|
||||
// Test 4: Cubemap Generation
|
||||
test('Cubemap Generation (64x64 faces)', () => {
|
||||
const result = HDRGenerator.generate({
|
||||
preset: 'white-furnace',
|
||||
width: 64,
|
||||
height: 64,
|
||||
projection: 'cubemap',
|
||||
format: 'hdr',
|
||||
output: path.join(outputDir, 'test_cube'),
|
||||
presetOptions: { intensity: 1.0 }
|
||||
});
|
||||
|
||||
if (!result.faces) throw new Error('No cubemap faces generated');
|
||||
if (result.faces.length !== 6) throw new Error('Should generate 6 faces');
|
||||
|
||||
// Check each face
|
||||
for (const face of result.faces) {
|
||||
if (!face.image) throw new Error('Missing face image');
|
||||
if (face.image.width !== 64) throw new Error('Wrong face size');
|
||||
}
|
||||
});
|
||||
|
||||
// Test 5: HDR Image Class
|
||||
test('HDRImage class', () => {
|
||||
const img = new HDRImage(100, 50);
|
||||
if (img.width !== 100) throw new Error('Wrong width');
|
||||
if (img.height !== 50) throw new Error('Wrong height');
|
||||
if (img.data.length !== 100 * 50 * 3) throw new Error('Wrong data size');
|
||||
|
||||
img.setPixel(10, 20, 1.5, 2.5, 3.5);
|
||||
const pixel = img.getPixel(10, 20);
|
||||
if (Math.abs(pixel.r - 1.5) > 0.001) throw new Error('setPixel/getPixel failed');
|
||||
});
|
||||
|
||||
// Test 6: Vec3 math
|
||||
test('Vec3 math utilities', () => {
|
||||
const v1 = new Vec3(1, 2, 3);
|
||||
const v2 = new Vec3(4, 5, 6);
|
||||
|
||||
const sum = Vec3.add(v1, v2);
|
||||
if (sum.x !== 5 || sum.y !== 7 || sum.z !== 9) throw new Error('Vec3.add failed');
|
||||
|
||||
const dot = Vec3.dot(v1, v2);
|
||||
if (dot !== 32) throw new Error('Vec3.dot failed');
|
||||
|
||||
const len = new Vec3(3, 4, 0).length();
|
||||
if (Math.abs(len - 5) > 0.001) throw new Error('Vec3.length failed');
|
||||
|
||||
const norm = new Vec3(0, 5, 0).normalize();
|
||||
if (Math.abs(norm.y - 1) > 0.001) throw new Error('Vec3.normalize failed');
|
||||
});
|
||||
|
||||
// Test 7: Lat-Long to Direction Conversion
|
||||
test('Lat-Long coordinate conversion', () => {
|
||||
// Test north pole (u=0.5, v=0)
|
||||
const north = HDRImage.latLongToDir(0.5, 0.0);
|
||||
if (Math.abs(north.y - 1) > 0.01) throw new Error('North pole conversion failed');
|
||||
|
||||
// Test south pole (u=0.5, v=1)
|
||||
const south = HDRImage.latLongToDir(0.5, 1.0);
|
||||
if (Math.abs(south.y + 1) > 0.01) throw new Error('South pole conversion failed');
|
||||
|
||||
// Test equator front (u=0.5, v=0.5)
|
||||
const front = HDRImage.latLongToDir(0.5, 0.5);
|
||||
if (Math.abs(front.y) > 0.01) throw new Error('Equator conversion failed');
|
||||
});
|
||||
|
||||
// Test 8: Custom Intensity White Furnace
|
||||
test('White Furnace with custom intensity', () => {
|
||||
const result = HDRGenerator.generate({
|
||||
preset: 'white-furnace',
|
||||
width: 64,
|
||||
height: 32,
|
||||
projection: 'latlong',
|
||||
format: 'hdr',
|
||||
output: path.join(outputDir, 'test_furnace_10x.hdr'),
|
||||
presetOptions: { intensity: 10.0 }
|
||||
});
|
||||
|
||||
const pixel = result.latLongImage.getPixel(32, 16);
|
||||
if (Math.abs(pixel.r - 10.0) > 0.01) throw new Error('Wrong intensity');
|
||||
});
|
||||
|
||||
// Summary
|
||||
console.log('='.repeat(60));
|
||||
console.log(`Test Results: ${passed} passed, ${failed} failed`);
|
||||
console.log('='.repeat(60));
|
||||
|
||||
if (failed > 0) {
|
||||
console.error('\n✗ Some tests failed');
|
||||
process.exit(1);
|
||||
} else {
|
||||
console.log('\n✓ All tests passed!');
|
||||
console.log(`\nTest outputs in: ${outputDir}/test_*.hdr`);
|
||||
process.exit(0);
|
||||
}
|
||||
BIN
tools/hdrgen/output/sky_test.bmp
Normal file
BIN
tools/hdrgen/output/sky_test.bmp
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 384 KiB |
BIN
tools/hdrgen/output/studio_test.png
Normal file
BIN
tools/hdrgen/output/studio_test.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 384 KiB |
6
tools/hdrgen/output/test_cube_+X.hdr
Normal file
6
tools/hdrgen/output/test_cube_+X.hdr
Normal file
File diff suppressed because one or more lines are too long
6
tools/hdrgen/output/test_cube_+Y.hdr
Normal file
6
tools/hdrgen/output/test_cube_+Y.hdr
Normal file
File diff suppressed because one or more lines are too long
6
tools/hdrgen/output/test_cube_+Z.hdr
Normal file
6
tools/hdrgen/output/test_cube_+Z.hdr
Normal file
File diff suppressed because one or more lines are too long
6
tools/hdrgen/output/test_cube_-X.hdr
Normal file
6
tools/hdrgen/output/test_cube_-X.hdr
Normal file
File diff suppressed because one or more lines are too long
6
tools/hdrgen/output/test_cube_-Y.hdr
Normal file
6
tools/hdrgen/output/test_cube_-Y.hdr
Normal file
File diff suppressed because one or more lines are too long
6
tools/hdrgen/output/test_cube_-Z.hdr
Normal file
6
tools/hdrgen/output/test_cube_-Z.hdr
Normal file
File diff suppressed because one or more lines are too long
6
tools/hdrgen/output/test_furnace.hdr
Normal file
6
tools/hdrgen/output/test_furnace.hdr
Normal file
File diff suppressed because one or more lines are too long
6
tools/hdrgen/output/test_furnace_10x.hdr
Normal file
6
tools/hdrgen/output/test_furnace_10x.hdr
Normal file
File diff suppressed because one or more lines are too long
6
tools/hdrgen/output/test_studio.hdr
Normal file
6
tools/hdrgen/output/test_studio.hdr
Normal file
File diff suppressed because one or more lines are too long
6
tools/hdrgen/output/test_sunsky.hdr
Normal file
6
tools/hdrgen/output/test_sunsky.hdr
Normal file
File diff suppressed because one or more lines are too long
31
tools/hdrgen/package.json
Normal file
31
tools/hdrgen/package.json
Normal file
@@ -0,0 +1,31 @@
|
||||
{
|
||||
"name": "hdrgen",
|
||||
"version": "1.1.0",
|
||||
"description": "Synthetic HDR/EXR/LDR environment map generator with rotation, scaling, and tone mapping",
|
||||
"main": "src/hdrgen.js",
|
||||
"type": "module",
|
||||
"bin": {
|
||||
"hdrgen": "./src/cli.js"
|
||||
},
|
||||
"scripts": {
|
||||
"generate": "node src/cli.js",
|
||||
"example": "node examples/generate-all.js",
|
||||
"test": "node examples/test-presets.js"
|
||||
},
|
||||
"keywords": [
|
||||
"hdr",
|
||||
"exr",
|
||||
"environment-map",
|
||||
"cubemap",
|
||||
"latlong",
|
||||
"ibl",
|
||||
"pbr"
|
||||
],
|
||||
"author": "TinyUSDZ Project",
|
||||
"license": "Apache-2.0",
|
||||
"dependencies": {},
|
||||
"devDependencies": {},
|
||||
"engines": {
|
||||
"node": ">=16.0.0"
|
||||
}
|
||||
}
|
||||
256
tools/hdrgen/src/cli.js
Normal file
256
tools/hdrgen/src/cli.js
Normal file
@@ -0,0 +1,256 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* HDRGen CLI - Command line interface for HDR environment map generation
|
||||
*
|
||||
* Copyright 2024 - Present, Light Transport Entertainment Inc.
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import { HDRGenerator, Vec3 } from './hdrgen.js';
|
||||
import * as path from 'path';
|
||||
import { fileURLToPath } from 'url';
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url);
|
||||
const __dirname = path.dirname(__filename);
|
||||
|
||||
// ============================================================================
|
||||
// CLI Argument Parser
|
||||
// ============================================================================
|
||||
|
||||
function parseArgs(argv) {
|
||||
const args = {
|
||||
preset: 'white-furnace',
|
||||
width: 2048,
|
||||
height: 1024,
|
||||
projection: 'latlong',
|
||||
format: 'hdr',
|
||||
output: null,
|
||||
presetOptions: {},
|
||||
rotation: 0,
|
||||
intensityScale: 1.0,
|
||||
tonemapOptions: {
|
||||
exposure: 0.0,
|
||||
gamma: 2.2,
|
||||
method: 'reinhard'
|
||||
},
|
||||
help: false
|
||||
};
|
||||
|
||||
for (let i = 2; i < argv.length; i++) {
|
||||
const arg = argv[i];
|
||||
|
||||
if (arg === '-h' || arg === '--help') {
|
||||
args.help = true;
|
||||
} else if (arg === '-p' || arg === '--preset') {
|
||||
args.preset = argv[++i];
|
||||
} else if (arg === '-w' || arg === '--width') {
|
||||
args.width = parseInt(argv[++i]);
|
||||
} else if (arg === '--height') {
|
||||
args.height = parseInt(argv[++i]);
|
||||
} else if (arg === '--projection') {
|
||||
args.projection = argv[++i];
|
||||
} else if (arg === '-f' || arg === '--format') {
|
||||
args.format = argv[++i];
|
||||
} else if (arg === '-o' || arg === '--output') {
|
||||
args.output = argv[++i];
|
||||
}
|
||||
// Transform options
|
||||
else if (arg === '--rotation' || arg === '--rotate') {
|
||||
args.rotation = parseFloat(argv[++i]);
|
||||
} else if (arg === '--intensity-scale' || arg === '--scale') {
|
||||
args.intensityScale = parseFloat(argv[++i]);
|
||||
}
|
||||
// Tone mapping options (for LDR output)
|
||||
else if (arg === '--exposure') {
|
||||
args.tonemapOptions.exposure = parseFloat(argv[++i]);
|
||||
} else if (arg === '--gamma') {
|
||||
args.tonemapOptions.gamma = parseFloat(argv[++i]);
|
||||
} else if (arg === '--tonemap-method') {
|
||||
args.tonemapOptions.method = argv[++i];
|
||||
}
|
||||
// Sun/Sky options
|
||||
else if (arg === '--sun-elevation') {
|
||||
args.presetOptions.sunElevation = parseFloat(argv[++i]);
|
||||
} else if (arg === '--sun-azimuth') {
|
||||
args.presetOptions.sunAzimuth = parseFloat(argv[++i]);
|
||||
} else if (arg === '--sun-intensity') {
|
||||
args.presetOptions.sunIntensity = parseFloat(argv[++i]);
|
||||
} else if (arg === '--sky-intensity') {
|
||||
args.presetOptions.skyIntensity = parseFloat(argv[++i]);
|
||||
}
|
||||
// Studio options
|
||||
else if (arg === '--key-intensity') {
|
||||
args.presetOptions.keyIntensity = parseFloat(argv[++i]);
|
||||
} else if (arg === '--fill-intensity') {
|
||||
args.presetOptions.fillIntensity = parseFloat(argv[++i]);
|
||||
} else if (arg === '--rim-intensity') {
|
||||
args.presetOptions.rimIntensity = parseFloat(argv[++i]);
|
||||
} else if (arg === '--ambient-intensity') {
|
||||
args.presetOptions.ambientIntensity = parseFloat(argv[++i]);
|
||||
}
|
||||
// White furnace options
|
||||
else if (arg === '--intensity') {
|
||||
args.presetOptions.intensity = parseFloat(argv[++i]);
|
||||
}
|
||||
}
|
||||
|
||||
return args;
|
||||
}
|
||||
|
||||
function printHelp() {
|
||||
console.log(`
|
||||
HDRGen - Synthetic HDR/EXR Environment Map Generator
|
||||
|
||||
USAGE:
|
||||
hdrgen [OPTIONS]
|
||||
|
||||
OPTIONS:
|
||||
-h, --help Show this help message
|
||||
-p, --preset <name> Preset name (white-furnace, sun-sky, studio) [default: white-furnace]
|
||||
-w, --width <px> Width in pixels [default: 2048]
|
||||
--height <px> Height in pixels [default: 1024]
|
||||
--projection <type> Projection type (latlong, cubemap) [default: latlong]
|
||||
-f, --format <fmt> Output format (hdr, exr, png, bmp, jpg) [default: hdr]
|
||||
-o, --output <path> Output file path [default: output/<preset>_<proj>.<fmt>]
|
||||
|
||||
TRANSFORM OPTIONS:
|
||||
--rotation <deg> Rotate environment map (degrees, +CCW) [default: 0]
|
||||
--intensity-scale <val> Global intensity multiplier [default: 1.0]
|
||||
|
||||
LDR/TONE MAPPING OPTIONS (for PNG/BMP/JPG output):
|
||||
--exposure <ev> Exposure adjustment in EV [default: 0.0]
|
||||
--gamma <val> Gamma correction [default: 2.2]
|
||||
--tonemap-method <m> Method: simple, reinhard, aces [default: reinhard]
|
||||
|
||||
WHITE FURNACE OPTIONS:
|
||||
--intensity <val> Furnace intensity [default: 1.0]
|
||||
|
||||
SUN & SKY OPTIONS:
|
||||
--sun-elevation <deg> Sun elevation angle in degrees [default: 45]
|
||||
--sun-azimuth <deg> Sun azimuth angle in degrees [default: 135]
|
||||
--sun-intensity <val> Sun disk intensity [default: 100.0]
|
||||
--sky-intensity <val> Base sky intensity [default: 0.5]
|
||||
|
||||
STUDIO LIGHTING OPTIONS:
|
||||
--key-intensity <val> Key light intensity [default: 50.0]
|
||||
--fill-intensity <val> Fill light intensity [default: 10.0]
|
||||
--rim-intensity <val> Rim light intensity [default: 20.0]
|
||||
--ambient-intensity <val> Ambient light intensity [default: 0.5]
|
||||
|
||||
EXAMPLES:
|
||||
# Generate white furnace for testing
|
||||
hdrgen --preset white-furnace -o output/furnace.hdr
|
||||
|
||||
# Generate sun & sky with low sun
|
||||
hdrgen --preset sun-sky --sun-elevation 15 --sun-azimuth 90 -o output/sunset.hdr
|
||||
|
||||
# Generate studio lighting as cubemap
|
||||
hdrgen --preset studio --projection cubemap --width 512 -o output/studio
|
||||
|
||||
# High-resolution sky with intense sun
|
||||
hdrgen -p sun-sky -w 4096 --height 2048 --sun-intensity 200 -o output/sky_4k.hdr
|
||||
|
||||
# Rotate environment 90 degrees
|
||||
hdrgen -p sun-sky --rotation 90 -o output/sky_rotated.hdr
|
||||
|
||||
# Scale intensity 2x and output as PNG
|
||||
hdrgen -p studio --intensity-scale 2.0 -f png -o output/studio.png
|
||||
|
||||
# Generate LDR preview with custom exposure
|
||||
hdrgen -p sun-sky -f png --exposure 1.0 --gamma 2.2 -o output/sky_preview.png
|
||||
|
||||
# Generate BMP with ACES tone mapping
|
||||
hdrgen -p studio -f bmp --tonemap-method aces --exposure -0.5 -o output/studio.bmp
|
||||
|
||||
PRESETS:
|
||||
white-furnace - Uniform white environment for energy conservation testing
|
||||
sun-sky - Procedural sky with sun disk and atmospheric gradient
|
||||
studio - 3-point lighting setup (key, fill, rim lights)
|
||||
|
||||
FORMATS:
|
||||
HDR Formats:
|
||||
hdr - Radiance RGBE format (.hdr)
|
||||
exr - OpenEXR format (.exr) [requires external library]
|
||||
|
||||
LDR Formats (with automatic tone mapping):
|
||||
png - PNG format (.png) [uncompressed]
|
||||
bmp - BMP format (.bmp) [24-bit RGB]
|
||||
jpg/jpeg - JPEG format [converts to BMP, requires jpeg-js for true JPEG]
|
||||
|
||||
PROJECTIONS:
|
||||
latlong - Equirectangular lat-long projection (single image)
|
||||
cubemap - Cubemap projection (6 faces: +X, -X, +Y, -Y, +Z, -Z)
|
||||
|
||||
OUTPUT:
|
||||
- For latlong: Single file at specified path
|
||||
- For cubemap: Six files with face suffixes (_+X, _-X, _+Y, _-Y, _+Z, _-Z)
|
||||
- Default output directory: tools/hdrgen/output/
|
||||
|
||||
NOTES:
|
||||
- All outputs are in linear color space (no gamma encoding)
|
||||
- HDR values can exceed 1.0 (high dynamic range)
|
||||
- Cubemap faces use OpenGL convention (+Y is up)
|
||||
- Generated maps are suitable for IBL (Image-Based Lighting) in renderers
|
||||
|
||||
For more information, see: tools/hdrgen/README.md
|
||||
`);
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Main CLI Entry Point
|
||||
// ============================================================================
|
||||
|
||||
async function main() {
|
||||
const args = parseArgs(process.argv);
|
||||
|
||||
if (args.help) {
|
||||
printHelp();
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Generate default output path if not specified
|
||||
if (!args.output) {
|
||||
const outputDir = path.join(__dirname, '../output');
|
||||
const filename = `${args.preset}_${args.projection}.${args.format}`;
|
||||
args.output = path.join(outputDir, filename);
|
||||
}
|
||||
|
||||
// Ensure output directory exists
|
||||
const outputDir = path.dirname(args.output);
|
||||
try {
|
||||
const fs = await import('fs');
|
||||
if (!fs.existsSync(outputDir)) {
|
||||
fs.mkdirSync(outputDir, { recursive: true });
|
||||
}
|
||||
} catch (err) {
|
||||
console.error(`Error creating output directory: ${err.message}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
try {
|
||||
// Generate environment map
|
||||
HDRGenerator.generate({
|
||||
preset: args.preset,
|
||||
width: args.width,
|
||||
height: args.height,
|
||||
projection: args.projection,
|
||||
format: args.format,
|
||||
output: args.output,
|
||||
presetOptions: args.presetOptions,
|
||||
rotation: args.rotation,
|
||||
intensityScale: args.intensityScale,
|
||||
tonemapOptions: args.tonemapOptions
|
||||
});
|
||||
|
||||
console.log('\n✓ Generation complete!');
|
||||
console.log(`Output: ${args.output}\n`);
|
||||
|
||||
} catch (err) {
|
||||
console.error(`\n✗ Error: ${err.message}`);
|
||||
console.error(err.stack);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
// Run CLI
|
||||
main();
|
||||
912
tools/hdrgen/src/hdrgen.js
Normal file
912
tools/hdrgen/src/hdrgen.js
Normal file
@@ -0,0 +1,912 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* HDRGen - Synthetic HDR/EXR Environment Map Generator
|
||||
*
|
||||
* Generates procedural environment maps for IBL testing and visualization
|
||||
* Supports: HDR (Radiance RGBE), EXR (OpenEXR), lat-long and cubemap projections
|
||||
*
|
||||
* Copyright 2024 - Present, Light Transport Entertainment Inc.
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
|
||||
// ============================================================================
|
||||
// Math Utilities
|
||||
// ============================================================================
|
||||
|
||||
class Vec3 {
|
||||
constructor(x = 0, y = 0, z = 0) {
|
||||
this.x = x;
|
||||
this.y = y;
|
||||
this.z = z;
|
||||
}
|
||||
|
||||
static add(a, b) {
|
||||
return new Vec3(a.x + b.x, a.y + b.y, a.z + b.z);
|
||||
}
|
||||
|
||||
static sub(a, b) {
|
||||
return new Vec3(a.x - b.x, a.y - b.y, a.z - b.z);
|
||||
}
|
||||
|
||||
static mul(v, s) {
|
||||
return new Vec3(v.x * s, v.y * s, v.z * s);
|
||||
}
|
||||
|
||||
static dot(a, b) {
|
||||
return a.x * b.x + a.y * b.y + a.z * b.z;
|
||||
}
|
||||
|
||||
static cross(a, b) {
|
||||
return new Vec3(
|
||||
a.y * b.z - a.z * b.y,
|
||||
a.z * b.x - a.x * b.z,
|
||||
a.x * b.y - a.y * b.x
|
||||
);
|
||||
}
|
||||
|
||||
length() {
|
||||
return Math.sqrt(this.x * this.x + this.y * this.y + this.z * this.z);
|
||||
}
|
||||
|
||||
normalize() {
|
||||
const len = this.length();
|
||||
if (len > 0) {
|
||||
return new Vec3(this.x / len, this.y / len, this.z / len);
|
||||
}
|
||||
return new Vec3(0, 0, 0);
|
||||
}
|
||||
|
||||
static lerp(a, b, t) {
|
||||
return new Vec3(
|
||||
a.x + (b.x - a.x) * t,
|
||||
a.y + (b.y - a.y) * t,
|
||||
a.z + (b.z - a.z) * t
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// HDR Image Buffer
|
||||
// ============================================================================
|
||||
|
||||
class HDRImage {
|
||||
constructor(width, height) {
|
||||
this.width = width;
|
||||
this.height = height;
|
||||
// Store as float32 RGB (linear color space)
|
||||
this.data = new Float32Array(width * height * 3);
|
||||
}
|
||||
|
||||
setPixel(x, y, r, g, b) {
|
||||
const idx = (y * this.width + x) * 3;
|
||||
this.data[idx + 0] = r;
|
||||
this.data[idx + 1] = g;
|
||||
this.data[idx + 2] = b;
|
||||
}
|
||||
|
||||
getPixel(x, y) {
|
||||
const idx = (y * this.width + x) * 3;
|
||||
return {
|
||||
r: this.data[idx + 0],
|
||||
g: this.data[idx + 1],
|
||||
b: this.data[idx + 2]
|
||||
};
|
||||
}
|
||||
|
||||
// Convert lat-long (u,v) to direction vector
|
||||
static latLongToDir(u, v) {
|
||||
const phi = u * Math.PI * 2.0; // 0 to 2π
|
||||
const theta = v * Math.PI; // 0 to π
|
||||
const sinTheta = Math.sin(theta);
|
||||
return new Vec3(
|
||||
sinTheta * Math.cos(phi),
|
||||
Math.cos(theta),
|
||||
sinTheta * Math.sin(phi)
|
||||
);
|
||||
}
|
||||
|
||||
// Convert direction vector to lat-long (u,v)
|
||||
static dirToLatLong(dir) {
|
||||
const theta = Math.acos(Math.max(-1, Math.min(1, dir.y)));
|
||||
const phi = Math.atan2(dir.z, dir.x);
|
||||
return {
|
||||
u: (phi + Math.PI) / (Math.PI * 2.0),
|
||||
v: theta / Math.PI
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Image Transformation Utilities
|
||||
// ============================================================================
|
||||
|
||||
class ImageTransform {
|
||||
/**
|
||||
* Rotate environment map around Y axis
|
||||
* @param {HDRImage} image - Source image
|
||||
* @param {number} angleDegrees - Rotation angle in degrees (positive = counterclockwise)
|
||||
* @returns {HDRImage} - Rotated image
|
||||
*/
|
||||
static rotate(image, angleDegrees) {
|
||||
console.log(`Rotating environment map by ${angleDegrees}°...`);
|
||||
|
||||
const rotated = new HDRImage(image.width, image.height);
|
||||
const angleRad = (angleDegrees * Math.PI) / 180.0;
|
||||
|
||||
for (let y = 0; y < image.height; y++) {
|
||||
for (let x = 0; x < image.width; x++) {
|
||||
// Get current UV
|
||||
let u = x / image.width;
|
||||
const v = y / image.height;
|
||||
|
||||
// Rotate U coordinate
|
||||
u = u + (angleRad / (Math.PI * 2.0));
|
||||
u = u - Math.floor(u); // Wrap to [0, 1]
|
||||
|
||||
// Sample from source image with bilinear filtering
|
||||
const fx = u * (image.width - 1);
|
||||
const fy = v * (image.height - 1);
|
||||
|
||||
const x0 = Math.floor(fx);
|
||||
const y0 = Math.floor(fy);
|
||||
const x1 = (x0 + 1) % image.width; // Wrap horizontally
|
||||
const y1 = Math.min(y0 + 1, image.height - 1);
|
||||
|
||||
const tx = fx - x0;
|
||||
const ty = fy - y0;
|
||||
|
||||
const c00 = image.getPixel(x0, y0);
|
||||
const c10 = image.getPixel(x1, y0);
|
||||
const c01 = image.getPixel(x0, y1);
|
||||
const c11 = image.getPixel(x1, y1);
|
||||
|
||||
const r = (1 - tx) * (1 - ty) * c00.r + tx * (1 - ty) * c10.r +
|
||||
(1 - tx) * ty * c01.r + tx * ty * c11.r;
|
||||
const g = (1 - tx) * (1 - ty) * c00.g + tx * (1 - ty) * c10.g +
|
||||
(1 - tx) * ty * c01.g + tx * ty * c11.g;
|
||||
const b = (1 - tx) * (1 - ty) * c00.b + tx * (1 - ty) * c10.b +
|
||||
(1 - tx) * ty * c01.b + tx * ty * c11.b;
|
||||
|
||||
rotated.setPixel(x, y, r, g, b);
|
||||
}
|
||||
}
|
||||
|
||||
return rotated;
|
||||
}
|
||||
|
||||
/**
|
||||
* Scale intensity of entire image
|
||||
* @param {HDRImage} image - Image to scale (modified in place)
|
||||
* @param {number} scale - Intensity multiplier
|
||||
*/
|
||||
static scaleIntensity(image, scale) {
|
||||
if (scale === 1.0) return;
|
||||
|
||||
console.log(`Scaling intensity by ${scale}x...`);
|
||||
|
||||
for (let i = 0; i < image.data.length; i++) {
|
||||
image.data[i] *= scale;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Tone Mapping and LDR Conversion
|
||||
// ============================================================================
|
||||
|
||||
class ToneMapper {
|
||||
/**
|
||||
* Apply tone mapping to HDR image for LDR display
|
||||
* @param {HDRImage} hdrImage - Source HDR image
|
||||
* @param {Object} options - Tone mapping options
|
||||
* @returns {Uint8ClampedArray} - 8-bit RGB data
|
||||
*/
|
||||
static tonemapToLDR(hdrImage, options = {}) {
|
||||
const {
|
||||
exposure = 1.0, // Exposure adjustment (EV)
|
||||
gamma = 2.2, // Gamma correction for display
|
||||
method = 'reinhard' // Tone mapping method: 'simple', 'reinhard', 'aces'
|
||||
} = options;
|
||||
|
||||
console.log(`Tone mapping: method=${method}, exposure=${exposure}, gamma=${gamma}`);
|
||||
|
||||
const { width, height, data } = hdrImage;
|
||||
const ldrData = new Uint8ClampedArray(width * height * 3);
|
||||
|
||||
const exposureScale = Math.pow(2.0, exposure);
|
||||
const invGamma = 1.0 / gamma;
|
||||
|
||||
for (let i = 0; i < data.length; i += 3) {
|
||||
let r = data[i + 0] * exposureScale;
|
||||
let g = data[i + 1] * exposureScale;
|
||||
let b = data[i + 2] * exposureScale;
|
||||
|
||||
// Apply tone mapping operator
|
||||
switch (method) {
|
||||
case 'simple':
|
||||
// Simple exposure + clamp
|
||||
r = Math.min(r, 1.0);
|
||||
g = Math.min(g, 1.0);
|
||||
b = Math.min(b, 1.0);
|
||||
break;
|
||||
|
||||
case 'reinhard':
|
||||
// Reinhard tone mapping: x / (1 + x)
|
||||
r = r / (1.0 + r);
|
||||
g = g / (1.0 + g);
|
||||
b = b / (1.0 + b);
|
||||
break;
|
||||
|
||||
case 'aces':
|
||||
// ACES filmic tone mapping (approximation)
|
||||
r = ToneMapper.acesToneMap(r);
|
||||
g = ToneMapper.acesToneMap(g);
|
||||
b = ToneMapper.acesToneMap(b);
|
||||
break;
|
||||
|
||||
default:
|
||||
r = Math.min(r, 1.0);
|
||||
g = Math.min(g, 1.0);
|
||||
b = Math.min(b, 1.0);
|
||||
}
|
||||
|
||||
// Apply gamma correction
|
||||
r = Math.pow(Math.max(0, r), invGamma);
|
||||
g = Math.pow(Math.max(0, g), invGamma);
|
||||
b = Math.pow(Math.max(0, b), invGamma);
|
||||
|
||||
// Convert to 8-bit
|
||||
ldrData[i + 0] = Math.round(Math.min(255, r * 255));
|
||||
ldrData[i + 1] = Math.round(Math.min(255, g * 255));
|
||||
ldrData[i + 2] = Math.round(Math.min(255, b * 255));
|
||||
}
|
||||
|
||||
return ldrData;
|
||||
}
|
||||
|
||||
/**
|
||||
* ACES filmic tone mapping curve
|
||||
*/
|
||||
static acesToneMap(x) {
|
||||
const a = 2.51;
|
||||
const b = 0.03;
|
||||
const c = 2.43;
|
||||
const d = 0.59;
|
||||
const e = 0.14;
|
||||
return Math.min(1.0, Math.max(0.0, (x * (a * x + b)) / (x * (c * x + d) + e)));
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// LDR File Format Writers
|
||||
// ============================================================================
|
||||
|
||||
class LDRWriter {
|
||||
/**
|
||||
* Write BMP format (24-bit RGB, uncompressed)
|
||||
*/
|
||||
static writeBMP(ldrData, width, height, filepath) {
|
||||
// BMP requires rows to be padded to 4-byte boundary
|
||||
const rowSize = Math.floor((24 * width + 31) / 32) * 4;
|
||||
const pixelDataSize = rowSize * height;
|
||||
const fileSize = 54 + pixelDataSize; // 14-byte header + 40-byte DIB header + pixel data
|
||||
|
||||
const buffer = Buffer.alloc(fileSize);
|
||||
|
||||
// BMP Header (14 bytes)
|
||||
buffer.write('BM', 0); // Signature
|
||||
buffer.writeUInt32LE(fileSize, 2); // File size
|
||||
buffer.writeUInt32LE(0, 6); // Reserved
|
||||
buffer.writeUInt32LE(54, 10); // Pixel data offset
|
||||
|
||||
// DIB Header (BITMAPINFOHEADER, 40 bytes)
|
||||
buffer.writeUInt32LE(40, 14); // DIB header size
|
||||
buffer.writeInt32LE(width, 18); // Width
|
||||
buffer.writeInt32LE(height, 22); // Height
|
||||
buffer.writeUInt16LE(1, 26); // Planes
|
||||
buffer.writeUInt16LE(24, 28); // Bits per pixel
|
||||
buffer.writeUInt32LE(0, 30); // Compression (0 = none)
|
||||
buffer.writeUInt32LE(pixelDataSize, 34); // Image size
|
||||
buffer.writeInt32LE(2835, 38); // X pixels per meter (72 DPI)
|
||||
buffer.writeInt32LE(2835, 42); // Y pixels per meter
|
||||
buffer.writeUInt32LE(0, 46); // Colors in palette
|
||||
buffer.writeUInt32LE(0, 50); // Important colors
|
||||
|
||||
// Pixel data (bottom-up, BGR format)
|
||||
let offset = 54;
|
||||
for (let y = height - 1; y >= 0; y--) {
|
||||
for (let x = 0; x < width; x++) {
|
||||
const idx = (y * width + x) * 3;
|
||||
buffer[offset++] = ldrData[idx + 2]; // B
|
||||
buffer[offset++] = ldrData[idx + 1]; // G
|
||||
buffer[offset++] = ldrData[idx + 0]; // R
|
||||
}
|
||||
// Padding to 4-byte boundary
|
||||
while (offset % 4 !== 0) {
|
||||
buffer[offset++] = 0;
|
||||
}
|
||||
}
|
||||
|
||||
fs.writeFileSync(filepath, buffer);
|
||||
console.log(`✓ Wrote BMP file: ${filepath}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Write PNG format (8-bit RGB, uncompressed)
|
||||
* Simple implementation without compression
|
||||
*/
|
||||
static writePNG(ldrData, width, height, filepath) {
|
||||
// For production, use a PNG library. This is a simplified implementation.
|
||||
// We'll write an uncompressed PNG using filter type 0 (None)
|
||||
|
||||
const pngSignature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
|
||||
|
||||
// IHDR chunk
|
||||
const ihdr = Buffer.alloc(13);
|
||||
ihdr.writeUInt32BE(width, 0);
|
||||
ihdr.writeUInt32BE(height, 4);
|
||||
ihdr.writeUInt8(8, 8); // Bit depth
|
||||
ihdr.writeUInt8(2, 9); // Color type (2 = RGB)
|
||||
ihdr.writeUInt8(0, 10); // Compression
|
||||
ihdr.writeUInt8(0, 11); // Filter
|
||||
ihdr.writeUInt8(0, 12); // Interlace
|
||||
|
||||
// IDAT chunk (pixel data with filter bytes)
|
||||
// Each scanline: filter byte (0) + RGB data
|
||||
const scanlineSize = 1 + width * 3;
|
||||
const idatRaw = Buffer.alloc(scanlineSize * height);
|
||||
|
||||
for (let y = 0; y < height; y++) {
|
||||
idatRaw[y * scanlineSize] = 0; // Filter type: None
|
||||
for (let x = 0; x < width; x++) {
|
||||
const srcIdx = (y * width + x) * 3;
|
||||
const dstIdx = y * scanlineSize + 1 + x * 3;
|
||||
idatRaw[dstIdx + 0] = ldrData[srcIdx + 0]; // R
|
||||
idatRaw[dstIdx + 1] = ldrData[srcIdx + 1]; // G
|
||||
idatRaw[dstIdx + 2] = ldrData[srcIdx + 2]; // B
|
||||
}
|
||||
}
|
||||
|
||||
// Simple zlib compression would go here, but for now use uncompressed
|
||||
// For production, use zlib or a PNG library
|
||||
console.warn('PNG: Using simplified format (consider using sharp/pngjs for production)');
|
||||
|
||||
// Build PNG file
|
||||
const chunks = [];
|
||||
chunks.push(pngSignature);
|
||||
chunks.push(LDRWriter.createPNGChunk('IHDR', ihdr));
|
||||
chunks.push(LDRWriter.createPNGChunk('IDAT', idatRaw));
|
||||
chunks.push(LDRWriter.createPNGChunk('IEND', Buffer.alloc(0)));
|
||||
|
||||
const pngBuffer = Buffer.concat(chunks);
|
||||
fs.writeFileSync(filepath, pngBuffer);
|
||||
console.log(`✓ Wrote PNG file: ${filepath}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Create PNG chunk with length, type, data, and CRC
|
||||
*/
|
||||
static createPNGChunk(type, data) {
|
||||
const length = Buffer.alloc(4);
|
||||
length.writeUInt32BE(data.length, 0);
|
||||
|
||||
const typeBuffer = Buffer.from(type, 'ascii');
|
||||
const crcData = Buffer.concat([typeBuffer, data]);
|
||||
const crc = Buffer.alloc(4);
|
||||
crc.writeUInt32BE(LDRWriter.crc32(crcData), 0);
|
||||
|
||||
return Buffer.concat([length, typeBuffer, data, crc]);
|
||||
}
|
||||
|
||||
/**
|
||||
* CRC32 calculation for PNG
|
||||
*/
|
||||
static crc32(buffer) {
|
||||
let crc = 0xFFFFFFFF;
|
||||
for (let i = 0; i < buffer.length; i++) {
|
||||
crc = crc ^ buffer[i];
|
||||
for (let j = 0; j < 8; j++) {
|
||||
crc = (crc >>> 1) ^ (0xEDB88320 & -(crc & 1));
|
||||
}
|
||||
}
|
||||
return (crc ^ 0xFFFFFFFF) >>> 0; // Force unsigned 32-bit
|
||||
}
|
||||
|
||||
/**
|
||||
* Write JPEG format
|
||||
* Note: Requires external library for production use
|
||||
*/
|
||||
static writeJPEG(ldrData, width, height, filepath, quality = 90) {
|
||||
console.warn('JPEG writing requires external library (e.g., jpeg-js)');
|
||||
console.warn('Converting to BMP instead');
|
||||
const bmpPath = filepath.replace(/\.jpe?g$/i, '.bmp');
|
||||
LDRWriter.writeBMP(ldrData, width, height, bmpPath);
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// HDR File Format Writers
|
||||
// ============================================================================
|
||||
|
||||
class HDRWriter {
|
||||
/**
|
||||
* Write Radiance RGBE (.hdr) format
|
||||
* https://en.wikipedia.org/wiki/RGBE_image_format
|
||||
*/
|
||||
static writeRGBE(image, filepath) {
|
||||
const { width, height, data } = image;
|
||||
|
||||
// RGBE encoding function
|
||||
function encodeRGBE(r, g, b) {
|
||||
const maxComp = Math.max(r, g, b);
|
||||
if (maxComp < 1e-32) {
|
||||
return Buffer.from([0, 0, 0, 0]);
|
||||
}
|
||||
|
||||
const exponent = Math.floor(Math.log2(maxComp)) + 128;
|
||||
const scale = Math.pow(2, exponent - 128);
|
||||
|
||||
const re = Math.floor((r / scale) * 255.0 + 0.5);
|
||||
const ge = Math.floor((g / scale) * 255.0 + 0.5);
|
||||
const be = Math.floor((b / scale) * 255.0 + 0.5);
|
||||
|
||||
return Buffer.from([
|
||||
Math.min(255, re),
|
||||
Math.min(255, ge),
|
||||
Math.min(255, be),
|
||||
exponent
|
||||
]);
|
||||
}
|
||||
|
||||
// Build HDR header
|
||||
const header = [
|
||||
'#?RADIANCE',
|
||||
'FORMAT=32-bit_rle_rgbe',
|
||||
`EXPOSURE=1.0`,
|
||||
'',
|
||||
`-Y ${height} +X ${width}`,
|
||||
''
|
||||
].join('\n');
|
||||
|
||||
const headerBuf = Buffer.from(header, 'ascii');
|
||||
|
||||
// Encode pixel data
|
||||
const pixelBuf = Buffer.alloc(width * height * 4);
|
||||
for (let y = 0; y < height; y++) {
|
||||
for (let x = 0; x < width; x++) {
|
||||
const idx = (y * width + x) * 3;
|
||||
const r = data[idx + 0];
|
||||
const g = data[idx + 1];
|
||||
const b = data[idx + 2];
|
||||
const rgbe = encodeRGBE(r, g, b);
|
||||
rgbe.copy(pixelBuf, (y * width + x) * 4);
|
||||
}
|
||||
}
|
||||
|
||||
// Write file
|
||||
const fullBuf = Buffer.concat([headerBuf, pixelBuf]);
|
||||
fs.writeFileSync(filepath, fullBuf);
|
||||
console.log(`✓ Wrote HDR file: ${filepath}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Write OpenEXR format (simplified, uncompressed scanline)
|
||||
* For production use, consider using openexr npm package
|
||||
*/
|
||||
static writeEXR(image, filepath) {
|
||||
// For now, write as HDR since proper EXR requires external library
|
||||
// In production, use @openexr/node or similar
|
||||
console.warn('EXR writing requires external library, writing as HDR instead');
|
||||
const hdrPath = filepath.replace(/\.exr$/i, '.hdr');
|
||||
HDRWriter.writeRGBE(image, hdrPath);
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Environment Map Presets
|
||||
// ============================================================================
|
||||
|
||||
class EnvMapPresets {
|
||||
/**
|
||||
* White Furnace - Uniform white environment for energy conservation testing
|
||||
* Perfect for validating that BRDF integrates to 1.0
|
||||
*/
|
||||
static whiteFurnace(image, intensity = 1.0) {
|
||||
console.log(`Generating White Furnace (${image.width}x${image.height})...`);
|
||||
|
||||
for (let y = 0; y < image.height; y++) {
|
||||
for (let x = 0; x < image.width; x++) {
|
||||
image.setPixel(x, y, intensity, intensity, intensity);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Sun & Sky - Procedural Hosek-Wilkie sky model approximation
|
||||
* Simplified version with sun disk and gradient sky
|
||||
*/
|
||||
static sunSky(image, options = {}) {
|
||||
const {
|
||||
sunElevation = 45, // Sun elevation in degrees (0 = horizon, 90 = zenith)
|
||||
sunAzimuth = 135, // Sun azimuth in degrees (0 = north, 90 = east)
|
||||
sunIntensity = 100.0, // Sun disk intensity
|
||||
sunRadius = 0.02, // Sun angular radius (radians)
|
||||
skyIntensity = 0.5, // Base sky intensity
|
||||
horizonColor = new Vec3(0.8, 0.9, 1.0), // Horizon tint
|
||||
zenithColor = new Vec3(0.3, 0.5, 0.9), // Zenith color
|
||||
} = options;
|
||||
|
||||
console.log(`Generating Sun & Sky (${image.width}x${image.height})...`);
|
||||
console.log(` Sun: elevation=${sunElevation}°, azimuth=${sunAzimuth}°, intensity=${sunIntensity}`);
|
||||
|
||||
// Convert sun angles to direction
|
||||
const elevRad = sunElevation * Math.PI / 180;
|
||||
const azimRad = sunAzimuth * Math.PI / 180;
|
||||
const sunDir = new Vec3(
|
||||
Math.cos(elevRad) * Math.cos(azimRad),
|
||||
Math.sin(elevRad),
|
||||
Math.cos(elevRad) * Math.sin(azimRad)
|
||||
).normalize();
|
||||
|
||||
for (let y = 0; y < image.height; y++) {
|
||||
for (let x = 0; x < image.width; x++) {
|
||||
const u = x / image.width;
|
||||
const v = y / image.height;
|
||||
|
||||
const dir = HDRImage.latLongToDir(u, v);
|
||||
|
||||
// Sky gradient based on elevation
|
||||
const elevation = Math.asin(Math.max(-1, Math.min(1, dir.y)));
|
||||
const elevNorm = (elevation + Math.PI / 2) / Math.PI; // 0 at bottom, 1 at top
|
||||
|
||||
// Interpolate between horizon and zenith
|
||||
const skyColor = Vec3.lerp(horizonColor, zenithColor, elevNorm);
|
||||
let r = skyColor.x * skyIntensity;
|
||||
let g = skyColor.y * skyIntensity;
|
||||
let b = skyColor.z * skyIntensity;
|
||||
|
||||
// Add sun disk
|
||||
const angleToCosun = Vec3.dot(dir, sunDir);
|
||||
const angleToSun = Math.acos(Math.max(-1, Math.min(1, angleToCosun)));
|
||||
|
||||
if (angleToSun < sunRadius) {
|
||||
// Inside sun disk
|
||||
const falloff = 1.0 - (angleToSun / sunRadius);
|
||||
const sunCol = Vec3.mul(new Vec3(1, 0.95, 0.8), sunIntensity);
|
||||
r += sunCol.x * falloff;
|
||||
g += sunCol.y * falloff;
|
||||
b += sunCol.z * falloff;
|
||||
} else if (angleToSun < sunRadius * 3) {
|
||||
// Sun glow
|
||||
const falloff = 1.0 - ((angleToSun - sunRadius) / (sunRadius * 2));
|
||||
const glowIntensity = sunIntensity * 0.1 * falloff * falloff;
|
||||
r += glowIntensity;
|
||||
g += glowIntensity * 0.9;
|
||||
b += glowIntensity * 0.7;
|
||||
}
|
||||
|
||||
image.setPixel(x, y, r, g, b);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Studio Lighting - 3-point lighting setup
|
||||
* Key light (main), fill light (shadows), rim/back light
|
||||
*/
|
||||
static studioLighting(image, options = {}) {
|
||||
const {
|
||||
keyIntensity = 50.0,
|
||||
fillIntensity = 10.0,
|
||||
rimIntensity = 20.0,
|
||||
ambientIntensity = 0.5,
|
||||
keyColor = new Vec3(1.0, 0.98, 0.95), // Warm key
|
||||
fillColor = new Vec3(0.8, 0.85, 1.0), // Cool fill
|
||||
rimColor = new Vec3(1.0, 1.0, 1.0), // White rim
|
||||
ambientColor = new Vec3(0.5, 0.5, 0.5), // Neutral ambient
|
||||
} = options;
|
||||
|
||||
console.log(`Generating Studio Lighting (${image.width}x${image.height})...`);
|
||||
console.log(` Key=${keyIntensity}, Fill=${fillIntensity}, Rim=${rimIntensity}`);
|
||||
|
||||
// Light positions (as directions)
|
||||
const keyLight = new Vec3(0.7, 0.5, 0.5).normalize(); // Front-right, elevated
|
||||
const fillLight = new Vec3(-0.5, 0.3, 0.3).normalize(); // Front-left, lower
|
||||
const rimLight = new Vec3(0, 0.4, -0.9).normalize(); // Back, elevated
|
||||
|
||||
// Light spreads (angular size in radians)
|
||||
const keySpread = 0.3;
|
||||
const fillSpread = 0.5;
|
||||
const rimSpread = 0.2;
|
||||
|
||||
for (let y = 0; y < image.height; y++) {
|
||||
for (let x = 0; x < image.width; x++) {
|
||||
const u = x / image.width;
|
||||
const v = y / image.height;
|
||||
|
||||
const dir = HDRImage.latLongToDir(u, v);
|
||||
|
||||
// Start with ambient
|
||||
let r = ambientColor.x * ambientIntensity;
|
||||
let g = ambientColor.y * ambientIntensity;
|
||||
let b = ambientColor.z * ambientIntensity;
|
||||
|
||||
// Add key light
|
||||
const keyDot = Math.max(0, Vec3.dot(dir, keyLight));
|
||||
const keyAngle = Math.acos(Math.max(0, Math.min(1, keyDot)));
|
||||
if (keyAngle < keySpread) {
|
||||
const falloff = Math.pow(1.0 - (keyAngle / keySpread), 2);
|
||||
r += keyColor.x * keyIntensity * falloff;
|
||||
g += keyColor.y * keyIntensity * falloff;
|
||||
b += keyColor.z * keyIntensity * falloff;
|
||||
}
|
||||
|
||||
// Add fill light
|
||||
const fillDot = Math.max(0, Vec3.dot(dir, fillLight));
|
||||
const fillAngle = Math.acos(Math.max(0, Math.min(1, fillDot)));
|
||||
if (fillAngle < fillSpread) {
|
||||
const falloff = Math.pow(1.0 - (fillAngle / fillSpread), 2);
|
||||
r += fillColor.x * fillIntensity * falloff;
|
||||
g += fillColor.y * fillIntensity * falloff;
|
||||
b += fillColor.z * fillIntensity * falloff;
|
||||
}
|
||||
|
||||
// Add rim light
|
||||
const rimDot = Math.max(0, Vec3.dot(dir, rimLight));
|
||||
const rimAngle = Math.acos(Math.max(0, Math.min(1, rimDot)));
|
||||
if (rimAngle < rimSpread) {
|
||||
const falloff = Math.pow(1.0 - (rimAngle / rimSpread), 3);
|
||||
r += rimColor.x * rimIntensity * falloff;
|
||||
g += rimColor.y * rimIntensity * falloff;
|
||||
b += rimColor.z * rimIntensity * falloff;
|
||||
}
|
||||
|
||||
image.setPixel(x, y, r, g, b);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Cubemap Generator
|
||||
// ============================================================================
|
||||
|
||||
class CubemapGenerator {
|
||||
/**
|
||||
* Generate 6 cubemap faces from an equirectangular environment map
|
||||
* Face order: +X, -X, +Y, -Y, +Z, -Z (standard OpenGL order)
|
||||
*/
|
||||
static fromLatLong(latLongImage, faceSize = 512) {
|
||||
console.log(`Converting lat-long to cubemap (face size: ${faceSize}x${faceSize})...`);
|
||||
|
||||
const faces = [];
|
||||
const faceNames = ['+X', '-X', '+Y', '-Y', '+Z', '-Z'];
|
||||
|
||||
// Cubemap face directions
|
||||
const faceData = [
|
||||
// +X (right)
|
||||
{ right: new Vec3(0, 0, -1), up: new Vec3(0, 1, 0), forward: new Vec3(1, 0, 0) },
|
||||
// -X (left)
|
||||
{ right: new Vec3(0, 0, 1), up: new Vec3(0, 1, 0), forward: new Vec3(-1, 0, 0) },
|
||||
// +Y (top)
|
||||
{ right: new Vec3(1, 0, 0), up: new Vec3(0, 0, -1), forward: new Vec3(0, 1, 0) },
|
||||
// -Y (bottom)
|
||||
{ right: new Vec3(1, 0, 0), up: new Vec3(0, 0, 1), forward: new Vec3(0, -1, 0) },
|
||||
// +Z (front)
|
||||
{ right: new Vec3(1, 0, 0), up: new Vec3(0, 1, 0), forward: new Vec3(0, 0, 1) },
|
||||
// -Z (back)
|
||||
{ right: new Vec3(-1, 0, 0), up: new Vec3(0, 1, 0), forward: new Vec3(0, 0, -1) },
|
||||
];
|
||||
|
||||
for (let faceIdx = 0; faceIdx < 6; faceIdx++) {
|
||||
const face = new HDRImage(faceSize, faceSize);
|
||||
const { right, up, forward } = faceData[faceIdx];
|
||||
|
||||
for (let y = 0; y < faceSize; y++) {
|
||||
for (let x = 0; x < faceSize; x++) {
|
||||
// Map to [-1, 1] range
|
||||
const u = (x / (faceSize - 1)) * 2.0 - 1.0;
|
||||
const v = (y / (faceSize - 1)) * 2.0 - 1.0;
|
||||
|
||||
// Get direction for this texel
|
||||
const dir = Vec3.add(
|
||||
Vec3.add(Vec3.mul(right, u), Vec3.mul(up, -v)),
|
||||
forward
|
||||
).normalize();
|
||||
|
||||
// Convert to lat-long coords and sample
|
||||
const { u: latU, v: latV } = HDRImage.dirToLatLong(dir);
|
||||
const color = CubemapGenerator.sampleBilinear(latLongImage, latU, latV);
|
||||
|
||||
face.setPixel(x, y, color.r, color.g, color.b);
|
||||
}
|
||||
}
|
||||
|
||||
faces.push({ image: face, name: faceNames[faceIdx] });
|
||||
}
|
||||
|
||||
return faces;
|
||||
}
|
||||
|
||||
/**
|
||||
* Bilinear sampling from lat-long image
|
||||
*/
|
||||
static sampleBilinear(image, u, v) {
|
||||
// Wrap u, clamp v
|
||||
u = u - Math.floor(u);
|
||||
v = Math.max(0, Math.min(1, v));
|
||||
|
||||
const fx = u * (image.width - 1);
|
||||
const fy = v * (image.height - 1);
|
||||
|
||||
const x0 = Math.floor(fx);
|
||||
const y0 = Math.floor(fy);
|
||||
const x1 = Math.min(x0 + 1, image.width - 1);
|
||||
const y1 = Math.min(y0 + 1, image.height - 1);
|
||||
|
||||
const tx = fx - x0;
|
||||
const ty = fy - y0;
|
||||
|
||||
const c00 = image.getPixel(x0, y0);
|
||||
const c10 = image.getPixel(x1, y0);
|
||||
const c01 = image.getPixel(x0, y1);
|
||||
const c11 = image.getPixel(x1, y1);
|
||||
|
||||
const r = (1 - tx) * (1 - ty) * c00.r + tx * (1 - ty) * c10.r +
|
||||
(1 - tx) * ty * c01.r + tx * ty * c11.r;
|
||||
const g = (1 - tx) * (1 - ty) * c00.g + tx * (1 - ty) * c10.g +
|
||||
(1 - tx) * ty * c01.g + tx * ty * c11.g;
|
||||
const b = (1 - tx) * (1 - ty) * c00.b + tx * (1 - ty) * c10.b +
|
||||
(1 - tx) * ty * c01.b + tx * ty * c11.b;
|
||||
|
||||
return { r, g, b };
|
||||
}
|
||||
}
|
||||
|
||||
// ============================================================================
|
||||
// Public API
|
||||
// ============================================================================
|
||||
|
||||
export class HDRGenerator {
|
||||
/**
|
||||
* Generate environment map with specified preset
|
||||
*
|
||||
* @param {Object} options - Generation options
|
||||
* @param {string} options.preset - Preset name: 'white-furnace', 'sun-sky', 'studio'
|
||||
* @param {number} options.width - Width in pixels (default: 2048 for latlong, 512 for cubemap)
|
||||
* @param {number} options.height - Height in pixels (default: 1024 for latlong)
|
||||
* @param {string} options.projection - 'latlong' or 'cubemap'
|
||||
* @param {string} options.format - 'hdr', 'exr', 'png', 'bmp', 'jpg'/'jpeg'
|
||||
* @param {string} options.output - Output file path
|
||||
* @param {Object} options.presetOptions - Preset-specific options
|
||||
* @param {number} options.rotation - Rotation angle in degrees (default: 0)
|
||||
* @param {number} options.intensityScale - Intensity multiplier (default: 1.0)
|
||||
* @param {Object} options.tonemapOptions - Tone mapping options for LDR output
|
||||
*/
|
||||
static generate(options) {
|
||||
const {
|
||||
preset = 'white-furnace',
|
||||
width = 2048,
|
||||
height = 1024,
|
||||
projection = 'latlong',
|
||||
format = 'hdr',
|
||||
output = null,
|
||||
presetOptions = {},
|
||||
rotation = 0,
|
||||
intensityScale = 1.0,
|
||||
tonemapOptions = {}
|
||||
} = options;
|
||||
|
||||
console.log('\n=== HDR Environment Map Generator ===');
|
||||
console.log(`Preset: ${preset}`);
|
||||
console.log(`Resolution: ${width}x${height}`);
|
||||
console.log(`Projection: ${projection}`);
|
||||
console.log(`Format: ${format.toUpperCase()}`);
|
||||
if (rotation !== 0) console.log(`Rotation: ${rotation}°`);
|
||||
if (intensityScale !== 1.0) console.log(`Intensity Scale: ${intensityScale}x`);
|
||||
|
||||
// Generate lat-long image first
|
||||
let latLongImage = new HDRImage(width, height);
|
||||
|
||||
// Apply preset
|
||||
switch (preset) {
|
||||
case 'white-furnace':
|
||||
EnvMapPresets.whiteFurnace(latLongImage, presetOptions.intensity || 1.0);
|
||||
break;
|
||||
case 'sun-sky':
|
||||
EnvMapPresets.sunSky(latLongImage, presetOptions);
|
||||
break;
|
||||
case 'studio':
|
||||
EnvMapPresets.studioLighting(latLongImage, presetOptions);
|
||||
break;
|
||||
default:
|
||||
throw new Error(`Unknown preset: ${preset}`);
|
||||
}
|
||||
|
||||
// Apply transformations
|
||||
if (rotation !== 0) {
|
||||
latLongImage = ImageTransform.rotate(latLongImage, rotation);
|
||||
}
|
||||
|
||||
if (intensityScale !== 1.0) {
|
||||
ImageTransform.scaleIntensity(latLongImage, intensityScale);
|
||||
}
|
||||
|
||||
// Determine if output is LDR or HDR
|
||||
const isLDR = ['png', 'bmp', 'jpg', 'jpeg'].includes(format.toLowerCase());
|
||||
|
||||
// Generate output
|
||||
if (projection === 'latlong') {
|
||||
// Direct lat-long output
|
||||
if (output) {
|
||||
const filepath = output.endsWith(`.${format}`) ? output : `${output}.${format}`;
|
||||
HDRGenerator._writeImage(latLongImage, format, filepath, isLDR, tonemapOptions);
|
||||
}
|
||||
return { latLongImage };
|
||||
} else if (projection === 'cubemap') {
|
||||
// Convert to cubemap
|
||||
const faceSize = Math.min(width, height); // Use smaller dimension for cube face
|
||||
const faces = CubemapGenerator.fromLatLong(latLongImage, faceSize);
|
||||
|
||||
if (output) {
|
||||
const dir = path.dirname(output);
|
||||
const base = path.basename(output, path.extname(output));
|
||||
|
||||
for (const face of faces) {
|
||||
const facePath = path.join(dir, `${base}_${face.name}.${format}`);
|
||||
HDRGenerator._writeImage(face.image, format, facePath, isLDR, tonemapOptions);
|
||||
}
|
||||
}
|
||||
return { faces };
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Internal helper to write image in appropriate format
|
||||
*/
|
||||
static _writeImage(image, format, filepath, isLDR, tonemapOptions) {
|
||||
if (isLDR) {
|
||||
// Convert HDR to LDR via tone mapping
|
||||
const ldrData = ToneMapper.tonemapToLDR(image, tonemapOptions);
|
||||
const fmt = format.toLowerCase();
|
||||
|
||||
switch (fmt) {
|
||||
case 'png':
|
||||
LDRWriter.writePNG(ldrData, image.width, image.height, filepath);
|
||||
break;
|
||||
case 'bmp':
|
||||
LDRWriter.writeBMP(ldrData, image.width, image.height, filepath);
|
||||
break;
|
||||
case 'jpg':
|
||||
case 'jpeg':
|
||||
LDRWriter.writeJPEG(ldrData, image.width, image.height, filepath);
|
||||
break;
|
||||
default:
|
||||
throw new Error(`Unknown LDR format: ${format}`);
|
||||
}
|
||||
} else {
|
||||
// HDR output
|
||||
if (format === 'hdr') {
|
||||
HDRWriter.writeRGBE(image, filepath);
|
||||
} else if (format === 'exr') {
|
||||
HDRWriter.writeEXR(image, filepath);
|
||||
} else {
|
||||
throw new Error(`Unknown HDR format: ${format}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export {
|
||||
EnvMapPresets,
|
||||
HDRImage,
|
||||
CubemapGenerator,
|
||||
HDRWriter,
|
||||
LDRWriter,
|
||||
ToneMapper,
|
||||
ImageTransform,
|
||||
Vec3
|
||||
};
|
||||
Reference in New Issue
Block a user