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 — 整體', '…'); 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>圖 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 px 寬度下為單欄,無橫向滾動。
說明您無法檢查的項目(例如真實 GPU 的影格率)。
致謝
lamina 融合了來自 teardown(elvarofficial)、anatomy(Ryan)和 claude-motion(whaleyxbt)的想法,皆為 MIT 授權。請參閱 CREDITS.md。