sand3d 装配程序编写指南:八条规则、错误示例与源码级实现解析
sand3d 装配程序编写指南:八条规则、错误示例与源码级实现解析
本文以 sand3d 官方文档 docs/guidelines.md 为主线,系统讲解用 sand3d 编写多零件装配对象(assembly program)的八条规则。每条规则都保留了原文档中的“正确/错误/应如何改写”三段式代码对照,并结合仓库源码说明 at、local、joint、material、shell 等动词在底层究竟做了什么。读完后,你可以独立写出结构清晰、参数可推导、可动可导出的装配程序,也能据此审查 LLM 生成的建模代码。
文档背景与适用前提
这八条规则并非凭空设定,而是来自对已生成资产程序与可动关节程序的一次复查。按原文说明:规则“was drawn from a review of generated asset and articulated programs, and have not been tested as a prompt”,即它们是编写经验的归纳,而不是经过提示词工程验证的规范模板;文中所有示例都是真实程序,运行于 1.4.0 版本,当时项目名为 sky3d。当前仓库的版本号为 1.6.2(见 src/sand3d/init.py),示例用到的动词在现行源码中仍然存在,例如 at、local、transform、grid、ring、along、copy、assembly、attach、joint、pose、material、shell、loft、station、wire、body、stroke,均可从 src/sand3d/init.py 的 __all__ 清单中查到。因此这些示例可以直接作为当前版本的设计范式使用,只需注意文中提到的统计数字属于当时语料。
规则的总体思路可以用一句话概括:先写"计划",再写"细节",最后写"零件"。这与 docs/examples/chair.py 的文件头注释完全一致——chair 读起来像目录,chair_frame 是计划,add_ 开头的函数把细节挂到计划的锚点上,零件函数放在最后、各自在自己的原点建模。
一个程序长什么样
原文档给出的完整骨架是:一个短小的“头”,然后每个零件一个函数,尺寸写在函数签名里。
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
注意示例中 # ← 注释的作用:它们标出的是作者自己承认的问题,而不是正确写法。floor_lamp 的两行分别用 -801 和 -774 两个实测高度来摆放零件,第二个高度其实是“27 之上”这种关系的确凿证据被写成了两个独立数字;round_base 里锥形收口用了 collar_d-edge_r*2,把倒角半径和收口斜度绑定成了偶然关系;open_shade 只有一个实体,多套一层 group 是冗余的。
这四类毛病正好对应后文的规则 1、2、3、4。
规则 1:头部就是目录
第一个函数以对象命名,不生产任何几何体:它调用零件、摆放零件、返回 s3d.assembly。执行器调用的是第一个函数,所以头必须放在最前面;模块级除了 import 不应有其它语句。需要“删掉也不影响主体”的细节,可以挂在装配体上,用 attach 完成,正如 docs/examples/chair.py 中的做法;原文提到在其复查的 1 089 个程序里,没有一个需要 attach 之外的手段。
正确:一张野餐桌。
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)
错误:一个旋转闸机。
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))
这个“头”自己在建地板和主轴。读者必须穿过实体建模代码才能找到整体布局,而且任何零件都无法复用或单独删除。
应当这样写:头部每个零件一行。形状相同(对原版 F 1.000)。
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))
源码层面也有直接证据支持“头部可被机械地调用”:示例测试会把示例文件当作模块加载,然后用文件名同名函数去执行,见 tests/test_examples.py:
for name in ("bracket", "lamp", "rack", "chair", "gate"):
spec = importlib.util.spec_from_file_location(name, EXAMPLES / f"{name}.py")
...
getattr(module, name)()
也就是说,文件 gate.py 的第一个函数必须叫 gate,这正是“以对象命名的第一个函数”可以写成硬约定、而不是风格偏好的原因。chair.py 更进一步,用 assembly 发布的锚点串起细节:
def chair(width=440, depth=420, seat_h=450):
chair = chair_frame(width, depth, seat_h) # the plan
add_back(chair) # the details, on the plan's anchors
add_rails(chair)
return chair.root
chair_frame 返回 s3d.assembly("chair", seat, legs, width=width, depth=depth, seat_h=seat_h, inset=inset, back_y=depth / 2 - 20),随后 add_back 直接读取 chair.width、chair.back_y、chair.seat_h。这些名字来自 Handle:assembly 只是 Handle(group(...), **anchors),锚点被保存为属性(src/sand3d/assembly.py)。attach 则创建一个挂在根对象下的分组,不返回任何会被继续读取的句柄,所以删除那一行只会删掉细节本身(src/sand3d/assembly.py)。
规则 2:每个独立零件一个函数
零件函数围绕自己的原点建模,把有差异的量作为参数,并且只返回一个对象。返回什么取决于零件内部各块如何结合:
| 各块的关系 | 动词 | 得到什么 |
|---|---|---|
| 永久熔合 | join |
一个实体,一个材质:第一个对象的材质 |
| 分开但一起运动 | group |
每块保留自己的网格和材质 |
| 相互之间会运动 | joint |
挂在 frame 上的零件,写在头部(见规则 8) |
assembly 就是顶层 group 加上它发布的锚点。一个实体不需要 group:直接返回实体。陷阱是:只身放置的实体如果在函数内部被摆过位置,下一次 at 会丢掉那次摆放——z=50 再 z=100 最终落在 100;而放进组里则会是 150(组的摆放会叠加在子级的既有摆放之上)。所以单个实体要在原点构建。
这个陷阱可以在源码里精确解释清楚。at 的实现会先“回忆”对象上次被 at 摆放时的 frame 与各分量,然后只更新本次显式给出的值(src/sand3d/frames.py):
kept_frame, values, kept_anchor, point = _recalled(ob)
if frame is not None:
kept_frame = frame
values.update(given)
values.update(given) 是“设置给出的值、保留其余值”的字面实现,因此第二次 z=100 是覆盖而不是累加。而 group 的作用是把子对象 parent 到新根上,子对象保留自己在父级坐标系中的摆放(src/sand3d/assembly.py),世界位置于是成为“组的摆放 × 子级的摆放”,这就是 50 + 100 = 150 的由来。
正确:一个函数,三根手柄。
lever1 = lever_part(150, "lever1", "#cc3333")
lever2 = lever_part(120, "lever2", "#33cc33")
lever3 = lever_part(100, "lever3", "#3333cc")
错误:一个跷跷板。
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)
这里不会崩溃,但它是同一个函数的两个名字:改动要写两遍,读者还得逐行比对才能发现它们相同。
应当这样写:一个函数,另一侧镜像(规则 5)。形状相同(对原版 F 1.000)。
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)
join 与 group 的语义差异不是约定,而是实现事实:join 走布尔并集,不剥离材质,并在合并前检查材质是否会被吞掉,如果被并入的零件材质与主零件不同,会发出警告提示改用 group(src/sand3d/edit.py);group 只建立父子关系,让每个网格保留自己的材质(材质如何解析见规则 7)。
规则 3:每个尺寸只命名一次,其余全部推导
主要尺寸以关键字参数写在函数签名里,单位是毫米。在目标模型上量到的值只出现一次;由其它值推出的值,就写成那个值的表达式。
- 数数字。 目标是每个零件 15 个,上限 40。数字指任何数值字面量,包括关键字默认值,但
0、0.5、1、2、45、90、180、270、360不计。原文的统计是:干净程序的中位数是 15,与库“较劲”的程序是 53。 - 读每个参数。 原文统计有 31.0% 的程序声明了从不读取的尺寸。
- 不写
if x == 28,不写来路不明的分数。 这类写法只在周围数字都不变时成立。 - 接受精度损失。 数字少意味着与目标的匹配更粗,这是一次权衡。
- 允许从源文件抄写一次。 从 URDF 抄来的关节原点属于“测量值”,不算重复命名。
正确:每个点都是参数的表达式。
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")
错误:一个冷冻柜柜体。
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)
它能跑,也能匹配目标。但 475、1440、720、740、910、930 全都由 width、depth、height 推出:一旦改高度,柜体就散架。
应当这样写:三个命名尺寸,其余推导。形状相同(对原版 F 1.000)。
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)
这里有一个容易忽略的实现细节:cut 会用掉刀具对象(源码注释与 _guard.using_up 都明确说明,见 src/sand3d/edit.py)。因此每次切割都要新建刀具、命名、摆放,不能复用同一个 tool。改写版把每次切割的刀具都当作一次性对象处理,这既符合语义,也让 z=height - slot/2 这类推导表达式不会被“上一次的位置”污染。
“从源文件抄写一次”的最佳落点是关节原点:URDF 里的 xyz 与 rpy 可以直接写成 s3d.local(parent, x, y, z, rx, ry, rz),它的实现正是把给定数值当作“父级自身空间中的一个点和一次旋转”来读(src/sand3d/frames.py)。
规则 4:每个零件只在父坐标系中摆一次
头部用 at 在对象坐标系里摆放顶层零件;每个零件自己摆放它的子件。能由尺寸推出的摆放,就写成尺寸的表达式。典型错误是:零件先按世界坐标建模,再整体回移。
- 当“关系”本身是重点时,优先用 frame:
on=ob.face("+Z")、bbox、local。 - 每个实体都从 z = 0 开始,在 x、y 上居中;
extrude(both=True)让实体关于其平面居中。 at设置给出的值并保留其余值;transform是在当前位置上移动。
正确:碗坐在灯杆的高度上。
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)
错误:一副眼镜。
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)])
头部把镜腿摆在 (64.5, -14.6, 37.5),零件又把同样的数字从每个点上减掉。每个坐标都先按世界写一遍,然后再撤销。
应当这样写:样条直接写在镜腿自己的坐标系里。形状相同(对原版 F 1.000)。
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)])
原文给出的判断标准很实用:出现 -origin_x、-base 这类“把自己减回去”的表达式,就是世界坐标被写进了零件函数。transform 与 at 的分工在源码里也是分离的:at 用 frame 与分量合成摆放矩阵,transform 直接把变换矩阵左乘到现有 matrix_basis 上(src/sand3d/frames.py)。所以 at 表达“在哪里”,transform 表达“相对移动/镜像”。
用 frame 表达关系,而不是用数字
bbox 用包围盒的方向命名取点:"+X" 是朝向 +X 一侧面的中心,"+X-Y" 是棱中点,"+X-Y+Z" 是角点,其轴向与“朝第一个方向看的那个面”一致(src/sand3d/frames.py)。这一条直接替代了手算中心点:
handle = s3d.at(s3d.box("handle", 24, 110, 30), on=s3d.bbox(ring, "+X").move(x=door_d / 2 - 40))
这是 programs/washing_machine.py 中的真实用法:把手挂在门圈 +X 侧面的 frame 上,再沿该 frame 自己的 X 微调,而不是先在脑内把中心点算成世界坐标。
规则 5:用 frames 重复,用 copy 镜像
成组复制通过 on=s3d.grid(…)、ring(…)、along(…) 传入 frame 列表完成;一对零件中的另一侧用 s3d.transform(s3d.copy(placed), mirror="x")。at 用于“放到某处”,transform 用于“镜像”。永远不要在循环里手写 cos 和 sin。
正确:一圈杆。
rods = s3d.at(s3d.cylinder("rod", d=rod_d, h=h), on=s3d.ring(n=count, r=radius))
正确:两对镜像。
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")
错误:一个上下铺床架。
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))
三根立柱,等距 93。一个三元素列表掩盖了“它们等距”这一事实。
应当这样写:把间距命名,让 grid 说出其余部分。形状相同(对原版 F 1.000)。
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)
三个分发器的实现各有要点:
grid(nx, ny=1, px=0, py=0, stagger=False, on=None):nx × ny个 frame,间距px、py,整体以on为中心;stagger让相邻行错开半个间距(src/sand3d/frames.py)。ring(n, r, start=0, angle=360, on=None):n个 frame 绕on的法线分布,每个 frame 的 X 指向外侧,所以放在环上的零件会随之转向(src/sand3d/frames.py)。源码里Frame(base.origin + radial * r, base.z, base.z.cross(radial))的 up 取法正是为了让 X 保持径向。along(path, pitch=None, count=None):沿路径按间距或数量布 frame,方向朝路径前进方向;闭合路径会把首尾接上(src/sand3d/frames.py)。
at 收到 frame 列表时是“消费式”的:原对象被复制到每个 frame 上,原对象随后被删除,返回副本列表(_on_frames,src/sand3d/frames.py)。因此头部那行 rods = s3d.at(..., on=s3d.ring(...)) 得到的是列表,可以直接交给 assembly(列表在接收对象的地方等价于其元素)。
Rack 示例把规则 5 用到了极致:挂钩先用 at 放好,再 transform(copy(...), mirror="x") 得到对称件,最后 join(base, pegs, hook, image) 一次合并(docs/examples/rack.py)。copy 会连同关节、名称、摆放、面/边命名一起复制(src/sand3d/edit.py),这也是镜像侧能保持完整语义的原因。
规则 6:用命名该形状的动词来表达形状
sand3d 能用一个动词说清楚的形状,就不要写成点表。bpy 与 bmesh 是禁止使用的:如果 sand3d 说不出某个形状,应当为缺失的动词开 issue。自由曲面仍然顽固——在这些动词齐备之前,点表可能更贴合目标。
| 形状 | 动词 |
|---|---|
| 绕轴回转 | revolve(name, profile) |
| 中空、一侧开口 | shell(ob, t=…, open="top") |
| 一个孔、一个螺栓圈 | hole(ob, d=…, on=…) |
| 弯管 | wire(name, path, d, fillet=…) |
| 截面沿轴变化 | loft(name, station(z, w, d), …) |
| 由视图描述的长形体 | body(name, plan, top, bottom) |
| 沿路径的带 | stroke(path, t) |
station 是主力。它是高度 z 处的一个截面:宽、深、偏移 x、y,以及从椭圆(n=2)到方形(n=4)的方正度 n。loft 里的几个 station 就能表达收腰、鼓起或漂移。
正确:一枚钉子,三个 station,每个值都有名字。
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))
正确:一个灯罩,四点回转。
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)]))
正确:一个动词做出托盘。
tray = s3d.shell(s3d.box("tray", w=w, d=d, h=h), t=t, open="top")
错误:一只汤碗。
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)))])
内壁是照着外壁逐点手打的。shell 一个词就能表达,而且壁厚均匀。
应当这样写:只写外表面,然后 shell。形状相同(对原版 F 1.000)。
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")
这一条最值得结合源码讲,因为 shell 不是简单的“内缩一层”。它把每个顶点沿其接触面的带符号偏移平面做最小二乘求解,得到“均匀壁厚”的内壁;求解在双精度下进行,因为 Matrix 是 float32,而光滑表面的相邻面片夹角极小会让方程病态(src/sand3d/edit.py)。源码还明确拒绝一种用法:用一个方向(如 open="+Z")去开口时,如果该方向最远的“面”其实是曲面的一圈面片,会抛错并提示先用平面切掉再开——所以 open 的取值要么是建模器命名的面名("top"、"cut"、"shell"),要么是真正的平面朝向。
station 的实现很薄,它只是“把超椭圆摆到 (x, y, z)”:
return at(superellipse(w, d, n=n, taper=taper), x=x, y=y, z=z)
见 src/sand3d/profile.py。而 loft 会在这几个截面之间按 CAD 放样方式插值:每个点沿一条穿过其在各截面中位置的样条行走,两端封盖;follow=True 时截面转正到中心连线方向(src/sand3d/solids.py)。这解释了为什么“几个 station 就能说出收腰与鼓起”——形状的复杂度被动词吸收了,程序里只剩下可读的尺寸。
顺带一提,programs/cutlery.py 展示了同一套动词如何组合出非平凡曲面:勺柄是 loft(..., follow=True) 的圆角截面,勺斗是 scale(sphere) + split + shell + fillet,叉齿是 poly 轮廓减去一排 slot 再与弯曲的 sweep 求交(programs/cutlery.py)。全文没有出现 bpy 或 bmesh。
规则 7:外观重要时给零件“穿衣”
当目标模型带颜色和材质时,每个零件都调用一次 s3d.material(ob, kind, color="#rrggbb"),且在复制之前调用。对于只有形状的数据(如 CAD 零件),这一步是可选的。
- 在 group 上调用
material,会作用到其下所有自己没有材质的零件;最近的一次调用获胜。 join保留第一个对象的材质,group保留每个零件各自的材质。只把同色的东西 join 在一起。
正确:在 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))
“最近的一次调用获胜”在源码里就是一次向上查找:_nearest 从网格对象开始沿 parent 链上溯,返回第一个带 s3d_material 标签的祖先或自身(src/sand3d/materials.py)。标签存放在对象上而不是网格上,所以 cut、hole、fillet 这些重建网格的动词不会丢掉它,copy 也会带走它;而作为刀具的对象,其标签会随刀具一起被消耗,join 则保留第一个对象的标签。
原文档只写了 kind 与 color,实际签名还支持更多外观参数(src/sand3d/materials.py):
material(ob, kind, color=None, roughness=None, metallic=None, opacity=None, emission=None)
kind 必须是内置预设之一。可从 PRESETS 查到的预设包括木材(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(src/sand3d/materials.py)。opacity 取 1 为不透明、0 为不可见;emission 是自发光强度,颜色就用材质自身颜色。写错 kind 时,源码会用 difflib 给出相近名字的建议。
一个容易踩的坑:material 作用在装配体(Handle)上时,标签打在根对象上,于是所有未单独命名的子零件都会继承它——这正是 chair/lamp 这类示例把 material 写在零件函数里、而不是写在 assembly 上的原因。
规则 8:每个关节一个 frame
在头部,f = s3d.local(parent, x, y, z) 给出枢轴;同一个 f 同时交给 s3d.at(child, on=f) 和 s3d.joint(name, child, f, …)。
- 每个关节都写在头部:frame、零件、关节三行并排,这样一个零件可以连同它的几行一起被摘掉。
local读取父级自己的空间,无论链有多深,没有任何坐标被合成到世界坐标。axis是一个方向,写在父级所在的空间里,如"+X"。源文件的轴会先被其rpy旋转。- 轴的符号决定打开方向。 正值按右手定则绕轴旋转。原文统计:在 23 份“只需小改就能让关节正确”的草稿中,有 8 份只改了符号。
- 不动的东西没有关节。 先摆放、放进父级的组,再声明关节,否则父级运动时它会留在原地。
- 在静止状态建模。 每个关节都在 0,程序里不出现
s3d.pose。
正确:两个滑轨,以及一个铰接在滑动盖上的舱门。
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))
错误:一个旋转轴,零件在一个 frame 上、关节在另一个 frame 上,1 个关节中 0 个正确。
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")
模型在下一稿中修正:两者共用一个 frame,1 个中 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")
错误:一个壁柜,门朝柜内打开,1 个关节中 0 个正确。
s3d.joint("door_hinge", door, f, kind="revolute", axis="+Z", range=(0, 114.59))
模型在下一稿中修正:只改一个符号,1 个中 1 个正确。
s3d.joint("door_hinge", door, f, kind="revolute", axis="-Z", range=(0, 114.59))
这段规则每一条都能在 src/sand3d/joints.py 中找到实现依据:
枢轴来自 frame 与父级的关系,而不是世界坐标。 joint 用子级世界矩阵的逆去乘“父级世界矩阵 × frame 在父级自身空间中的位置”,得到枢轴(pivot = world(child)⁻¹ @ world(on frame),src/sand3d/joints.py)。而 local 记录的是 (root, basis),所以父级之后被移动、旋转,甚至嵌在更深的链里,枢轴都会跟着走。这也是“一个 frame 两个用途”必须成立的技术原因:at(child, on=f) 与 joint(..., f) 消费的是同一个已被“读在某个零件上”的 frame 对象;手动构造的 Frame(...) 会因为没有 part 而被拒绝(同一文件 L300-L307)。
轴的空间。 轴不是世界坐标方向,而是父级所在空间的方向:
space = _core.world(parent.parent).to_3x3() if parent.parent is not None else Matrix.Identity(3)
a = _clean(W_on.to_3x3().inverted() @ (space @ direction))
见 src/sand3d/joints.py。W_on 由父级世界矩阵与 frame 在父级内的位置组成,所以当 local 带了 rpy,该旋转会自然地把 "+X" 转向源文件描述的方向——正对应“源文件的轴会先被其 rpy 旋转”。
范围必须包含 0。 _range 会拒绝 low > high、拒绝空区间、拒绝不包含 0 的区间,并提示“一切都在静止状态构建,每个关节都在 0”(src/sand3d/joints.py)。continuous 与 free 不接受 range;prismatic 的单位是程序单位,revolute 的单位是度。
关节声明时机构必须静止。 at_rest 会沿运动链查找任何非 0 的关节值并抛错,提示“要么先把关节归零,要么先声明关节”(src/sand3d/joints.py;joint 在 L336 调用它)。这就是“程序里不出现 pose”的强制边界:pose 属于展示状态,不属于定义。
已有关节就不能再 at。 refuse_at 明确拒绝给已有关节的对象做摆放,理由是会把它从枢轴上撕下来,并提示“先摆放再声明关节,或用 transform,它会带着枢轴一起移动”(src/sand3d/joints.py)。
关节不会重新挂父级。 关节的运动学树(子 → 父)与场景树是分开的:没有关节的零件跟随自己的组运动,有关节的零件按关节运动,无论它在哪个组里(src/sand3d/joints.py)。tests/test_pose.py 用一个“装在门组里、却铰接在柜体上”的灯直接验证了这一点。
真实的完整例子是 programs/washing_machine.py:四个关节全部集中在头部,door_hinge 用 axis="-Z"、范围 (0, 143) 让门向外开;drum_spin 与 dial_turn 是 continuous;drawer_slide 是 +X 方向 0–200 mm 的 prismatic。文件把“定义”与“展示”拆成两个函数:washer() 返回静止状态的装配体,washer_open() 在其上做 pose。这正是规则 8 最后一条的推荐组织方式。
镜像件上的关节为什么要小心
gate.py 里有这样的写法:
s3d.joint("hinge", leaf, s3d.bbox(l_post, "+X+Y"), axis="+Z", range=(0, 90)) # the post's edge it opens toward
twin = s3d.transform(s3d.copy(leaf), mirror="x") # its image, hinged at x = +w
镜像后的子件仍然按“运动之像”来运动:源码在计算关节轴时,如果子级变换的行列式为负,就把旋转轴取反(axis_in_world,src/sand3d/joints.py)。tests/test_pose.py 的 Mirrored 用例断言两侧门都以同一方向朝 +Y 打开,且镜像侧的世界矩阵行列式为负。这解释了规则 5 与规则 8 的交界:镜像用 copy + transform,关节照旧声明一次即可。
八条规则的源码对照表
| 规则 | 关键动词 | 实现位置 | 可由源码确认的约束 |
|---|---|---|---|
| 1 头部即目录 | assembly、attach |
src/sand3d/assembly.py | 锚点保存为 Handle 属性;attach 的细节可整行删除 |
| 2 一零件一函数 | join、group |
src/sand3d/edit.py | join 单一材质并警告丢失;group 各自保留 |
| 3 尺寸只命名一次 | 关键字参数、local |
src/sand3d/frames.py | local 原样接受源文件的 xyz/rpy |
| 4 在父坐标系摆一次 | at、transform、bbox |
src/sand3d/frames.py | at 覆盖给出的分量,transform 左乘移动 |
| 5 frames 重复、copy 镜像 | grid、ring、along、copy |
src/sand3d/frames.py | 列表 frame 为消费式;ring 的 X 向外 |
| 6 用命名动词说形状 | revolve、shell、loft、station |
src/sand3d/edit.py、src/sand3d/solids.py | shell 等壁厚最小二乘;曲面侧面不能按方向开口 |
| 7 按需穿衣 | material |
src/sand3d/materials.py | 标签在对象上;最近的祖先获胜 |
| 8 一关节一 frame | local、joint、pose |
src/sand3d/joints.py | 枢轴随父级;轴在父级空间;范围须含 0 |
如何自检一段装配程序
把八条规则反过来读,就是一份可执行的检查表:
- 文件里第一个函数是否与对象同名,且函数体只有“调用零件 +
at/local+ 返回assembly”? - 每个零件函数是否只返回一个对象,且围绕自身原点建模(不以“把世界坐标减回去”的方式补偿)?
- 函数签名中的数值字面量是否接近 15 个?是否每个参数都被真正读取?是否出现
if x == 28或无法解释的分数? - 有没有按世界坐标建好再回移的零件?能否改用
face、bbox、local? - 重复处是否用了
grid/ring/along?对称处是否用了copy+mirror?是否出现手写cos/sin循环? - 是否用
revolve/shell/loft/station/wire/body/stroke替代了点表?是否出现bpy/bmesh? - 有外观要求时,
material是否在复制前、按零件调用,且没有把不同材质强行join? - 每个关节的 frame 是否同时用于
at与joint?关节是否都在头部、都在 0 状态声明、范围是否包含 0、axis符号是否正确?
在仓库层面,还有两类自动化验证可以作为回归保障:
- 示例必须成闭合实体。 tests/test_examples.py 会加载
bracket、lamp、rack、chair、gate五个示例并断言每条边都有两个相邻面、且网格只有一个壳。这条测试对规则 2、4、6 特别有效:漏封盖、把两个实体误当整体、shell开口开错都会在这里暴露。 - 确定性基准。 tests/test_golden.py 把一批程序构建出的网格与世界摆放哈希后与 tests/golden/bpy-5.2.json 比对,任何几何移动都必须显式更新基准文件。这对应 README 中“同一程序逐位构建同一网格”的确定性承诺,也意味着按规则 3 做的“数值改写成表达式”如果数学等价,就不应改变哈希。
需要说明的是,规则 3 里的“15 个数字 / 上限 40 / 31.0% 未读参数”属于原文档基于当时语料的统计经验,源码并没有相应校验器;它们是写作与评审的启发式指标,而不是库的硬约束。规则 1 的“第一个函数”、规则 8 的“关节在 0”等则由库的运行时检查或测试实际兜底。
把规则交给模型时
README 把 docs/api.md 定位为“放进系统提示的词汇表”,把 docs/guidelines.md 定位为“多零件对象的八条规则”。两者分工不同:api.md 回答“有哪些动词、签名是什么、摆放与关节的语义规则”,guidelines.md 回答“一个装配程序应该长成什么结构”。实践上,把本文中的“头部—细节—零件”三分法与八条检查项一起交给模型,比只给 API 清单更容易得到可读、可改、可复用的程序;而验证手段仍然应落在仓库已有的测试上——示例闭合性、确定性和关节姿态。
原文末尾的分段结构也值得保留为写作模板:先给出“一个程序长什么样”的完整骨架,再逐条用“正确 / 错误 / 应当这样写”三连击说明。这种格式的好处是,每条规则都有一个可运行的反例,读者能直接看到“不会崩溃但会腐化”的代码是什么样子——这恰恰是代码评审中最难靠文字描述清楚的部分。