sand3d 装配程序编写指南:八条规则、错误示例与源码级实现解析

原创2026-11-09 11:21:041,629 阅读
文章标签:3D建模图形学AI 应用

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

如何自检一段装配程序

把八条规则反过来读,就是一份可执行的检查表:

  1. 文件里第一个函数是否与对象同名,且函数体只有“调用零件 + at/local + 返回 assembly”?
  2. 每个零件函数是否只返回一个对象,且围绕自身原点建模(不以“把世界坐标减回去”的方式补偿)?
  3. 函数签名中的数值字面量是否接近 15 个?是否每个参数都被真正读取?是否出现 if x == 28 或无法解释的分数?
  4. 有没有按世界坐标建好再回移的零件?能否改用 face、bbox、local?
  5. 重复处是否用了 grid/ring/along?对称处是否用了 copy + mirror?是否出现手写 cos/sin 循环?
  6. 是否用 revolve/shell/loft/station/wire/body/stroke 替代了点表?是否出现 bpy/bmesh?
  7. 有外观要求时,material 是否在复制前、按零件调用,且没有把不同材质强行 join?
  8. 每个关节的 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 清单更容易得到可读、可改、可复用的程序;而验证手段仍然应落在仓库已有的测试上——示例闭合性、确定性和关节姿态。

原文末尾的分段结构也值得保留为写作模板:先给出“一个程序长什么样”的完整骨架,再逐条用“正确 / 错误 / 应当这样写”三连击说明。这种格式的好处是,每条规则都有一个可运行的反例,读者能直接看到“不会崩溃但会腐化”的代码是什么样子——这恰恰是代码评审中最难靠文字描述清楚的部分。

登录后查看全文
sand3d