3D modeling in Python, built for LLMs.
Writing an assembly program
Eight rules for any program that builds a multi-part object in sand3d, by hand or by model. They were
drawn from a review of generated asset and articulated programs, and have not been tested as a prompt.
Every example is a real program, run under 1.4.0, when sand3d was still named sky3d. A fault is followed by how it should have been
written: # ← comments are added to the original, and rewrites keep the original's shape.
- The head is the table of contents. First function, named after the object, no geometry.
- One function per distinct part. Built about its own origin; returns one object.
- Name each dimension once, derive the rest. Target 15 numbers per part, ceiling 40.
- Place each part once, in its parent's frame.
- Repeat with frames, mirror with a copy.
- Say each shape with the verb that names it. No
bpy, nobmesh. - Dress the parts when appearance matters. Optional on shape-only data.
- One frame per joint.
What a program looks like
A short head, then one function per part, each with its dimensions in its signature.
import sand3d as s3d
def floor_lamp():
base = s3d.at(round_base(), z=-801) # ← better: stand the stem on the base, derived from it
stem = s3d.at(slender_stem(), z=-774) # ← better: 27 above the base, not a second measured height
return s3d.assembly("floor_lamp", base, stem)
def round_base(d=202, h=30, edge_r=6, collar_d=68, collar_h=9):
base = s3d.cylinder("base", d=d, h=h)
base = s3d.fillet(base, r=edge_r) # ← accidental relation: the taper has nothing to do with the fillet
collar = s3d.at(s3d.cone("collar", d=collar_d, d2=collar_d-edge_r*2, h=collar_h), z=h-1)
base = s3d.join(base, collar)
s3d.material(base, "painted_metal", color="#606060")
return s3d.group("round_base", base)
def slender_stem(d=29, h=1419, shade_z=1300):
stem = s3d.cylinder("stem", d=d, h=h)
s3d.material(stem, "painted_metal", color="#595959")
shade = s3d.at(open_shade(), z=shade_z)
return s3d.group("slender_stem", stem, shade)
def open_shade(d=330.3, top_d=320, h=273, bottom_wall=6, top_wall=13):
wall = s3d.revolve("shade_wall", s3d.poly([(d/2,0),(top_d/2,h),(top_d/2-top_wall,h),(d/2-bottom_wall,0)]))
s3d.material(wall, "fabric", color="#cfc5b6")
return s3d.group("open_shade", wall) # ← one solid at its origin: return wall would do
1. The head is the table of contents
The first function is named after the object. It builds no geometry: it calls the parts, places them
and returns s3d.assembly. Runners call the first function, so the head comes first. Nothing at module
level but the import. A detail that should stay deletable can hang on the assembly with attach, as in
examples/chair.py; none of the 1 089 programs needed it.
Right: a picnic table.
def picnic_table():
top = s3d.at(tabletop(), z=788)
frame = s3d.at(end_frame(), x=659, z=3)
twin = s3d.transform(s3d.copy(frame), mirror="x")
seats = s3d.at(benches(), z=447)
return s3d.assembly("picnic_table", top, frame, twin, seats)
Wrong: a turnstile.
def industrial_turnstile_gate():
base = s3d.extrude("floor_plate", s3d.rect(2700, 2700), 60, both=True)
frame = s3d.group("frame", s3d.at(base, z=30))
rotor = s3d.group(
"rotor", s3d.at(s3d.extrude("spindle_shaft", s3d.circle(96), 760, both=True), z=350)
)
f = s3d.local(frame, z=800)
rotor = s3d.at(rotor, on=f)
s3d.joint("frame_to_rotor", rotor, f, kind="revolute", axis="+Z", range=(-120, 120))
The head is building a floor plate and a shaft. A reader must go through solids to find the plan, and no part can be reused or removed.
How it should read: one line per part in the head. Same shape (F 1.000 against the original).
def industrial_turnstile_gate():
frame = frame_part()
f = s3d.local(frame, z=800)
rotor = s3d.at(rotor_part(), on=f)
s3d.joint("frame_to_rotor", rotor, f, kind="revolute", axis="+Z", range=(-120, 120))
p = s3d.local(frame, x=535, y=-355, z=1345)
pawl = s3d.at(pawl_part(), on=p)
s3d.joint("frame_to_lockout", pawl, p, kind="revolute", axis="normal", range=(0, 46))
return s3d.assembly("industrial_turnstile_gate", frame, rotor, pawl)
...
def frame_part(w=2700, t=60):
base = s3d.extrude("floor_plate", s3d.rect(w, w), t, both=True)
return s3d.group("frame", s3d.at(base, z=t / 2))
...
def rotor_part(d=96, h=760, z=350):
shaft = s3d.extrude("spindle_shaft", s3d.circle(d), h, both=True)
return s3d.group("rotor", s3d.at(shaft, z=z))
...
def pawl_part(length=305, w=20, h=40, x=-182.5):
bar = s3d.extrude("pawl_bar", s3d.rect(length, w), h, both=True)
return s3d.group("lockout_pawl", s3d.at(bar, x=x))
2. One function per distinct part
A part builds about its own origin, takes what differs as arguments, and returns one object. Which one depends on how its pieces hold together:
| the pieces | the verb | what you get |
|---|---|---|
| fused for good | join |
one solid, one material: the first object's |
| separate, moving together | group |
each piece keeps its mesh and its material |
| moving against each other | joint |
parts hung on frames, in the head (rule 8) |
assembly is the top-level group, plus the anchors it publishes. One solid needs no group: return the
solid. The trap: a lone solid placed inside its function loses that placement at the next at (z=50
then z=100 lands at 100, and in a group at 150). Build a lone solid at its origin.
Right: one function, three levers.
lever1 = lever_part(150, "lever1", "#cc3333")
lever2 = lever_part(120, "lever2", "#33cc33")
lever3 = lever_part(100, "lever3", "#3333cc")
Wrong: a seesaw.
end = s3d.at(end_crossrail(), y=-1143, z=134)
other = s3d.at(opposite_crossrail(), y=1143, z=134)
...
def end_crossrail(width=325, d=31, height=182, stem_d=29):
solid = s3d.wire('crossrail', path=[(-width/2+d/2,0,height-d/2),(width/2-d/2,0,height-d/2)], d=d)
stem = s3d.cylinder('upright', d=stem_d, h=height-d/2)
s3d.join(solid, stem)
s3d.material(solid, 'painted_metal', color='#4c71ae')
return s3d.group('end_crossrail', solid)
...
def opposite_crossrail(width=325, d=31, height=182, stem_d=29): # ← the same six lines as end_crossrail
solid = s3d.wire('crossrail', path=[(-width/2+d/2,0,height-d/2),(width/2-d/2,0,height-d/2)], d=d)
stem = s3d.cylinder('upright', d=stem_d, h=height-d/2)
s3d.join(solid, stem)
s3d.material(solid, 'painted_metal', color='#4c71ae')
return s3d.group('opposite_crossrail', solid)
Nothing here crashes. These are one function under two names: a change has to be made twice, and a reader has to compare them line by line to learn they are the same.
How it should read: one function, the other side mirrored (rule 5). Same shape (F 1.000 against the original).
end = s3d.at(end_crossrail(), y=-1143, z=134)
other = s3d.transform(s3d.copy(end), mirror="y")
...
def end_crossrail(width=325, d=31, height=182, stem_d=29):
solid = s3d.wire('crossrail', path=[(-width/2+d/2,0,height-d/2),(width/2-d/2,0,height-d/2)], d=d)
stem = s3d.cylinder('upright', d=stem_d, h=height-d/2)
s3d.join(solid, stem)
s3d.material(solid, 'painted_metal', color='#4c71ae')
return s3d.group('end_crossrail', solid)
3. Name each dimension once, derive the rest
Main dimensions are keyword arguments in millimetres. A value measured on the target appears once. A value that follows from another is written as an expression of it.
- Count the numbers. Target 15 per part, ceiling 40. A number is any numeric literal, keyword defaults included, except 0, 0.5, 1, 2, 45, 90, 180, 270 and 360. Clean programs have a median of 15, programs that fought the library 53.
- Read every argument. 31.0 % of the programs declare a dimension they never read.
- No
if x == 28, no unexplained fraction. They hold only while the numbers around them stay put. - Expect to lose a little fidelity. Fewer numbers means a coarser match to a target. It is a trade.
- Copying a value from a source is allowed, once. A joint origin copied from a URDF is a measurement.
Right: each point an expression of the arguments.
profile = s3d.poly([(d/2,0), (d/2,shoulder), (mouth_d/2,h), (mouth_d/2-wall,h), (d/2-wall,shoulder), (d/2-wall,0)])
neck = s3d.revolve("neck", profile)
s3d.material(neck, kind="steel", color="#888888")
Wrong: a freezer cabinet.
def cabinet_part(width=1500, depth=800, height=940):
shell = s3d.extrude("shell", s3d.rect(width, depth), height, both=True)
shell = s3d.at(shell, z=height / 2)
inner = s3d.at(
s3d.extrude("inner_tool", s3d.rect(width - 100, depth - 100), height - 90, both=True), z=475
)
s3d.cut(shell, inner)
tool1 = s3d.at(s3d.extrude("slot_tool1", s3d.rect(1440, 720), 20, both=True), z=910)
s3d.cut(shell, tool1)
tool2 = s3d.at(s3d.extrude("slot_tool2", s3d.rect(1440, 740), 20, both=True), z=930)
s3d.cut(shell, tool2)
It runs and matches its target. But 475, 1440, 720, 740, 910 and 930 all follow from width, depth and height: change the height and the cabinet breaks.
How it should read: three named dimensions, the rest derived. Same shape (F 1.000 against the original).
def cabinet_part(width=1500, depth=800, height=940, wall=50, lip=30, slot=20):
shell = s3d.extrude("shell", s3d.rect(width, depth), height, both=True)
shell = s3d.at(shell, z=height / 2)
well = height - 2 * slot - wall
inner = s3d.at(
s3d.extrude("inner_tool", s3d.rect(width - 2 * wall, depth - 2 * wall), well, both=True),
z=wall + well / 2,
)
s3d.cut(shell, inner)
open_w, open_d = width - 2 * lip, depth - 2 * lip
tool1 = s3d.at(
s3d.extrude("slot_tool1", s3d.rect(open_w, open_d - slot), slot, both=True),
z=height - 1.5 * slot,
)
s3d.cut(shell, tool1)
tool2 = s3d.at(
s3d.extrude("slot_tool2", s3d.rect(open_w, open_d), slot, both=True),
z=height - slot / 2,
)
s3d.cut(shell, tool2)
4. Place each part once, in its parent's frame
The head places the top-level parts with at, in the object's frame. Each part places its own children.
A placement that follows from a dimension is written from it. The fault is a part built at its world
position, then shifted back.
- Prefer a frame when the relation is the point:
on=ob.face("+Z"),bbox,local. - Every solid starts at z = 0, centred in x and y;
extrude(both=True)centres it on its plane. atsets the values it is given and keeps the others.transformmoves by.
Right: the bowl sits at the stem’s height.
def stem(h=70, waist=6.5, overlap=0.5):
solid = s3d.revolve("stem", s3d.poly([(0,0),(14,0),(7.5,14),(waist,34),(9,57),(16,h+overlap),(0,h+overlap)]))
s3d.material(solid, "plastic", color="#737373")
bowl_placed = s3d.at(bowl(), z=h)
return s3d.group("stem_group", solid, bowl_placed)
Wrong: glasses.
arm = s3d.at(temple_arm(), x=64.5, y=-14.6, z=37.5)
...
def temple_arm(w=3, length=119.2, base=37.5, origin_y=-14.6, origin_x=64.5):
path = s3d.spline([(62-origin_x,-72-origin_y,55-base),(63-origin_x,-45-origin_y,54-base),(66-origin_x,0-origin_y,54-base),(66-origin_x,20-origin_y,53-base),(65-origin_x,32-origin_y,46-base),(65-origin_x,44-origin_y,40-base)])
The head places the arm at (64.5, -14.6, 37.5), and the part takes those same numbers off every point. Each coordinate is written in the world, then undone.
How it should read: the spline in the arm’s own frame. Same shape (F 1.000 against the original).
arm = s3d.at(temple_arm(), x=64.5, y=-14.6, z=37.5)
...
def temple_arm(w=3, d=5):
path = s3d.spline([(-2.5,-57.4,17.5),(-1.5,-30.4,16.5),(1.5,14.6,16.5),(1.5,34.6,15.5),(0.5,46.6,8.5),(0.5,58.6,2.5)])
5. Repeat with frames, mirror with a copy
Copies go through on=s3d.grid(…), ring(…) or along(…). The other side of a pair is
s3d.transform(s3d.copy(placed), mirror="x"). at is for a place, transform for a mirror image. Never
cos and sin in a loop.
Right: a ring of rods.
rods = s3d.at(s3d.cylinder("rod", d=rod_d, h=h), on=s3d.ring(n=count, r=radius))
Right: two mirrored pairs.
end = s3d.at(end_panel(), x=end_x, z=0)
twin = s3d.transform(s3d.copy(end), mirror="x")
...
feet = s3d.at(corner_feet(), x=foot_x, z=foot_z)
other_feet = s3d.transform(s3d.copy(feet), mirror="x")
Wrong: a bunk frame.
for y in (-233, -140, -47):
solids.append(s3d.at(s3d.box("return_post", w=rail, d=rail, h=h-rail), x=w/2-rail/2, y=y))
Three posts at an even pitch of 93. A list of three positions hides that they are evenly spaced.
How it should read: the pitch named, the grid says the rest. Same shape (F 1.000 against the original).
solids += s3d.at(s3d.box("return_post", w=rail, d=rail, h=h-rail), on=s3d.grid(nx=1, ny=3, py=post_pitch), x=w/2-rail/2, y=-140)
6. Say each shape with the verb that names it
A shape sand3d says in one verb is not written as a table of points. bpy and bmesh are forbidden: if
sand3d cannot say a shape, open an issue for the missing verb. Free forms still resist: until sand3d has
their verbs, a table may match a target better.
| the shape | the verb |
|---|---|
| round about an axis | revolve(name, profile) |
| hollow, open on one side | shell(ob, t=…, open="top") |
| a bore, a bolt circle | hole(ob, d=…, on=…) |
| a bent tube | wire(name, path, d, fillet=…) |
| a section that changes along an axis | loft(name, station(z, w, d), …) |
| a long body from its views | body(name, plan, top, bottom) |
| a band along a path | stroke(path, t) |
station is the workhorse. It is a section at height z: width, depth, an offset x, y, and n from
ellipse (2) to box (4). A few stations in a loft say a taper, a bulge or a drift.
Right: a nail, three stations and every value named.
def shaft(length=97.6, base_w=5.8, tip_w=4.0, base_h=6.5, tip_h=2.6, mid_w=4.7, mid_h=4.4, drift=-1.2, rise=0.4):
solid = s3d.loft("shaft", s3d.station(z=0, w=base_w, d=base_h, y=-base_h/2, n=4), s3d.station(z=length/2, w=mid_w, d=mid_h, x=drift, y=-mid_h/2, n=4), s3d.station(z=length, w=tip_w, d=tip_h, y=-tip_h/2-rise, n=4))
Right: a lamp shade, a revolve of four points.
def open_shade(d=330.3, top_d=320, h=273, bottom_wall=6, top_wall=13):
wall = s3d.revolve("shade_wall", s3d.poly([(d/2,0),(top_d/2,h),(top_d/2-top_wall,h),(d/2-bottom_wall,0)]))
Right: a tray in one verb.
tray = s3d.shell(s3d.box("tray", w=w, d=d, h=h), t=t, open="top")
Wrong: a soup bowl.
def bowl_body(r=60, h=66.18, t=1):
profile = s3d.poly([(0, 0), s3d.spline([(0, 0), (21, 4), (42, 19), (56, 43), (r, h)], tangents=((1, 0), (0, 1))), (r-t, h), s3d.spline([(r-t, h), (54, 41), (41, 19), (21, 5), (0, t)], tangents=((0, -1), (-1, 0)))])
The inner wall is typed by hand, point by point, beside the outer one. shell says it in one word, and keeps the wall even.
How it should read: the outside only, then shell. Same shape (F 1.000 against the original).
def bowl_body(r=60, h=66.18, t=1):
profile = s3d.poly([(0, 0), s3d.spline([(0, 0), (21, 4), (42, 19), (56, 43), (r, h)], tangents=((1, 0), (0, 1))), (0, h)])
body = s3d.shell(s3d.revolve("curved_bowl", profile), t=t, open="+Z")
7. Dress the parts when appearance matters
When the target has colours and materials, every part gets s3d.material(ob, kind, color="#rrggbb"),
once, before it is repeated. On shape-only data, such as CAD pieces, it is optional.
- On a group,
materialreaches every part with no material of its own. The nearest call wins. joinkeeps the first object's material,groupkeeps each part's. Join only what is one colour.
Right: dressed before the grid.
plank = s3d.box("top_plank", w=w, d=plank_d, h=h)
s3d.material(plank, "oak", color="#5d4533")
planks = s3d.at(plank, on=s3d.grid(nx=1, ny=5, py=pitch))
8. One frame per joint
In the head, f = s3d.local(parent, x, y, z) gives the pivot. The same f goes to s3d.at(child, on=f)
and to s3d.joint(name, child, f, …).
- Every joint sits in the head, frame, part and joint side by side, so a part comes off with its own lines.
localreads the parent's own space, however deep the chain. No coordinate is composed into the world.axisis a direction in the space the parent lives in:"+X". A source's axis is turned by itsrpyfirst.- The sign of the axis decides which way it opens. A positive value turns by the right hand about the axis. Of 23 drafts where a small edit made the joints right, 8 changed that sign and nothing else.
- What does not move has no joint. Place it and put it in its parent's group before the joint is declared, or it stays behind when the parent moves.
- Build at rest. Every joint at 0, no
s3d.posein the program.
Right: two slides and a hatch hinged on a sliding lid.
left_f = s3d.local(cabinet, -350, 0, 900)
left = s3d.at(lid_left_part(), on=left_f)
s3d.joint("slide_left", left, left_f, kind="prismatic", axis="+X", range=(0, 650))
right_f = s3d.local(cabinet, 350, 0, 920)
right = s3d.at(lid_right_part(), on=right_f)
s3d.joint("slide_right", right, right_f, kind="prismatic", axis="-X", range=(0, 650))
hatch_f = s3d.local(right, 0, 170, 18)
hatch = s3d.at(service_hatch_part(), on=hatch_f)
s3d.joint("hatch_hinge", hatch, hatch_f, kind="revolute", axis="-X", range=(0, 114.59))
Wrong: a rotary shaft, the part on one frame and the joint on another, 0 of 1 joints right.
f = s3d.local(body, 1, 0, 5)
spindle = s3d.at(spindle, on=s3d.local(body))
s3d.joint("body_to_spindle", spindle, f, kind="continuous", axis="+X")
Fixed by the model in its next draft: one frame for both, 1 of 1.
f = s3d.local(body, 0, 0, 0)
spindle = s3d.at(spindle, on=f)
s3d.joint("body_to_spindle", spindle, f, kind="continuous", axis="+X")
Wrong: a wall cabinet, the door swings into the cabinet, 0 of 1 joints right.
s3d.joint("door_hinge", door, f, kind="revolute", axis="+Z", range=(0, 114.59))
Fixed by the model in its next draft: one sign changed, 1 of 1.
s3d.joint("door_hinge", door, f, kind="revolute", axis="-Z", range=(0, 114.59))