OpenUSD 体积数据指南Field3DAsset Schema 与 Field3D (.f3d) 体积资产的完整使用手册【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSDField3DAsset 是 OpenUSDUniversal Scene Description中 usdVol 域提供的具体 schema具体类型用于在 USD 场景中以 Field3D.f3d文件为数据源描述体积字段Volume Field。本文将以 Field3DAsset 官方 schema 文档 为核心骨架结合 usdVol schema 定义、C 实现与测试代码完整讲解 Field3DAsset 的定位、字段属性、USD 数据编写示例及在体积渲染管线中的用法帮助读者在 OpenUSD 中正确组织基于 Field3D 资产的体积数据。Field3DAsset 是什么Field3DAsset 是一种 Field representing a Field3D volume field表示 Field3D 体积字段的字段 prim。它属于 usdVol 域的 VolumeFieldAsset 一族 schema代表由外部文件定义的体积字段体积数据本身存放在磁盘上的 Field3D.f3d格式文件中而 USD 场景内的 Field3DAsset prim 负责以资产路径asset path的形式引用该文件并提供描述字段语义的元数据。从 schema 定义看schema.usda 中声明class Field3DAsset Field3DAsset ( doc Field3D field primitive. The FieldAsset filePath attribute must specify a file in the Field3D format on disk. inherits /FieldAsset )在 schema 继承体系中的位置Field3DAsset 处于一条清晰的继承链上其祖先类分别是Schema类型作用VolumeFieldBase抽象所有体积字段 prim 的基类继承自XformableFieldBase抽象已弃用旧版基类未来版本将移除应改用VolumeFieldBaseVolumeFieldAsset抽象由外部文件定义的体积字段的公共基类声明filePath、fieldName、fieldIndex、fieldDataType、vectorDataRoleHintFieldAsset抽象已弃用旧版中间层继承自VolumeFieldAssetField3DAsset具体类型可直接实例化的 Field3D 字段 prim其中FieldBase与FieldAsset在 schema.usda 中被标记为 deprecatedThis schema will be removed in a future release当前实际使用的继承路径为VolumeFieldBase → VolumeFieldAsset。因此Field3DAsset 最终拥有VolumeFieldAsset声明的全部属性再加上自身声明的fieldPurpose与收窄取值范围的fieldDataType。在 C 中对应类为UsdVolField3DAssetfield3DAsset.h继承自UsdVolFieldAsset其schemaKind为UsdSchemaKind::ConcreteTyped即可以直接用UsdVolField3DAsset::Define(stage, path)在舞台上定义而 Python 绑定位于 wrapField3DAsset.cpp可通过UsdVol.Field3DAsset直接访问。最小可用示例引用单个密度场原文档给出了一个最典型的 Field3DAsset 用例——引用 .f3d 文件中的单个密度场def Field3DAsset densityField3D { token fieldDataType float token fieldName density token fieldPurpose cluster_0 asset filePath.timeSamples { 1: /f3ddata/Volumes_Cumulus01_Puff01M.1.f3d, } }这段代码演示了 Field3DAsset 的四个核心要素filePath指向磁盘上的 Field3D.f3d文件且此处以时间采样timeSamples形式给出表示该字段是随时间变化的动画数据fieldName.f3d文件内部具体字段Field的名字这里是densityfieldPurpose字段用途或分组的标识消费 Field3D 文件的客户端应将其视为 Field3D 字段的name与fieldName的区别见下文fieldDataType字段数据类型这里是float。注意原文档明确指出filePath属性必须指向磁盘上 Field3D.f3d格式的文件这是 Field3DAsset 与 OpenVDBAsset.vdb等其它 VolumeFieldAsset 子类最大的区别。属性详解PropertiesField3DAsset 的属性分为自身声明与继承自祖先两部分下面逐一说明。自身属性fieldPurposeUSD 类型token可选属性fieldPurpose用于指明单个字段的用途或分组。消费 Field3D 文件的客户端应将此 token 视为 Field3D 字段的名称name。它出现在 schema.usda 的 Field3DAsset 类声明中是 Field3DAsset 区别于其它 VolumeFieldAsset 子类的专属属性。典型用途是区分一个 .f3d 文件中的多个字段用途例如示例中的cluster_0表示该字段属于某个聚类分组。由于它是可选属性未编写时消费者可按 Field3D 文件中的默认字段信息处理。继承自 VolumeFieldAsset 的属性fieldDataTypeUSD 类型token字段的数据类型例如float。设置该属性可以让消费者无需打开资产文件即可获知字段类型信息。其允许的 token 集合在 Field3DAsset 中收窄为标量类型向量类型half、float、doublehalf3、float3、double3这一限定列表定义于 schema.usda与 field3DAsset.h 中注释的 Allowed Values 一致反映了 Field3D 格式实际支持的数据类型选择。相比之下OpenVDBAsset 的fieldDataType允许集合大得多含int、uint、bool、mask、string、matrix3d等这体现了不同体积格式的能力差异。在VolumeFieldAsset基类中fieldDataType被描述为A missing value is considered an error缺失值视为错误因此为 Field3DAsset 编写fieldDataType是推荐做法。fieldIndexUSD 类型int可选属性一个资产文件中可能包含多个同名字段fieldIndex用于在多个同名字段之间消歧。例如一个 OpenVDB 文件中可能有两个名为 density 的 Grid此时fieldIndex为 0 表示引用第一个 density Grid。Field3D 文件同样适用这一约定。fieldNameUSD 类型token表示 VolumeFieldAsset 资产文件内部某个字段的名称。一个资产文件可以包含多个字段该属性精确指定引用其中的哪一个。例如 OpenVDB 文件中可能有 density、temperature 等多个命名 GridfieldName指定其中之一。与 Volume 上 field 关系的命名区别Volume prim 还通过field:命名空间前缀的关系relationship为字段提供名称但这个名称与资产数据无关是 Volume 为渲染管线组织字段而使用的。字段关系名与fieldName的区别详见 usdVol userDoc 总览 的 Understanding fieldName and the Fields Relationship Name 一节源码位于 overview.md。例如Volume 的 shader 需要 velocity 输入但 .f3d 文件里的字段名叫 vel此时可在 Volume 中写rel field:velocity /.../fieldPrim而 Field 内的fieldName仍为 vel。filePathUSD 类型asset指向磁盘文件的资产路径属性。对于 Field3DAsset其指向的文件类型必须是 Field3D.f3d文件对于 OpenVDBAsset 则必须是 OpenVDB.vdb文件。该属性的 C 类型为SdfAssetPath见 volumeFieldAsset.h。两个关键约束可随时间动画大多数体积资产格式只代表体积的单个时间采样single timeSample因此filePath可以也通常需要通过 timeSamples 逐帧指定不同文件实现体积动画不支持模式替换当前版本的filePath不支持$F之类的帧号模式替换必须逐帧显式编写时间采样。动画写法示例以 OpenVDBAsset 为例Field3DAsset 同理来自 overview.mddef 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 } }vectorDataRoleHintUSD 类型tokenFallback 值None可选属性用于指明向量值字段的角色role例如Color。它决定字段在渲染器中以何种数据类型暴露以及向量值是否需要被变换。允许的 token 为None, Point, Normal, Vector, Color该列表在 schema.usda 中通过allowedTokens声明。对向量型 Field3D 字段half3/float3/double3设置正确的 role hint 可让渲染器做出正确解释例如把字段数据当作法线Normal还是颜色Color。继承自 Xformable 的属性xformOpOrderUSD 类型token[]继承自Xformable控制字段 prim 的变换操作顺序。字段 prim 的 local-to-world 变换会将提取出的网格grid定位到世界空间详见下文变换与组织。继承自 Imageable 的属性proxyPrimUSD 类型rel关系指向代理 prim 的关系用于指示可替代本 prim 进行渲染的轻量代理。purposeUSD 类型tokenFallback 值defaultprim 的渲染用途如default、render、proxy、guide控制该 prim 是否参与渲染、以何种质量渲染。visibilityUSD 类型tokenFallback 值inherited可见性控制取值inherited、invisible等决定字段是否参与绘制。在 Volume 中使用 Field3DAssetField3DAsset 通常不单独出现而是作为 Volume prim 的字段被引用。usdVol 的 Volume schemaschema.usda规定Volume 由任意数量的 FieldBase 派生 prim 组成每个字段通过命名空间前缀为field的关系绑定def Volume Volume ( prepend apiSchemas [MaterialBindingAPI] ) { custom rel field:density /Volume/densityField3D 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 Field3DAsset densityField3D { token fieldDataType float token fieldName density token fieldPurpose cluster_0 asset filePath /f3ddata/Volumes_Cumulus01_Puff01M.1.f3d } }要点关系名即渲染器绑定名field:density中的 density 被渲染器用来把该字段与体积 shader 上的同名输入参数关联字段 prim 名称无关紧要Volume 引用字段靠关系而非字段 prim 的名字因此单个字段 prim 可被多个 Volume 复用、或作为不同 shader 参数使用推荐组织方式除非需要多 Volume 共享否则建议将字段 prim 置于 Volume 命名空间之下如上面的/Volume/densityField3D便于场景组织与随 Volume 一起变换。字段 prim 提取出的网格由字段 prim 的 local-to-world 变换外加外部资产编码内含的变换定位到世界空间。Volume 同样继承自 GPrim/Imageable可绑定材质并通过 primvars 将数据接入 USD Material/Shader 管线若无材质绑定Hydra 会使用回退体积材质。测试用例佐证在 testenv/testUsdVolVolume.py 中Field3DAsset 以 Python API 方式被实际创建与验证f1 UsdVol.Field3DAsset.Define(stage, /base/volume/f3dField) ... refVol.CreateFieldRelationship(diffuse, /volModel/volume/f3dField)该测试依次验证了在 Volume 下定义 Field3DAsset prim、通过CreateFieldRelationship建立field:命名空间关系、以及场景引用的解析。这为Field3DAsset Volume field 关系的用法提供了直接的实现证据。常见问题与最佳实践文件格式必须匹配filePath必须指向 .f3d 文件。若指向其它格式如 .vdb应改用对应的 OpenVDBAsset 等 schema而不是 Field3DAsset。动画数据务必逐帧写 timeSamples由于不支持$F等模式替换逐帧资产序列需要显式列出每个时间采样如文档示例所示。fieldName与关系名是两个概念fieldName是资产文件内部字段的名字Volume 上的field:xxx关系名服务于渲染管线的 shader 参数绑定。二者可以不同。同名字段用fieldIndex消歧当 .f3d 文件中存在多个同名 Field 时用整数索引指定目标。fieldDataType尽量填写它让消费者无需读取文件即可获知数据类型在VolumeFieldAsset基类语义中缺失值视为错误。Field3DAsset 的取值限于half/float/double/half3/float3/double3。向量字段配合vectorDataRoleHint对向量型字段设置Point/Normal/Vector/Color角色可帮助渲染器决定数据类型与是否做向量变换。延伸阅读Schema 权威定义usdVol/schema.usdaC 类实现field3DAsset.h、volumeFieldAsset.hPython 绑定wrapField3DAsset.cpp体积与字段总览usdVol userDoc overview测试用例testUsdVolVolume.py姊妹 schemaOpenVDBAsset 文档若要了解 Volume 的整体机制、字段关系的完整语义以及粒子场ParticleField等进阶主题可继续阅读 usdVol 用户指南总览 与 usdVol 域相关文档。【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考