sand3d：面向 LLM 的 Python 3D 建模库，用短程序描述零件与装配

sand3d 是一个用于用 Python 编写 3D 对象的库，目标读者包括语言模型。它把 3D 模型表达为短程序，在 Blender 的 bpy 之上组织轮廓、实体、编辑、坐标系、关节和装配。程序描述一个形状是“如何”按零件、按名称构建出来的，因此模型可以用几百个 token 写出一个对象，人也可以直接阅读。

项目定位与解决的问题

传统 3D 建模代码往往依赖手工计算的坐标和不直观的几何操作。sand3d 试图把零件、边和面通过名称来引用，而不是让用户或 LLM 手动计算坐标。它强调程序的可读性和短小，使语言模型更容易生成结构化 3D 程序，也让人能按零件逐段检查模型。

核心特点

• 短程序表达：README 称同一个零件相比 Blender Python、CadQuery 或 FeatureScript，可少用 2 到 6 倍 token。
• API 可整体放入提示词：完整 API 约 3,600 token，便于作为 LLM 的系统提示。
• 按名称引用：零件、边和面通过名称访问，无需手算坐标。
• 确定性构建：同一个程序构建出逐位相同的网格。
• 面向装配：支持关节和姿态，示例中一台前开门洗衣机由 38 行代码描述，包含柜体、滚筒、门体、玻璃、把手、洗涤剂抽屉和旋钮，以及四个关节。

功能范围

sand3d 将所有操作放在扁平的 s3d. 接口下，覆盖多个功能族：

• 轮廓：rect、circle、slot、polygon、poly、arc、spline、superellipse、text、offset、stroke 等。
• 实体与路径：extrude、revolve、sweep、loft、wire、helix、box、cylinder、tube、sphere、torus、dome 等。
• 编辑：cut、join、intersect、split、hole、pocket、fillet、chamfer、shell、dent 等。
• 坐标系与放置：Frame、face、edge、bbox、local、at、transform、grid、ring、along、snap。
• 关节与姿态：joint、pose、seat。
• 装配与导出：group、assembly、attach、export、units、fingerprint 等。
• 零件与材质：gear、knurl、thread、material。

README 特别说明，sand3d 没有 chair()、table() 这类类别级动词；一个类别对应的是用 sand3d 写成的程序。

导出格式

模型可以通过一次 export 调用导出，文件扩展名决定格式，长度单位为米。支持的格式及用途如下：

另外，.usd、.usdc、.usdz 需要通过 USD 自带工具（usdcat、usdzip）从 .usda 转换生成。README 也提到 Revit 的 .rvt 只能由 Revit 自己写入，因此 export 对 Revit 场景提供 .ifc，这是 Revit 可打开和链接的开放标准。IFC 导出当前姿态且不包含关节；其 GlobalId 依赖几何与放置，编辑或移动零件可能改变 ID，不同模型中的相同零件也可能共享同一个 ID，因此不宜用它在多次导出间追踪零件。

安装与运行环境

sand3d 推荐 Python 3.13，也支持 Python 3.11。Blender 作为 bpy 模块随环境提供：Python 3.13 对应 5.2 LTS，Python 3.11 对应 4.5 LTS；CI 运行 bpy 5.2。README 说明 bpy 没有 Python 3.12 的 wheel，从 5.2 起也不支持 Intel Mac，因此这些环境应使用 Python 3.11。

给 LLM 使用

把 docs/api.md 放入系统提示词，即可提供词汇规则、全部签名和示例，约 3,600 token；llms.txt 可引导模型找到该文件。对于多零件对象，文档中的指南给出装配程序的八条规则：先规划，再细节，最后零件。

数据集与示例

项目在 Hugging Face 上发布了五组 sand3d 程序数据集，均采用 CC BY 4.0 许可，来源包括 Objaverse、公开 CAD 模型、Articraft、NVIDIA SimReady 和 AutoMate，分别对应日常物体、机械零件、带关节的铰接物体、仿真就绪资产和机械装配。读者可以在 explorer 中浏览，或在 collection 中查看全部五组。

README 提到，快速入门的每个动词都有可运行代码和渲染结果，gallery 提供可逐个关节播放的对象，API 文档列出全部签名；示例程序位于 docs/examples/ 和 programs/。

适用人群与注意事项

sand3d 适合希望用代码生成 3D 模型、需要把建模能力交给 LLM 的开发者，以及需要将零件和装配导出到 GLB、URDF、USD、IFC 等格式的工程或仿真场景。需要注意，项目主要语言标记为 HTML，但核心是 Python 库；运行依赖 Blender 的 bpy，因此环境选择受 Python 版本和平台限制。使用 IFC 的 GlobalId 时不要将其作为跨导出追踪零件的稳定标识。

项目主页：https://github.com/Sandflow-ai/sand3d

项目地址：sand3d