OpenUSD usdUI AccessibilityAPI 指南：用 label / description / priority 三元组为场景构建无障碍信息

OpenUSD usdUI AccessibilityAPI 指南用 label / description / priority 三元组为场景构建无障碍信息【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD导读UsdUIAccessibilityAPI即AccessibilityAPI是 OpenUSDusdUI库中负责在 Prim 上描述无障碍Accessibility信息的 API Schema。它并不自带无障碍运行时而是以标准的标签label、描述description、优先级priority三元组形式为语音控制、屏幕阅读器等辅助工具assistive tooling提供提取与呈现所需的场景信息。读完本文你将掌握该 Schema 的 USDA 编写语法、多实例multiple apply用法、C / Python 读写 API以及官方推荐的落地最佳实践。一、AccessibilityAPI 是什么在 OpenUSD 的usdUI领域pxr/usd/usdUI中AccessibilityAPI用于在 Prim 上记录可被特定运行时无障碍框架读取的信息供语音控制voice controls、屏幕阅读器screen readers等辅助工具使用。需要特别强调的是OpenUSD 本身不提供无障碍运行时它只负责把无障碍运行时需要的原料——即描述性信息——以标准格式组织并存储下来交由兼容的运行时去提取与呈现。这一点在 Schema 文档docs/user_guides/schemas/usdUI/AccessibilityAPI.md与源码注释pxr/usd/usdUI/accessibilityAPI.h中均有明确说明。AccessibilityAPI继承自UsdAPISchemaBase属于MultipleApplyAPI多实例应用型 API Schema即同一 Prim 上可以同时存在多个命名空间实例见 pxr/usd/usdUI/accessibilityAPI.h 中的schemaKind UsdSchemaKind::MultipleApplyAPI。二、核心三元组label / description / priority无障碍信息由三个属性组成一个标准三元组属性统一使用accessibility作为属性命名空间前缀属性USD 类型默认值说明labelstring无对 Prim 的简短、精炼标签descriptionstring无对 Prim 的扩展描述提供更多细节prioritytokenstandard给无障碍运行时的优先级提示可选值low、standard、high2.1 label标签用途用一句话简明扼要地描述该 Prim。不建议随时间变化time vary除非该 Prim 的简明描述发生了实质性改变。官方对长度没有硬性建议但推荐保持简洁见 pxr/usd/usdUI/accessibilityAPI.h。2.2 description描述用途提供更详尽的扩展描述。约束如果某个实例名instance name下没有编写label则不应以description代替label使用description是可选属性部分无障碍系统可能只读取label。允许随时间变化对于支持时间采样time sampled信息的运行时可以通过不同时间点描述角色的不同动作例如角色正在奔跑角色正在跳跃。2.3 priority优先级用途向无障碍运行时提示该实例的 label / description 相对于其他实例的优先级。允许的 token 值low、standard、high见 pxr/usd/usdUI/schema.usda 中的allowedTokens。回退值fallback valuestandard。该属性是可选的且仅是一个提示运行时可以忽略它例如当运行时认为有其他更优先的需求时可以不采纳该优先级。priority 不允许随时间变化may not be time varying。属性定义细节可在生成的 C 头文件中找到GetLabelAttr()/CreateLabelAttr()、GetDescriptionAttr()/CreateDescriptionAttr()、GetPriorityAttr()/CreatePriorityAttr()见 pxr/usd/usdUI/accessibilityAPI.h。三、USDA 编写示例以下代码块来自官方文档演示如何在MeshPrim 上挂载一个default实例的 AccessibilityAPIdef Mesh Cube ( prepend apiSchemas [AccessibilityAPI:default] ) { string accessibility:default:label Luxo, Jr string accessibility:default:description The lamp has round base with two sections above it that may be adjusted. It has a conical head with a lightbulb inside. It likes to chase inflatable balls. token accessibility:default:priority standard }可以看到apiSchemas中写入AccessibilityAPI:default表示应用一个名为default的实例属性命名遵循accessibility:实例名:属性名的规则即accessibility:default:label、accessibility:default:description、accessibility:default:priority。四、多实例Multiple Apply与命名空间三元组由于AccessibilityAPI是 multiple apply schema同一个 Prim 可以携带多个命名空间三元组实例名用来表达该三元组的使用目的。例如你可能希望对 Prim 的尺寸颜色等不同方面分别给出不同的无障碍信息。pxr/usd/usdUI/userDoc/overview.md 中给出了同时使用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 }实例名的解析规则从源码实现看pxr/usd/usdUI/accessibilityAPI.cppIsAccessibilityAPIPath()负责识别某条属性路径是否属于 AccessibilityAPI路径必须是属性路径IsPropertyPath对属性名按标识符分词后最后一个 token 不能是 Schema 的基名属性label / description / priority 之一当分词结果 2 且第一个 token 等于accessibility时属性名中accessibility:之后的字符串即被视为实例名。也就是说accessibility:foo:label会被解析为实例名foo这正对应测试中namedAPI Apply(prim, TfToken(foo))后创建的accessibility:foo:label等属性见 pxr/usd/usdUI/testenv/testUsdUIAccessibilityAPI.cpp。五、官方推荐的最佳实践官方文档总结了三条针对该 Schema 的使用规范docs/user_guides/schemas/usdUI/AccessibilityAPI.md1. 关键信息使用default命名空间大多数无障碍运行时只支持单个无障碍描述。因此任何关键信息都应写在名为default的实例中以保证被绝大多数运行时读取。2. 使用时间采样信息时务必编写默认值如果使用时间采样的无障碍信息必须同时编写一个默认值default value。这是为了兼容那些目前不支持时间采样信息的无障碍运行时——它们会退回到读取默认值。3. 在 layer 的默认 Prim 与根级 Prim 上提供无障碍信息建议在 layer 的默认 Primdefault prim及所有根级root levelPrim 上提供场景的无障碍信息。这样做有两个好处无障碍系统可以据此向用户提供简洁的整场景描述能够兼容两类运行时不支持层级信息的运行时以及用户关闭了层级粒度显示的运行时。当然层级中其他 Prim 上依然可以继续提供无障碍信息。关于继承的特别说明在默认 Prim 和根级 Prim 上编写场景无障碍描述只是一个推荐约定。除此之外无障碍信息不会通过 Prim 层级隐式继承not implicitly inherited through a prim hierarchy。是否以及如何向上/向下传递信息应当交由无障碍运行时自行决定如何向用户呈现。六、C API 使用UsdUIAccessibilityAPI的 C 接口围绕获取 / 创建属性展开。核心静态方法与成员方法如下见 pxr/usd/usdUI/accessibilityAPI.hAPI作用Get(stage, path)/Get(prim, name)获取指定路径或 Prim 上的 Schema 实例GetAll(prim)返回 Prim 上所有命名实例Apply(prim, name)以指定实例名应用 SchemaApplyDefaultAPI(prim)以default实例名应用 SchemaCreateDefaultAPI(prim)以default实例名构造 Schema 对象CanApply(prim, name, whyNot)检查 Schema 能否应用到该 PrimGetLabelAttr()/CreateLabelAttr()获取 / 创建 label 属性GetDescriptionAttr()/CreateDescriptionAttr()获取 / 创建 description 属性GetPriorityAttr()/CreatePriorityAttr()获取 / 创建 priority 属性Apply的实现是把AccessibilityAPI:name追加到 Prim 的apiSchemaslistOp 元数据中见 pxr/usd/usdUI/accessibilityAPI.h。ApplyDefaultAPI则是在此基础上固定使用defaulttoken 作为实例名见 pxr/usd/usdUI/accessibilityAPI.cpp。#include pxr/usd/usd/stage.h #include pxr/usd/usdUI/accessibilityAPI.h auto stage UsdStage::CreateInMemory(); auto prim stage-DefinePrim(SdfPath(/Root)); // 应用 default 实例并写入三元组 auto api UsdUIAccessibilityAPI::ApplyDefaultAPI(prim); api.CreateLabelAttr(VtValue(The root prim)); api.CreateDescriptionAttr(VtValue(The greatest prim of all time)); api.CreatePriorityAttr(VtValue(UsdUITokens-high));七、Python API 使用usdUI通过 pxr/usd/usdUI/wrapAccessibilityAPI.cpp 导出 Python 绑定模块名为UsdUI.AccessibilityAPI。可用的 Python 方法与 C 一一对应from pxr import Usd, UsdUI stage Usd.Stage.CreateInMemory() prim stage.DefinePrim(/Root) # 应用 default 实例 api UsdUI.AccessibilityAPI.ApplyDefaultAPI(prim) api.CreateLabelAttr(The root prim) api.CreateDescriptionAttr(The greatest prim of all time) api.CreatePriorityAttr(UsdUI.Tokens.high) # 应用具名实例 named UsdUI.AccessibilityAPI.Apply(prim, size) named.CreateLabelAttr(Regular sized cube) # 枚举 Prim 上所有实例 for inst in UsdUI.AccessibilityAPI.GetAll(prim): print(inst.GetName(), inst.GetLabelAttr().Get())其中UsdUI.Tokens提供了accessibility、accessibility:__INSTANCE_NAME__:label/:description/:priority模板 token、low/standard/high等预声明 token见 pxr/usd/usdUI/tokens.h。八、源码级佐证Schema 定义与测试Schema 定义AccessibilityAPI的权威定义位于 pxr/usd/usdUI/schema.usdaclass AccessibilityAPI ( inherits /APISchemaBase ... customData { token apiSchemaType multipleApply token propertyNamespacePrefix accessibility ... } ) { string label ( ... ) string description ( ... ) token priority standard ( allowedTokens [low, standard, high] ) }从定义可见apiSchemaType multipleApply决定了它是多实例 APIpropertyNamespacePrefix accessibility决定了属性的命名空间前缀而priority的allowedTokens与默认值standard决定了合法取值。生成的头文件pxr/usd/usdUI/accessibilityAPI.h和实现pxr/usd/usdUI/accessibilityAPI.cpp均由schema.usda通过代码生成器产出该文档头部也标注了 GENERATED BY genSchemaDocs。测试验证仓库自带的测试 pxr/usd/usdUI/testenv/testUsdUIAccessibilityAPI.cpp 验证了以下关键行为ApplyDefaultAPI(prim)创建出的属性名精确为accessibility:default:label、accessibility:default:description、accessibility:default:priorityApply(prim, TfToken(foo))创建出的属性名为accessibility:foo:label等写入的值可以被Get完整读回且类型正确std::string与TfToken。这为多实例命名 三元组属性的行为提供了直接的可执行验证。九、适用场景与边界适用场景为 3D 场景中的角色、道具、灯光等 Prim 编写屏幕阅读器可读的说明为语音控制提供可朗读/可识别的对象标签为不支持层级信息的辅助系统提供根级整场景描述利用description的时间采样能力描述角色随时间变化的动作。边界与注意AccessibilityAPI只负责信息的存储与组织不提供无障碍运行时也不负责信息呈现无障碍信息不会沿 Prim 层级隐式继承层级继承策略由运行时决定priority仅是提示运行时可以忽略description不能脱离label单独承担描述职责时间采样信息必须搭配默认值编写以兼容不支持时间采样的运行时。相关资源Schema 用户文档docs/user_guides/schemas/usdUI/AccessibilityAPI.mdSchema 权威定义代码生成源pxr/usd/usdUI/schema.usdaC 头文件pxr/usd/usdUI/accessibilityAPI.hC 实现pxr/usd/usdUI/accessibilityAPI.cppPython 绑定pxr/usd/usdUI/wrapAccessibilityAPI.cppToken 定义pxr/usd/usdUI/tokens.h测试用例pxr/usd/usdUI/testenv/testUsdUIAccessibilityAPI.cppusdUI 总览pxr/usd/usdUI/userDoc/overview.md【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考