OpenUSD UsdVol VolumeFieldAsset 深度指南基于外部文件资产的体积场 Schema 解析与实战【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSDVolumeFieldAsset 是 OpenUSD 的 UsdVol 模式域中用于描述体积场数据存储在 layer 外部文件资产中的抽象基类 Schema是 OpenVDBAsset、Field3DAsset 等一切文件型体积场 Schema 的公共父类。本文以 VolumeFieldAsset.md 为核心骨架结合 schema.usda、volumeFieldAsset.h 等源码系统讲解其继承体系、全部属性语义、派生 Schema 的用法、动画体积数据组织方式以及如何基于它扩展自定义文件型场 Schema帮助你完整掌握 UsdVol 中以文件为载体的体积场的建模与使用。一、VolumeFieldAsset 是什么文件型体积场的抽象基类在 UsdVol 模式域中体积Volume由若干场Field构成场封装了离散化的体积数据可能稀疏、可能随时间变化用于表现烟雾、火焰等效果。UsdVol 为此定义了一套抽象 Schema 层级VolumeFieldBase所有场 Schema 的公共抽象基类直接继承自Xformable参见 VolumeFieldBase.mdVolumeFieldAsset继承自 VolumeFieldBase 的抽象 Schema专门描述体积数据存储在 layer 之外的场例如以文件资产file asset形式存在的体积数据OpenVDBAsset / Field3DAsset继承自 VolumeFieldAsset 的具体concreteSchema分别表示 OpenVDB.vdb与 Field3D.f3d格式的体积场。文档明确指出如果你需要为 UsdVol 扩展自定义的、基于文件的场 Schema你的自定义 Schema 应当继承自 VolumeFieldAsset。这是该 Schema 的核心设计意图——它把如何定位外部文件filePath、如何从文件中挑选一个场fieldName/fieldIndex、如何描述场的数据特征fieldDataType/vectorDataRoleHint这些跨格式公共能力收敛到一个基类中各文件格式只需在其上补充格式特有属性。源码视角Schema 在 schema.usda 中的定义在 schema.usda 中可以看到完整的声明链class VolumeFieldBase ( inherits /Xformable doc Base class for volume field primitives. ) { } class FieldBase ( inherits /VolumeFieldBase doc \deprecated This schema will be removed in a future release... ) { } class VolumeFieldAsset ( doc Base class for volume field primitives defined by an external file. inherits /FieldBase ) { asset filePath (...) token fieldName (...) int fieldIndex (...) token fieldDataType (...) token vectorDataRoleHint None ( allowedTokens [None, Point, Normal, Vector, Color] ) }注意VolumeFieldAsset在声明上继承了已标记弃用的FieldBase而FieldBase又继承自VolumeFieldBase这是为了保持向后兼容的历史链条同时文档也提示旧的 FieldAsset.md Schema 已弃用应改用 VolumeFieldAsset。从代码结构看当前体系下 VolumeFieldBase → FieldBase → VolumeFieldAsset →OpenVDBAsset / Field3DAsset / 自定义派生 Schema所有继承链最终都锚定在Xformable之上因此场 prim 天然携带完整的变换能力。在生成的 C 类 volumeFieldAsset.h 中UsdVolVolumeFieldAsset被标记为UsdSchemaKind::AbstractTyped即抽象类型化 Schema——它不能直接实例化 prim只作为基类存在这与文档应使用 OpenVDBAsset 或 Field3DAsset 等派生 Schema 创建 prim的说明完全一致。每个属性都对应一对Get*Attr()/Create*Attr()方法例如 GetFilePathAttr / CreateFilePathAttr 在 C 侧按SdfValueTypeNames-Asset对应 USD 类型asset创建属性。二、VolumeFieldAsset 属性详解VolumeFieldAsset 定义了五个自有属性语义全部围绕引用并描述外部文件中的单个场展开。以下逐一说明类型、含义、可选性与实践要点。filePath类型asset指向磁盘上文件的资产路径属性是文件型场最核心的属性。指向的文件类型必须被派生 Schema 支持例如 OpenVDBAsset 要求.vdb文件Field3DAsset 要求.f3d文件该属性可以随时间动画化由于大多数体积资产格式只表示体积的单个时间采样single timeSample动画通常通过为filePath设置多个时间采样timeSamples来实现例如在帧 101 指向wisp_01.101.vdb、帧 102 指向wisp_01.102.vdb目前不支持任何模式替换如$F也就是说你不能写./wisp_01.$F.vdb这种带序号的路径必须显式列出每一帧的资产路径。关于动画用法的完整示例见下文使用动画场数据一节也可直接阅读 overview.md 中的usdVol_using_animated_field_data小节。fieldName类型token表示场在资产文件内部的名称。一个 VolumeFieldAsset 资产文件可能包含多个场该属性用于指定引用其中哪一个。例如一个 OpenVDB 资产文件里可能有多个命名 Grid如 density、temperaturefieldName指定其中之一需要特别注意Volume 还通过field命名空间下的关系relationship为场提供另一套名称那套名称与资产数据无关是 Volume 为渲染管线组织场而使用的。fieldName与 field 关系名的区别详见理解 fieldName 与场的关系名一节对应原文档中的usdVol_understanding_fieldname锚点。fieldIndex类型int可选资产文件中可能存在同名多个场此可选属性用于消歧disambiguate。例如一个 OpenVDB 资产中有两个名为 density 的 GridfieldIndex 0表示引用第一个 density Grid。fieldDataType类型token场的数据类型例如 float。其作用是在不打开资产文件的情况下向消费者渲染器等传达场的类型信息因此允许的 token 列表由具体资产类型指定详见下文 OpenVDBAsset / Field3DAsset 的字段。缺失该属性视为错误。vectorDataRoleHint类型tokenFallback 值None可选向量值场的角色提示例如 Color。它可以驱动渲染器中场可用的数据类型或决定向量值是否需要被变换。允许的 token 包括None、Point、Normal、Vector、Color在 schema.usda 中以allowedTokens显式声明。继承属性Xformable 与 Imageable作为Xformable与Imageable的间接派生 SchemaVolumeFieldAsset 还继承了以下属性属性USD 类型Fallback 值来源基类说明xformOpOrdertoken[]—Xformable变换操作列表决定场的局部坐标变换proxyPrimrel关系—Imageable代理 prim 关系purposetokendefaultImageableprim 用途如 render / proxy / guidevisibilitytokeninheritedImageable可见性默认随父级继承其中变换能力对场具有重要意义从场 prim 提取的网格其世界空间位置由场 prim 的局部到世界变换决定如果是 VolumeFieldAsset 派生 prim还要叠加外部资产编码中携带的变换。因此文档建议将场 prim 设为 Volume 的子 prim这样重定位 Volume 时子场会随之一起移动除非场需要被多个 Volume 共享。三、派生的具体 SchemaOpenVDBAsset 与 Field3DAssetVolumeFieldAsset 是抽象类实际工作中应使用其派生 Schema 创建 prim。UsdVol 内置了两个文件格式派生 Schema。OpenVDBAsset表示一个 OpenVDB 体积网格grid。除继承 VolumeFieldAsset 的全部属性外还定义了格式特有属性fieldClasstoken可选单个 grid 的类别映射 OpenVDB 的openvdb::GridClass取值对应GRID_LEVEL_SET、GRID_FOG_VOLUME、GRID_STAGGERED、GRID_UNKNOWNfieldDataType 的允许 token比基类更宽泛包括half、float、double、int、uint、int64、half2/float2/double2/int2、half3/float3/double3/int3、matrix3d、matrix4d、quatd、bool、mask、string见 schema.usda。OpenVDBAsset.md 给出了引用单个 density 场的完整示例def OpenVDBAsset densityVDB { token fieldDataType float int fieldIndex.timeSamples { 10: 0, } token fieldName density asset filePath.timeSamples { 10: /vdb_test_data/grids.vdb, } }注意示例把fieldIndex与filePath都写成timeSamples形式说明这些属性均可在时间上变化。Field3DAsset表示一个 Field3D 体积场。特有属性为fieldPurposetoken可选单个场的用途或分组消费 Field3D 文件的客户端应将其视为 Field3D 场的名称fieldDataType 的允许 tokenhalf、float、double、half3、float3、double3见 schema.usda。Field3DAsset.md 的示例def Field3DAsset densityField3D { token fieldDataType float token fieldName density token fieldPurpose cluster_0 asset filePath.timeSamples { 1: /f3ddata/Volumes_Cumulus01_Puff01M.1.f3d, } }四、在 Volume 中组织场field 关系与最佳实践Volume prim 代表可渲染的体积如雾、火效果它通过field命名空间前缀的关系relationship引用 VolumeFieldBase 派生 prim。关系名如density由渲染器用来把各个场与体积着色器上的命名输入参数关联起来。完整示例Volume OpenVDBAsset 场以下示例取自 overview.md 的usdVol_working_with_volumes小节展示了 Volume、场关系、材质绑定与作为子 prim 的 OpenVDBAsset 的配合def Volume Volume ( prepend apiSchemas [MaterialBindingAPI] ) { custom rel field:density /Volume/densityVDB uniform token purpose render double3 xformOp:scale (1, 1, 1) double3 xformOp:translate (0, -3, 0) token[] xformOpOrder [xformOp:translate, xformOp:scale] rel material:binding /Materials/VolumeMaterial def OpenVDBAsset densityVDB { token fieldName density asset filePath /vdbdata/smoke_plume.101.vdb } }要点场应尽量作为 Volume 的子 prim。这样场容易查找和引用且重定位 Volume 时子场自动跟随场可以被多个 Volume 共享。如果确有共享需求也可以不把场放在任何 Volume 之下文档明确说明这不是强制要求Volume 继承自 GPrim主要用于可渲染/可成像的体积但按文档说明Volume prim 也可用于不可渲染的场景例如封装供仿真使用的体积数据。field关系的增删改查在源码侧有完整 API 支撑测试文件 testUsdVolVolume.py 演示了CreateFieldRelationship、GetFieldPaths、GetFieldPath、HasFieldRelationship、BlockFieldRelationship等操作包括对引用internal reference中场的查找、屏蔽与本地重建验证了 field 关系在层合成composition下的行为。使用动画场数据体积数据经常是动画的。对 VolumeFieldAsset 派生场而言动画通过在filePath属性上设置时间采样来表达。overview.md中的示例如下def Volume wisp { float3[] extent [(-57, -91, -44), (57, 31, -23)] rel field:density /wisp/density def OpenVDBAsset density { asset filePath.timeSamples { 101: ./wisp_01.101.vdb, 102: ./wisp_01.102.vdb, 103: ./wisp_01.103.vdb, 104: ./wisp_01.104.vdb, } token fieldName density } }每一帧都显式列出对应的.vdb文件这是filePath动画的标准写法不支持$F通配。理解 fieldName 与场的关系名VolumeFieldAsset 派生场用fieldName标识场在资产文件内的名称如 VDB 文件中的 grid 名而 Volume 通过field命名空间的关系为场定义另一套名称这套名称面向 Volume 与渲染管线与资产数据无直接绑定。二者的分离带来两个实际好处Volume 可以使用与资产内部不同的名称。例如 Volume 的着色器参数需要名为 velocity 的场但 OpenVDB 资产中的 grid 名为 vel那么就在 Volume 上建field:velocity关系指向引用该 VDB 数据且fieldName vel的 OpenVDBAsset场 prim 可以被复用到多个 Volume 的不同场位上如需复用可组织上不把场作为任何 Volume 的子 prim。五、扩展指南编写自定义文件型场 SchemaVolumeFieldAsset 的主要价值之一就是作为扩展点。若你的管线需要新的体积文件格式自定义 Schema 的推荐做法是在模式schema声明中让自定义类继承VolumeFieldAsset即沿用asset filePathtoken fieldNameint fieldIndextoken fieldDataTypetoken vectorDataRoleHint的公共属性组合在派生类中补充格式特有属性参照 OpenVDBAsset 的fieldClass、Field3DAsset 的fieldPurpose模式并为fieldDataType声明该格式允许的 token 列表沿用一种文件格式对应一个派生 Schema的约定——从 volumeFieldAsset.h 的注释for each supported file format, a separate FieldAsset subclass is required可以看出这是官方明确的设计原则。至于粒子场ParticleField等不依赖外部文件、直接在 layer 内携带数据的场则走另一条继承路线直接派生自 ParticleField 基类不属于 VolumeFieldAsset 的适用范围。六、相关资源速查Schema 文档VolumeFieldAsset.md、VolumeFieldBase.md、OpenVDBAsset.md、Field3DAsset.md、FieldAsset.md已弃用模式域总览overview.md含 Volume 组织、动画场数据、fieldName 与关系名辨析等主题模式声明权威属性定义schema.usdaC 生成类volumeFieldAsset.h 与 volumeFieldAsset.cpp提供Get/Create/Get*Attr/Create*Attr系列 API测试佐证testUsdVolVolume.py验证 Volume 对场关系的管理行为上图为 UsdVol 文档中展示的 Volume 效果示例Volume 中的密度场指向 OpenVDB 资产来自 overview.md直观体现了Volume 承载场关系、VolumeFieldAsset 派生 prim 承载文件引用的分层组织方式。【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考