OpenUSD UsdLux ShapingAPI 完全指南灯光塑形、聚光锥与 IES 配光曲线实战【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSDShapingAPI 是 OpenUSD 的 UsdLux 光照体系中专用于控制灯光发射塑形light shaping的应用型 API Schema负责管理灯光的光锥角度、光锥柔和度、发射聚焦与 IES 光度学配光曲线等属性。本文以 ShapingAPI 官方 Schema 文档 为核心骨架结合 UsdLux 源码实现 与 schema 定义、UsdLux 用户指南 和 单元测试深入解析每个属性的数学公式、默认值与实战用法帮助你写出可直接落地、可被渲染器正确消费的聚光灯与 IES 灯光 USD 场景。什么是 ShapingAPI定位与使用前提在 OpenUSD 的 UsdLux 域中灯光能力由一套分层 Schema 提供LightAPI 赋予 prim“是一盏灯”的基本能力intensity、color、exposure 等ShapingAPI 在 LightAPI 之上叠加发射塑形能力光锥cone、聚焦focus、IES 配光ShadowAPI 提供阴影控制。关键前提LightAPI 并不会自动附带 ShapingAPI。从源码看ShapingAPI 是一个SingleApply类型的应用型 API Schema见 shapingAPI.h必须显式应用到灯光 prim 上才能使用。在 USD 文本格式中通过prepend apiSchemas [ShapingAPI]声明def SphereLight Spot ( prepend apiSchemas [ShapingAPI] ) { float inputs:radius 1 float inputs:intensity 10.0 }在 Python 中则使用UsdLux.ShapingAPI.Apply(prim)或Apply(lightAPI.GetPrim())来应用该 Schema这与 testUsdLuxLight.py 中的用法一致测试还验证了 ShapingAPI 是“可连接”connectable的——shaping:focus等输入可以通过 UsdShade 连接图如连接到灯光的输出outputs:out参与材质/灯光网络见 testUsdLuxLight.py。需要说明的是并非所有渲染器都会为所有灯型消费全部塑形控件。例如 UsdLux 用户指南 指出对于 DistantLightRenderMan 会使用shaping:focus但不会使用shaping:cone:angle。因此在实际制作中应根据目标渲染器确认其对各属性的支持范围。ShapingAPI 共定义 7 个属性全部位于inputs:命名空间声明与默认值在 generatedSchema.usda 中集中定义属性USD 类型默认值语义inputs:shaping:cone:anglefloat90.0限制主轴偏移角度的光锥角度inputs:shaping:cone:softnessfloat0.0光锥边缘的柔和过渡程度inputs:shaping:focusfloat0.0将光向中心聚焦、收窄光斑inputs:shaping:focusTintcolor3f(0,0,0)对边缘衰减区域进行颜色着色inputs:shaping:ies:fileasset无IES 配光曲线文件路径inputs:shaping:ies:angleScalefloat0.0对 IES 曲线纬度角度做缩放inputs:shaping:ies:normalizeboolFalse归一化 IES 曲线能量光锥控制cone:angle 与 cone:softness光锥spotlight cone是让灯光表现得像聚光灯的核心手段。两个属性配合使用cone:angle决定“照到哪里”cone:softness决定“边缘有多软”。cone:angle硬性截止角度inputs:shaping:cone:angle的物理含义是偏离主轴的最大角度限制单位是度。凡是偏离主轴角度大于该值的发射其光照强度被保证为零_offAxis acos(lightAxis · emissionDir) _cutoff toRadians(coneAngle) _offAxis _cutoff ⟹ L_Scalar 0其中lightAxis是灯光主轴向emissionDir是发射方向。在默认的cone:softness 0下当_offAxis coneAngle时光照亮度保持不变因此 coneAngle 表现为一个硬性的二元“关闭”开关角度以内全亮角度以外全暗。实用技巧该属性不影响已应用的 IES 配光曲线——若同时设置了shaping:ies:fileIES 会接管角度分布coneAngle 不再起截止作用见 ShapingAPI.md。cone:softness边缘柔和过渡inputs:shaping:cone:softness控制截止边缘的柔和度典型取值范围为 0硬边到 1平滑过渡也允许大于 1 以获得更强的渐变超出 [0,1] 范围的值会被钳制clamp。其数学定义是_offAxis acos(lightAxis · emissionDir) _cutoff toRadians(coneAngle) _smoothStart lerp(coneSoftness, _cutoff, 0) L_Scalar L_Scalar · (1 - smoothStep(_offAxis, _smoothStart, _cutoff))当 softness 落在 (0, 1] 时它定义了在非截止角度区间内亮度从 0 平滑插值到 1 的比例softness 越大平滑过渡区间占光锥内的比例越高边缘越柔。实战示例来自 UsdLux 用户指南 的聚光灯对比场景三盏 SphereLight 使用相同cone:angle 25softness 分别为 0、0.25、0.75即可得到“硬边→较软→很软”的边缘渐变效果def Scope Lights { def SphereLight Light1 ( prepend apiSchemas [ShapingAPI] ) { float inputs:radius 1 float inputs:intensity 10.0 # 硬边聚光 float inputs:shaping:cone:angle 25.0 float inputs:shaping:cone:softness 0 } def SphereLight Light2 ( references /Lights/Light1 ) { # 软边聚光 float inputs:shaping:cone:softness 0.25 } def SphereLight Light3 ( references /Lights/Light1 ) { # 更软的边缘 float inputs:shaping:cone:softness 0.75 } }聚焦控制focus 与 focusTintfocus收窄光斑强度inputs:shaping:focus用于重塑灯光的光斑分布数值越高光被拉向中心越强光斑越窄。负值被忽略Values 0 are ignored。其核心公式在默认纯黑 focusTint 下的简化形式为focusFactor |emissionDirection · lightAxis|^focus L_Color focusFactor · L_Color即以灯光主轴与发射方向点积的绝对值、取focus次幂作为倍率。完整形式含 focusTint见下节。重要陷阱公式中的绝对值意味着SphereLight、CylinderLight 等会在“灯后”方向也产生发射。若需要只向前发射可将shaping:cone:angle设置为 90 度或更小见 shapingAPI.h。下面的场景出自 UsdLux 用户指南用 DiskLight 照射一个 Cube通过修改 focus 观察光斑变化def Scope Lights { def DiskLight Light1 ( prepend apiSchemas [ShapingAPI] ) { float inputs:radius 1 float inputs:shaping:focus 0 # 改为 20 观察聚焦效果 double3 xformOp:translate (0, 0, -11) uniform token[] xformOpOrder [xformOp:translate] } } def Xform TestGeom { def Cube Cube1 { double size 2 color3f[] primvars:displayColor [(1, 1, 1)] ( interpolation constant ) double3 xformOp:translate (0, 0, -13) uniform token[] xformOpOrder [xformOp:translate] } def Plane Plane { color3f[] primvars:displayColor [(1, 1, 1)] ( interpolation constant ) double length 20 double width 20 double3 xformOp:translate (0, 0, -14) uniform token[] xformOpOrder [xformOp:translate] } }focus 取 0 时光斑呈均匀大范围分布取 20 时光线被显著拉向中心、光斑收窄。focusTint衰减区着色inputs:shaping:focusTint为衰减区从灯光的偏离轴方向朝向中心的发射叠加颜色。其完整公式是对focusTint与白色[1,1,1]按 focus 因子做线性插值再逐分量相乘focusFactor |emissionDirection · lightAxis|^focus focusColor lerp(focusFactor, focusTint, [1,1,1]) L_Color componentwiseMultiply(focusColor, L_Color)由此可推出两个实用结论focusTint 为纯白 (1,1,1) 时focus 功能被禁用插值结果恒为白不产生任何缩放与 focus 一样绝对值公式使得球/圆柱灯会在灯后方向也着色——想只向前发射同样把cone:angle设到 90 度或更小。结合前两张图可以看到focus20已把光斑聚焦收窄再加上focusTint(1,0,0)红色后光斑边缘到中心的过渡区域呈现由红到白的渐变着色——这正是“以 focusTint 标记衰减区”的直观效果示例场景同样出自 UsdLux 用户指南 的 focus 对比演示。IES 配光曲线file、angleScale 与 normalizeIESIllumination Engineering Society配光曲线是灯具行业描述光强角分布的标准格式其文件格式规范为 ANSI/IES LM-63-19。ShapingAPI 用三个属性来接入并操控 IES 分布。采样管线与公式IES 的完整计算管线定义于 ShapingAPI.md如下_light, toPolarCoordinates(emissionDirectionInLightSpace) _ies applyAngleScale(_light, angleScale) iesSample sampleIES(iesFile, _ies, ) iesNormalize ⟹ iesSample iesSample · iesProfilePower(iesFile) L_Color iesSample · L_Color即先在灯光局部坐标系内把发射方向转换为极坐标纬度角 、经度角 经 angleScale 变换后采样 IES 文件得到光强采样值若开启 normalize 则再乘以曲线总功率进行能量归一化最后作为缩放系数作用于光照颜色。shaping:ies:file指定 IES 文件inputs:shaping:ies:file为asset类型指向.ies配光曲线文件。注意其采样基于灯光局部空间的发射方向在应用 angleScale 变换之后因此灯光自身的旋转/位移会直接影响配光朝向。shaping:ies:angleScale角度缩放inputs:shaping:ies:angleScale对 IES 曲线的纬度方向垂直极坐标角度做缩放从而“收缩”或“扩张”配光曲线的角范围。缩放原点取决于正负号angleScale 0: _ies _light / angleScale # 原点在 theta 0 angleScale 0: _ies _light # 不缩放 angleScale 0: _ies (_light - π) / -angleScale π # 原点在 theta π (180°)|angleScale| 1收缩 IES 应用的角范围光束变窄|angleScale| 1扩张 IES 映射的角范围光束变宽。最佳实践详见 ShapingAPI.md同样以文档形式固化在 shapingAPI.h 中朝下照射的聚光灯 IES使用正 angleScale 0。0 scale 1收窄光束scale 1加宽光束。例如原始曲线总锥角 60°scale 取 0.5 收窄到 30°取 1.5 加宽到 90°朝上照射的聚光灯 IES使用负 angleScale 0。-1 scale 0收窄光束scale -1加宽光束。同样以 60° 锥角为例-0.5 收窄到 30°-1.5 加宽到 90°违背上述规则如对朝下的灯用负 scaleangleScale 仍会改变垂直角度映射但效果不直观——收窄/加宽可能反转曲线甚至像在垂直角度间“平移”而非均匀缩放非单一朝向或非正上/正下的曲线应用 angleScale 会改变垂直映射但难以直观预判效果需谨慎使用。shaping:ies:normalize能量归一化inputs:shaping:ies:normalize默认 False开启后IES 采样值会乘以曲线的总功率进行归一化使配光曲线只影响光线的形状分布、而不改变灯光的整体能量输出总功率通过对曲线上所有立体角面片的光强积分得到。这对于“保持灯具能量恒定、只换配光形状”的灯光设计场景非常有用。一个完整的 IES 灯光示例出自 UsdLux 用户指南配合暖色温 2500K 营造街灯氛围def Scope Lights { def DiskLight Light1 ( prepend apiSchemas [ShapingAPI] ) { float inputs:radius 1 float inputs:shaping:ies:angleScale 0.3 asset inputs:shaping:ies:file antique_street_lamp.ies bool inputs:shaping:ies:normalize 1 float inputs:colorTemperature 2500 bool inputs:enableColorTemperature 1 double3 xformOp:translate (0, 0, -6) uniform token[] xformOpOrder [xformOp:translate] } }从渲染结果可见IES 曲线把原本均匀的 DiskLight 变成了具有明确方向性配光中心与四周明暗不同、带环形光晕分布的灯具这正是接入真实灯具光度数据的典型效果。在代码中读写 ShapingAPI 属性ShapingAPI 的 C 接口由 Schema 生成器自动生成见 shapingAPI.h每个属性都有对应的Get*Attr与Create*Attr方法例如GetShapingConeAngleAttr()/CreateShapingConeAngleAttr()GetShapingConeSoftnessAttr()/CreateShapingConeSoftnessAttr()GetShapingFocusAttr()/CreateShapingFocusAttr()GetShapingFocusTintAttr()/CreateShapingFocusTintAttr()GetShapingIesFileAttr()/CreateShapingIesFileAttr()GetShapingIesAngleScaleAttr()/CreateShapingIesAngleScaleAttr()GetShapingIesNormalizeAttr()/CreateShapingIesNormalizeAttr()由于 ShapingAPI 继承自UsdAPISchemaBase且是 SingleApply API还提供Apply(prim)、CanApply(prim, whyNot)、Get(stage, path)等静态方法见 shapingAPI.hApply通过在 prim 的apiSchemaslistOp 元数据中追加ShapingAPI来记录应用状态。此外源码中UsdLuxShapingAPI(const UsdShadeConnectableAPI connectable)与ConnectableAPI()等转换接口允许 ShapingAPI 与 UsdShade 连接网络互操作shapingAPI.h这也是 testUsdLuxLight.py 所验证的“shaping 输入可连接到灯光输出”能力的基础。在 Python 中对应地使用UsdLux.ShapingAPIApply()返回 Schema 对象后通过GetShapingFocusAttr()、GetInput(shaping:cone:angle)等获取属性句柄进行读写单元测试 testUsdLuxLight.py 同时验证了GetInput(shaping:cone:angle)与GetShapingConeAngleAttr()返回的是同一属性。综合实战打造一整套塑形灯光将上述能力组合起来可以在一个 USD 场景中同时使用硬边聚光、软边聚光与 IES 街灯三种塑形灯光。以下是把各节示例整合并增加 lightLink 控制的完整场景基于 UsdLux 用户指南 的示例体系#usda 1.0 ( upAxis Y ) def Scope Lights { # 硬边聚光灯 def SphereLight HardSpot ( prepend apiSchemas [ShapingAPI] ) { uniform bool collection:lightLink:includeRoot 0 rel collection:lightLink:includes [ /TestGeom/Sphere1, /TestGeom/Plane ] float inputs:radius 1 float inputs:intensity 10.0 float inputs:shaping:cone:angle 25.0 float inputs:shaping:cone:softness 0 } # 软边聚光灯引用硬边聚光灯再覆盖 softness def SphereLight SoftSpot ( references /Lights/HardSpot ) { uniform bool collection:lightLink:includeRoot 0 rel collection:lightLink:includes [ /TestGeom/Sphere2, /TestGeom/Plane ] float inputs:shaping:cone:softness 0.75 } # 聚焦 边缘着色灯 def DiskLight FocusedLight ( prepend apiSchemas [ShapingAPI] ) { float inputs:radius 1 float inputs:shaping:focus 20 color3f inputs:shaping:focusTint (1, 0, 0) } # IES 街灯配光 能量归一化 暖色温 def DiskLight StreetLamp ( prepend apiSchemas [ShapingAPI] ) { float inputs:radius 1 float inputs:shaping:ies:angleScale 0.3 asset inputs:shaping:ies:file antique_street_lamp.ies bool inputs:shaping:ies:normalize 1 float inputs:colorTemperature 2500 bool inputs:enableColorTemperature 1 } } def Xform TestGeom { def Sphere Sphere1 { color3f[] primvars:displayColor [(1, 1, 1)] ( interpolation constant ) } def Sphere Sphere2 ( references /TestGeom/Sphere1 ) { } def Plane Plane { color3f[] primvars:displayColor [(1, 1, 1)] ( interpolation constant ) double length 20 double width 20 } }小结与速查启用方式ShapingAPI 不会随 LightAPI 自动启用需在 prim 上通过prepend apiSchemas [ShapingAPI]USD 文本或UsdLux.ShapingAPI.Apply(prim)Python/C显式应用聚光锥cone:angle默认 90°硬截止cone:softness默认 0硬边0~1 平滑过渡超界被钳制聚焦focus默认 0越高越聚焦负值忽略focusTint默认纯黑纯白将禁用 focus两者都因绝对值公式导致球/圆柱灯向后发射可用cone:angle 90限制为只向前IESies:file指定 .ies 曲线ies:angleScale缩放垂直角度正值原点在 0°负值原点在 180°|scale|1 收窄、1 加宽注意正负号与灯具朝向的匹配ies:normalize默认 False开启后保持灯光总能量不变只改变配光形状限制渲染器对各属性的支持范围不同如 RenderMan 的 DistantLight 只用 focus 不用 cone且 cone:angle 不影响已应用的 IES 曲线落地前应以目标渲染器为准。如需进一步深入可继续阅读ShapingAPI 属性参考、UsdLux 用户指南含完整示例与渲染对比图、ShapingAPI Schema 声明、ShapingAPI C 头文件 以及 UsdLux 单元测试。【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenUSD UsdLux ShapingAPI 完全指南：灯光塑形、聚光锥与 IES 配光曲线实战
OpenUSD UsdLux ShapingAPI 完全指南灯光塑形、聚光锥与 IES 配光曲线实战【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSDShapingAPI 是 OpenUSD 的 UsdLux 光照体系中专用于控制灯光发射塑形light shaping的应用型 API Schema负责管理灯光的光锥角度、光锥柔和度、发射聚焦与 IES 光度学配光曲线等属性。本文以 ShapingAPI 官方 Schema 文档 为核心骨架结合 UsdLux 源码实现 与 schema 定义、UsdLux 用户指南 和 单元测试深入解析每个属性的数学公式、默认值与实战用法帮助你写出可直接落地、可被渲染器正确消费的聚光灯与 IES 灯光 USD 场景。什么是 ShapingAPI定位与使用前提在 OpenUSD 的 UsdLux 域中灯光能力由一套分层 Schema 提供LightAPI 赋予 prim“是一盏灯”的基本能力intensity、color、exposure 等ShapingAPI 在 LightAPI 之上叠加发射塑形能力光锥cone、聚焦focus、IES 配光ShadowAPI 提供阴影控制。关键前提LightAPI 并不会自动附带 ShapingAPI。从源码看ShapingAPI 是一个SingleApply类型的应用型 API Schema见 shapingAPI.h必须显式应用到灯光 prim 上才能使用。在 USD 文本格式中通过prepend apiSchemas [ShapingAPI]声明def SphereLight Spot ( prepend apiSchemas [ShapingAPI] ) { float inputs:radius 1 float inputs:intensity 10.0 }在 Python 中则使用UsdLux.ShapingAPI.Apply(prim)或Apply(lightAPI.GetPrim())来应用该 Schema这与 testUsdLuxLight.py 中的用法一致测试还验证了 ShapingAPI 是“可连接”connectable的——shaping:focus等输入可以通过 UsdShade 连接图如连接到灯光的输出outputs:out参与材质/灯光网络见 testUsdLuxLight.py。需要说明的是并非所有渲染器都会为所有灯型消费全部塑形控件。例如 UsdLux 用户指南 指出对于 DistantLightRenderMan 会使用shaping:focus但不会使用shaping:cone:angle。因此在实际制作中应根据目标渲染器确认其对各属性的支持范围。ShapingAPI 共定义 7 个属性全部位于inputs:命名空间声明与默认值在 generatedSchema.usda 中集中定义属性USD 类型默认值语义inputs:shaping:cone:anglefloat90.0限制主轴偏移角度的光锥角度inputs:shaping:cone:softnessfloat0.0光锥边缘的柔和过渡程度inputs:shaping:focusfloat0.0将光向中心聚焦、收窄光斑inputs:shaping:focusTintcolor3f(0,0,0)对边缘衰减区域进行颜色着色inputs:shaping:ies:fileasset无IES 配光曲线文件路径inputs:shaping:ies:angleScalefloat0.0对 IES 曲线纬度角度做缩放inputs:shaping:ies:normalizeboolFalse归一化 IES 曲线能量光锥控制cone:angle 与 cone:softness光锥spotlight cone是让灯光表现得像聚光灯的核心手段。两个属性配合使用cone:angle决定“照到哪里”cone:softness决定“边缘有多软”。cone:angle硬性截止角度inputs:shaping:cone:angle的物理含义是偏离主轴的最大角度限制单位是度。凡是偏离主轴角度大于该值的发射其光照强度被保证为零_offAxis acos(lightAxis · emissionDir) _cutoff toRadians(coneAngle) _offAxis _cutoff ⟹ L_Scalar 0其中lightAxis是灯光主轴向emissionDir是发射方向。在默认的cone:softness 0下当_offAxis coneAngle时光照亮度保持不变因此 coneAngle 表现为一个硬性的二元“关闭”开关角度以内全亮角度以外全暗。实用技巧该属性不影响已应用的 IES 配光曲线——若同时设置了shaping:ies:fileIES 会接管角度分布coneAngle 不再起截止作用见 ShapingAPI.md。cone:softness边缘柔和过渡inputs:shaping:cone:softness控制截止边缘的柔和度典型取值范围为 0硬边到 1平滑过渡也允许大于 1 以获得更强的渐变超出 [0,1] 范围的值会被钳制clamp。其数学定义是_offAxis acos(lightAxis · emissionDir) _cutoff toRadians(coneAngle) _smoothStart lerp(coneSoftness, _cutoff, 0) L_Scalar L_Scalar · (1 - smoothStep(_offAxis, _smoothStart, _cutoff))当 softness 落在 (0, 1] 时它定义了在非截止角度区间内亮度从 0 平滑插值到 1 的比例softness 越大平滑过渡区间占光锥内的比例越高边缘越柔。实战示例来自 UsdLux 用户指南 的聚光灯对比场景三盏 SphereLight 使用相同cone:angle 25softness 分别为 0、0.25、0.75即可得到“硬边→较软→很软”的边缘渐变效果def Scope Lights { def SphereLight Light1 ( prepend apiSchemas [ShapingAPI] ) { float inputs:radius 1 float inputs:intensity 10.0 # 硬边聚光 float inputs:shaping:cone:angle 25.0 float inputs:shaping:cone:softness 0 } def SphereLight Light2 ( references /Lights/Light1 ) { # 软边聚光 float inputs:shaping:cone:softness 0.25 } def SphereLight Light3 ( references /Lights/Light1 ) { # 更软的边缘 float inputs:shaping:cone:softness 0.75 } }聚焦控制focus 与 focusTintfocus收窄光斑强度inputs:shaping:focus用于重塑灯光的光斑分布数值越高光被拉向中心越强光斑越窄。负值被忽略Values 0 are ignored。其核心公式在默认纯黑 focusTint 下的简化形式为focusFactor |emissionDirection · lightAxis|^focus L_Color focusFactor · L_Color即以灯光主轴与发射方向点积的绝对值、取focus次幂作为倍率。完整形式含 focusTint见下节。重要陷阱公式中的绝对值意味着SphereLight、CylinderLight 等会在“灯后”方向也产生发射。若需要只向前发射可将shaping:cone:angle设置为 90 度或更小见 shapingAPI.h。下面的场景出自 UsdLux 用户指南用 DiskLight 照射一个 Cube通过修改 focus 观察光斑变化def Scope Lights { def DiskLight Light1 ( prepend apiSchemas [ShapingAPI] ) { float inputs:radius 1 float inputs:shaping:focus 0 # 改为 20 观察聚焦效果 double3 xformOp:translate (0, 0, -11) uniform token[] xformOpOrder [xformOp:translate] } } def Xform TestGeom { def Cube Cube1 { double size 2 color3f[] primvars:displayColor [(1, 1, 1)] ( interpolation constant ) double3 xformOp:translate (0, 0, -13) uniform token[] xformOpOrder [xformOp:translate] } def Plane Plane { color3f[] primvars:displayColor [(1, 1, 1)] ( interpolation constant ) double length 20 double width 20 double3 xformOp:translate (0, 0, -14) uniform token[] xformOpOrder [xformOp:translate] } }focus 取 0 时光斑呈均匀大范围分布取 20 时光线被显著拉向中心、光斑收窄。focusTint衰减区着色inputs:shaping:focusTint为衰减区从灯光的偏离轴方向朝向中心的发射叠加颜色。其完整公式是对focusTint与白色[1,1,1]按 focus 因子做线性插值再逐分量相乘focusFactor |emissionDirection · lightAxis|^focus focusColor lerp(focusFactor, focusTint, [1,1,1]) L_Color componentwiseMultiply(focusColor, L_Color)由此可推出两个实用结论focusTint 为纯白 (1,1,1) 时focus 功能被禁用插值结果恒为白不产生任何缩放与 focus 一样绝对值公式使得球/圆柱灯会在灯后方向也着色——想只向前发射同样把cone:angle设到 90 度或更小。结合前两张图可以看到focus20已把光斑聚焦收窄再加上focusTint(1,0,0)红色后光斑边缘到中心的过渡区域呈现由红到白的渐变着色——这正是“以 focusTint 标记衰减区”的直观效果示例场景同样出自 UsdLux 用户指南 的 focus 对比演示。IES 配光曲线file、angleScale 与 normalizeIESIllumination Engineering Society配光曲线是灯具行业描述光强角分布的标准格式其文件格式规范为 ANSI/IES LM-63-19。ShapingAPI 用三个属性来接入并操控 IES 分布。采样管线与公式IES 的完整计算管线定义于 ShapingAPI.md如下_light, toPolarCoordinates(emissionDirectionInLightSpace) _ies applyAngleScale(_light, angleScale) iesSample sampleIES(iesFile, _ies, ) iesNormalize ⟹ iesSample iesSample · iesProfilePower(iesFile) L_Color iesSample · L_Color即先在灯光局部坐标系内把发射方向转换为极坐标纬度角 、经度角 经 angleScale 变换后采样 IES 文件得到光强采样值若开启 normalize 则再乘以曲线总功率进行能量归一化最后作为缩放系数作用于光照颜色。shaping:ies:file指定 IES 文件inputs:shaping:ies:file为asset类型指向.ies配光曲线文件。注意其采样基于灯光局部空间的发射方向在应用 angleScale 变换之后因此灯光自身的旋转/位移会直接影响配光朝向。shaping:ies:angleScale角度缩放inputs:shaping:ies:angleScale对 IES 曲线的纬度方向垂直极坐标角度做缩放从而“收缩”或“扩张”配光曲线的角范围。缩放原点取决于正负号angleScale 0: _ies _light / angleScale # 原点在 theta 0 angleScale 0: _ies _light # 不缩放 angleScale 0: _ies (_light - π) / -angleScale π # 原点在 theta π (180°)|angleScale| 1收缩 IES 应用的角范围光束变窄|angleScale| 1扩张 IES 映射的角范围光束变宽。最佳实践详见 ShapingAPI.md同样以文档形式固化在 shapingAPI.h 中朝下照射的聚光灯 IES使用正 angleScale 0。0 scale 1收窄光束scale 1加宽光束。例如原始曲线总锥角 60°scale 取 0.5 收窄到 30°取 1.5 加宽到 90°朝上照射的聚光灯 IES使用负 angleScale 0。-1 scale 0收窄光束scale -1加宽光束。同样以 60° 锥角为例-0.5 收窄到 30°-1.5 加宽到 90°违背上述规则如对朝下的灯用负 scaleangleScale 仍会改变垂直角度映射但效果不直观——收窄/加宽可能反转曲线甚至像在垂直角度间“平移”而非均匀缩放非单一朝向或非正上/正下的曲线应用 angleScale 会改变垂直映射但难以直观预判效果需谨慎使用。shaping:ies:normalize能量归一化inputs:shaping:ies:normalize默认 False开启后IES 采样值会乘以曲线的总功率进行归一化使配光曲线只影响光线的形状分布、而不改变灯光的整体能量输出总功率通过对曲线上所有立体角面片的光强积分得到。这对于“保持灯具能量恒定、只换配光形状”的灯光设计场景非常有用。一个完整的 IES 灯光示例出自 UsdLux 用户指南配合暖色温 2500K 营造街灯氛围def Scope Lights { def DiskLight Light1 ( prepend apiSchemas [ShapingAPI] ) { float inputs:radius 1 float inputs:shaping:ies:angleScale 0.3 asset inputs:shaping:ies:file antique_street_lamp.ies bool inputs:shaping:ies:normalize 1 float inputs:colorTemperature 2500 bool inputs:enableColorTemperature 1 double3 xformOp:translate (0, 0, -6) uniform token[] xformOpOrder [xformOp:translate] } }从渲染结果可见IES 曲线把原本均匀的 DiskLight 变成了具有明确方向性配光中心与四周明暗不同、带环形光晕分布的灯具这正是接入真实灯具光度数据的典型效果。在代码中读写 ShapingAPI 属性ShapingAPI 的 C 接口由 Schema 生成器自动生成见 shapingAPI.h每个属性都有对应的Get*Attr与Create*Attr方法例如GetShapingConeAngleAttr()/CreateShapingConeAngleAttr()GetShapingConeSoftnessAttr()/CreateShapingConeSoftnessAttr()GetShapingFocusAttr()/CreateShapingFocusAttr()GetShapingFocusTintAttr()/CreateShapingFocusTintAttr()GetShapingIesFileAttr()/CreateShapingIesFileAttr()GetShapingIesAngleScaleAttr()/CreateShapingIesAngleScaleAttr()GetShapingIesNormalizeAttr()/CreateShapingIesNormalizeAttr()由于 ShapingAPI 继承自UsdAPISchemaBase且是 SingleApply API还提供Apply(prim)、CanApply(prim, whyNot)、Get(stage, path)等静态方法见 shapingAPI.hApply通过在 prim 的apiSchemaslistOp 元数据中追加ShapingAPI来记录应用状态。此外源码中UsdLuxShapingAPI(const UsdShadeConnectableAPI connectable)与ConnectableAPI()等转换接口允许 ShapingAPI 与 UsdShade 连接网络互操作shapingAPI.h这也是 testUsdLuxLight.py 所验证的“shaping 输入可连接到灯光输出”能力的基础。在 Python 中对应地使用UsdLux.ShapingAPIApply()返回 Schema 对象后通过GetShapingFocusAttr()、GetInput(shaping:cone:angle)等获取属性句柄进行读写单元测试 testUsdLuxLight.py 同时验证了GetInput(shaping:cone:angle)与GetShapingConeAngleAttr()返回的是同一属性。综合实战打造一整套塑形灯光将上述能力组合起来可以在一个 USD 场景中同时使用硬边聚光、软边聚光与 IES 街灯三种塑形灯光。以下是把各节示例整合并增加 lightLink 控制的完整场景基于 UsdLux 用户指南 的示例体系#usda 1.0 ( upAxis Y ) def Scope Lights { # 硬边聚光灯 def SphereLight HardSpot ( prepend apiSchemas [ShapingAPI] ) { uniform bool collection:lightLink:includeRoot 0 rel collection:lightLink:includes [ /TestGeom/Sphere1, /TestGeom/Plane ] float inputs:radius 1 float inputs:intensity 10.0 float inputs:shaping:cone:angle 25.0 float inputs:shaping:cone:softness 0 } # 软边聚光灯引用硬边聚光灯再覆盖 softness def SphereLight SoftSpot ( references /Lights/HardSpot ) { uniform bool collection:lightLink:includeRoot 0 rel collection:lightLink:includes [ /TestGeom/Sphere2, /TestGeom/Plane ] float inputs:shaping:cone:softness 0.75 } # 聚焦 边缘着色灯 def DiskLight FocusedLight ( prepend apiSchemas [ShapingAPI] ) { float inputs:radius 1 float inputs:shaping:focus 20 color3f inputs:shaping:focusTint (1, 0, 0) } # IES 街灯配光 能量归一化 暖色温 def DiskLight StreetLamp ( prepend apiSchemas [ShapingAPI] ) { float inputs:radius 1 float inputs:shaping:ies:angleScale 0.3 asset inputs:shaping:ies:file antique_street_lamp.ies bool inputs:shaping:ies:normalize 1 float inputs:colorTemperature 2500 bool inputs:enableColorTemperature 1 } } def Xform TestGeom { def Sphere Sphere1 { color3f[] primvars:displayColor [(1, 1, 1)] ( interpolation constant ) } def Sphere Sphere2 ( references /TestGeom/Sphere1 ) { } def Plane Plane { color3f[] primvars:displayColor [(1, 1, 1)] ( interpolation constant ) double length 20 double width 20 } }小结与速查启用方式ShapingAPI 不会随 LightAPI 自动启用需在 prim 上通过prepend apiSchemas [ShapingAPI]USD 文本或UsdLux.ShapingAPI.Apply(prim)Python/C显式应用聚光锥cone:angle默认 90°硬截止cone:softness默认 0硬边0~1 平滑过渡超界被钳制聚焦focus默认 0越高越聚焦负值忽略focusTint默认纯黑纯白将禁用 focus两者都因绝对值公式导致球/圆柱灯向后发射可用cone:angle 90限制为只向前IESies:file指定 .ies 曲线ies:angleScale缩放垂直角度正值原点在 0°负值原点在 180°|scale|1 收窄、1 加宽注意正负号与灯具朝向的匹配ies:normalize默认 False开启后保持灯光总能量不变只改变配光形状限制渲染器对各属性的支持范围不同如 RenderMan 的 DistantLight 只用 focus 不用 cone且 cone:angle 不影响已应用的 IES 曲线落地前应以目标渲染器为准。如需进一步深入可继续阅读ShapingAPI 属性参考、UsdLux 用户指南含完整示例与渲染对比图、ShapingAPI Schema 声明、ShapingAPI C 头文件 以及 UsdLux 单元测试。【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考