OpenUSD usdLux DomeLight 全解析环境照明IBL穹顶灯的原理、属性与实战示例【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD本文以 OpenUSD 仓库中 DomeLight 官方 Schema 文档 为主线系统讲解 usdLux 体系中的 DomeLight穹顶灯它如何通过远距离环境贴图模拟天空或 HDR 图像带来的 Image Based LightingIBL其经纬度朝向约定、全部可用属性与取值、以及配套的 DomeLight_1poleAxis变体。读完本文你将能够直接在 USDA 场景中写出可运行的环境照明配置并理解其底层 Schema 定义与 C/Python API 的实现细节。DomeLight 渲染输出示例环境贴图照亮带基础材质球体的结果来自 usdLux 用户指南 目录下的图片资源。DomeLight 是什么DomeLight 是一种内置intrinsic光源它从极其遥远的外部环境向内发光——这个环境可以是天空也可以是一张用于 Image Based LightingIBL的高动态范围HDR图像。官方 Schema 文档将其概括为An intrinsic light that emits light inwards from a very distant external environment, such as a sky, or a light environment captured in a High Dynamic Range (HDR) image used for Image Based Lighting (IBL).一句话来说使用 DomeLight 即可模拟环境照明Use DomeLights to simulate environment lighting。在 OpenUSD 的 usdLux 模块中DomeLight 继承自NonboundableLightBase非有界光源基类其 Schema 声明位于 pxr/usd/usdLux/schema.usda生成的 C 类为UsdLuxDomeLight定义于 pxr/usd/usdLux/domeLight.h。与 RectLight、DiskLight、SphereLight 等有界光源不同DomeLight 不携带发光面积/几何体概念而是围绕场景包裹一个远距离环境从四面八方提供光照。版本说明usdLux 提供了两个 DomeLight 变体——本文主讲的DomeLight以及提供poleAxis朝向控制的DomeLight_1。两者除朝向控制方式外属性完全一致详见后文 DomeLight_1 与 poleAxis 朝向控制。默认朝向与 OpenEXR 经纬度贴图约定DomeLight 的默认朝向是顶部极点与世界 Y 轴对齐。这一约定严格遵守 OpenEXR 规范 对 latitude-longitude经纬度贴图的规定。官方文档引用了 OpenEXR 文档的原文这里完整保留以便理解纹理像素与 3D 空间的映射关系Latitude-Longitude Map环境图像使用极坐标纬度和经度投影。像素的 x 坐标对应经度y 坐标对应纬度。像素(dataWindow.min.x, dataWindow.min.y)的纬度为pi/2、经度为pi像素(dataWindow.max.x, dataWindow.max.y)的纬度为-pi/2、经度为-pi。在 3D 空间中纬度-pi/2与pi/2分别对应负 Y 与正 Y 方向。纬度 0、经度 0 指向正 Z 方向纬度 0、经度pi/2指向正 X 方向。data window 的尺寸应为 2*N 乘 N 像素宽 × 高其中 N 为任意大于 0 的整数。这段约定对贴图制作有直接指导意义图像宽高比必须是 2:1否则无法与球面投影严格对应图像顶部边缘纬度pi/2对应穹顶顶端Y底部边缘对应 -Y图像水平中线纬度 0对应的方位图像左/右边缘的经度为±pi图像水平中心经度为 0指向 Z。在 schema.usda 的doc注释中完整保留了同样的说明确保生成的所有语言绑定文档口径一致。最小可运行示例DomeLight 球体 材质官方文档给出了一个完整的 USDA 示例用一个带环境贴图纹理的 DomeLight 照亮一个应用了基础材质PxrSurface的球体。原样继承如下#usda 1.0 ( ) def Scope Lights { def DomeLight Dome { asset inputs:texture:file orientationLatLong.tex } } def Xform TestGeom { def Sphere Sphere1 ( prepend apiSchemas [MaterialBindingAPI] ) { rel material:binding /Material } } def Material Material { token outputs:ri:surface.connect /Material/Surface.outputs:out def Shader Surface { uniform token info:id PxrSurface float inputs:diffuseGain 0.3 color3f inputs:specularEdgeColor (1, 1, 1) color3f inputs:specularFaceColor (0.4, 0.4, 0.4) float inputs:specularRoughness 0.02 token outputs:out } }对示例的逐段拆解def DomeLight Dome在LightsScope 下定义穹顶灯 prim。其类型DomeLight即 usdLux 注册的 schema 类型名渲染器据此识别光源类型对应light:shaderId见下文。asset inputs:texture:file orientationLatLong.tex为穹顶指定环境贴图。...是 USD 中 asset 路径的书写语法orientationLatLong.tex是按 OpenEXR 经纬度布局生成的纹理建议 2:1 宽高比。rel material:binding /Material通过MaterialBindingAPI将球体的材质绑定到场景根部的Material。PxrSurface着色器这是 RenderMan 风格的材质节点。文档特意将diffuseGain调低为 0.3、设置非纯白的镜面反射参数是为了让环境贴图对球面的贡献清晰可见避免材质自身漫反射过强掩盖 IBL 效果。渲染提示该示例按 RenderMan 管线书写outputs:ri:surface前缀、PxrSurfaceshader id。若使用 Hydra 的 Storm 等其他渲染委托需要换成对应渲染器支持的材质节点与连接语法DomeLight 本身的属性定义是渲染器无关的。属性详解以下属性均定义在 schema.usda 的 DomeLight 类 中并通过生成代码暴露为UsdLuxDomeLight的 C API 与 Python APIUsdLux.DomeLight。guideRadiusUSD 类型floatFallback 值100000.0用于设置可视化穹顶灯的辅助几何体guide geometry半径单位为 USD 单位。默认值1.0e5在场景metersPerUnit为 USD 默认值0.01即 1 单位 1 cm时恰好等于1 公里。该属性属于 Guides 显示分组仅影响视口/编辑器中穹顶的可视化表现如 usdview 中半透明的穹顶示意球不参与光照计算。inputs:texture:fileUSD 类型assetFallback 值无必须由用户提供才有效果DomeLight 使用的颜色纹理通常是专为 IBL 准备的 HDR 图像。在生成的 C API 中对应GetTextureFileAttr()/CreateTextureFileAttr()见 domeLight.h显示分组为 Basic显示名 Color Map。属性名为inputs:前缀意味着它是一个可连接的着色器输入可由渲染器采样。inputs:texture:formatUSD 类型tokenFallback 值automaticAllowed tokens在 schema.usda 中由allowedTokens声明automatic、latlong、mirroredBall、angular、cubeMapVerticalCross描述颜色纹理的参数化投影方式渲染器据此正确采样贴图。五种取值的官方说明取值含义automatic渲染器尝试从文件本身推断布局。例如 RenderMan 纹理文件会内嵌显式的参数化信息latlong文件按纬度为 X、经度为 Y参数化即标准的经纬度等距柱状投影2:1 宽高比mirroredBall文件是环境在球面上的反射图像采用隐式正交投影镜像球式环境贴图angular类似mirroredBall但径向维度按角度线性映射在边缘处提供更好的采样质量cubeMapVerticalCross文件是立方体贴图面片按竖直十字形排列需要说明latlong项在文档正文写作 latitude as X, longitude as Y指的是纹理的 U/V 两个轴分别对应纬度/经度方向。配合上一节的 OpenEXR 约定理解纬度对应图像纵向V经度对应横向U。light:shaderIdUSD 类型tokenFallback 值DomeLightDomeLight 的着色器标识。当该属性被设置或使用默认值时USD 会注册一个标识符为DomeLight、source type 为USD的Sdr shader node使该光源的输入属性如inputs:texture:file可以通过 UsdShade 的连接/发现机制被渲染器识别。Schema 中以uniform token声明且带apiSchemaOverride标记说明它作为该光源类型的稳定标识供渲染委托匹配对应的灯光实现。相关 API 为UsdLuxDomeLight::GetLightShaderIdAttr继承自 LightAPI 体系。portalsUSD 类型relrelationshipFallback 值无可选的采样引导门户Optional portals to guide light sampling。通过该关系DomeLight 可以引用一个或多个PortalLightprim——即 schema.usda 中定义的矩形门户位于局部 XY 平面、向 -Z 方向透光、边长 1 单位可通过inputs:width、inputs:height调整。在建筑可视化等室外光通过窗户进入室内的场景中门户可以显著减少路径追踪采样噪声。对应 API 为GetPortalsRel()/CreatePortalsRel()见 domeLight.h。DomeLight_1 与 poleAxis 朝向控制官方文档明确指向了替代版本DomeLight_1见 DomeLight_1 文档它在DomeLight 基础上额外提供poleAxis属性来控制穹顶朝向适用于 Z-up 场景或需要 Y/Z 轴切换的工作流。poleAxisUSD 类型tokenFallback 值sceneAllowed tokensscene、Y、Z见 schema.usda决定穹顶顶部极点的初始对齐方向scene穹顶顶部极点与stage 的上轴up axis对齐Y穹顶顶部极点与Y 轴对齐Z穹顶顶部极点与Z 轴对齐。文档特别强调两点注意事项将穹顶对齐到poleAxis所需的旋转只应用于穹顶本身不会继承到该穹顶 prim 的命名空间子级dome light prim 的 namespace children当poleAxis为Y或scene且 stage 上轴为 Y 时默认朝向与 OpenEXR 经纬度规范一致当poleAxis为Z或scene且 stage 上轴为 Z 时纬度±pi/2对应 ±Z 方向纬度 0、经度 0 在 3D 空间中指向-Y方向见 schema.usda 的补充说明。继承属性Xformable 与 Imageable除自有属性外DomeLight 还继承了两个通用基类的属性与其他 usdLux 光源一致继承自 XformablexformOpOrderxformOpOrdertoken[]类型。声明变换操作translate/rotate/scale 等的求值顺序用于摆放穹顶在场景中的位置与姿态。继承自 ImageableproxyPrim、purpose、visibilityproxyPrimrelrelationship。指定一个代理 prim 用于视口加速显示。purposetokenFallback 值default。控制该 prim 参与渲染/预览/代理等用途的可见性。visibilitytokenFallback 值inherited。控制该 prim 的显隐支持inherited/invisible。这些属性使 DomeLight 与 OpenUSD 的变换、代理和可见性体系无缝衔接例如可通过purpose让环境光不参与某类 passes或用visibility在动画中关闭环境光。源码级实现OrientToStageUpAxis 与测试佐证在生成代码之外UsdLuxDomeLight提供了一个自定义方法OrientToStageUpAxis()声明见 domeLight.h实现见 domeLight.cpp调用UsdGeomGetStageUpAxis()查询 stage 的上轴若上轴为Z则自动在穹顶上添加一个RotateX 90°的变换操作op 后缀为orientToStageUpAxis对应 token 定义于 tokens.cpp使穹顶顶部极点对齐到 Z 轴若已存在同名 op则视为已校正并直接返回若上轴为 Y则不创建任何 op因为 Y 对齐是默认朝向。这一行为有明确的单元测试覆盖testenv/testUsdLuxLight.py 中的test_DomeLight_OrientToStageUpAxis验证了Y-up 场景下不产生任何 xform op将 stage 切换为 Z-up 后再调用恰好产生一个TypeRotateX、数值为90.0的 op。这个 API 与DomeLight_1.poleAxis是互补的两种对 Z-up 场景提供支持的途径前者通过代码便捷地补一个旋转 op后者通过显式的poleAxistoken 声明意图。对于生成 API可参考 wrapDomeLight.cpp 中的 Python 绑定在 Python 中可通过UsdLux.DomeLight.Define(stage, /dome)创建、light.GetTextureFileAttr()读写纹理、light.OrientToStageUpAxis()校正朝向。总结选择哪个 DomeLight 版本需求推荐版本Y-up 场景、标准 OpenEXR latlong 贴图、无需特殊朝向DomeLight默认 Y 极点Z-up 场景或需要显式声明穹顶朝向DomeLight_1poleAxisscene/Y/Z需要代码动态校正 stage 上轴DomeLightOrientToStageUpAxis()DomeLight 是 OpenUSD 中实现环境照明、IBL 和天空模拟的标准方案。核心要点可归纳为贴图按 OpenEXR 2:1 经纬度约定制作通过inputs:texture:file指定 HDR 贴图、用inputs:texture:format声明投影类型用portals挂接 PortalLight 优化采样必要时用DomeLight_1.poleAxis或OrientToStageUpAxis()适配 Z-up 管线。相关 Schema 源码位于 pxr/usd/usdLux/schema.usdaC 头文件与 Python 绑定分别位于 pxr/usd/usdLux/domeLight.h 与 pxr/usd/usdLux/wrapDomeLight.cpp配套测试见 pxr/usd/usdLux/testenv/testUsdLuxLight.py可供进一步深入研读。【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考