编者摘要：sand3d 是基于 Blender bpy、面向大模型的 Python 三维建模库，以简短代码程序描述 3D 形体、特征、运动副与装配体，代码可读且 token 开销远低于原生 bpy、CadQuery 等方案，整套 API 仅约 3600token，适合放进 LLM 提示词。它采用命名式访问零件、边和面，无需手动计算坐标，生成结果可确定性复现。内置轮廓、实体生成、布尔编辑、定位排布、关节装配等丰富算子，支持参数化建模与带运动副的机构定义，可导出 GLB、URDF、USD、STL、OBJ 等格式，适配网页可视化、机器人仿真、3D 打印、Omniverse 等场景。环境推荐 Python3.13，兼容 3.11。项目配套 5 份开源数据集，将 Objaverse、SimReady 等海量资产转为 sand3d 代码，开放在线预览。采用 Apache2.0 协议，配套建模规范，方便 LLM 直接生成合规装配代码。
sand3d 10 个问题问与答
- Q：sand3d 是什么？
A：它是基于 Blender bpy、专为大模型设计的 Python 三维建模库，用简短代码描述零件、特征、关节和装配体。 - Q：sand3d 最大优势是什么？
A：代码更省 token，比原生 bpy、CadQuery 等少 2–6 倍 token；全套 API 仅约 3600token，适合放入 LLM 提示词。 - Q：它怎么定位零件，需要手动算坐标吗？
A：通过名称引用零件、边、面，不需要手动计算坐标索引。 - Q：建模结果是否稳定可复现？
A：具备确定性，同一段代码每次生成完全一致的网格。 - Q：支持哪些导出格式，分别适合什么场景？
A：支持 GLB、URDF、USD、OBJ、STL；覆盖网页展示、机器人仿真、Omniverse、3D 打印等场景。 - Q：运行 sand3d 推荐什么 Python 版本？
A：推荐 Python3.13，也支持 3.11；bpy 不支持 Python3.12。 - Q：能不能做带运动关节的装配体？
A：可以，内置 joint 运动副，支持转动、滑动等机构，比如洗衣机舱门、滚筒。 - Q：有没有现成开源数据集？
A：Hugging Face 上有 5 套 CC BY 4.0 数据集，把 Objaverse、SimReady 等资产转为 sand3d 代码。 - Q：sand3d 有没有封装桌椅这类现成物体函数？
A：没有，不提供高层物体封装；桌椅这类模型本身就是用 sand3d 代码编写出来的。 - Q：项目开源协议是什么？
A：Apache License 2.0，可在研究与项目中使用。
sand3d 是一个 Python 库，支持用简短代码程序来描述三维物体：包含截面轮廓、实体、特征编辑、坐标系、运动副与装配体，底层基于 Blender 的 bpy 模块。一段代码描述形状的生成方式，分部件、用自然的语义表达；模型仅需几百个 token 即可描述，同时人类也能读懂。
相关链接：
官网：https://sandflow.ai/sand3d/文档站点：https://sand3d.sandflow.ai/
HuggingFace 合集：https://huggingface.co/collections/Sandflow/sand3d-6aec268fbdcd3bc174236168
在线预览空间：https://huggingface.co/spaces/Sandflow/sand3d-explorer
许可证：Apache 2.0支持 Python 3.11 / 3.13，bpy 4.5 / 5.2
为什么选择 sand3d
-
极简省 token：描述同一个零件，相比原生 Blender Python、CadQuery、FeatureScript，token 数量可减少 2～6 倍。整套 API 全部放进提示词也仅约 3600 token。 -
基于命名访问，而非硬算坐标：零件、边、面都通过名字引用，不需要手动计算坐标索引。 -
结果确定性强：同一段代码生成完全一致的网格，结果可复现。
完整装配体：分部件搭建
一台前置滚筒洗衣机仅需 38 行代码即可定义：柜体、滚筒、带玻璃与把手的舱门、洗涤剂盒、旋钮，每个都是独立命名零件；同时定义 4 组运动副，描述它们的运动方式。
door = s3d.group(”door”, ring, glass, handle)# 把手和玻璃随舱门一起运动s3d.joint(”door_hinge”, door, hinge, axis=”-Z”, range=(0, 143))s3d.joint(”drum_spin”, drum, front.move(0, 400), kind=”continuous”)s3d.joint(”drawer_slide”, drawer, top_band.move(150), kind=”prismatic”, axis=”+X”, range=(0, 200))s3d.joint(”dial_turn”, dial, top_band.move(-150), kind=”continuous”)return s3d.assembly(”washing_machine”, cab, drum, door, drawer, dial, front=front)
导出格式：GLB、URDF、USD、OBJ、STL
一行导出，后缀名自动指定格式；单位默认米。
s3d.export(machine, ”washer.glb”)# 也支持 .urdf, .usda, .obj, .stl
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.usd、.usdc、.usdz 可由 .usda 文件通过 USD 自带工具（usdcat、usdzip）转换。整个场景本身就是标准 Blender 场景，Blender 原生支持的其他导出功能都可以继续使用。
安装要求
Python 3.13（推荐）或 Python 3.11。底层依赖 Blender 自带的 bpy 模块：bpy 5.2 LTS 适配 Python3.13，bpy 4.5 LTS 适配 Python3.11；CI 测试环境使用 bpy 5.2。
pip install sand3d# uv 项目中使用：uv add sand3d
注意：bpy 没有提供 Python3.12 的预编译包；5.2 版本之后 Intel Mac 环境也不支持，这类环境请使用 Python3.11。
第一个示例程序
import sand3d as s3ddef bracket(w=80, d=40, t=6, hole_d=6.6, pitch=50):plate = s3d.extrude(”plate”, s3d.rect(w, d, r=4), t)s3d.hole(plate, hole_d, on=s3d.grid(2, 1, pitch, 0))s3d.fillet(plate, 1, edges=”top”)return plates3d.export(bracket(), ”bracket.glb”)
默认单位：毫米。
快速上手文档：https://sand3d.sandflow.ai/quickstart.html装配样例展厅：https://sand3d.sandflow.ai/gallery.html完整 API 文档：https://sand3d.sandflow.ai/api.html示例代码仓库：https://github.com/Sandflow-ai/sand3d/tree/main/docs/examples/https://github.com/Sandflow-ai/sand3d/tree/main/programs/
接入大语言模型
把 docs/api.md 放入系统提示词：里面包含语法规则、全部函数签名与示例，总 token 约 3600；llms.txt 文件可以引导模型读取这份文档。对于多零件装配体，配套指南文档（https://sand3d.sandflow.ai/guidelines.html）给出了编写装配代码的 8 条原则：先总体规划、再细化细节、最后定义各个零件。
库内置能力清单
全部接口统一在 s3d.xxx 下调用：
-
轮廓（16 个）：rect 矩形、circle 圆、slot 长圆孔、polygon 多边形、poly 折线、arc 圆弧、spline 样条曲线、superellipse 超椭圆、text 文字、offset 偏移、stroke 描边等 -
实体与路径（15 个）：extrude 拉伸、revolve 旋转、sweep 扫掠、loft 放样、wire 线框、helix 螺旋线、box 立方体、cylinder 圆柱、tube 圆管、sphere 球体、torus 圆环、dome 穹顶等 -
特征编辑（15 个）：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 指纹校验等（8 个） -
零件与材质：gear 齿轮、knurl 滚花、thread 螺纹、material 材质
没有封装
chair()、table()这类高层对象函数；椅子、桌子这类物品本身就是用 sand3d 代码写出来的程序。
数据集
在 HuggingFace 上开放了 5 套三维数据集，协议 CC BY 4.0，全部是 sand3d 代码形式描述三维物体：
-
sand3d-objaverse：基于 Objaverse 日常物体，全部重写成 sand3d 程序 -
sand3d-cad：来自公开 CAD 模型的机械零件 -
sand3d-articraft：来自 Articraft 的带运动关节物体 -
sand3d-simready：NVIDIA SimReady 仿真资产 -
sand3d-automate：AutoMate 机械装配体，每个零件都参数化
在线浏览工具：sand3d-explorer
引用
如果你在研究工作中使用 sand3d，请按如下格式引用；仓库内 CITATION.cff 文件也包含该信息，GitHub 页面可一键引用。
@misc{sand3d2026,author = {Neveu, Thibault and Loy, Andréa},title = {sand3d},year = {2026},note = {Version 1.6.3},url = {https://github.com/Sandflow-ai/sand3d}}
贡献与许可证
库的构建、测试、版本管理规范见 CONTRIBUTING.md。许可证：Apache License 2.0。