Sandflow-ai/sand3d

项目介绍

sand3d 是一个 Python 库，把 3D 物体写成简短程序，底层基于 Blender 的 bpy。程序由轮廓、实体、编辑、坐标系、关节和装配等构件组成，按部件说明形状是如何生成的；部件、边和面通过名称引用，而不是手算坐标。项目宣称同一程序逐位生成相同的网格。

它面向由 LLM 写模型的场景：完整 s3d.<verb> API 约 3,600 token 即可放进提示词，单个部件消耗的 token 据称比等价的 Blender Python、CadQuery 或 FeatureScript 少 2 到 6 倍。除网格外，程序还能声明关节并导出可动结构。输出支持 GLB、URDF、USDA、OBJ 和 STL；导出长度单位为米，建模默认使用毫米。

适合希望用代码生成可编辑程序化 3D 资产的人，以及把 LLM 接入建模流程的团队。

安装与第一个模型

使用 Python 3.13（推荐）或 3.11。Blender 以 bpy 模块随包提供：Python 3.13 对应 5.2 LTS，Python 3.11 对应 4.5 LTS。Python 3.12 没有 bpy wheel，5.2 起的 Intel Mac 也没有，这些环境应改用 Python 3.11。

pip install sand3d

uv 项目也可以使用 uv add sand3d。下面是最小示例，生成带圆角和四个通孔的支架并导出：

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")

执行后会在当前目录写出 bracket.glb。更多可直接运行的示例见快速上手、可动对象展示页和 examples 目录。

配合 LLM 使用

把 docs/api.md 放进 system prompt，其中包含词汇规则、全部签名和示例；llms.txt 可引导模型找到该文件。多部件对象参考装配指南 给出的八条规则：先规划、再细节、后部件。

格式与使用约束

一次 export 调用按扩展名选择格式。GLB 保存当前姿态下的网格、材质和关节，面向网页、查看器和游戏引擎；URDF 为每个活动部件生成一个 link，包含关节和限位，以静止姿态输出并附带 OBJ 网格，面向 ROS、PyBullet、MuJoCo 和 Isaac；USDA 以 OpenUSD（UsdGeom、UsdPhysics）表达同一棵结构树，面向 Omniverse 和 Isaac Sim；OBJ 与 STL 只包含网格，OBJ 为 Y 轴向上，二进制 STL 为 Z 轴向上，适合通用 3D 工具和切片软件。.usd、.usdc 和 .usdz 需要用 USD 自带工具从 .usda 转换得到。

项目采用 Apache-2.0 许可证。库中没有 chair() 之类的类别动词，可复用的形状要以 sand3d 程序的形式编写。基于 Objaverse、CAD、Articraft、SimReady 和 AutoMate 的五个 sand3d 程序数据集已发布在 Hugging Face，采用 CC BY 4.0 许可，可在浏览器中查看。

HotRepo 点评

在 2026-11-05 的新项目榜上，sand3d 在一个一小时的统计窗口内新增 28 star，从 103 增至 131，fork 为 14；尚未出现在 GitHub 全语言日榜的最好名次记录中。观察窗口很短，只能说明项目发布后短时间内获得关注，不足以判断后续热度。技术层面的依据来自项目官网公布的 token 效率测量，以及为放进模型提示词而刻意压缩的 API 规模。