OpenUSD 已经成为数字孪生与仿真管线的事实标准,但它一直缺一块拼图:精确的实体几何。USD 原生表达的是多边形网格(UsdGeomMesh),而机械设计里的零件是 NURBS 面片与解析曲面围成的实体——转成网格就意味着精度丢失、参数丢失、拓扑丢失。
NVIDIA Omniverse 团队在 2026 年 10 月开源的 usd-brep,正是来补这块拼图的:一套独立的 C++ / Python 库,让 BRep 实体能原样存进 USD,并在内存里完成创建与编辑。仓库开放一个多月就拿到 2,000 多 star,说明这个缺口有多真实。
本文的重点是它的内核 SMLib——整个项目真正承载几何能力的地方,也是被名字里那个「USD」遮住的部分。
一、先看它解决了什么
核心是一个新的 USD 图元:BrepArray。BRep(边界表示)实体连同它的完整拓扑与几何,被写进这个 prim 里。几何可以是 NURBS,也可以是解析曲面——平面、圆柱、圆锥、球、圆环这五类面会以解析曲面的形式写入 USD;边曲线统一写为 NURBS,而从其他工具导入的解析直线、圆、椭圆边,则按解析曲线读入。抛物面、回转面等其余 SMLib 类型则以 NURBS 形式写出。
这个取舍很关键:能保持解析形式的一律保持解析。圆柱面存成圆柱面,而不是一堆拟合出来的样条,下游做求交、偏置、展开时才不会引入近似误差。
二、SMLib:项目真正的内核
SMLib 是一个面向 NURBS 与解析几何的 BRep 实体建模内核。它把实体表示成一组拓扑实体(壳、面、边、顶点)绑定到精确几何定义(NURBS 曲面、B 样条曲线、解析基元)上,因此形状定义在数学上是精确的、与分辨率无关——这也是它和「一堆三角形」最根本的区别。
2.1 五层结构
仓库的分层非常清晰,理解这五层基本就理解了整个项目:
- SMLib——最底层内核。拥有全部几何与拓扑类(
SmBrep、SmFace、SmEdge、SmSurface、SmBSplineCurve等)以及作用其上的算法,是一个用内部SmContext管理内存的 C++ 库。 - SM_API——包在 SMLib 外面的高层 C 风格 C++ API,把常用操作收敛成一个个
SmApi*函数。这是绝大多数使用者直接面对的接口。 - SM_API_USD——USD 集成层,负责 BRep 数据在 OpenUSD 文件(.usda / .usdc / .usd)里的导入导出。
- BREP_SM_USD / BREP_USD_DATA——内部的 BRep ↔ USD 数据转换库,一般不直接调用。
- SmPyLib(
_omni_solid)——基于 pybind11 的 Python 绑定,把 SM_API 与 SM_API_USD 暴露成 Python 模块,附带网格化结果PolyBrep与多边形网格布尔。
2.2 拓扑与几何是怎么组织的
一个 SmBrep 包含一个或多个 SmShell;每个壳由若干 SmFace(裁剪曲面)组成,面与面沿 SmEdge 相连,边在 SmVertex 处交汇。这套拓扑结构记录的是邻接关系——你可以问「哪两个面共用这条边」「这个面的外环由哪些边构成」,而不是只拿到坐标数组。
几何侧同时支持解析、NURBS 与其他曲线曲面子类。有两点值得注意:其一,NURBS 本身就能精确表示球面这类形状;其二,布尔与圆角不要求所有输入统一转成 NURBS,数值求解与逼近使用按操作设定的容差。这意味着在混合几何(解析面 + 样条面)上做运算时,不必然发生一次全量格式转换。
2.3 能力地图
按头文件看,SMLib 覆盖的能力远超「建个盒子求个差」:
基元(SmApiPrimitives.h):盒、球、锥、柱、环、棱锥,以及部分球/锥/柱/环、圆柱形盒、无极点球、扫成基元与过渡体。
布尔(SmApiBrep.h):并、差、交之外,还有 merge、2D 布尔、布尔列表、CSG 树求值、非流形布尔、分段合并。
扫掠(SmApiBrep.h):线性、旋转、拔模、管道四类基本扫掠,加上锥度拉伸、沿平面路径扫掠、带重复的线性/旋转扫掠、曲线扫掠,以及非流形版本。
圆角(SmApiFillets.h):等半径圆角、倒角、按边分别设置、变半径圆角、移除圆角、面-面圆角、预览、拐角倒角设置。
曲线与曲面:直线、圆、圆弧、螺旋线、椭圆、矩形、正多边形、插值/逼近曲线、偏移、连续性求值、投影到曲面、转成直线与圆弧、UV 曲线提升、曲线兼容化、去除节点;曲面侧支持从点集构造、直纹面、回转面、偏置面、拉伸面、扫掠面、蒙皮面、平面面片。
偏置与抽壳、缝合、求交、裁剪:offset_brep / shell_brep;缝合为实体或壳体并统一法向;BRep-BRep、面-面、曲线-曲面等多组合求交;切割、投影、投影并裁剪、轮廓线提取。
查询与校验:is_manifold_solid 判断是否为合法封闭实体、compute_volume 求体积、包围盒、最近点、面积、边长、曲面点与法向及导数求值。
2.4 网格化与 PolyBrep
把精确 BRep 变成三角网格是渲染侧的必经一步。SMLib 的网格化由弦高容差(多边形到真实曲面的最大距离)、角度容差、最大边长、最大长宽比共同控制,输出 PolyBrep。这个网格对象并不是死数据——它支持拓扑遍历、包围盒、质量属性、平面剖切和射线测试,因此可以在网格层面继续做布尔与查询。
也正因为网格化是独立的一步,同一条管线才能既喂渲染器三角形,又喂求解器精确曲面。
2.5 三个必须懂的调用契约
这一条对写代码的人最实用。SMLib 的操作按所有权语义分成三类,搞错了就会出现「结果对的、却被释放了」这类问题:
- Pure:返回新对象,输入保持不变。
create_box、linear_sweep、offset_brep、shell_brep、tessellate都属于这一类。 - Consumes:输入的所有权转移给操作,之后只能用返回值。
boolean_union、boolean_difference、merge_breps如此;返回值可能复用被修改的主操作数,并不保证是新分配。 - Mutates:原地修改第一个参数并返回它,所以可以链式调用。
fillet_edges、cut、translate、rotate、heal_brep属于这一类。
需要在 Mutates 操作中保留原对象时,先 copy()。另外,文档特意提醒:光看函数名判断不出属于哪类——非流形扫掠会修改源对象,create_blend_primitive 会往传入的 BRep 里插入内容,必须逐个看契约。
2.6 错误模型
SM_API 的函数统一返回 SmApiStatus(本质是 long),SM_SUCCESS 表示成功;Python 绑定会检查状态并在失败时抛出 RuntimeError,信息里带错误码、内核调用栈或绑定侧的回退信息。常见成因是空指针、退化几何(零长边、零面积面)和拓扑不一致。仓库还提供了一份逐错误码的说明文档,讲清每个 SM_ERR_* 的典型原因与修法——对几何内核这种报错晦涩的领域,这份文档的价值不亚于 API 本身。
并发方面需要提前知道:当前发布的版本操作是单线程执行的,框架提供 SmContext 管理上下文生命周期,多任务的推荐做法是每 worker 一个进程。
三、仓库里还有什么
围绕 SMLib 与 USD,仓库提供了相当完整的一套工具:
- Schema(omniSolid):定义
BrepArray图元,附提案与问题陈述文档 - USD 校验器 / 几何校验器:前者检查文件是否符合 schema,后者对每个
BrepArray跑内核的 AssertValid - Healer:整场景修复 BRep,同时保留层、引用、实例化、变换与材质——很多修复工具一跑就把场景结构打散,这一点很难得
- 网格化器:为每个 BRep 生成
UsdGeomMesh - 三个查看器:
hdUsdBrep(Hydra 插件,直接在 usdview 里看 BRep)、view_usd(PyVista 窗口)、smlib_gui(可打开、检查、编辑 BRep 的桌面程序) - OpenCASCADE 双向转换:
occt_to_usd与usd_to_occt
四、五分钟上手
PyPI 上已有包,支持 CPython 3.12 的 Linux(x86_64、aarch64)与 Windows:
pip install usd-brep
README 的例子正好演示了完整闭环——建体、求差、导出 USD、再读回来:
import usd_brep
sphere = usd_brep.primitives.create_sphere((0.0, 0.0, 0.0), 1.0)
box = usd_brep.primitives.create_box((0.0, 0.0, 0.0), 1.0, 1.0, 1.0)
cut = usd_brep.booleans.boolean_difference(sphere, box) # 切掉一角的球
usd_brep.usd.export_brep(cut, "cut.usda")
(brep,) = usd_brep.usd.import_breps("cut.usda")
想直接摸 SMLib 本身,就走底层绑定(_omni_solid),接口更贴近内核:
import _omni_solid as sm
box = sm.create_box((0, 0, 0), 10, 10, 10)
sph = sm.create_sphere((0, 0, 0), 5)
merged = sm.boolean_union(box.copy(), sph.copy())
mesh = sm.tessellate(merged, chord_height_tolerance=0.0,
curve_angle_tolerance_deg=25.0,
surface_angle_tolerance_deg=25.0)
print(merged.volume(), [f for f in merged.faces()])
修复已有场景则是最省事的一次调用:
usd_brep.usd.heal_file("input.usdc", "input_healed.usdc")
它会处理场景所用各层里的 BrepArray 几何,并原样保留层、引用、实例化、变换与材质。
五、两个值得注意的设计取舍
显示与几何分离。USD 里存的是 BRep,显示走网格化器生成 UsdGeomMesh。Hydra 插件把这件事做在了查看层——在 usdview 里看到的仍是 BRep 的真实外形,而不是离线导出的网格。
为编码代理准备文档。仓库根目录的 AGENTS.md 指向一整套 .agents 文档:库的分层与关键概念、每个错误码的含义与修法、按 API 领域划分的操作指南(布尔、圆角、网格化、修复、USD 导入导出),以及调试内核操作、维护 C++/Python API 的工作流。把「让 AI 参与开发」当成一等公民来组织仓库——对几何内核这种文档稀缺、上手陡峭的领域,这个方向值得关注。
六、现状与限制
- 暂不接受外部贡献:README 写明 currently not accepting contributions,问题单与 bug 报告仍然欢迎
- Python 包限定 CPython 3.12,二进制覆盖 Linux x86_64 / aarch64 与 Windows;macOS 需从源码构建
- 内核操作是单线程的,要并行得自己按进程切分
- 几何类型有取舍:五类解析曲面以外的类型统一写为 NURBS,跨工具往返时会有形式转换
- 与 OCCT 的互转是重点路径,但仓库未声称全类型无损,实际项目里建议逐类型验证
七、为什么值得放进工具箱
如果你在做 CAD 与仿真、数字孪生之间的数据打通,这套库给出的是一条「保留精确几何」的路线:BRep 原样进 USD,需要看的时候再网格化。相比把模型一次性三角化丢进管线,它多保留了参数化信息与解析曲面,给后续的布尔、偏置、网格划分留了余地。
如果你关心的是几何内核本身,SMLib 值得单独读:NURBS 与解析几何混存而不强制统一格式、纯函数与消费式接口的明确分工、整场景修复时保持结构不变的处理方式,以及围绕 Hydra 把 BRep 直接接进查看管线的做法——这些都是自己写内核时会撞上的问题,而这里有现成的答案。
项目地址:https://github.com/NVIDIA-Omniverse/usd-brep
文档:nvidia-omniverse.github.io/usd-brep
许可:Apache License 2.0








