SMLib 的 Examples 导读：PyAPI / SM_API / SMLib 三组示例怎么读

学一个新库，最有效的方式不是读文档，而是读示例 + 跑起来 + 改一改 。SMLib 仓库的 Examples/ 目录就是为此设计的------它按 API 层分组，每组只演示该层的用法。

这篇带你逐组导读，给出阅读顺序和运行方法。

一、Examples 目录结构

Examples/
├── README.md              ← 总索引（每个类别一个子 README）
├── PyAPI/
│   ├── README.md
│   └── round_corner_pipe.py   ← Python 公开 API 组合示例
├── SM_API/
│   ├── README.md
│   └── boolean_bounds.cpp     ← C++ 包装示例（布尔 + 包围盒成本）
└── SMLib/
    ├── README.md
    └── step_derivatives.cpp   ← 内核原生示例（STEP 曲面导数）

设计原则（README 明示）：

原则	含义
独立可运行	每个示例能单独跑，不依赖其他示例
只用本层 API	PyAPI 只用 Python、SM_API 只用 C++ 包装、SMLib 才碰内核
声明输入范围与所有权	明确示例的输入前提与对象归属
有测试覆盖	重要行为由测试套件验证
README 索引	每个类别有子 README 索引

注意：端到端的 text-to-3D 资产生成脚本不在 Examples 里 ，而在 tools/scripts/example_generate_asset.py（见 《用 SMLib 做 CAD Agent》）。

二、三组示例逐组导读

1️⃣ PyAPI：round_corner_pipe.py（Python 组合）

演示什么 ：一个"矩形路径 + 球形圆角"的闭合正交圆管（OCP 风格参考件），由平面路径扫掠 + 图元 + 变换 + 精确布尔组合而成。

关键设计：

• 示例不新增任何 API，只演示"如何组合现有操作"；
• 明确边界：只支持"四段矩形路径"，每段长度必须大于管径两倍（保证球形切割器不相交）；
• 有对应测试：source/SmPyLib/tests/test_round_corner_pipe_example.py。

运行：

python Examples/PyAPI/round_corner_pipe.py --output round_corner_pipe.smb

适合学 ：Python 组合建模、参数化脚本、usd_brep 连续调用。

2️⃣ SM_API：boolean_bounds.cpp（C++ 包围盒成本）

演示什么 ：从一块板上减去 16 个圆柱切割器，对比三种模式：

1. 不做每次切割后的包围盒查询；
2. 普通包围盒（bTight=FALSE）；
3. 紧包围盒（bTight=TRUE）。

关键设计：

• 每轮都从全新几何开始（避免输入消耗影响对比）；
• 结论：布尔调用本身不需要调用方查包围盒；如果消费方不需要包围盒，就别查；做视野裁剪/宽相位时用普通包围盒，需要更紧包围盒再请求紧版；
• 包围盒是只读查询，但可能填充内部缓存------改变模式不影响布尔参数与建模容差。

构建运行：

./repo.sh build -r --target sm_api_boolean_bounds_example
LD_LIBRARY_PATH="$PWD/_build/linux-x86_64/release:$PWD/_build/target-deps/usd/release/lib:$LD_LIBRARY_PATH" \
    ./_build/linux-x86_64/release/sm_api_boolean_bounds_example

适合学 ：C++ 布尔用法、性能优化意识、SmApi* 的调用风格。

3️⃣ SMLib：step_derivatives.cpp（内核原生示例）

演示什么 ：0.19 版本的 STEP 曲面导数单位修正------构造五种曲面，直接使用返回的导数（不做调用方侧的单位缩放），并与有限差分结果对比验证。

关键设计：

• 这是内核原生 示例------直接调用 SmBSplineSurface 等内核类，不走稳定包装；
• 必须使用包含该修正的构建：旧版本构建会直接失败（而不是静默兼容），避免把错误数据带入生产。

构建运行：

./repo.sh build -r --target smlib_step_derivatives_example
LD_LIBRARY_PATH="$PWD/_build/linux-x86_64/release:$PWD/_build/target-deps/usd/release/lib:$LD_LIBRARY_PATH" \
    ./_build/linux-x86_64/release/smlib_step_derivatives_example

适合学：曲面导数/参数化、内核级 API、数值验证方法（有限差分对比）。

三、怎么读 Examples（推荐路径）

步骤	做什么
① 读 README	先看 Examples/README.md 和每个子目录的 README（它们本身就是索引）
② 选对层	按你的技术栈选：Python → PyAPI；C++ 应用 → SM_API；内核开发 → SMLib
③ 先跑通	按 README 命令构建运行，确认环境没问题
④ 改参数	改尺寸/切割器数量/导数检查容差，观察结果变化
⑤ 对测试	打开对应测试文件，看示例的"预期行为"是如何断言的
⑥ 迁移	把示例结构复制到你的项目里，按需替换几何

四、FAQ

问题	答
为什么 PyAPI 只有一个示例？	示例是"可运行文档"，宁少勿滥；更重要的是每个示例都被测试覆盖
示例能直接用在生产吗？	它们是教学示例：独立、清晰、有边界声明；生产代码要考虑错误处理与扩展性
想找 text-to-3D 的示例？	在 tools/scripts/example_generate_asset.py，不在 Examples 目录
示例报错找不到库？	Linux 跑 C++ 示例需要设置 LD_LIBRARY_PATH 指向 _build/.../release 与 USD lib 目录（README 里有完整命令）

五、一句话总结

Examples 按 API 层分组、每个示例都是一个"可运行的最小知识点"：PyAPI 学组合、SM_API 学性能意识、SMLib 学内核级数值细节。先跑通再改参数，最后对照测试文件理解预期行为。

---

系列文章

SMLib 系列共 10 篇，本篇为第 10 篇，可互相跳转：

• 第 1 篇：《NVIDIA 开源 CAD 内核 SMLib：USD BRep 里有什么、能怎么用》
• 第 2 篇：《Agent 如何用 SMLib 做 CAD 创作：从 AGENTS.md 到 text-to-3D 流水线》
• 第 3 篇：《SMLib 五层架构深度解析》
• 第 4 篇：《SMLib Python API 实战：用 _omni_solid 建模的 10 个常用操作》
• 第 5 篇：《SMLib vs OpenCASCADE：2026 开源 CAD 内核怎么选？》
• 第 6 篇：《SMLib 的 usd.heal_file：STEP/IGES 导入模型修复实战》
• 第 7 篇：《SMLib 镶嵌（Tessellation）参数调优：chord-height 与角度容差怎么选》
• 第 8 篇：《用 SMLib + Claude Code 做一个 CAD 资产生成 Agent（实战）》
• 第 9 篇：《SMLib 的 20 个 Agent 技能详解：skill 化封装怎么做》
• 第 10 篇（本文）：《SMLib 的 Examples 导读：PyAPI / SM_API / SMLib 三组示例怎么读》

仓库：https://github.com/NVIDIA-Omniverse/usd-brep（Apache 2.0，C++ / Python）

版本与构建备注 ：Examples 的构建命令、USD 版本与 LD_LIBRARY_PATH 组合在各平台上差异较大，本文以 v1.0.0（2026-10-08）为准。之后遇到的新报错与可行解法，记录在 www.asksi.com.cn 的 SMLib 系列（含内核构建、STEP 导入修复两篇）。