sand3d - 用 Python 短程序为 LLM 描述 3D 物体的建模库

sand3d 是一个用 Python 编写 3D 物体的库，由 Sandflow-ai 维护，采用 Apache-2.0 许可证。它的思路不是让使用者手工拖拽建模，也不是让模型直接输出坐标堆砌的脚本，而是把形状写成一段段短程序：轮廓、实体、编辑、坐标系、关节与装配，全部建立在 Blender 的 bpy 之上。据项目自述，一段程序描述的是「这个形状是怎么做出来的」，按零件分块、用自己的词汇表达，因此模型用几百个 token 就能写出一个零件，人也能直接读懂。它适合两类读者：一是希望让大语言模型稳定生成 3D 几何的开发者，二是需要可读、可复现建模脚本的工程师。

维护者与状态

项目由 Sandflow-ai 维护，仓库创建于 2026-11-03，最后提交时间为 2026-11-05。最新 release 为 v1.6.2，发布于 2026-11-04。截至 2026-11-06，仓库星标数为 295。项目另有一个官网页面，用于展示项目本身。

主要能力

以下能力均据项目 README 自述，未经过实际运行验证。

• 面向 LLM 的紧凑表达。 项目称，同一个零件用 sand3d 写比用 Blender Python、CadQuery 或 FeatureScript 写少 2 到 6 倍 token；整套 API 约 3600 token，可以完整放进提示词。
• 按名字引用，而非手算坐标。 零件、边、面通过名称访问，不需要手工计算坐标。
• 确定性构建。 项目称同一段程序构建出的网格逐位一致。
• 统一的扁平 API。 所有动词挂在 s3d. 这一层上，涵盖轮廓（rect、circle、slot、polygon、spline、text 等 16 个）、实体与路径（extrude、revolve、sweep、loft、helix、box、cylinder、sphere 等 15 个）、编辑（cut、join、hole、pocket、fillet、chamfer、shell 等 15 个）、坐标系与放置（Frame、face、edge、bbox、grid、ring、along、snap 等）、关节（joint、pose、seat）、装配（group、assembly、attach、export、units、fingerprint 等）以及零件与材质（gear、knurl、thread、material）。README 明确说明不提供 chair()、table() 这类类别动词，类别本身就是用 sand3d 写出来的一段程序。
• 多格式导出。 一次调用即可导出，文件扩展名决定格式，长度单位为米。GLB 携带网格、材质以及各节点 extras 中的关节信息，面向网页、查看器与游戏引擎；URDF 为每个运动零件生成一个 link 及其关节和限位，并附带 OBJ 网格，面向 ROS、PyBullet、MuJoCo、Isaac；USDA 以 OpenUSD 的 UsdGeom、UsdPhysics 表达同一棵树并带材质，面向 Omniverse、Isaac Sim 与 USD 管线；OBJ 与 STL 只导出当前姿态的网格，OBJ 为 Y 轴向上，二进制 STL 为 Z 轴向上。项目说明 .usd、.usdc、.usdz 需借助 USD 自带工具从 .usda 转换。
• 关节与装配。 README 给出的示例是一台前开式洗衣机，38 行代码里包含柜体、滚筒、带玻璃与把手的门、洗涤剂抽屉和旋钮，每个都是具名零件，并用四个关节描述运动方式，例如门铰链的旋转范围、滚筒的连续旋转、抽屉的直线滑动。
• 配套数据集。 项目称在 Hugging Face 上以 CC BY 4.0 发布了五个来源的 sand3d 程序数据集，分别对应 Objaverse 日常物体、公开 CAD 机械零件、Articraft 铰接物体、NVIDIA SimReady 仿真资产与 AutoMate 机械装配。

使用入口

代码仓库位于 Sandflow-ai/sand3d，项目主页为 sandflow.ai/sand3d。

据项目说明，安装需要 Python 3.13（推荐）或 3.11，Blender 以 bpy 模块的形式随包提供：Python 3.13 对应 Blender 5.2 LTS，Python 3.11 对应 4.5 LTS，CI 运行在 bpy 5.2 上。安装命令为：

pip install sand3d
# 或在 uv 项目中使用：
uv add sand3d

README 给出的第一个程序如下，默认单位为毫米：

import sand3d as s3d

def 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 plate

s3d.export(bracket(), "bracket.glb")

若要把 sand3d 交给大模型使用，项目建议把 docs/api.md 放进系统提示词，其中包含词汇规则、全部函数签名与示例，约 3600 token；llms.txt 则用于把模型指向该文件。对于多零件物体，项目另提供装配程序的八条准则：先规划，再细节，最后零件。

许可与限制

项目采用 Apache-2.0 许可证，具体条款以仓库中的 LICENSE 文件为准。数据集方面，README 称其在 Hugging Face 上以 CC BY 4.0 发布。

已知限制主要来自运行环境：bpy 没有面向 Python 3.12 的 wheel，从 Blender 5.2 起也不再支持 Intel Mac，在这些环境下需改用 Python 3.11。此外，.usd、.usdc、.usdz 不能直接导出，需要借助 USD 自带工具从 .usda 转换。项目不提供类别级的高层动词，使用者需要自己用基础动词组合出具体物体。以上能力描述与 token 数量均来自项目自述，实际表现需以使用者自己的测试为准。