lamina 是做什么的?
一台机器,一个模型,一个页面。读者滚动一段简短的说明,就会多次看到这台机器:整体、剖开、机构单独、运动、分解。每一幅图都是同一个经过审计的3D模型,因此页面上没有任何内容会与其他内容矛盾。
SKILL_DIR 是这个文件所在的文件夹。examples/colibri/ 是一个完整的页面(一只12克的机器人蜂鸟,44个零件,六幅图):在开始之前先阅读它,并复制它的结构。
cd "$SKILL_DIR" && npm install && npx playwright install chromium # 一次性
python examples/colibri/model.py --audit # 模型 → colibri.glb,必须打印 `audit passed`
node build.mjs examples/colibri # → out/colibri.html,一个离线文件
node scripts/shots.mjs out/colibri.html # 每幅图的截图 + 控件检查
如果使用 Blender 而不是 bpy 模块:blender -b -P examples/colibri/model.py -- --audit
工作流程
按此顺序进行。大部分质量在步骤1到3中决定,在所有网格之前。
- 事实优先。 收集真实数据:尺寸、质量、速度、齿数、传动比、极限。搜索它们。将它们放入一个小的纯模块(
kin.js)中,并在页面上说明它们的来源。虚构的零件使用虚构的名称:一个带有型号的虚构产品,绝不使用真实品牌。 - 单一输入。 命名驱动机器的单一变量(曲柄角度、行程、阀门位置)。每个姿态和每个读数都是它的函数。
- 零件清单和布局,在纸上。 40多个零件,按组件分组,每个零件标明其安装位置。在建模之前用数字规划机构布局:中心距 (z1 + z2)·m / 2,轴位置,什么必须避开什么,每根轴在哪里穿过外壳。在
model.py顶部写出清单。 - 在 Blender 中建模,使用
blender/tdb.py(参见“建模”)。 - 审计至零。 运行
python model.py --audit,直到它打印出audit passed。 - 编写页面,使用
kit/page.js(参见“页面”):4到7幅图,每幅回答一个问题。 - 查看它。 运行
node scripts/shots.mjs out/<name>.html必须打印checks passed。然后阅读它写入的每一张PNG。修复并重复,直到一次完整的通过找不到任何问题。
在编写页面的其余部分之前,先向用户展示一幅图(整台机器,构建并渲染完成)。
建模
任何带有弯曲主体、外壳覆盖机构或相互运动部分的零件,都在 Blender 中建模,而不是用 three.js 基本体。凭眼睛放置基本体是零件相互穿透的原因。
- 主体是一个解析曲面,绝不是一个球体或一个代表它的车削体。 定义控制截面,用
spline连接它们,然后用patch(surf, u0, u1, v0, v1, thick=0.7)将曲面切割成面板:真实的厚度,在留出参数范围的地方留下真实的间隙,每个边缘都有倒角。 part(name, bmesh, mat, asm, bevel, cut, explode, open, mats)在其父框架中注册一个封闭零件。cut=[…]使用精确布尔运算进行减操作:为每根穿过外壳的轴、腿、眼睛或电缆开一个孔。carve()在零件焊接到一起之前切割一个块。- 一个焊接结构是一个零件(
join):龙骨、环形框架、板、柱、凸台。螺栓、舱口和通风口融合到它们所属的面板上。审计发生在零件之间,因此要慎重决定一个零件是什么。 - 运动:
joint(part, 'rev' | 'slide', axis, law, input),其中value = k·q + a·sin(h·q + p) + c + b·tanh(g·cos q)。rig_input(name, lo, hi, samples, rest)声明审计扫描的内容。mate(a, b, depth)声明啮合的轮齿;gear_info(...)声明齿轮和齿条;frame(...)是一个携带关节的空物体;anchor(name, at)是一个命名点。 - 接触是齐平(0.05 mm 间隙)、相切或轮缘在表面上。 没有任何东西嵌入其他东西。浮动的零件是一个错误:给它一个支架。
- 材质是名称(
shell、orange= 强调色、ink、dark、steel、brass、carbon、lens、membrane、pcb);页面赋予它们外观。mats={'orange': predicate}绘制零件的一个区域。
审计
blender/audit.py 使用与页面相同的关节定律,通过每个输入对模型进行姿态变换,并在真实网格上验证:
| 检查项 | 含义 |
|---|---|
| 干涉 | 在静止状态、每个采样姿态或爆炸视图中,没有两个零件相互穿过。声明的配合可重叠至其深度。 |
| 支撑 | 每个零件都接触另一个零件,并且所有零件作为一个整体装配在一起。 |
| 齿轮 | 中心距 (z1 + z2)·m / 2,反速度比,齿条行程 = 小齿轮角度 × 节圆半径。 |
| 封闭 | 每个零件都是一个封闭的体积;板材有厚度。 |
每次失败都会指出零件对、姿态、深度和点。修复几何体:移动它、缩小它、开一个孔、更改布局、减少行程。切勿为了消除错误而扩大配合、删除零件或跳过姿态。如果审计显示真实数据不匹配,页面上的数据也会更改。如果您无法运行它(没有 Blender,没有 bpy),请说明原因,并且不要认为模型已完成。
页面
kit/rig.js 加载 GLB 并对其施加姿态:rig.pose(inputs, {explode, focus, open})。kit/page.js 就是页面:
import {createPage} from 'lamina-kit/page.js';
const P = await createPage({title, model}); // model: {root, meshes, update(state)}
P.header({code, kicker, name, sub}); P.lead('…'); P.h2('01 — El conjunto', '…'); P.text('…');
P.figure({n: 1, title, cam: {az, el, d, ty, tz}, controls, step: (fig, dt) => state, readout: (fig, state) => html});
P.caption('<b>Fig 1.</b> …'); P.chain([...]); P.table([...]); P.footer(left, right); P.start();
- 每个图形一个渲染器。 每个可见卡片都被施加姿态、渲染并复制到其自己的画布上。绝不为每个图形使用单独的 WebGL 上下文。
- 图形的
step函数返回用于model.update的状态。state.look(part, asm)为每个网格返回'solid'、'ghost'或'hide':这就是同一个模型如何变成整台机器、打开的机器和单独的机构。 - 控件很少且真实: 每个图形最多一个暂停、三个速度和一个滑块(
P.range、P.speeds、data-pp)。仅限原生输入。没有控制台、仪表板、时间线或状态面板。 - 命名零件:
...P.partsPanel(PARTS)为每个零件添加一个按钮,并附带一行说明;选择一个(或在图形中点击它)会使其他零件变暗,并将相机聚焦到该零件上。PARTS是[name, /regex/, line]。 - 要考虑的图形,按此顺序:整台机器工作 · 内部(滑块升起外壳) · 单独机构,慢速,带有可擦洗相位的 · 重要的运动,被追踪的 · 补偿或限制 · 带有命名零件的爆炸视图。然后是一个数据表格。
写作
默认使用西班牙语(与用户语言匹配)。简短。开头两句的引语,然后每个图形:一个标题,两到三句话说明要看什么以及为什么,图形,以及带有一个事实的标题。文本中的每个数字都来自模型。说明哪些是虚构的,以及真实数据来自何处。
外观
总是深色。页面 #0e0f11,文字 #ece8df,一种强调色:金色 #d4a94e。每个卡片在模型后面有一个柔和的光池,以便深色部分保持轮廓。模型是白色和金色:光亮的白色外壳,orange 材质标记的部分用金色,下面是石墨和钢。文字使用 Inter,标签、数字和按钮使用小型大写的 JetBrains Mono。
深色页面上的深色部分会失去边缘。保留黑色用于少数零件;使内部机构呈现钢色、铝色或黄铜色,并在 fig*-part.png 中检查每个选中的零件与背景的对比。
审查
您无法观看页面;但可以阅读帧。scripts/shots.mjs 写入 top.png、figN.png、figN-part.png 和 phone.png,按下每个暂停,移动每个滑块,选择一个零件并报告控制台错误。然后查看:
- 模型。 当前文件通过
audit passed。一眼望去像是真实的东西;4倍放大下没有裸露的面。 - 每个图形。 一个主题,填满卡片的一半,不被裁剪;其阴影在卡片内;读数真实。
- 每个控件。 它更改了标题所说的内容。
- 文本。 每个数字与读数和表格匹配。
- 手机。 在390像素宽度下单列显示,没有横向滚动。
说明您无法检查的内容(例如,真实 GPU 的帧率)。
致谢
lamina 融合了来自 teardown (elvarofficial)、anatomy (Ryan) 和 claude-motion (whaleyxbt) 的想法,均为 MIT 许可。参见 CREDITS.md。