OpenUSD项目中的Schema类生成教程-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00313/article/details/148466087

OpenUSD项目中的Schema类生成教程

OpenUSD Universal Scene Description 项目地址: https://gitcode.com/gh_mirrors/ope/OpenUSD

前言

在OpenUSD项目中，Schema（模式）是构建3D场景数据模型的核心概念。本文将深入讲解如何使用OpenUSD提供的工具生成自定义Schema类，帮助开发者扩展USD的功能以满足特定需求。

环境准备

在开始生成Schema类之前，需要确保开发环境满足以下条件：

Python依赖：
- 安装jinja2模板引擎模块
- 安装argparse模块
Python环境配置：
- 确保Python能够找到USD的Python模块
- 设置PYTHONPATH环境变量，包含USD安装目录下的lib/python路径

Schema类基础概念

什么是Schema类？

Schema类是USD中一种特殊的类，它封装了UsdPrim并提供了一层特定的命名API。简单来说，Schema类为底层场景图提供了高级的、类型化的接口。

USD提供了usdGenSchema脚本来自动生成这些Schema类。例如，UsdModelAPI、UsdGeomImageable等都是通过这个工具生成的。

Schema类的类型

USD中的Schema类主要分为两大类：

1. IsA Schema

IsA Schema可以为prim提供类型名称(typeName)和接口特性。特点包括：

必须从核心类UsdTyped派生
可以是具体的(concrete)或抽象的(non-concrete)
- 具体Schema：提供schema名称和typeName，可以被实例化
- 抽象Schema：只提供schema名称，不能直接实例化，通常作为基类使用

2. API Schema

API Schema只提供prim特性的接口，不指定typeName。特点包括：

类名必须以"API"结尾
不能提供typeName，因此被视为非具体的
分为两种子类型：
- 非应用型API Schema：不记录应用状态，如UsdModelAPI
- 应用型API Schema：记录应用状态，又分为：
  - 单应用API Schema：只能应用一次
  - 多应用API Schema：可多次应用，每次使用不同实例名

Schema生成流程

1. 准备schema.usda文件

Schema生成需要一个USD层文件（通常命名为schema.usda），该文件必须满足以下要求：

必须指定libraryName作为层元数据
必须包含usd/schema.usda在层栈中
Schema类型名称必须在所有库中唯一
属性名称和token必须是有效的驼峰式标识符

2. 编写Schema定义

示例：非具体IsA Schema

class "SimplePrim" (
    doc = "一个非具体IsA Schema示例"
    inherits = </Typed>
    customData = {
        string className = "Simple"
    }
)  {
    int intAttr = 0 (
        doc = "默认值为0的整数属性"
    )
    rel target (
        doc = "指向其他prim或属性的关系"
    )
}

示例：具体IsA Schema

class ComplexPrim "ComplexPrim" (
    doc = "一个具体IsA Schema示例"
    inherits = </SimplePrim>
    customData = {
        string className = "Complex"
    }
)  {
    string complexString = "somethingComplex"
}

示例：应用型API Schema

class "ParamsAPI" (
    inherits = </APISchemaBase>
    customData = {
        token apiSchemaType = "singleApply"
    }
) {
    double params:mass (
        customData = {
            string apiName = "mass"
        }
        doc = "表示质量的double值"
    )
    double params:velocity (
        customData = {
            string apiName = "velocity"
        }
        doc = "表示速度的double值"
    )
    double params:volume (
        customData = {
            string apiName = "volume"
        }
        doc = "表示体积的double值"
    )
}

3. 生成Schema代码

使用usdGenSchema命令生成代码：

usdGenSchema schema.usda .

该命令会生成以下文件：

头文件和源文件(.h/.cpp)
包装文件(wrap*.cpp)
token文件
plugInfo.json
generatedSchema.usda

4. 构建Schema插件

使用CMake构建生成的Schema：

cmake --build . --target install --config Release

使用生成的Schema

配置插件路径

在使用Schema插件前，需要让USD知道插件的位置，可以通过以下方式之一：

设置PXR_PLUGINPATH_NAME环境变量指向插件的resources目录
将插件文件复制到USD的插件目录

示例USD文件

创建一个测试文件Test.usda：

#usda 1.0

def ComplexPrim "Complex" {
    string complexString = "a really complex string"
    int intAttr = 10
    add rel target = </Object>
}

def Xform "Object" (
    prepend apiSchemas = ["ParamsAPI"]
) {
    custom double params:mass = 1.0;
    custom double params:velocity = 10.0;
    custom double params:volume = 4.0;
}

C++使用示例

UsdStageRefPtr stage = UsdStage::Open("/path/to/testenv/Test.usda");

UsdPrim cp = stage->GetPrimAtPath("/Complex");

UsdSchemaExamplesSimple simple(cp);
UsdRelationship target = simple.GetTargetRel();
UsdAttribute intAttr = simple.GetIntAttrAttr();