OpenUSD 教程：检查与编写 Prim 属性（Inspecting and Authoring Properties）

OpenUSD 教程检查与编写 Prim 属性Inspecting and Authoring Properties【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD本篇指南基于 OpenUSD 官方教程 tut_inspect_and_author_props.rst带你使用 Python API 完成对场景中 Prim 的几何属性检查—读取—修改—着色—保存的完整闭环。读完后你将掌握如何用UsdPrim枚举一个 Prim 的全部属性名如何用Usd.Attribute读取回退fallback值并写入新值如何用UsdGeom一级 Schema API 编写displayColor以及如何将修改导回 USD 层文件。起始层HelloWorld.usda本练习的起点是 Hello World 教程中创建的场景文件位于 HelloWorld.usda。其内容为#usda 1.0 def Xform hello { def Sphere world { } }可以看到/hello是一个 Xform其子 Prim/hello/world是一个 Sphere且没有显式编写任何几何属性——这正是理解回退值概念的绝佳起点。教程中对应的可运行脚本是 authorProperties.py每一步操作都可在 Python 交互环境中对照执行。第一步打开 Stage 并获取 Primfrom pxr import Usd, Vt stage Usd.Stage.Open(HelloWorld.usda) xform stage.GetPrimAtPath(/hello) sphere stage.GetPrimAtPath(/hello/world)Usd.Stage.Open按路径打开 USD 文件并解析出整个 StageGetPrimAtPath通过绝对路径SdfPath拿到具体的UsdPrim句柄后续所有属性操作都基于这两个对象展开。第二步枚举 Prim 上的属性名 xform.GetPropertyNames() [proxyPrim, purpose, visibility, xformOpOrder] sphere.GetPropertyNames() [doubleSided, extent, orientation, primvars:displayColor, primvars:displayOpacity, proxyPrim, purpose, radius, visibility, xformOpOrder]注意两个列表的区别Sphere 比 Xform 多出doubleSided、extent、orientation、primvars:displayColor、primvars:displayOpacity、radius等几何属性。这些属性在文件中并未被显式编写它们是 Schema 声明的默认存在的属性——GetPropertyNames返回的是该 Schema 类型可用的全部属性名包含未在层中 author 的。从源码结构看这一行为实现在 prim.cppUsdPrim::GetPropertyNames调用内部的_GetPropertyNames对 Xformable 等类型会把primDef.GetPropertyNames()来自 Sdf 层定义与 Schema 内建属性合并。教程特别提示了一个 API 使用技巧API TipGetPropertyNames适合按名称获取单个属性若需要遍历一个 Prim 的全部属性更便捷的是UsdPrim::GetProperties、UsdPrim::GetAttributes或UsdPrim::GetRelationships——它们直接返回UsdProperty、UsdAttribute、UsdRelationship对象可无需再按名字查找就直接操作。这三个方法的实现在 prim.cpp 中内部统一走_GetPropertyNames_MakeProperties构建对象列表。第三步读取 extent 属性理解回退值 extentAttr sphere.GetAttribute(extent) extentAttr.Get() Vt.Vec3fArray(2, (Gf.Vec3f(-1.0, -1.0, -1.0), Gf.Vec3f(1.0, 1.0, 1.0)))这个 2×3 数组是球体轴对齐、对象空间包围盒extent的两个端点。由于起始层从未编写过extent这里返回的是该属性的回退值fallback valueUSD 规定当场景描述中没有关于某属性值的任何意见opinion时属性使用其类型默认的回退值。对 Sphere 而言radius的回退值是 1.0因此(-1,-1,-1) ~ (1,1,1)的 extent 与之自洽。从源码结构看这类几何包围盒的回退值并非硬编码在 API 里而是由插件按 Prim 类型注册的ComputeExtent函数计算得出——boundableComputeExtent.cpp 中的_FunctionRegistry维护类型 → 计算函数的注册表UsdGeomBoundable::ComputeExtentFromPlugins据此按time参数动态求值。另外两点值得记住不带时间参数调用Usd.Attribute.Get()返回 Default 时间的值。属性还可以拥有按时间采样的值——例如为UsdGeom.Mesh的points属性提供时间样本即可创建动画形变网格官方文档tut_end_to_end教程演示了该管线的雏形。属性名的字典序GetPropertyNames的结果默认按字典序排列。第四步修改半径并手动同步 extent radiusAttr sphere.GetAttribute(radius) radiusAttr.Set(2) True extentAttr.Set(extentAttr.Get() * 2) True关键要点几何包围盒不会随radius修改而自动重算必须手动把 extent 也更新为新尺寸的 2 倍。Set()与Get()同理只传值不传时间即在 Default 时间编写。此时导出根层内容#usda 1.0 def Xform hello { def Sphere world { float3[] extent [(-2, -2, -2), (2, 2, 2)] double radius 2 } }注意 extent 的类型是float3[]两个Gf.Vec3fdouble radius 2被按 double 类型落盘——类型信息由属性的 Schema 声明决定。第五步用 Schema API 编写 displayColor直接写原始属性名primvars:displayColor很繁琐OpenUSD 提供一级 Schema API 来隐藏这种细节 from pxr import UsdGeom sphereSchema UsdGeom.Sphere(sphere) color sphereSchema.GetDisplayColorAttr() color.Set([(0,0,1)]) TrueUsdGeom.Sphere包装器暴露了GetDisplayColorAttr()等具名访问器客户端代码无需知道其底层原始名是primvars:displayColor。修改后的场景描述为#usda 1.0 def Xform hello { def Sphere world { float3[] extent [(-2, -2, -2), (2, 2, 2)] color3f[] primvars:displayColor [(0, 0, 1)] double radius 2 } }注意primvars:displayColor落盘类型为color3f[]——即三元组向量。这是因为该属性既可表示整个 Prim 的统一颜色也可表示逐元素如每个 mesh 面的颜色因此统一以数组形式承载。该属性在各几何类型上的声明可在 generatedSchema.usda 中检索到例如 Imageable API 下的color3f[] primvars:displayColor定义。第六步保存修改 stage.GetRootLayer().Save()Save()把内存中的根层写回磁盘文件。在 usdview 中打开该文件相机自动框选几何体由于半径从 1 变为 2球体比 Hello World 教程中更大可在 Attribute browser 中检查属性值加以确认。进一步阅读UsdProperty访问属性及其公共 metadata 的编写与查询基类UsdAttribute在UsdProperty基础上细化提供对带类型、按时间采样的属性数据的专用 APIUsdRelationship在UsdProperty基础上细化提供对其他 Prim/属性的目标target解析支持沿关系链稳健解析属性默认按字典序排列可用UsdPrim::SetPropertyOrder显式指定顺序。以上三个类族UsdProperty/UsdAttribute/UsdRelationship的 C 实现集中在 pxr/usd/usd 目录下是理解 USD 属性编写体系最直接的入口。小结本教程展示了 USD 属性操作的标准工作流Stage.Open→GetPrimAtPath→GetPropertyNames/GetProperties枚举 →GetAttributeGet()读值注意回退值语义→Set()写值注意 extent 需手动维护→ 用UsdGeomSchema API 编写着色属性 →GetRootLayer().Save()持久化。配套的可执行脚本 authorProperties.py 内置了各步骤的断言校验如属性名列表、extent 回退值适合作为回归验证或二次开发的起点。【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考