tinyusdz/doc/openpbr-parameters-reference.md

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:

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

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
• MaterialX Specification v1.38
• Three.js MeshPhysicalMaterial Documentation
• TinyUSDZ OpenPBR Implementation
• Three.js MaterialX Loader

---

Revision History

Date	Version	Changes
2025-11-06	1.0	Initial comprehensive parameter reference