尧图网页设计 
OpenUSD UsdUI 指南用 Schema 描述节点图、无障碍信息与 UI 呈现提示【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSDUsdUI 是 OpenUSDUniversal Scene Description中专门用于描述用户界面相关特性的 schema 域。本文以 UsdUI 概览文档 为主线系统讲解如何用SceneGraphPrimAPI、NodeGraphNodeAPI与Backdrop描述节点图如材质/着色网络的布局与外观用AccessibilityAPI为 Prim 提供无障碍信息以及用ObjectHints、PrimHints、PropertyHints、AttributeHints四组 UI 提示控制 Prim 与属性在 DCC 工具中的呈现方式。读完本文你将掌握 UsdUI 全部核心属性的含义、可直接复制的 USDA 示例以及基于布尔表达式的条件 UI 控制方案。UsdUI 是什么UsdUI schema 域源码位于 pxr/usd/usdUI提供了一系列与通用用户界面相关的 schema其核心定位是为呈现层提供提示hints而非直接驱动某个具体 UI 的实现。典型用途包括描述节点图node graph中节点的布局、颜色、尺寸、层级、图标等视觉信息帮助 DCC 工具把着色网络、材质网络这类复杂连接可视化得更容易理解描述用于辅助功能assistive UI的无障碍信息供语音控制、屏幕阅读器等运行时使用通过 UI 提示描述 Prim 和属性应该如何被呈现在 UI 中。需要强调的是UsdUI 只是描述信息最终如何呈现完全由消费这些信息的工具或应用决定。本文引用的 schema 定义与示例分别来自 overview.md、NodeGraphNodeAPI.md、SceneGraphPrimAPI.md、Backdrop.md、AccessibilityAPI.md 以及 UI Hints 系列文档schema 的底层定义可在 schema.usda 中查阅。使用 UsdUI 描述节点图节点图可以用来描述一组 Prim 构成的网络例如着色网络、材质网络。消费方如 DCC 工具可以据此把复杂网络可视化。UsdUI 提供三类工具来组织节点图SceneGraphPrimAPI为每个节点提供描述性名称与分组NodeGraphNodeAPI定义每个节点在节点图中的外观位置、颜色、图标、尺寸、层级等Backdrop以视觉方式如彩色矩形圈出一组节点并给出该分组的说明。SceneGraphPrimAPI节点的名称与分组SceneGraphPrimAPI让每个节点携带一个描述性名称ui:displayName和一个描述性分组ui:displayGroup。从 SceneGraphPrimAPI.md 中的示例可以看到它通过prepend apiSchemas [SceneGraphPrimAPI]挂到 Shader Prim 上def Material MyMaterial { token outputs:mtlx:surface.connect /World/MyMaterial/PreviewSurface.outputs:out def Shader PreviewSurface ( prepend apiSchemas [SceneGraphPrimAPI] ) { uniform token info:id ND_UsdPreviewSurface_surfaceshader color3f inputs:diffuseColor.connect /World/MyMaterial/Color.outputs:out token outputs:out uniform token ui:displayGroup MyMaterial Nodes uniform token ui:displayName Preview Surface Node } def Shader Color ( prepend apiSchemas [SceneGraphPrimAPI] ) { uniform token info:id ND_constant_color3 color3f inputs:value (1, 0.023, 0.701) color3f outputs:out uniform token ui:displayGroup MyMaterial Nodes uniform token ui:displayName Color Node } }该 schema 的两个属性均为token类型属性USD 类型说明ui:displayGrouptoken节点所属分组的描述性名称。它可能与该节点其他的 USD 分组特性如所属 Scope 名、父 Prim 名无关ui:displayNametoken节点在其连接的节点图语境中的描述性名称可以与 Prim 自身的核心 displayName 不同NodeGraphNodeAPI节点的位置与外观NodeGraphNodeAPI定义了节点在节点图中的呈现信息包括位置、颜色、文档链接、展开状态、图标、尺寸与相对深度。下表汇总了 NodeGraphNodeAPI.md 中定义的属性属性USD 类型说明ui:nodegraph:node:displayColorcolor3f节点的颜色ui:nodegraph:node:docURIstring指向该节点文档的 URI 链接ui:nodegraph:node:expansionStatetoken节点当前显示的信息量状态取值为open、closed或minimizedui:nodegraph:node:iconasset用于标识节点用途的图像。它描述的是节点本身而非节点动作的结果例如 Add 节点可以用 号图标ui:nodegraph:node:posfloat2节点的 x,y 坐标位置ui:nodegraph:node:sizefloat2节点可选的 x,y 像素尺寸。可选是因为节点尺寸也可以由其输入输出数量自动生成ui:nodegraph:node:stackingOrderint节点重叠时的显示层级stackingOrder值越大的节点绘制在越上层关于ui:nodegraph:node:pos有两点重要约定单位不是像素假定典型节点的尺寸为 1.0×1.0坐标描述的是相对节点大小的位置关系Y 轴正方向向下例如 -1.0 高于 1.0位置是相对于父节点的如果存在父节点。NodeGraphNodeAPI.md给出了一个包含全部属性的完整示例注意其中PreviewSurface为红色、open展开状态且尺寸更大而Color为蓝色、closed状态若两者重叠stackingOrder更大的Color会绘制在上方def Material MyMaterial { token outputs:mtlx:surface.connect /World/MyMaterial/PreviewSurface.outputs:out def Shader PreviewSurface { uniform token info:id ND_UsdPreviewSurface_surfaceshader color3f inputs:diffuseColor.connect /World/MyMaterial/Color.outputs:out token outputs:out uniform color3f ui:nodegraph:node:displayColor (1.0, 0.0, 0.0) uniform string ui:nodegraph:node:docURI https://openusd.org/release/spec_usdpreviewsurface.html uniform token ui:nodegraph:node:expansionState open uniform asset ui:nodegraph:node:icon preview_surface_icon.png uniform float2 ui:nodegraph:node:pos (-0.85, 1.9) uniform float2 ui:nodegraph:node:size (300.0, 400.0) uniform int ui:nodegraph:node:stackingOrder 1 } def Shader Color { uniform token info:id ND_constant_color3 color3f inputs:value (1.0, 0.023, 0.701) color3f outputs:out uniform color3f ui:nodegraph:node:displayColor (0.0, 0.0, 1.0) uniform string ui:nodegraph:node:docURI docURI uniform token ui:nodegraph:node:expansionState closed uniform asset ui:nodegraph:node:icon color_icon.png uniform float2 ui:nodegraph:node:pos (-2, 2) uniform float2 ui:nodegraph:node:size (100.0, 200.0) uniform int ui:nodegraph:node:stackingOrder 2 } }注意UsdUI 不做属性同步。USD 不会把displayColor、pos等节点属性与其它 schema 中的同名属性例如 GPrim 的primvars:displayColor自动同步。如果应用希望二者保持一致需要由实现节点显示的应用自行处理。Backdrop视觉化分组Backdrop提供一种把节点视觉圈起来的方式并附带对该分组的说明。与SceneGraphPrimAPI.displayGroup不同Backdrop 与节点之间没有直接关联——某个 Shader 节点是否属于某个 Backdrop按 schema.usda 中的约定是由节点图 UI 根据Shader 节点的包围盒是否恰好放进最小的 Backdrop来判断的。Backdrop 的视觉尺寸与位置同样使用NodeGraphNodeAPI的属性来决定。从 Backdrop.md 的示例可以直观理解其坐标语义def Material MyMaterial { token outputs:mtlx:surface.connect /World/Material/PreviewSurface.outputs:out def Shader PreviewSurface ( prepend apiSchemas [NodeGraphNodeAPI] ) { uniform token info:id ND_UsdPreviewSurface_surfaceshader color3f inputs:diffuseColor.connect /World/Material/Color.outputs:out token outputs:out uniform float2 ui:nodegraph:node:pos (-0.85, 1.9) } def Shader Color ( prepend apiSchemas [NodeGraphNodeAPI] ) { uniform token info:id ND_constant_color3 color3f inputs:value (1, 0.023, 0.701) color3f outputs:out uniform float2 ui:nodegraph:node:pos (-2, 2) } def Backdrop Backdrop ( prepend apiSchemas [NodeGraphNodeAPI] ) { uniform token ui:description MyMaterial Nodes uniform color3f ui:nodegraph:node:displayColor (1, 0, 0) uniform float2 ui:nodegraph:node:pos (-0.8, 0.5) uniform float2 ui:nodegraph:node:size (450, 330) } }观察这个例子Backdrop 的 x 起点为 -0.8PreviewSurface为 -0.85Color为 -2.0Backdrop 宽 450典型节点可能约 200px 宽足以覆盖两个节点y 坐标为 0.5、1.9、2而 Y 坐标向下递增因此 Backdrop 位于两个节点上方并向下延伸 330。Backdrop 的说明文字由ui:descriptiontoken类型提供例如用 Noise 说明一组节点共同参与噪声生成。综合示例一个完整的节点图overview.md 给出了一个综合场景假定应用中有一个如下图所示open 展开的 PreviewSurface、closed 收起的 Color 节点、以及一个写着 Do not edit! 的绿色 Backdrop的节点图对应的 USD 表示为def Material Material { token outputs:mtlx:surface.connect /World/Material/PreviewSurface.outputs:out def Shader PreviewSurface ( prepend apiSchemas [NodeGraphNodeAPI] ) { uniform token info:id ND_UsdPreviewSurface_surfaceshader color3f inputs:diffuseColor.connect /World/Material/Color.outputs:out token outputs:out uniform color3f ui:nodegraph:node:displayColor (0.780, 0.698, 0.6) uniform token ui:nodegraph:node:expansionState open uniform float2 ui:nodegraph:node:pos (-.85, 1.9) } def Shader Color ( prepend apiSchemas [NodeGraphNodeAPI] ) { uniform token info:id ND_constant_color3 color3f inputs:value (1, 0.023, 0.701) color3f outputs:out uniform color3f ui:nodegraph:node:displayColor (0.549, 0.133, 1.0) uniform token ui:nodegraph:node:expansionState closed uniform float2 ui:nodegraph:node:pos (-2, 2) } def Backdrop Backdrop ( prepend apiSchemas [NodeGraphNodeAPI] ) { uniform token ui:description Do not edit! uniform color3f ui:nodegraph:node:displayColor (0.764, 1.0, 0.698) uniform float2 ui:nodegraph:node:pos (-0.8, 0.5) uniform float2 ui:nodegraph:node:size (450, 330) } }从这个例子可以观察到几个关键点ui:nodegraph:node:displayColor帮助快速区分不同类型的节点Backdrop 的ui:description可以为节点图中的区域分组提供上下文说明例如 Do not edit!ui:nodegraph:node:expansionState控制节点显示的信息量——对比PreviewSurface与Color的信息密度差异ui:nodegraph:node:size与ui:nodegraph:node:pos决定节点在节点图中的放置位置与相对布局。在源码层面Backdrop类定义于 schema.usda其文档明确指出Backdrop 只是组织工具不包含 Shader 节点、没有影响渲染结果的输入输出导入时可以被安全忽略但 Backdrop 与 Shader、NodeGraph 一样订阅NodeGraphNodeAPI来指定位置与尺寸。仓库中的 testUsdUIBackdrop.py、testUsdUINodeGraphNode.py 等测试用例覆盖了这些 API 的读写行为。使用 AccessibilityAPI 描述无障碍信息AccessibilityAPIschema 在 Prim 上描述无障碍信息这些信息可以被暴露给某个运行时的无障碍框架accessibility frameworks供语音控制、屏幕阅读器等辅助功能使用。其源码定义同样位于 schema.usda实现为 multiple apply APIapiSchemaType multipleApply属性命名空间前缀为accessibility。无障碍信息以标准的label标签、description描述、priority优先级三元组提供。由于它是 multiple apply schema一个 Prim 上可以有多个带命名空间的三元组实例名可以反映该三元组的用途。以下示例为一个 Mesh 提供了 default 与 size 两组无障碍三元组def Mesh Cube ( prepend apiSchemas [AccessibilityAPI:default, AccessibilityAPI:size] ) { string accessibility:default:label Regular cube string accessibility:default:description A plain featureless cube token accessibility:default:priority standard string accessibility:size:label Regular sized cube string accessibility:size:description A 4-meter featureless cube token accessibility:size:priority low }三个属性的语义详见 AccessibilityAPI.md属性USD 类型说明labelstring简洁描述 Prim 的短标签。不建议随时间变化除非简明描述发生重大变化没有建议的固定长度但应保持精炼descriptionstring提供更多细节的扩展描述可选属性某些无障碍系统可能只使用 label。若某个实例名未编写 label则不应以 description 代替。description 可以随时间变化如描述角色在某一时刻的动作prioritytoken提示运行时如何相对其他实例排序本实例的 label 与 description。允许的取值是low、standard、high回退值为standard。该属性可选、可被运行时忽略且不允许随时间变化AccessibilityAPI.md 还给出了几条重要的最佳实践大多数无障碍运行时只支持单一的无障碍描述因此建议把关键信息放在名为 default 的命名空间中如果使用时间采样time sampled的无障碍信息应编写一个默认值以兼容当前不支持时间采样信息的运行时建议在层的 default prim 以及所有根级 Prim上提供场景的无障碍信息这既能帮助无障碍系统向用户提供简洁的场景描述也能兼容不支持层级信息、或用户关闭了该粒度信息层的无障碍系统。当然层级中其他 Prim 也可以继续提供无障碍信息。需要说明的是除上述约定外无障碍信息不会沿 Prim 层级隐式继承继承行为应交由无障碍运行时自行决定如何呈现给用户。仓库中的 testUsdUIAccessibilityAPI.cpp 对该 multiple apply API 的创建、属性读写进行了验证。使用 UI Hints 描述 UI 呈现方式UsdUI 提供了一组 schema 风格的 APIUI hints用于在 Prim 和属性上编写 UI 提示告诉 DCC 工具或其他应用 UI应该怎样呈现该 Prim 或属性。UI 提示以**元数据metadata**形式编写在uiHints字典中不需要应用任何 schema 即可访问或编写这与节点图 API 需要通过prepend apiSchemas挂接不同。UI hints 目前分为以下分组分组适用范围核心字段ObjectHints适用于任何 Prim 或属性的通用 UI 提示displayName、hiddenPrimHintsPrim 级 UI 提示控制显示组display groups如何、何时显示displayGroupsExpanded、displayGroupsShownIfPropertyHints属性级 UI 提示如属性所属的显示组、是否显示displayGroup、shownIfAttributeHints属性级 UI 提示如属性值的 UI 标签及其显示顺序valueLabels、valueLabelsOrder注意不存在单独的 RelationshipHints 分组——没有仅适用于 relationship 的独特提示。提示是建议而非强制。UI hints 只是关于如何在 UI 中呈现 Prim/属性的建议最终呈现方式由实现 UI 的工具或应用决定。一个完整的 UI Hints 示例overview.md 用一个 TreeA 示例展示了四个分组的典型用法#usda 1.0 def TreeA ( uiHints { # ObjectHints hints string displayName Tree template # PrimHints hints dictionary displayGroupsExpanded { bool Trunk settings 1 bool Body settings 1 bool Body settings:Branch settings 0 bool Body settings:Leaf settings 1 } dictionary displayGroupsShownIf { string Body settings:Leaf settings trunkSize ! 1 } } ) { color3f trunkColor (0.6, 0.3, 0.0) ( uiHints { # ObjectHints hints string displayName color # PropertyHints hints string displayGroup Trunk settings } ) int trunkSize 2 ( uiHints { # ObjectHints hints string displayName size # PropertyHints hints string displayGroup Trunk settings # AttributeHints hints dictionary valueLabels { int huge 3 int sapling 1 int standard 2 } token[] valueLabelsOrder [sapling, standard, huge] } ) float bodyRadius 5.0 ( uiHints { # ObjectHints hints string displayName size # PropertyHints hints string displayGroup Body settings } ) float branchDensity 1.0 ( uiHints { # ObjectHints hints string displayName density # PropertyHints hints string displayGroup Body settings:Branch settings } ) float branchLength 5.0 ( uiHints { # ObjectHints hints string displayName length # PropertyHints hints string displayGroup Body settings:Branch settings } ) color3f leafColor (0.4, 0.7, 0.25) ( uiHints { # ObjectHints hints string displayName color # PropertyHints hints string displayGroup Body settings:Leaf settings } ) float leafComplexity 1.0 ( uiHints { # ObjectHints hints string displayName complexity # PropertyHints hints string displayGroup Body settings:Leaf settings string shownIf leafStyle 1 } ) int leafStyle 1 ( uiHints { # ObjectHints hints string displayName style # PropertyHints hints string displayGroup Body settings:Leaf settings # AttributeHints hints dictionary valueLabels { int acute 1 int obtuse 2 int truncate 3 } token[] valueLabelsOrder [acute, obtuse, truncate] } ) string tempNotes ( uiHints { # We never want to show this attribute in the UI bool hidden 1 } ) # Use property re-ordering to control UI order of properties and # display groups reorder properties [trunkColor, trunkSize, bodyRadius, branchDensity, branchLength, leafColor, leafStyle, leafComplexity] }该示例对应的 UI 呈现效果如下图所示关于该示例还有两点值得说明hidden 1使tempNotes属性永远不会出现在 UI 中但正如 ObjectHints.md 强调的hidden只是 UI 提示渲染器不应据此把对象从渲染场景中隐藏——例如一个带此提示的 Gprim 仍应被渲染器绘制通过reorder properties控制属性与显示组在 UI 中的排列顺序见下文。各分组字段详解ObjectHints详见 ObjectHints.md字段USD 类型说明displayNamestring对象Prim 或属性在 UI 中呈现给用户的名称hiddenbool是否从 UI 中隐藏。仅用于 UI渲染器不应据此隐藏对象。对 PrimPixar 的做法是只隐藏对象自身的表示而不隐藏其子树并将子树在层级中上提一级对属性该提示与shownIf配合决定属性可见性PrimHints详见 PrimHints.md字段USD 类型说明displayGroupsExpandeddictionary以显示组名为键的字典指示某个显示组在 UI 中默认展开还是折叠displayGroupsShownIfdictionary以显示组名为键的字典值为基于SdfBooleanExpression的布尔表达式用于条件控制显示组是否出现在 UI 中PropertyHints详见 PropertyHints.md字段USD 类型说明displayGroupstring属性所属显示组的名称一个属性只能属于一个显示组可用 : 指定嵌套组shownIfstring基于SdfBooleanExpression的表达式控制属性是否显示。表达式为真时显示否则省略。与对象级hidden提示共同决定属性可见性AttributeHints详见 AttributeHints.md字段USD 类型说明valueLabelsdictionary以标签名为键的字典把 UI 标签映射到属性值valueLabelsOrdertoken[]指示值标签在 UI如下拉列表中的展示顺序的 token 数组对于 string/token 类型的属性还可以使用allowedTokens属性元数据定义允许的取值若同时使用valueLabels/valueLabelsOrder应保证 UI 提示值与该属性允许的 token 集合一致。此外属性支持值域限制UsdAttributeLimits可与属性 UI 提示配合在 UI 中提示用户哪些值是有效的。用 API 而非直接读元数据UI hints 以uiHints元数据字典形式编写但官方推荐优先使用 API访问与编写。这样做的关键收益是当某个 UI hint 未编写时API 会提供合理的回退值fallback而直接读取元数据只会得到None。以 overview.md 中的 Python 示例为例# PrimWithNoHints is a prim with an empty uiHints dictionary, e.g. # def PrimWithNoHints ( # uiHints {} # ) # { # } noHintsPrim stage.GetPrimAtPath(/PrimWithNoHints) hints UsdUI.ObjectHints(noHintsPrim) # APIs will return an empty string print(NoHints: DisplayName from objHints: hints.GetDisplayName()) metadata noHintsPrim.GetMetadata(uiHints) # Metadata.get returns None if metadata doesnt exist if metadata.get(displayName) is not None: print(NoHints: DisplayName from prim metadata: metadata.get(displayName))对一个uiHints为空的 PrimObjectHints.GetDisplayName()返回空字符串fallback而metadata.get(displayName)返回None。不过当编写自定义的 UI hint 键时直接访问uiHints元数据可能是必要的。在源码层面objectHints.h 中的ObjectHints类提供了GetDisplayName()、SetDisplayName()、SetHidden()等接口其注释明确说明SetDisplayName只写uiHints字典不会调用UsdObject::SetDisplayName即旧式独立元数据字段。Python 绑定对应文件为 wrapObjectHints.cppUsdUI模块在init.py 中导出。向后兼容提示displayName、hidden、displayGroup过去可以通过UsdObject/UsdProperty的独立元数据字段编写。UI hints API 在uiHints字典中找不到对应值时会向后兼容地查找这些独立字段。但今后不应再编写这些独立字段而应改用 UI hints API 或uiHints字典。显示组Display Groups与属性顺序UI Hints 使用显示组把属性组织成组然后在 UI 中作为一组显示。使用显示组是可选的但它有助于把相关联的属性聚合在一起便于高效访问。设置属性的显示组属性通过指定它所属的显示组来参与分组使用 UI hints API 设置property prim.GetProperty(myProperty) hints UsdUI.PropertyHints(property) hints.SetDisplayGroup(Custom Properties)显示组可以嵌套使用 : 分隔符。例如displayGroup为 GroupA:NestedGroup 的属性属于 NestedGroup 显示组而后者是 GroupA 显示组的子组。Prim 可以通过displayGroupsExpanded和displayGroupsShownIf两个 UI hints 控制显示组在 UI 中的呈现方式详见 PrimHints.md。控制属性的显示顺序属性通过Usd.Prim.GetProperties()之类的 API 获取时默认按字典序排列。要控制属性在 UI 中的一般顺序可以在 Prim 上通过Usd.Prim.SetPropertyOrder()API 设置属性顺序或在 USDA 中编写 reorder propertiesdef PropertyOrderPrim ( ) { reorder properties [attribute2, attribute4, attribute1, attribute3] int attribute1 1 int attribute2 2 int attribute3 3 int attribute4 4 }属性顺序同样作用于带显示组的属性。DCC 工具在排列显示组时应考虑属性顺序把显示组放在其第一个被属性引用的位置并按 Prim 的属性顺序排列组内属性。以下示例定义了一组属性、部分属性的显示组以及特定的属性顺序def PropertyOrderPrimWithDisplayGroups ( uiHints { string displayName Example dictionary displayGroupsExpanded { bool Group A 1 bool Group B 1 } } ) { reorder properties [attribute4, attribute2, attribute1, attribute3] int attribute1 1 ( uiHints { string displayGroup Group B } ) int attribute2 2 int attribute3 3 ( uiHints { string displayGroup Group B } ) int attribute4 4 ( uiHints { string displayGroup Group A } ) }其 UI 排列效果应类似下图Group A 中为 attribute4Group B 中为 attribute1、attribute3无组属性 attribute2 夹在中间整体遵循reorder properties的顺序注意既有的displayGroupOrderPrim 元数据字段已被视为弃用deprecated不应再与属性顺序、显示组相关的 UI hints 组合使用。条件 UI Hints布尔表达式某些 UI hints——例如 PropertyHints 的shownIf、PrimHints 的displayGroupsShownIf——使用布尔表达式字符串条件化地控制对象在 UI 中的显示。通常表达式用于测试包含该对象的 Prim 中某个属性的解析值。例如下面的 Prim 在materialHardness属性值小于等于 2.0 时显示 Deformation parameters 显示组而fractureAmount属性位于该显示组内只有在isFractured为 true 时才显示def PrimUsingExpressions ( uiHints { dictionary displayGroupsShownIf { string Deformation parameters materialHardness 2.0 } } ) { float bendAmount 0.0 ( uiHints { string displayGroup Deformation parameters string displayName Bend amount } ) float bendDirection 0.0 ( uiHints { string displayGroup Deformation parameters string displayName Bend direction } ) float fractureAmount 0.0 ( uiHints { string displayGroup Deformation parameters string displayName Fracture amount string shownIf isFractured true } ) float materialHardness 10.0 bool isFractured false }布尔表达式支持以下运算符运算符含义等于!不等于小于小于等于大于大于等于逻辑与\|\|逻辑或此外布尔表达式还支持一元非运算!以及括号()来分组与限定运算顺序。例如属性shownIf表达式可以写作!(status active || level 5)表示仅当status属性值不是 active且level属性值小于等于 5 时才显示该属性。hidden与shownIf是与的关系对象级hidden提示始终与shownIf一起被考虑。也就是说只要shownIf表达式求值为 false或者hidden提示为 true属性就不会在 UI 中显示。关于布尔表达式的更多信息可参考SdfBooleanExpression表达式实现位于 pxr/usd/sdf。仓库中的 testUsdUIHints.py 对 UI hints 的读取回退值、显示组嵌套、表达式求值等行为均有对应测试覆盖可作为理解 API 行为的参考。小结UsdUI 是 OpenUSD 面向界面呈现的一整套描述性 schema 体系其设计哲学是描述信息、不替应用做决定节点图SceneGraphPrimAPI提供节点名称与分组NodeGraphNodeAPI提供位置、颜色、图标、尺寸、展开状态与叠放层级Backdrop以纯视觉方式圈组节点三者共同让 DCC 工具把着色/材质网络可视化得清晰可读无障碍AccessibilityAPI以可多实例化的 label/description/priority 三元组向辅助运行时提供无障碍信息并配套了 default 命名空间、默认值、default prim/根级 Prim 等最佳实践UI 提示ObjectHints、PrimHints、PropertyHints、AttributeHints四个分组覆盖从对象通用属性显示名、隐藏到显示组组织、属性排序、值标签以及基于SdfBooleanExpression的条件显示控制全部以uiHints元数据编写、推荐用 API 访问以获得合理的回退值。无论是为材质编辑器、节点图工具提供布局提示还是为无障碍工具链补充场景语义UsdUI 都提供了标准、可移植、与工具无关的描述方式。建议继续阅读本目录下的 NodeGraphNodeAPI.md、SceneGraphPrimAPI.md、AccessibilityAPI.md 及 UI Hints 系列文档并结合 pxr/usd/usdUI 下的 schema 定义与测试用例深入实践。【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenUSD UsdUI 指南：用 Schema 描述节点图、无障碍信息与 UI 呈现提示
OpenUSD UsdUI 指南用 Schema 描述节点图、无障碍信息与 UI 呈现提示【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSDUsdUI 是 OpenUSDUniversal Scene Description中专门用于描述用户界面相关特性的 schema 域。本文以 UsdUI 概览文档 为主线系统讲解如何用SceneGraphPrimAPI、NodeGraphNodeAPI与Backdrop描述节点图如材质/着色网络的布局与外观用AccessibilityAPI为 Prim 提供无障碍信息以及用ObjectHints、PrimHints、PropertyHints、AttributeHints四组 UI 提示控制 Prim 与属性在 DCC 工具中的呈现方式。读完本文你将掌握 UsdUI 全部核心属性的含义、可直接复制的 USDA 示例以及基于布尔表达式的条件 UI 控制方案。UsdUI 是什么UsdUI schema 域源码位于 pxr/usd/usdUI提供了一系列与通用用户界面相关的 schema其核心定位是为呈现层提供提示hints而非直接驱动某个具体 UI 的实现。典型用途包括描述节点图node graph中节点的布局、颜色、尺寸、层级、图标等视觉信息帮助 DCC 工具把着色网络、材质网络这类复杂连接可视化得更容易理解描述用于辅助功能assistive UI的无障碍信息供语音控制、屏幕阅读器等运行时使用通过 UI 提示描述 Prim 和属性应该如何被呈现在 UI 中。需要强调的是UsdUI 只是描述信息最终如何呈现完全由消费这些信息的工具或应用决定。本文引用的 schema 定义与示例分别来自 overview.md、NodeGraphNodeAPI.md、SceneGraphPrimAPI.md、Backdrop.md、AccessibilityAPI.md 以及 UI Hints 系列文档schema 的底层定义可在 schema.usda 中查阅。使用 UsdUI 描述节点图节点图可以用来描述一组 Prim 构成的网络例如着色网络、材质网络。消费方如 DCC 工具可以据此把复杂网络可视化。UsdUI 提供三类工具来组织节点图SceneGraphPrimAPI为每个节点提供描述性名称与分组NodeGraphNodeAPI定义每个节点在节点图中的外观位置、颜色、图标、尺寸、层级等Backdrop以视觉方式如彩色矩形圈出一组节点并给出该分组的说明。SceneGraphPrimAPI节点的名称与分组SceneGraphPrimAPI让每个节点携带一个描述性名称ui:displayName和一个描述性分组ui:displayGroup。从 SceneGraphPrimAPI.md 中的示例可以看到它通过prepend apiSchemas [SceneGraphPrimAPI]挂到 Shader Prim 上def Material MyMaterial { token outputs:mtlx:surface.connect /World/MyMaterial/PreviewSurface.outputs:out def Shader PreviewSurface ( prepend apiSchemas [SceneGraphPrimAPI] ) { uniform token info:id ND_UsdPreviewSurface_surfaceshader color3f inputs:diffuseColor.connect /World/MyMaterial/Color.outputs:out token outputs:out uniform token ui:displayGroup MyMaterial Nodes uniform token ui:displayName Preview Surface Node } def Shader Color ( prepend apiSchemas [SceneGraphPrimAPI] ) { uniform token info:id ND_constant_color3 color3f inputs:value (1, 0.023, 0.701) color3f outputs:out uniform token ui:displayGroup MyMaterial Nodes uniform token ui:displayName Color Node } }该 schema 的两个属性均为token类型属性USD 类型说明ui:displayGrouptoken节点所属分组的描述性名称。它可能与该节点其他的 USD 分组特性如所属 Scope 名、父 Prim 名无关ui:displayNametoken节点在其连接的节点图语境中的描述性名称可以与 Prim 自身的核心 displayName 不同NodeGraphNodeAPI节点的位置与外观NodeGraphNodeAPI定义了节点在节点图中的呈现信息包括位置、颜色、文档链接、展开状态、图标、尺寸与相对深度。下表汇总了 NodeGraphNodeAPI.md 中定义的属性属性USD 类型说明ui:nodegraph:node:displayColorcolor3f节点的颜色ui:nodegraph:node:docURIstring指向该节点文档的 URI 链接ui:nodegraph:node:expansionStatetoken节点当前显示的信息量状态取值为open、closed或minimizedui:nodegraph:node:iconasset用于标识节点用途的图像。它描述的是节点本身而非节点动作的结果例如 Add 节点可以用 号图标ui:nodegraph:node:posfloat2节点的 x,y 坐标位置ui:nodegraph:node:sizefloat2节点可选的 x,y 像素尺寸。可选是因为节点尺寸也可以由其输入输出数量自动生成ui:nodegraph:node:stackingOrderint节点重叠时的显示层级stackingOrder值越大的节点绘制在越上层关于ui:nodegraph:node:pos有两点重要约定单位不是像素假定典型节点的尺寸为 1.0×1.0坐标描述的是相对节点大小的位置关系Y 轴正方向向下例如 -1.0 高于 1.0位置是相对于父节点的如果存在父节点。NodeGraphNodeAPI.md给出了一个包含全部属性的完整示例注意其中PreviewSurface为红色、open展开状态且尺寸更大而Color为蓝色、closed状态若两者重叠stackingOrder更大的Color会绘制在上方def Material MyMaterial { token outputs:mtlx:surface.connect /World/MyMaterial/PreviewSurface.outputs:out def Shader PreviewSurface { uniform token info:id ND_UsdPreviewSurface_surfaceshader color3f inputs:diffuseColor.connect /World/MyMaterial/Color.outputs:out token outputs:out uniform color3f ui:nodegraph:node:displayColor (1.0, 0.0, 0.0) uniform string ui:nodegraph:node:docURI https://openusd.org/release/spec_usdpreviewsurface.html uniform token ui:nodegraph:node:expansionState open uniform asset ui:nodegraph:node:icon preview_surface_icon.png uniform float2 ui:nodegraph:node:pos (-0.85, 1.9) uniform float2 ui:nodegraph:node:size (300.0, 400.0) uniform int ui:nodegraph:node:stackingOrder 1 } def Shader Color { uniform token info:id ND_constant_color3 color3f inputs:value (1.0, 0.023, 0.701) color3f outputs:out uniform color3f ui:nodegraph:node:displayColor (0.0, 0.0, 1.0) uniform string ui:nodegraph:node:docURI docURI uniform token ui:nodegraph:node:expansionState closed uniform asset ui:nodegraph:node:icon color_icon.png uniform float2 ui:nodegraph:node:pos (-2, 2) uniform float2 ui:nodegraph:node:size (100.0, 200.0) uniform int ui:nodegraph:node:stackingOrder 2 } }注意UsdUI 不做属性同步。USD 不会把displayColor、pos等节点属性与其它 schema 中的同名属性例如 GPrim 的primvars:displayColor自动同步。如果应用希望二者保持一致需要由实现节点显示的应用自行处理。Backdrop视觉化分组Backdrop提供一种把节点视觉圈起来的方式并附带对该分组的说明。与SceneGraphPrimAPI.displayGroup不同Backdrop 与节点之间没有直接关联——某个 Shader 节点是否属于某个 Backdrop按 schema.usda 中的约定是由节点图 UI 根据Shader 节点的包围盒是否恰好放进最小的 Backdrop来判断的。Backdrop 的视觉尺寸与位置同样使用NodeGraphNodeAPI的属性来决定。从 Backdrop.md 的示例可以直观理解其坐标语义def Material MyMaterial { token outputs:mtlx:surface.connect /World/Material/PreviewSurface.outputs:out def Shader PreviewSurface ( prepend apiSchemas [NodeGraphNodeAPI] ) { uniform token info:id ND_UsdPreviewSurface_surfaceshader color3f inputs:diffuseColor.connect /World/Material/Color.outputs:out token outputs:out uniform float2 ui:nodegraph:node:pos (-0.85, 1.9) } def Shader Color ( prepend apiSchemas [NodeGraphNodeAPI] ) { uniform token info:id ND_constant_color3 color3f inputs:value (1, 0.023, 0.701) color3f outputs:out uniform float2 ui:nodegraph:node:pos (-2, 2) } def Backdrop Backdrop ( prepend apiSchemas [NodeGraphNodeAPI] ) { uniform token ui:description MyMaterial Nodes uniform color3f ui:nodegraph:node:displayColor (1, 0, 0) uniform float2 ui:nodegraph:node:pos (-0.8, 0.5) uniform float2 ui:nodegraph:node:size (450, 330) } }观察这个例子Backdrop 的 x 起点为 -0.8PreviewSurface为 -0.85Color为 -2.0Backdrop 宽 450典型节点可能约 200px 宽足以覆盖两个节点y 坐标为 0.5、1.9、2而 Y 坐标向下递增因此 Backdrop 位于两个节点上方并向下延伸 330。Backdrop 的说明文字由ui:descriptiontoken类型提供例如用 Noise 说明一组节点共同参与噪声生成。综合示例一个完整的节点图overview.md 给出了一个综合场景假定应用中有一个如下图所示open 展开的 PreviewSurface、closed 收起的 Color 节点、以及一个写着 Do not edit! 的绿色 Backdrop的节点图对应的 USD 表示为def Material Material { token outputs:mtlx:surface.connect /World/Material/PreviewSurface.outputs:out def Shader PreviewSurface ( prepend apiSchemas [NodeGraphNodeAPI] ) { uniform token info:id ND_UsdPreviewSurface_surfaceshader color3f inputs:diffuseColor.connect /World/Material/Color.outputs:out token outputs:out uniform color3f ui:nodegraph:node:displayColor (0.780, 0.698, 0.6) uniform token ui:nodegraph:node:expansionState open uniform float2 ui:nodegraph:node:pos (-.85, 1.9) } def Shader Color ( prepend apiSchemas [NodeGraphNodeAPI] ) { uniform token info:id ND_constant_color3 color3f inputs:value (1, 0.023, 0.701) color3f outputs:out uniform color3f ui:nodegraph:node:displayColor (0.549, 0.133, 1.0) uniform token ui:nodegraph:node:expansionState closed uniform float2 ui:nodegraph:node:pos (-2, 2) } def Backdrop Backdrop ( prepend apiSchemas [NodeGraphNodeAPI] ) { uniform token ui:description Do not edit! uniform color3f ui:nodegraph:node:displayColor (0.764, 1.0, 0.698) uniform float2 ui:nodegraph:node:pos (-0.8, 0.5) uniform float2 ui:nodegraph:node:size (450, 330) } }从这个例子可以观察到几个关键点ui:nodegraph:node:displayColor帮助快速区分不同类型的节点Backdrop 的ui:description可以为节点图中的区域分组提供上下文说明例如 Do not edit!ui:nodegraph:node:expansionState控制节点显示的信息量——对比PreviewSurface与Color的信息密度差异ui:nodegraph:node:size与ui:nodegraph:node:pos决定节点在节点图中的放置位置与相对布局。在源码层面Backdrop类定义于 schema.usda其文档明确指出Backdrop 只是组织工具不包含 Shader 节点、没有影响渲染结果的输入输出导入时可以被安全忽略但 Backdrop 与 Shader、NodeGraph 一样订阅NodeGraphNodeAPI来指定位置与尺寸。仓库中的 testUsdUIBackdrop.py、testUsdUINodeGraphNode.py 等测试用例覆盖了这些 API 的读写行为。使用 AccessibilityAPI 描述无障碍信息AccessibilityAPIschema 在 Prim 上描述无障碍信息这些信息可以被暴露给某个运行时的无障碍框架accessibility frameworks供语音控制、屏幕阅读器等辅助功能使用。其源码定义同样位于 schema.usda实现为 multiple apply APIapiSchemaType multipleApply属性命名空间前缀为accessibility。无障碍信息以标准的label标签、description描述、priority优先级三元组提供。由于它是 multiple apply schema一个 Prim 上可以有多个带命名空间的三元组实例名可以反映该三元组的用途。以下示例为一个 Mesh 提供了 default 与 size 两组无障碍三元组def Mesh Cube ( prepend apiSchemas [AccessibilityAPI:default, AccessibilityAPI:size] ) { string accessibility:default:label Regular cube string accessibility:default:description A plain featureless cube token accessibility:default:priority standard string accessibility:size:label Regular sized cube string accessibility:size:description A 4-meter featureless cube token accessibility:size:priority low }三个属性的语义详见 AccessibilityAPI.md属性USD 类型说明labelstring简洁描述 Prim 的短标签。不建议随时间变化除非简明描述发生重大变化没有建议的固定长度但应保持精炼descriptionstring提供更多细节的扩展描述可选属性某些无障碍系统可能只使用 label。若某个实例名未编写 label则不应以 description 代替。description 可以随时间变化如描述角色在某一时刻的动作prioritytoken提示运行时如何相对其他实例排序本实例的 label 与 description。允许的取值是low、standard、high回退值为standard。该属性可选、可被运行时忽略且不允许随时间变化AccessibilityAPI.md 还给出了几条重要的最佳实践大多数无障碍运行时只支持单一的无障碍描述因此建议把关键信息放在名为 default 的命名空间中如果使用时间采样time sampled的无障碍信息应编写一个默认值以兼容当前不支持时间采样信息的运行时建议在层的 default prim 以及所有根级 Prim上提供场景的无障碍信息这既能帮助无障碍系统向用户提供简洁的场景描述也能兼容不支持层级信息、或用户关闭了该粒度信息层的无障碍系统。当然层级中其他 Prim 也可以继续提供无障碍信息。需要说明的是除上述约定外无障碍信息不会沿 Prim 层级隐式继承继承行为应交由无障碍运行时自行决定如何呈现给用户。仓库中的 testUsdUIAccessibilityAPI.cpp 对该 multiple apply API 的创建、属性读写进行了验证。使用 UI Hints 描述 UI 呈现方式UsdUI 提供了一组 schema 风格的 APIUI hints用于在 Prim 和属性上编写 UI 提示告诉 DCC 工具或其他应用 UI应该怎样呈现该 Prim 或属性。UI 提示以**元数据metadata**形式编写在uiHints字典中不需要应用任何 schema 即可访问或编写这与节点图 API 需要通过prepend apiSchemas挂接不同。UI hints 目前分为以下分组分组适用范围核心字段ObjectHints适用于任何 Prim 或属性的通用 UI 提示displayName、hiddenPrimHintsPrim 级 UI 提示控制显示组display groups如何、何时显示displayGroupsExpanded、displayGroupsShownIfPropertyHints属性级 UI 提示如属性所属的显示组、是否显示displayGroup、shownIfAttributeHints属性级 UI 提示如属性值的 UI 标签及其显示顺序valueLabels、valueLabelsOrder注意不存在单独的 RelationshipHints 分组——没有仅适用于 relationship 的独特提示。提示是建议而非强制。UI hints 只是关于如何在 UI 中呈现 Prim/属性的建议最终呈现方式由实现 UI 的工具或应用决定。一个完整的 UI Hints 示例overview.md 用一个 TreeA 示例展示了四个分组的典型用法#usda 1.0 def TreeA ( uiHints { # ObjectHints hints string displayName Tree template # PrimHints hints dictionary displayGroupsExpanded { bool Trunk settings 1 bool Body settings 1 bool Body settings:Branch settings 0 bool Body settings:Leaf settings 1 } dictionary displayGroupsShownIf { string Body settings:Leaf settings trunkSize ! 1 } } ) { color3f trunkColor (0.6, 0.3, 0.0) ( uiHints { # ObjectHints hints string displayName color # PropertyHints hints string displayGroup Trunk settings } ) int trunkSize 2 ( uiHints { # ObjectHints hints string displayName size # PropertyHints hints string displayGroup Trunk settings # AttributeHints hints dictionary valueLabels { int huge 3 int sapling 1 int standard 2 } token[] valueLabelsOrder [sapling, standard, huge] } ) float bodyRadius 5.0 ( uiHints { # ObjectHints hints string displayName size # PropertyHints hints string displayGroup Body settings } ) float branchDensity 1.0 ( uiHints { # ObjectHints hints string displayName density # PropertyHints hints string displayGroup Body settings:Branch settings } ) float branchLength 5.0 ( uiHints { # ObjectHints hints string displayName length # PropertyHints hints string displayGroup Body settings:Branch settings } ) color3f leafColor (0.4, 0.7, 0.25) ( uiHints { # ObjectHints hints string displayName color # PropertyHints hints string displayGroup Body settings:Leaf settings } ) float leafComplexity 1.0 ( uiHints { # ObjectHints hints string displayName complexity # PropertyHints hints string displayGroup Body settings:Leaf settings string shownIf leafStyle 1 } ) int leafStyle 1 ( uiHints { # ObjectHints hints string displayName style # PropertyHints hints string displayGroup Body settings:Leaf settings # AttributeHints hints dictionary valueLabels { int acute 1 int obtuse 2 int truncate 3 } token[] valueLabelsOrder [acute, obtuse, truncate] } ) string tempNotes ( uiHints { # We never want to show this attribute in the UI bool hidden 1 } ) # Use property re-ordering to control UI order of properties and # display groups reorder properties [trunkColor, trunkSize, bodyRadius, branchDensity, branchLength, leafColor, leafStyle, leafComplexity] }该示例对应的 UI 呈现效果如下图所示关于该示例还有两点值得说明hidden 1使tempNotes属性永远不会出现在 UI 中但正如 ObjectHints.md 强调的hidden只是 UI 提示渲染器不应据此把对象从渲染场景中隐藏——例如一个带此提示的 Gprim 仍应被渲染器绘制通过reorder properties控制属性与显示组在 UI 中的排列顺序见下文。各分组字段详解ObjectHints详见 ObjectHints.md字段USD 类型说明displayNamestring对象Prim 或属性在 UI 中呈现给用户的名称hiddenbool是否从 UI 中隐藏。仅用于 UI渲染器不应据此隐藏对象。对 PrimPixar 的做法是只隐藏对象自身的表示而不隐藏其子树并将子树在层级中上提一级对属性该提示与shownIf配合决定属性可见性PrimHints详见 PrimHints.md字段USD 类型说明displayGroupsExpandeddictionary以显示组名为键的字典指示某个显示组在 UI 中默认展开还是折叠displayGroupsShownIfdictionary以显示组名为键的字典值为基于SdfBooleanExpression的布尔表达式用于条件控制显示组是否出现在 UI 中PropertyHints详见 PropertyHints.md字段USD 类型说明displayGroupstring属性所属显示组的名称一个属性只能属于一个显示组可用 : 指定嵌套组shownIfstring基于SdfBooleanExpression的表达式控制属性是否显示。表达式为真时显示否则省略。与对象级hidden提示共同决定属性可见性AttributeHints详见 AttributeHints.md字段USD 类型说明valueLabelsdictionary以标签名为键的字典把 UI 标签映射到属性值valueLabelsOrdertoken[]指示值标签在 UI如下拉列表中的展示顺序的 token 数组对于 string/token 类型的属性还可以使用allowedTokens属性元数据定义允许的取值若同时使用valueLabels/valueLabelsOrder应保证 UI 提示值与该属性允许的 token 集合一致。此外属性支持值域限制UsdAttributeLimits可与属性 UI 提示配合在 UI 中提示用户哪些值是有效的。用 API 而非直接读元数据UI hints 以uiHints元数据字典形式编写但官方推荐优先使用 API访问与编写。这样做的关键收益是当某个 UI hint 未编写时API 会提供合理的回退值fallback而直接读取元数据只会得到None。以 overview.md 中的 Python 示例为例# PrimWithNoHints is a prim with an empty uiHints dictionary, e.g. # def PrimWithNoHints ( # uiHints {} # ) # { # } noHintsPrim stage.GetPrimAtPath(/PrimWithNoHints) hints UsdUI.ObjectHints(noHintsPrim) # APIs will return an empty string print(NoHints: DisplayName from objHints: hints.GetDisplayName()) metadata noHintsPrim.GetMetadata(uiHints) # Metadata.get returns None if metadata doesnt exist if metadata.get(displayName) is not None: print(NoHints: DisplayName from prim metadata: metadata.get(displayName))对一个uiHints为空的 PrimObjectHints.GetDisplayName()返回空字符串fallback而metadata.get(displayName)返回None。不过当编写自定义的 UI hint 键时直接访问uiHints元数据可能是必要的。在源码层面objectHints.h 中的ObjectHints类提供了GetDisplayName()、SetDisplayName()、SetHidden()等接口其注释明确说明SetDisplayName只写uiHints字典不会调用UsdObject::SetDisplayName即旧式独立元数据字段。Python 绑定对应文件为 wrapObjectHints.cppUsdUI模块在init.py 中导出。向后兼容提示displayName、hidden、displayGroup过去可以通过UsdObject/UsdProperty的独立元数据字段编写。UI hints API 在uiHints字典中找不到对应值时会向后兼容地查找这些独立字段。但今后不应再编写这些独立字段而应改用 UI hints API 或uiHints字典。显示组Display Groups与属性顺序UI Hints 使用显示组把属性组织成组然后在 UI 中作为一组显示。使用显示组是可选的但它有助于把相关联的属性聚合在一起便于高效访问。设置属性的显示组属性通过指定它所属的显示组来参与分组使用 UI hints API 设置property prim.GetProperty(myProperty) hints UsdUI.PropertyHints(property) hints.SetDisplayGroup(Custom Properties)显示组可以嵌套使用 : 分隔符。例如displayGroup为 GroupA:NestedGroup 的属性属于 NestedGroup 显示组而后者是 GroupA 显示组的子组。Prim 可以通过displayGroupsExpanded和displayGroupsShownIf两个 UI hints 控制显示组在 UI 中的呈现方式详见 PrimHints.md。控制属性的显示顺序属性通过Usd.Prim.GetProperties()之类的 API 获取时默认按字典序排列。要控制属性在 UI 中的一般顺序可以在 Prim 上通过Usd.Prim.SetPropertyOrder()API 设置属性顺序或在 USDA 中编写 reorder propertiesdef PropertyOrderPrim ( ) { reorder properties [attribute2, attribute4, attribute1, attribute3] int attribute1 1 int attribute2 2 int attribute3 3 int attribute4 4 }属性顺序同样作用于带显示组的属性。DCC 工具在排列显示组时应考虑属性顺序把显示组放在其第一个被属性引用的位置并按 Prim 的属性顺序排列组内属性。以下示例定义了一组属性、部分属性的显示组以及特定的属性顺序def PropertyOrderPrimWithDisplayGroups ( uiHints { string displayName Example dictionary displayGroupsExpanded { bool Group A 1 bool Group B 1 } } ) { reorder properties [attribute4, attribute2, attribute1, attribute3] int attribute1 1 ( uiHints { string displayGroup Group B } ) int attribute2 2 int attribute3 3 ( uiHints { string displayGroup Group B } ) int attribute4 4 ( uiHints { string displayGroup Group A } ) }其 UI 排列效果应类似下图Group A 中为 attribute4Group B 中为 attribute1、attribute3无组属性 attribute2 夹在中间整体遵循reorder properties的顺序注意既有的displayGroupOrderPrim 元数据字段已被视为弃用deprecated不应再与属性顺序、显示组相关的 UI hints 组合使用。条件 UI Hints布尔表达式某些 UI hints——例如 PropertyHints 的shownIf、PrimHints 的displayGroupsShownIf——使用布尔表达式字符串条件化地控制对象在 UI 中的显示。通常表达式用于测试包含该对象的 Prim 中某个属性的解析值。例如下面的 Prim 在materialHardness属性值小于等于 2.0 时显示 Deformation parameters 显示组而fractureAmount属性位于该显示组内只有在isFractured为 true 时才显示def PrimUsingExpressions ( uiHints { dictionary displayGroupsShownIf { string Deformation parameters materialHardness 2.0 } } ) { float bendAmount 0.0 ( uiHints { string displayGroup Deformation parameters string displayName Bend amount } ) float bendDirection 0.0 ( uiHints { string displayGroup Deformation parameters string displayName Bend direction } ) float fractureAmount 0.0 ( uiHints { string displayGroup Deformation parameters string displayName Fracture amount string shownIf isFractured true } ) float materialHardness 10.0 bool isFractured false }布尔表达式支持以下运算符运算符含义等于!不等于小于小于等于大于大于等于逻辑与\|\|逻辑或此外布尔表达式还支持一元非运算!以及括号()来分组与限定运算顺序。例如属性shownIf表达式可以写作!(status active || level 5)表示仅当status属性值不是 active且level属性值小于等于 5 时才显示该属性。hidden与shownIf是与的关系对象级hidden提示始终与shownIf一起被考虑。也就是说只要shownIf表达式求值为 false或者hidden提示为 true属性就不会在 UI 中显示。关于布尔表达式的更多信息可参考SdfBooleanExpression表达式实现位于 pxr/usd/sdf。仓库中的 testUsdUIHints.py 对 UI hints 的读取回退值、显示组嵌套、表达式求值等行为均有对应测试覆盖可作为理解 API 行为的参考。小结UsdUI 是 OpenUSD 面向界面呈现的一整套描述性 schema 体系其设计哲学是描述信息、不替应用做决定节点图SceneGraphPrimAPI提供节点名称与分组NodeGraphNodeAPI提供位置、颜色、图标、尺寸、展开状态与叠放层级Backdrop以纯视觉方式圈组节点三者共同让 DCC 工具把着色/材质网络可视化得清晰可读无障碍AccessibilityAPI以可多实例化的 label/description/priority 三元组向辅助运行时提供无障碍信息并配套了 default 命名空间、默认值、default prim/根级 Prim 等最佳实践UI 提示ObjectHints、PrimHints、PropertyHints、AttributeHints四个分组覆盖从对象通用属性显示名、隐藏到显示组组织、属性排序、值标签以及基于SdfBooleanExpression的条件显示控制全部以uiHints元数据编写、推荐用 API 访问以获得合理的回退值。无论是为材质编辑器、节点图工具提供布局提示还是为无障碍工具链补充场景语义UsdUI 都提供了标准、可移植、与工具无关的描述方式。建议继续阅读本目录下的 NodeGraphNodeAPI.md、SceneGraphPrimAPI.md、AccessibilityAPI.md 及 UI Hints 系列文档并结合 pxr/usd/usdUI 下的 schema 定义与测试用例深入实践。【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考