3D modeling in Python, built for LLMs.
<!DOCTYPE html>
<html lang="en"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>sand3d: the API for LLMs</title>
<meta name="description" content="3D modeling in Python, built for LLMs.">
<link rel="icon" href="assets/sandflow-symbol-black.svg">
<link rel="stylesheet" href="assets/site.css">
</head><body><div class="page">
<div class="nav"><a class="titre" href="index.html"><img src="assets/sandflow-symbol-black.svg" alt="">sand3d</a><nav><a href="https://sandflow.ai/sand3d/">Website</a><span class="hfg"><img src="assets/hf-logo.svg" alt="Hugging Face"><a href="https://huggingface.co/collections/Sandflow/sand3d-6aec268fbdcd3bc174236168">Datasets</a><span class="sep">·</span><a href="https://huggingface.co/spaces/Sandflow/sand3d-explorer">Explorer</a></span><a class="gh" href="https://github.com/Sandflow-ai/sand3d"><img src="assets/github.svg" alt="">GitHub</a></nav></div>
<p class="repere">API for LLMs</p>
<h1>The whole API, for a prompt</h1>
<div class="bande"></div>
<p class="chapo">Everything a model needs to write sand3d: the rules of the vocabulary, every signature with
one line on it, and worked examples. 3 643 tokens (o200k_base). Paste it in a system prompt as it is.</p>
<div class="actions"><button class="btn plein" data-copy="raw">Copy for your prompt</button>
<a class="btn" href="api.md">api.md, raw</a><a class="btn" href="llms.txt">llms.txt</a></div>
<p><code>import sand3d as s3d</code>; mm, or <code>units("m")</code> first. Makers take a name, return the solid; edits return it. Edges and faces go by their maker's names (top bottom side rim seam start end cut, tool names, plate.top).</p>
<ol class="rules"><li>A placement is a frame plus values. <code>at</code> sets the values it is given and keeps the others; <code>on=</code> changes the frame, and x, y, z then run along its axes; <code>transform</code> moves the whole thing, as a parent would, mirror included.</li><li>To repeat, pass a list of frames to <code>on=</code>: once per frame, in <code>at</code>, <code>hole</code> and <code>pocket</code>.</li><li>A list of objects is worth its elements, wherever a verb takes objects.</li><li>What a verb uses up no longer exists. <code>copy</code> keeps it; always use what <code>at</code> returns.</li><li>Every solid starts at z = 0, centred in x and y: <code>box</code> is the <code>extrude</code> of its <code>rect</code>; <code>extrude(both=True)</code> centres one on its plane. A face's frame starts where the origin projects onto it: a vertical face's, at its foot. A frame's Z is the face's normal; on a face whose normal is ±Z its X is +X, on any other X is Z × normal: on a face looking +X, X is +Y and Y is up. A side, an edge or a corner of a box is named by directions: <code>bbox(ob, "+X")</code> is the centre of that side of its bounding box, <code>"+X-Y"</code> the middle of an edge, <code>"+X-Y+Z"</code> a corner, with the axes of a face looking the first way named, on a part or a group; <code>at</code>'s <code>anchor</code> takes the same ("-Z", "+Y-Z"; its words top bottom left right front back are +Z -Z -X +X -Y +Y).</li><li>A joint lets a part move on another. Place the part first: <code>joint</code> does not move it, it says how it moves — on the part its frame <code>on</code> was read on (<code>ob.face</code>, <code>bbox</code>, <code>local</code>, an assembly's anchor; it stays read on it through <code>.move</code>, <code>.turn</code>, <code>.offset</code>), about or along <code>axis</code>: a direction ("+Z", "-X"…) in the space the parent lives in, as in <code>face</code>, or "normal", <code>on</code>'s Z. A pivot given as numbers — a source's joint origin, xyz and rpy — is <code>local(parent, x, y, z, rx, ry, rz)</code>, in the parent's own space: <code>at(child, on=…)</code> places the child there, <code>joint</code> hangs it there. Positive values slide along the axis, or turn by the right hand about it: about +Z, +X turns toward +Y — a door hinged on the -Y edge of a +X face opens outward about "-Z". The range contains 0; a joint that follows another takes its range from it. Everything is built at rest, every joint at 0; <code>pose(child, value)</code> moves the mechanism. A part with no joint moves with its group; a jointed part moves by its joint, whatever group it is in; <code>on</code> is never read on the child itself. Joints may come before or after <code>group</code>/<code>assembly</code>. <code>copy</code> copies a jointed part's joints (it hangs on the same parent); <code>transform</code> moves the part with its pivot (a mirror image moves as the image of the motion); <code>at</code> refuses it. Two joints on one child compose in order (a screw: a turn, and a slide that follows it with <code>ratio=pitch / 360</code>).</li></ol>
<h2 id="signatures">Signatures</h2>
<h3>Profiles</h3><div class="fiche"><pre class="code">rect(w, d, r=<span class="n">0</span>, chamfer=<span class="n">0</span>) <span class="c"># Centred; corners rounded or cut</span>
circle(d) <span class="c"># Centred</span>
ellipse(w, d) <span class="c"># Centred</span>
slot(l, d) <span class="c"># Round-ended slot along X</span>
polygon(n, d) <span class="c"># Regular polygon, corner on +X</span>
poly(pts, fillet=<span class="n">0</span>, chamfer=<span class="n">0</span>) <span class="c"># Outline through points, arcs, splines</span>
arc(center=(<span class="n">0</span>, <span class="n">0</span>), r=<span class="n">1</span>, start=<span class="n">0</span>, end=<span class="n">360</span>, *, through=<span class="k">None</span>, to=<span class="k">None</span>) <span class="c"># Arc from start to end, anticlockwise if end > start: a path, or a poly run</span>
tangent_arc(to) <span class="c"># Poly run: arc leaving tangent</span>
spline(pts, closed=<span class="k">False</span>, tangents=<span class="k">None</span>, loop=<span class="k">False</span>) <span class="c"># Smooth curve; closed: a profile; loop: a ring path</span>
superellipse(w, d, n=<span class="n">2</span>, taper=<span class="n">0</span>) <span class="c"># Ellipse (n=2) to box (n=4); taper narrows its +Y side, an egg</span>
station(z, w, d, x=<span class="n">0</span>, y=<span class="n">0</span>, n=<span class="n">2</span>, taper=<span class="n">0</span>) <span class="c"># Loft section at height z; n and taper as superellipse</span>
text(s, size, font=<span class="k">None</span>) <span class="c"># Centred outline</span>
offset(p, t) <span class="c"># Grown by t</span>
stroke(path, t) <span class="c"># A band t wide along an open path, centred on it: a closed outline</span>
wrap(*profiles) <span class="c"># Convex outline round profiles</span>
mirror(p, flip=<span class="s">'x'</span>) <span class="c"># Plus its image, flip negated</span></pre><p class="counts">16 lines · 348 tokens (o200k_base)</p></div><h3>Solids, paths</h3><div class="fiche"><pre class="code">extrude(name, profile, h=<span class="k">None</span>, taper=<span class="n">0</span>, twist=<span class="n">0</span>, both=<span class="k">False</span>, h2=<span class="k">None</span>, on=<span class="k">None</span>, until=<span class="k">None</span>) <span class="c"># Prism up Z (taper > 0 narrows it upward), or until a plane or solid; on a face, by on</span>
revolve(name, profile, angle=<span class="n">360</span>) <span class="c"># X radius, Y height, turned about Z</span>
sweep(name, profile, path, scale=<span class="n">1</span>, twist=<span class="n">0</span>, frenet=<span class="k">False</span>) <span class="c"># Profile along a path</span>
loft(name, *sections, follow=<span class="k">False</span>, loop=<span class="k">False</span>) <span class="c"># Through placed sections, capped; loop: a ring</span>
body(name, plan, top, bottom, n=<span class="n">2</span>) <span class="c"># Solid along Y from its views, where they draw it: plan (y, width), side top and bottom (y, z) or numbers; superellipse sections</span>
wire(name, path, d, closed=<span class="k">None</span>, fillet=<span class="n">0</span>) <span class="c"># Round wire along a path: (x, y, z) points, a spline, an arc, a helix; fillet rounds the corners of points, d / 2 at least</span>
helix(d, pitch, h, left=<span class="k">False</span>) <span class="c"># Coil path up Z</span>
box(name, w, d, h) <span class="c"># On Z = 0, centred in X and Y</span>
cylinder(name, d, h) <span class="c"># Along Z, from Z = 0</span>
tube(name, d, d_in, h) <span class="c"># Along Z, from Z = 0</span>
cone(name, d, h, d2=<span class="n">0</span>) <span class="c"># Along Z, from Z = 0</span>
sphere(name, d) <span class="c"># On Z = 0</span>
wedge(name, w, d, h, top=<span class="n">0</span>) <span class="c"># Box narrowed on top</span>
torus(name, d, d_wire) <span class="c"># Ring about Z, on Z = 0</span>
dome(name, d, h) <span class="c"># Cap on Z = 0</span></pre><p class="counts">15 lines · 416 tokens (o200k_base)</p></div><h3>Edits</h3><div class="fiche"><pre class="code">cut(ob, *tools) <span class="c"># Subtract tools</span>
join(ob, *others) <span class="c"># Fuse others in; ob's material wins: group keeps each its own</span>
intersect(ob, tool) <span class="c"># Keep the common part</span>
split(ob, frame, keep=<span class="s">'above'</span>) <span class="c"># By a frame's plane</span>
delete(ob) <span class="c"># Remove it</span>
copy(ob) <span class="c"># An independent copy, its joints with it</span>
hole(ob, d, on=(<span class="n">0</span>, <span class="n">0</span>), depth=<span class="k">None</span>, cbore=<span class="k">None</span>, csk=<span class="k">None</span>) <span class="c"># On frames or points: through, or depth deep</span>
pocket(ob, profile, depth=<span class="k">None</span>, on=<span class="k">None</span>) <span class="c"># Profile cut in from a face</span>
merge(*obs) <span class="c"># No boolean</span>
scale(ob, s) <span class="c"># About its origin</span>
fillet(ob, r, edges=<span class="s">'all'</span>) <span class="c"># Round named edges</span>
chamfer(ob, d, edges=<span class="s">'all'</span>, d2=<span class="k">None</span>, angle=<span class="k">None</span>) <span class="c"># Bevel named edges</span>
soften(ob, r, angle=<span class="n">30</span>) <span class="c"># Round all sharp edges</span>
shell(ob, t, open=<span class="k">None</span>) <span class="c"># Hollow; open named faces, or the flat faces looking "+Y", "-X +X"</span>
dent(ob, points, r, depth) <span class="c"># Press hollows at points</span></pre><p class="counts">15 lines · 267 tokens (o200k_base)</p></div><h3>Frames, placement</h3><div class="fiche"><pre class="code">Frame(origin=(<span class="n">0</span>, <span class="n">0</span>, <span class="n">0</span>), normal=(<span class="n">0</span>, <span class="n">0</span>, <span class="n">1</span>), up=<span class="k">None</span>) <span class="c"># A place to build on</span>
.<span class="vb">offset</span>(d) .turn(rx=<span class="n">0</span>, ry=<span class="n">0</span>, rz=<span class="n">0</span>) .move(x=<span class="n">0</span>, y=<span class="n">0</span>, z=<span class="n">0</span>) .point(x=<span class="n">0</span>, y=<span class="n">0</span>, z=<span class="n">0</span>)
ob.face(which) <span class="c"># Frame of a named face, or furthest along "+Z"</span>
ob.edge(which) <span class="c"># Path along the edges named which, in the space ob is in: the longest run (as long: the one reaching furthest -X, then -Y, -Z), closed if it closes</span>
bbox(ob, which) <span class="c"># Frame on its bounding box: a side "+X", an edge "+X-Y", a corner "+X-Y+Z"</span>
local(ob, x=<span class="n">0</span>, y=<span class="n">0</span>, z=<span class="n">0</span>, rx=<span class="n">0</span>, ry=<span class="n">0</span>, rz=<span class="n">0</span>) <span class="c"># Frame at (x, y, z) of its own space, turned (rx, ry, rz) degrees</span>
at(ob, x=<span class="k">None</span>, y=<span class="k">None</span>, z=<span class="k">None</span>, rx=<span class="k">None</span>, ry=<span class="k">None</span>, rz=<span class="k">None</span>, on=<span class="k">None</span>, anchor=<span class="k">None</span>) <span class="c"># Place it: set what is given, keep the rest; anchor: "-Z", "+Y-Z"…</span>
transform(ob, x=<span class="n">0</span>, y=<span class="n">0</span>, z=<span class="n">0</span>, rx=<span class="n">0</span>, ry=<span class="n">0</span>, rz=<span class="n">0</span>, mirror=<span class="k">None</span>) <span class="c"># Move it by, as a parent would; its placement, not its mesh</span>
grid(nx, ny=<span class="n">1</span>, px=<span class="n">0</span>, py=<span class="n">0</span>, stagger=<span class="k">False</span>, on=<span class="k">None</span>) <span class="c"># On a grid</span>
ring(n, r, start=<span class="n">0</span>, angle=<span class="n">360</span>, on=<span class="k">None</span>) <span class="c"># On a circle</span>
along(path, pitch=<span class="k">None</span>, count=<span class="k">None</span>) <span class="c"># Along a path</span>
snap(targets, points, direction=<span class="k">None</span>) <span class="c"># On a surface</span></pre><p class="counts">12 lines · 405 tokens (o200k_base)</p></div><h3>Parts</h3><div class="fiche"><pre class="code">gear(name, teeth, module, width, bore=<span class="n">0</span>, angle=<span class="n">20</span>) <span class="c"># Involute spur gear</span>
knurl(name, d, h, pitch=<span class="k">None</span>, straight=<span class="k">False</span>) <span class="c"># Knurled grip; pitch 1 mm by default</span>
thread(name, d, length, pitch, left=<span class="k">False</span>) <span class="c"># Threaded rod</span></pre><p class="counts">3 lines · 70 tokens (o200k_base)</p></div><h3>Materials</h3><div class="fiche"><pre class="code">material(ob, kind, color=<span class="k">None</span>, roughness=<span class="k">None</span>, metallic=<span class="k">None</span>, opacity=<span class="k">None</span>, emission=<span class="k">None</span>) <span class="c"># Kind: oak walnut pine birch steel brushed_steel chrome aluminium brass copper painted_metal plastic glossy_plastic rubber glass ceramic fabric velvet leather marble concrete light; color "#rrggbb"</span></pre><p class="counts">1 lines · 61 tokens (o200k_base)</p></div><h3>Articulation</h3><div class="fiche"><pre class="code">joint(name, child, on, kind=<span class="s">'revolute'</span>, axis=<span class="s">'normal'</span>, range=<span class="k">None</span>, follows=<span class="k">None</span>, ratio=<span class="n">1</span>) <span class="c"># How child moves on the part on was read on: revolute (range in degrees), continuous (no range), prismatic (range in the unit), free (no axis, no range); follows: a child or a joint name, and this joint's value is ratio × its (degrees per unit, or units per degree), no range; returns child</span>
pose(ob, value, joint=<span class="k">None</span>) <span class="c"># Move the mechanism: that joint to value (degrees or the unit), an error outside its range; what it carries follows; joint= when child has two</span>
seat(host, part) <span class="c"># Take out of host the volume part fills, as it sits at rest; part untouched</span></pre><p class="counts">3 lines · 168 tokens (o200k_base)</p></div><h3>Assembly</h3><div class="fiche"><pre class="code">group(name, *children) <span class="c"># Parent of children</span>
assembly(name, *children, **anchors) <span class="c"># Parts and anchors</span>
attach(handle, name, *children) <span class="c"># A detail, under a handle</span>
Handle(root, **anchors) <span class="c"># Root and anchors</span>
export(root, path) <span class="c"># root and what hangs on it by its joints, in metres: .glb at the current pose, joints in extras; .urdf a link per moving part, at rest, meshes beside it; .usda the URDF's tree as OpenUSD text, with the materials; .obj and .stl its meshes at the current pose</span>
empty_scene() <span class="c"># Fresh scene</span>
units(name=<span class="k">None</span>) <span class="c"># Length unit: "mm" (default), "cm", "m"</span>
fingerprint() <span class="c"># Digest of the source</span></pre><p class="counts">8 lines · 172 tokens (o200k_base)</p></div>
<h2 id="examples">Examples</h2>
<div class="fiche"><pre class="code"><span class="k">def</span> <span class="f">bracket</span>(w=<span class="n">80</span>, d=<span class="n">40</span>, t=<span class="n">6</span>, hole_d=<span class="n">6.6</span>, pitch=<span class="n">50</span>):
plate = s3d.<span class="vb">extrude</span>(<span class="s">"plate"</span>, s3d.<span class="vb">rect</span>(w, d, r=<span class="n">4</span>), t)
s3d.<span class="vb">hole</span>(plate, hole_d, on=s3d.<span class="vb">grid</span>(<span class="n">2</span>, <span class="n">1</span>, pitch, <span class="n">0</span>))
s3d.<span class="vb">fillet</span>(plate, <span class="n">1</span>, edges=<span class="s">"top"</span>)
<span class="k">return</span> plate
<span class="k">def</span> <span class="f">lamp</span>(stem_h=<span class="n">300</span>):
base = s3d.<span class="vb">revolve</span>(<span class="s">"base"</span>, [(<span class="n">0</span>, <span class="n">0</span>), (<span class="n">70</span>, <span class="n">0</span>), (<span class="n">60</span>, <span class="n">20</span>), (<span class="n">0</span>, <span class="n">20</span>)])
stem = s3d.<span class="vb">at</span>(s3d.<span class="vb">cylinder</span>(<span class="s">"stem"</span>, <span class="n">12</span>, stem_h), on=base.face(<span class="s">"top"</span>))
lamp = s3d.<span class="vb">assembly</span>(<span class="s">"lamp"</span>, base, stem, head=s3d.<span class="vb">Frame</span>((<span class="n">0</span>, <span class="n">0</span>, <span class="n">20</span> + stem_h)))
add_shade(lamp)
<span class="k">return</span> lamp
<span class="k">def</span> <span class="f">add_shade</span>(lamp, d=<span class="n">180</span>):
shade = s3d.<span class="vb">shell</span>(s3d.<span class="vb">cone</span>(<span class="s">"shade"</span>, d, <span class="n">120</span>, d2=d / <span class="n">2</span>), <span class="n">1.5</span>, open=<span class="s">"top bottom"</span>)
s3d.<span class="vb">attach</span>(lamp, <span class="s">"shade"</span>, s3d.<span class="vb">at</span>(shade, on=lamp.head))
<span class="k">def</span> <span class="f">rack</span>(n=<span class="n">4</span>, pitch=<span class="n">30</span>, depth=<span class="n">40</span>, t=<span class="n">5</span>):
base = s3d.<span class="vb">extrude</span>(<span class="s">"base"</span>, s3d.<span class="vb">rect</span>(n * pitch, depth, r=<span class="n">3</span>), t)
pegs = s3d.<span class="vb">at</span>(s3d.<span class="vb">cylinder</span>(<span class="s">"peg"</span>, <span class="n">6</span>, <span class="n">20</span>), on=s3d.<span class="vb">grid</span>(n, <span class="n">1</span>, pitch), z=t) <span class="c"># a copy per frame</span>
hook = s3d.<span class="vb">at</span>(s3d.<span class="vb">extrude</span>(<span class="s">"hook"</span>, s3d.<span class="vb">rect</span>(<span class="n">4</span>, <span class="n">12</span>), <span class="n">12</span>), x=n * pitch / <span class="n">2</span> - <span class="n">4</span>, z=t)
image = s3d.<span class="vb">transform</span>(s3d.<span class="vb">copy</span>(hook), mirror=<span class="s">"x"</span>) <span class="c"># its image across x = 0</span>
s3d.<span class="vb">join</span>(base, pegs, hook, image) <span class="c"># a list is its elements</span>
s3d.<span class="vb">hole</span>(base, <span class="n">4</span>, on=s3d.<span class="vb">grid</span>(<span class="n">2</span>, <span class="n">1</span>, (n - <span class="n">1</span>) * pitch).move(y=depth / <span class="n">2</span> - <span class="n">6</span>))
s3d.<span class="vb">chamfer</span>(base, <span class="n">0.6</span>, edges=<span class="s">"peg"</span>)
<span class="k">return</span> base
<span class="k">def</span> <span class="f">gate</span>(w=<span class="n">750</span>, h=<span class="n">1200</span>, post=<span class="n">100</span>):
l_post = s3d.<span class="vb">at</span>(s3d.<span class="vb">box</span>(<span class="s">"post"</span>, post, post, h + <span class="n">300</span>), x=-w - post / <span class="n">2</span>)
r_post = s3d.<span class="vb">transform</span>(s3d.<span class="vb">copy</span>(l_post), mirror=<span class="s">"x"</span>)
board = s3d.<span class="vb">at</span>(s3d.<span class="vb">box</span>(<span class="s">"board"</span>, w, <span class="n">40</span>, h), x=-w / <span class="n">2</span>, z=<span class="n">150</span>) <span class="c"># from the post to x = 0</span>
handle = s3d.<span class="vb">at</span>(s3d.<span class="vb">cylinder</span>(<span class="s">"handle"</span>, <span class="n">20</span>, <span class="n">60</span>), on=s3d.<span class="vb">bbox</span>(board, <span class="s">"+Y"</span>).move(x=<span class="n">60</span> - w / <span class="n">2</span>)) <span class="c"># near x = 0</span>
leaf = s3d.<span class="vb">group</span>(<span class="s">"leaf"</span>, board, handle) <span class="c"># the handle moves with it</span>
s3d.<span class="vb">joint</span>(<span class="s">"hinge"</span>, leaf, s3d.<span class="vb">bbox</span>(l_post, <span class="s">"+X+Y"</span>), axis=<span class="s">"+Z"</span>, range=(<span class="n">0</span>, <span class="n">90</span>)) <span class="c"># the post's edge it opens toward: +X turns toward +Y</span>
twin = s3d.<span class="vb">transform</span>(s3d.<span class="vb">copy</span>(leaf), mirror=<span class="s">"x"</span>) <span class="c"># its image, hinged at x = +w: opens toward +Y too</span>
gate = s3d.<span class="vb">assembly</span>(<span class="s">"gate"</span>, l_post, r_post, leaf, twin)
s3d.<span class="vb">pose</span>(leaf, <span class="n">60</span>)
<span class="k">return</span> gate</pre><p class="counts">38 lines · 837 tokens (o200k_base)</p></div>
<pre id="raw" hidden># sand3d
`import sand3d as s3d`; mm, or `units("m")` first. Makers take a name, return the solid; edits return
it. Edges and faces go by their maker's names (top bottom side rim seam start end cut, tool names,
plate.top).
1. A placement is a frame plus values. `at` sets the values it is given and keeps the others; `on=`
changes the frame, and x, y, z then run along its axes; `transform` moves the whole thing, as a parent
would, mirror included.
2. To repeat, pass a list of frames to `on=`: once per frame, in `at`, `hole` and `pocket`.
3. A list of objects is worth its elements, wherever a verb takes objects.
4. What a verb uses up no longer exists. `copy` keeps it; always use what `at` returns.
5. Every solid starts at z = 0, centred in x and y: `box` is the `extrude` of its `rect`; `extrude(both=True)`
centres one on its plane. A face's frame starts where the origin projects onto it: a vertical face's, at
its foot. A frame's Z is the face's normal; on a face whose normal is ±Z its X is +X, on any other
X is Z × normal: on a face looking +X, X is +Y and Y is up. A side, an edge or a corner of a box is
named by directions: `bbox(ob, "+X")` is the centre of that side of its bounding box, `"+X-Y"` the
middle of an edge, `"+X-Y+Z"` a corner, with the axes of a face looking the first way named, on a part
or a group; `at`'s `anchor` takes the same ("-Z", "+Y-Z"; its words top bottom left right front back
are +Z -Z -X +X -Y +Y).
6. A joint lets a part move on another. Place the part first: `joint` does not move it, it says how it
moves — on the part its frame `on` was read on (`ob.face`, `bbox`, `local`, an assembly's anchor; it
stays read on it through `.move`, `.turn`, `.offset`), about or along `axis`: a direction ("+Z", "-X"…)
in the space the parent lives in, as in `face`, or "normal", `on`'s Z. A pivot given as numbers — a
source's joint origin, xyz and rpy — is `local(parent, x, y, z, rx, ry, rz)`, in the parent's own space:
`at(child, on=…)` places the child there, `joint` hangs it there. Positive values slide along the axis,
or turn by the right hand about it: about +Z, +X turns toward +Y — a door hinged on the -Y edge of a +X
face opens outward about "-Z". The range contains 0; a joint that follows another takes its range from
it. Everything is built at rest, every joint at 0; `pose(child, value)` moves the mechanism. A part with
no joint moves with its group; a jointed part moves by its joint, whatever group it is in; `on` is never
read on the child itself. Joints may come before or after `group`/`assembly`. `copy` copies a jointed
part's joints (it hangs on the same parent); `transform` moves the part with its pivot (a mirror image
moves as the image of the motion); `at` refuses it. Two joints on one child compose in order (a screw: a
turn, and a slide that follows it with `ratio=pitch / 360`).
```python
# profiles
rect(w, d, r=0, chamfer=0) # Centred; corners rounded or cut
circle(d) # Centred
ellipse(w, d) # Centred
slot(l, d) # Round-ended slot along X
polygon(n, d) # Regular polygon, corner on +X
poly(pts, fillet=0, chamfer=0) # Outline through points, arcs, splines
arc(center=(0, 0), r=1, start=0, end=360, *, through=None, to=None) # Arc from start to end, anticlockwise if end > start: a path, or a poly run
tangent_arc(to) # Poly run: arc leaving tangent
spline(pts, closed=False, tangents=None, loop=False) # Smooth curve; closed: a profile; loop: a ring path
superellipse(w, d, n=2, taper=0) # Ellipse (n=2) to box (n=4); taper narrows its +Y side, an egg
station(z, w, d, x=0, y=0, n=2, taper=0) # Loft section at height z; n and taper as superellipse
text(s, size, font=None) # Centred outline
offset(p, t) # Grown by t
stroke(path, t) # A band t wide along an open path, centred on it: a closed outline
wrap(*profiles) # Convex outline round profiles
mirror(p, flip='x') # Plus its image, flip negated
# solids, paths
extrude(name, profile, h=None, taper=0, twist=0, both=False, h2=None, on=None, until=None) # Prism up Z (taper > 0 narrows it upward), or until a plane or solid; on a face, by on
revolve(name, profile, angle=360) # X radius, Y height, turned about Z
sweep(name, profile, path, scale=1, twist=0, frenet=False) # Profile along a path
loft(name, *sections, follow=False, loop=False) # Through placed sections, capped; loop: a ring
body(name, plan, top, bottom, n=2) # Solid along Y from its views, where they draw it: plan (y, width), side top and bottom (y, z) or numbers; superellipse sections
wire(name, path, d, closed=None, fillet=0) # Round wire along a path: (x, y, z) points, a spline, an arc, a helix; fillet rounds the corners of points, d / 2 at least
helix(d, pitch, h, left=False) # Coil path up Z
box(name, w, d, h) # On Z = 0, centred in X and Y
cylinder(name, d, h) # Along Z, from Z = 0
tube(name, d, d_in, h) # Along Z, from Z = 0
cone(name, d, h, d2=0) # Along Z, from Z = 0
sphere(name, d) # On Z = 0
wedge(name, w, d, h, top=0) # Box narrowed on top
torus(name, d, d_wire) # Ring about Z, on Z = 0
dome(name, d, h) # Cap on Z = 0
# edits
cut(ob, *tools) # Subtract tools
join(ob, *others) # Fuse others in; ob's material wins: group keeps each its own
intersect(ob, tool) # Keep the common part
split(ob, frame, keep='above') # By a frame's plane
delete(ob) # Remove it
copy(ob) # An independent copy, its joints with it
hole(ob, d, on=(0, 0), depth=None, cbore=None, csk=None) # On frames or points: through, or depth deep
pocket(ob, profile, depth=None, on=None) # Profile cut in from a face
merge(*obs) # No boolean
scale(ob, s) # About its origin
fillet(ob, r, edges='all') # Round named edges
chamfer(ob, d, edges='all', d2=None, angle=None) # Bevel named edges
soften(ob, r, angle=30) # Round all sharp edges
shell(ob, t, open=None) # Hollow; open named faces, or the flat faces looking "+Y", "-X +X"
dent(ob, points, r, depth) # Press hollows at points
# frames, placement
Frame(origin=(0, 0, 0), normal=(0, 0, 1), up=None) # A place to build on
.offset(d) .turn(rx=0, ry=0, rz=0) .move(x=0, y=0, z=0) .point(x=0, y=0, z=0)
ob.face(which) # Frame of a named face, or furthest along "+Z"
ob.edge(which) # Path along the edges named which, in the space ob is in: the longest run (as long: the one reaching furthest -X, then -Y, -Z), closed if it closes
bbox(ob, which) # Frame on its bounding box: a side "+X", an edge "+X-Y", a corner "+X-Y+Z"
local(ob, x=0, y=0, z=0, rx=0, ry=0, rz=0) # Frame at (x, y, z) of its own space, turned (rx, ry, rz) degrees
at(ob, x=None, y=None, z=None, rx=None, ry=None, rz=None, on=None, anchor=None) # Place it: set what is given, keep the rest; anchor: "-Z", "+Y-Z"…
transform(ob, x=0, y=0, z=0, rx=0, ry=0, rz=0, mirror=None) # Move it by, as a parent would; its placement, not its mesh
grid(nx, ny=1, px=0, py=0, stagger=False, on=None) # On a grid
ring(n, r, start=0, angle=360, on=None) # On a circle
along(path, pitch=None, count=None) # Along a path
snap(targets, points, direction=None) # On a surface
# parts
gear(name, teeth, module, width, bore=0, angle=20) # Involute spur gear
knurl(name, d, h, pitch=None, straight=False) # Knurled grip; pitch 1 mm by default
thread(name, d, length, pitch, left=False) # Threaded rod
# materials
material(ob, kind, color=None, roughness=None, metallic=None, opacity=None, emission=None) # Kind: oak walnut pine birch steel brushed_steel chrome aluminium brass copper painted_metal plastic glossy_plastic rubber glass ceramic fabric velvet leather marble concrete light; color "#rrggbb"
# articulation
joint(name, child, on, kind='revolute', axis='normal', range=None, follows=None, ratio=1) # How child moves on the part on was read on: revolute (range in degrees), continuous (no range), prismatic (range in the unit), free (no axis, no range); follows: a child or a joint name, and this joint's value is ratio × its (degrees per unit, or units per degree), no range; returns child
pose(ob, value, joint=None) # Move the mechanism: that joint to value (degrees or the unit), an error outside its range; what it carries follows; joint= when child has two
seat(host, part) # Take out of host the volume part fills, as it sits at rest; part untouched
# assembly
group(name, *children) # Parent of children
assembly(name, *children, **anchors) # Parts and anchors
attach(handle, name, *children) # A detail, under a handle
Handle(root, **anchors) # Root and anchors
export(root, path) # root and what hangs on it by its joints, in metres: .glb at the current pose, joints in extras; .urdf a link per moving part, at rest, meshes beside it; .usda the URDF's tree as OpenUSD text, with the materials; .obj and .stl its meshes at the current pose
empty_scene() # Fresh scene
units(name=None) # Length unit: "mm" (default), "cm", "m"
fingerprint() # Digest of the source
```
```python
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
def lamp(stem_h=300):
base = s3d.revolve("base", [(0, 0), (70, 0), (60, 20), (0, 20)])
stem = s3d.at(s3d.cylinder("stem", 12, stem_h), on=base.face("top"))
lamp = s3d.assembly("lamp", base, stem, head=s3d.Frame((0, 0, 20 + stem_h)))
add_shade(lamp)
return lamp
def add_shade(lamp, d=180):
shade = s3d.shell(s3d.cone("shade", d, 120, d2=d / 2), 1.5, open="top bottom")
s3d.attach(lamp, "shade", s3d.at(shade, on=lamp.head))
def rack(n=4, pitch=30, depth=40, t=5):
base = s3d.extrude("base", s3d.rect(n * pitch, depth, r=3), t)
pegs = s3d.at(s3d.cylinder("peg", 6, 20), on=s3d.grid(n, 1, pitch), z=t) # a copy per frame
hook = s3d.at(s3d.extrude("hook", s3d.rect(4, 12), 12), x=n * pitch / 2 - 4, z=t)
image = s3d.transform(s3d.copy(hook), mirror="x") # its image across x = 0
s3d.join(base, pegs, hook, image) # a list is its elements
s3d.hole(base, 4, on=s3d.grid(2, 1, (n - 1) * pitch).move(y=depth / 2 - 6))
s3d.chamfer(base, 0.6, edges="peg")
return base
def gate(w=750, h=1200, post=100):
l_post = s3d.at(s3d.box("post", post, post, h + 300), x=-w - post / 2)
r_post = s3d.transform(s3d.copy(l_post), mirror="x")
board = s3d.at(s3d.box("board", w, 40, h), x=-w / 2, z=150) # from the post to x = 0
handle = s3d.at(s3d.cylinder("handle", 20, 60), on=s3d.bbox(board, "+Y").move(x=60 - w / 2)) # near x = 0
leaf = s3d.group("leaf", board, handle) # the handle moves with it
s3d.joint("hinge", leaf, s3d.bbox(l_post, "+X+Y"), axis="+Z", range=(0, 90)) # the post's edge it opens toward: +X turns toward +Y
twin = s3d.transform(s3d.copy(leaf), mirror="x") # its image, hinged at x = +w: opens toward +Y too
gate = s3d.assembly("gate", l_post, r_post, leaf, twin)
s3d.pose(leaf, 60)
return gate
```
</pre>
<div class="fin"><span>sand3d 1.6.3 · Apache-2.0 · <a href="https://github.com/Sandflow-ai/sand3d">source</a></span>
<img src="assets/sandflow-signature.svg" alt="Sandflow"></div>
</div><script>
document.querySelectorAll("[data-copy]").forEach(b => b.addEventListener("click", () => {
const text = document.getElementById(b.dataset.copy).textContent;
navigator.clipboard.writeText(text).then(() => { const t = b.textContent; b.textContent = "Copied";
setTimeout(() => b.textContent = t, 1400); });
}));
</script></body></html>