Community影像github.com

lamina

將機器或機制的運作原理,以黑暗風格的說明網頁形式呈現,包含動態 3D 圖形(「láminas」):一段簡短文字,接著數個帶邊框的卡片,以同一模型分別展示整體、剖開、單獨機構、運動狀態與爆炸圖,每個卡片附有一至兩個控制項以及可選取的命名零件(選取時其他零件淡出)。模型透過程式碼在 Blender 中建構為真實的封閉零件,並經過審計確保無任何零件互相穿透。

lamina 是什麼?

lamina 是一個專為 Claude Code 設計的 AI 代理技能,可將任何機器或機制的運作原理轉換為一個視覺化、互動式的說明網頁。它會產生一個統一的 3D 模型,並以不同視角(整體、剖開、單獨機構、運動與爆炸圖)呈現在同一個頁面的多張卡片中,確保所有視圖完全一致。開發者只需定義一個驅動變數(如曲柄角度或閥門位置)、一個零件清單以及 Blender 幾何形狀,lamina 就會自動處理建模、審計重疊、產生靜態頁面 HTML,並透過螢幕截圖進行檢查。該技能對於需要精確機械分解的領域極具價值,例如機器人技術、工具設計或科普教育。它支援 Blender 4.2+ 且完全離線運作,生成的頁面採用深色主題,並包含可選取的零件面板與基本的播放控制。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/zeuscabanas/lamina/tree/HEAD

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 中決定,在建立任何網格之前。

  1. 事實優先。 收集真實數據:尺寸、質量、速度、齒數、傳動比、極限值。搜尋它們。將它們放入一個小的純模組(kin.js),並在頁面上說明來源。虛構零件需使用虛構名稱:一個帶有產品代碼的虛構產品,絕不能使用真實品牌。
  2. 單一輸入。 命名驅動機器的單一變數(曲柄角度、行程、閥門位置)。每個姿態和每個讀數都是它的函數。
  3. 零件清單與佈局,在紙上。 40 個以上的零件,按組裝體分組,每個零件標明其安裝基座。在建模前先用數字佈置機構:齒輪中心距 (z1 + z2)·m / 2、軸的位置、哪些部分必須避開哪些部分、每根軸穿過外殼的位置。將清單寫在 model.py 的最上方。
  4. 在 Blender 中建模,使用 blender/tdb.py(請見「建模」)。
  5. 審計至零。 執行 python model.py --audit,直到輸出 audit passed。
  6. 撰寫頁面,使用 kit/page.js(請見「頁面」):4 到 7 個圖形,每個回答一個問題。
  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。

相關技能