mirror of https://github.com/lighttransport/tinyusdz.git synced 2026-01-18 01:11:17 +01:00

Files

Syoyo Fujita 274e6826e4 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>

2025-11-06 02:18:48 +09:00

3.6 KiB

Raw Blame History

HDRGen Quick Start Guide

Installation

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:

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:

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:

node src/cli.js --preset studio -o output/studio.hdr

Output: output/studio.hdr (2048x1024, ~8MB)

Common Options

# 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

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:

# 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:

Switch to Shading workspace
Select World shader
Add Environment Texture node
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

Troubleshooting

Files too dark/bright?

Adjust intensity parameters:

# 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?

node src/cli.js --help

Next Steps

Read full README.md for detailed documentation
Check 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).

3.6 KiB Raw Blame History