企业官网建设流程全解析

usd-brep 是一款基于 NURBS 的边界表示（BRep）实体建模库，其 Python API（usd_brep包）将 SMLib 内核的建模能力完整开放给脚本用户。本文是 USD BRep Python API 的完整参考指南：先带你看懂Brep、PolyBrep、Curve、Surface四大核心类各自负责什么，再重点讲解 Pure、Consumes、Mutates 等四大变更契约——这是判断一个函数"会不会改动你的几何体"的关键，也是新手最容易踩坑的地方。

📦 快速安装 usd_brep 包与导入方式

一行命令完成安装，无需单独安装 OpenUSD：

pip install usd-brep

• 支持 CPython 3.12，平台为 Windows 与 Linux（x86_64 / aarch64）；Windows 还需安装 Visual C++ Redistributable。
• 导入名称是usd_brep，它内部加载编译模块_omni_solid，并自动注册 omniSolid 的 USD schema 插件。
• 建议在任何pxr打开 Stage之前先import usd_brep，否则 schema 插件可能不被识别。

import usd_brep as sm box = sm.primitives.create_box((0.0, 0.0, 0.0), 10, 10, 10) sm.usd.export_brep(box, "box.usda")

全局约定：角度单位是度，Z 轴向上，出错时抛出RuntimeError。API 文档入口见 docs/python.rst，包初始化逻辑在 source/SmPyLib/python/usd_brep/init.py。

🧊 核心类 Brep：实体边界表示与拓扑查询

Brep是整个 API 的中心：一个实体由 Shell → Face → Edge → Vertex 的拓扑层级描述，每个拓扑元素绑定精确的 NURBS 或解析几何，数学上无损、与分辨率无关。

常用查询方法：

Face提供uv_domain()、point_at_uv()、outward_normal_at_uv()等参数化查询；Edge提供length()、tangent_at()；Vertex提供point()。注意Face.surface()和Edge.curve()返回的是借用视图（borrowed view）——它们属于 Brep 所有，做turn_to_nurbs()或缩放等改变表示的操作前必须先释放（详见下方"四大变更契约"一节的注意事项）。

完整类型签名可查阅类型存根 source/SmPyLib/stubs/usd_brep/init.pyi。

🔺 核心类 PolyBrep：三角化网格与快速布尔

PolyBrep是Brep三角化（tessellate）后的多边形网格形态，适合渲染与高性能网格布尔。由tessellate(brep, chord_height_tolerance=..., surface_angle_tolerance_deg=...)等容差参数控制精度。

网格层面的布尔运算在poly子模块中：poly_boolean()搭配PolyBooleanOp（UNION / INTERSECTION / DIFFERENCE / MERGE）使用，比 BRep 布尔快得多，适合预览和碰撞检测。

📐 核心类 Curve 与 Surface：参数化几何引擎

Curve与Surface既是独立对象，也是Edge.curve()/Face.surface()返回的底层几何，支持完整的参数化求值：

• Curve：parameter_range()、evaluate(t)、length()、is_closed()；子类BSplineCurve、Line、Circle（Circle额外提供center()/radius()/normal()）。
• Surface：uv_domain()、evaluate(u, v)、normal(u, v)、derivatives(u, v)、is_planar()、is_periodic_u()。

创建函数按类别归入子模块：

• curves：线段、圆弧、椭圆、螺旋线、B 样条插值/逼近、曲线偏移、投影到面（drop_curve_to_surface）等；
• surfaces：放样（ruled）、旋转（revolution）、扫掠（sweep）、偏置（offset）、皮肤（skin）曲面。

🤖 四大变更契约：判断函数副作用的关键

这是理解 USD BRep Python API 最重要的规则：同一个函数，有的不碰输入，有的原地修改，有的直接"吃掉"输入。每个操作的文档字符串都会标注契约，共四类（约定见 AGENTS.md 的 Mutation conventions，以及模块总说明 source/SmPyLib/src/SmPyMain.cpp）：

⚠️两条常见陷阱：

1. 名字不代表行为：non-manifold 扫掠会修改源 BRep；create_blend_primitive会插入到传入的 Brep 中。以各函数文档标注的契约为准。
2. 想保留原对象就先拷贝：需要保留原件时先brep.copy()再传给修改型操作。

🗂️ 子模块清单：按功能类别快速定位函数

每个函数都有两种等价写法——顶层扁平名（sm.create_box）和分类子模块名（sm.primitives.create_box）。子模块纯粹为了可发现性：dir(sm.primitives)、help(sm.sweeps)可聚焦浏览。

💾 USD 互操作：Brep 与 Mesh 的 .usda 读写

usd子模块负责 OpenUSD 文件级别的导入导出（数据存放在自定义的BrepArrayschema 中）：

• import_breps(filename)/import_brep(filename, prim_path)：从.usda读回Brep列表；
• export_brep(brep, filename)/export_breps(...)/append_breps(...)：导出 BRep；
• import_meshes(...)/export_mesh(...)：多边形网格互转；
• tessellate_file(input, output, ...)/heal_file(input, output)：文件级批量三角化与修复，返回带ok、status_name、message的结果对象。

⚠️export_brep会把生成的 UV 裁剪曲线与 USD 路径属性直接写回传入的 Brep（输入副作用）；想隔离副作用时导出brep.copy()。类型签名见 source/SmPyLib/stubs/usd_brep/usd.pyi。

🧭 进一步学习路径

• 可运行示例：圆角弯管组合建模，见 Examples/PyAPI/round_corner_pipe.py 及其说明 Examples/PyAPI/README.md；
• Python 轮转测试：tests/python/roundtrip_usd_test.py、tests/python/roundtrip_smlib_test.py；
• 绑定层测试：source/SmPyLib/tests/；
• USD 测试文件（BrepArray 校验用例）：TestFiles/brep_validator/；
• BrepArray 数据结构：proposals/UsdSolid/README.md；
• IDE 类型提示：包内置py.typed与.pyi存根，导入即享受自动补全与静态检查。

掌握四大核心类 + 四大变更契约，你就能安全、高效地在 USD BRep 中完成从基元创建、布尔扫掠到 USD 资产输出的完整建模工作流。