Sandflow-ai/sand3d

3D modeling in Python, built for LLMs

Summary

sand3d is a Python library for procedural 3D modeling through Blender’s bpy module. It represents profiles, solids, edits, frames, joints, and assemblies as short, readable programs, with an API designed to fit within an LLM prompt.

What it is useful for

The library is useful when an engineer needs reproducible geometry for mechanical parts, articulated products, simulation assets, or LLM-generated models. Geometry is selected by names such as parts, faces, and edges rather than manually calculated coordinates.

The README’s bracket example shows the intended workflow: create a rounded rectangular profile, extrude it into a plate, drill a grid of holes, fillet the top edges, and export the result. More complex objects can be assembled from named parts and moving joints. Its washing-machine example combines a cabinet, drum, door, drawer, and dial, then defines a hinge, continuous rotation, prismatic slide, and dial rotation.

Exports are selected by file extension. GLB carries meshes, materials, and joint information at the current pose; URDF represents moving links and joint limits at rest, with OBJ meshes alongside it; USDA preserves the assembly tree, geometry, materials, and physics data. OBJ and STL export meshes alone. This makes sand3d relevant to workflows involving Blender, ROS, PyBullet, MuJoCo, Isaac, USD pipelines, viewers, game engines, and slicers.

For LLM-assisted modeling, the README documents adding docs/api.md to a system prompt. That reference contains the vocabulary, signatures, and examples in roughly 3,600 tokens, while llms.txt points a model toward it.

How engineers can use it

Install the documented package with:

pip install sand3d

or, in a uv project:

uv add sand3d

Python 3.13 is recommended; Python 3.11 is also supported. The documented Blender pairing is bpy 5.2 with Python 3.13 and bpy 4.5 with Python 3.11.

A minimal program can begin with:

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

Dimensions are millimetres by default, while exported lengths are metres. For .usd, .usdc, or .usdz, the README says to generate the file from .usda using USD tools such as usdcat and usdzip.

There are platform constraints: bpy has no wheel for Python 3.12, nor for Intel Macs from version 5.2 onward; the README directs those users to Python 3.11.