解剖式 Three.js — 互動式 3D 技術圖解

Anatomy Three.js — 互動式 3D 技術圖解

使用 Three.js + GLSL 建立可互動的等角 3D 技術插圖。每張圖都將一個技術概念解釋為一個實體的檯面儀器或剖面測試裝置，可以放在桌上：一個厚重的斜邊底板放在車削腳座上，領域真實的外殼和連桿，一個核心內部轉子或移動主體，可直接拖曳的 3D 控制項和專為該機器打造的儀器，以及一個嚴格限制在機器內部物理介質（火焰、電漿、流體、下洗流、光束）的自訂 GLSL 著色器。

與其撰寫 1500 行單一 HTML 檔案並在腦中猜測 3D 座標，不如先與使用者就裝置和互動方式達成一致（階段 0），然後在 figures/<slug>/ 內部以六個隔離階段建立每張圖，並由不可變的 kit/ 引擎支援，且每一步都由一套雙層的 3D 空間 + 正交視覺檢查工具進行驗證。

---

目錄結構

anatomy-threejs/
├── SKILL.md                    # 階段 0 簡報 + 六階段工作流程與代理入口點
├── kit/                        # 不可變引擎 — 從此處匯入；切勿為每個圖表編輯
│   ├── shaders.mjs             # 5 種主題、4 色 + 頂蓋單元著色器、反轉外殼、摺線
│   ├── primitives.mjs          # 軸向感知的板塊、圓柱、齒輪、螺絲、滾花、刻度
│   ├── registry.mjs            # Recorder3D：.group()、.part()、.anchor()、.tube()、.interactable()、.tag()
│   ├── audit3d.mjs             # 無頭 Node 3D 空間稽核（碰撞、浮空、內孔、管線）
│   ├── runtime.mjs             # 正交攝影機、光線投射 3D 拖曳、自訂控制項、彈簧、__ANATOMY_DEBUG__
│   ├── bundle.mjs              # 將圖表模組編譯為單一自包含的 HTML 檔案
│   └── shell.html              # 響應式卡片外框、5 種主題 CSS 變數、功能感知控制項
├── scripts/
│   ├── inspect.mjs             # 無頭 Chrome (CDP) 2x2 正交藍圖與接合覆疊
│   ├── drive.mjs               # 互動式縮圖展示 + 主體靜態圖 + 行動裝置 390px 驗證
│   └── chrome-port.mjs         # 零相依性的 WebSocket + PNG 拼接器，用於無頭 Chrome
├── references/
│   ├── craft-3d.md             # 3D 座標系統、色調階層、自訂控制項、反模式
│   ├── kit-3d.md               # Recorder3D、基本幾何、著色器和執行時間的 API 參考
│   └── verify-3d.md            # 如何解讀與修正 [COLLISION]、[FLOATING]、[TUBE KINK] 和正交視圖
└── figures/
    └── <slug>/                 # 圖表的工作目錄（例如 figures/wankel-engine/）
        ├── model.mjs           # 階段 1：純數學、尺寸、SPEC.features、SPEC.controls、錨點
        ├── base.mjs            # 階段 2：底板、腳座、光暈、尺、黃銅牌
        ├── structure.mjs       # 階段 3：基座、框架/外殼、連接埠、緊固件
        ├── subject.mjs         # 階段 4：移動核心組件（轉子、葉片、密封件、齒輪）
        ├── mechanism.mjs       # 階段 5：自訂控制項、儀器、3D 可互動元素、管線、updateKinematics()
        ├── shader.mjs          # 階段 6：限制在活躍物理介質內的自訂 GLSL 著色器
        ├── build.mjs           # CLI 入口：--test-model、--audit 和 HTML 完整套件
        └── dist/
            └── <slug>.html     # 編譯後的自包含互動式圖表

規則 1 — 切勿改寫 kit/：Three.js 攝影機、單元著色器、光線投射拖曳處理器、彈簧求解器、DOM 外框和除錯工具都存在於 kit/ 中。您的圖表檔案僅定義領域數學、3D 零件、運動學、可互動元素和自訂介質著色器。

規則 2 — 在撰寫幾何形狀之前先閱讀參考資料：

• 在階段 0/1 之前閱讀 references/craft-3d.md，以設計實體裝置、自訂控制項、功能旗標、色調階層和 3D 座標系。
• 在階段 2 之前閱讀 references/kit-3d.md，以了解 Recorder3D 和 kit/primitives.mjs 的準確簽章。
• 每當 --audit、inspect.mjs 或 drive.mjs 回報問題時，請閱讀 references/verify-3d.md。

---

階段 0 — 裝置與互動簡報（先達成共識再開始建構）

在建立檔案或撰寫階段 1 程式碼之前，請向使用者提出一份簡潔的裝置與互動簡報，並就機器的功能以及讀者如何與其互動達成共識（僅當使用者明確指示立即建構而不提問時才能跳過等待）：

1. 檯上裝置與主體部件：命名物理機制，以及哪一個單一組件承載 lit 強調色。
2. 直接 3D 操作 (reg.interactable)：識別讀者可以直接在視口中抓取和拖曳的 3D 組件或控制項（例如，拖曳斜盤以傾斜/升降並觀察旋翼葉片變距、滑動游標尺滑座、拉動連桿），包括在旋轉/模擬暫停時。
3. 領域真實控制項與遙測 (SPEC.controls)：選擇屬於此機器的檯面硬體和控制列滑塊（例如，2 軸循環操縱桿、集體螺距象限、量角器弧、千分尺鼓輪、游標尺、壓力計管）。切勿複製其他圖表的旋鈕、波登壓力錶或液壓箱，除非主體確實使用該確切儀器。
4. 視圖模式 (SPEC.features)：明確決定哪些可選模式值得存在：
   • explode：僅對具有堆疊軸向層的封閉同心機器（例如引擎、變速箱、泵浦） 啟用 (true)。對於開放式機械連桿、斜盤、光學平台或表面裝置，請設定 explode: false，因為分離零件會破壞連桿幾何形狀並增加雜亂。
   • cutaway：當外殼遮蓋移動內部零件時啟用 (true)；對於開放式框架機制則設定 false。
   • shader：當受限的物理介質（燃燒氣體、轉子尾流、光束、流體流動）能闡明機制時啟用 (true)。

階段 0 關卡：使用者確認或完善簡報（或明確指示立即進行非互動式建構）。

---

六階段工作流程

按順序執行這些階段。每個階段以驗證關卡結束 — 執行命令，修正任何錯誤，並在使用檔案讀取工具繼續下一階段之前，視覺檢查渲染的 PNG 圖像。

階段 1 — 模型與運動學 (model.mjs + build.mjs)

在接觸 Three.js 之前，將已同意的簡報轉換為純數學物理模組：

1. 在 figures/<slug>/model.mjs 中編碼物理隱喻：
   • SPEC.features：{ explode: boolean, cutaway: boolean, shader: boolean, crank: boolean } 符合階段 0。
   • SPEC.interactionHint：顯示在左下角的簡短提示，告訴使用者他們可以直接拖曳哪些 3D 零件（例如 "拖曳斜盤、操縱桿或集體桿"）。
   • SPEC.controls：領域特定的滑塊控制項陣列（{ id, label, min, max, step, initial, title }）。runtime.mjs 將這些渲染到控制列中，用彈簧使其平順，並將它們傳遞給 updateKinematics 和 formatReadout。
   • SPEC.auditPoses 與 SPEC.drivePoses：領域代表性的姿勢（極端控制角度、暫停操作、剖面/主題檢查），由 --audit 和 scripts/drive.mjs 使用。當 features.explode === false 時，省略爆炸姿勢。
   • SPEC：所有關鍵尺寸（BASE_W、BASE_D、BASE_H、BASE_Y、topSurfaceY、isoElevDeg: 30、isoAzimDeg: -36、initialZoom、initialPanY、minVertSpan、minHorizSpan）。
   • ANCHORS：底板上命名的 [x, y, z] 安裝座標（plaqueCenter、rulerCenter，以及您圖表的自訂控制項/儀器錨點）。請記住，在標準等角視角（30° 仰角, -36° 方位角）中，+Z 邊緣是前面板，而 -X, +Z / +X, +Z 是沒有阻擋的前角。
   • 純狀態與運動學函數（零 Three.js 匯入），由 theta 和來自 SPEC.controls 的瞬時 params 驅動。
   • formatReadout({ theta, effectiveRpm, params }) 為遙測列返回 { readout, phase } 字串。
2. 搭建 figures/<slug>/build.mjs（參考 figures/wankel-engine/build.mjs 或 figures/helicopter-swashplate/build.mjs），並調整標題、副標題、初始讀數和圖例。

階段 1 關卡：

node figures/<slug>/build.mjs --test-model

通過標準：在整個 $0 \dots 6\pi$ 週期內，所有錨點皆為有限值且讀數/狀態已驗證，退出碼為 0。

---

階段 2 — 底座 (base.mjs)

建構支撐整個儀器的厚重基準底板：

1. 建立 base.group（stage: "base"）。
2. 在 BASE_Y - 0.24 處添加柔和的地面陰影（makeHaloMesh）。
3. 使用 buildSlabGeometry(BASE_W, BASE_D, BASE_H, { radius: 0.26, bevel: true, bevelSize: 0.025, bevelThickness: 0.025 }) 添加 base.plate，並設定 ramp: "lo"、mountOn: "ground"。請注意，topSurfaceY = BASE_Y + BASE_H + 0.025 考慮了頂部倒角厚度，因此安裝在 topSurfaceY 的零件能平放在頂面上而不會陷入其中。
4. 透過 reg.anchor(id, x, y, z, baseGroup) 註冊所有底板安裝錨點，以便階段 3 和 5 能直接對齊到 base.plate。
5. 添加嵌入的周邊凹槽（makePlanOutline）、4 個車削角腳（base.foot.collar.i + base.foot.pad.i），頂部帶有埋頭螺絲（makeScrewDetail）、一個刻度尺（base.ruler + makeRulerTicks），以及在可見的前面板（+Z）上添加一個鉚接的 brass 規格銘牌（base.plaque），帶有蝕刻標籤（reg.tag("tag-plate", ...)）。

階段 2 關卡：

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate base --ortho --out figures/<slug>/dist/inspect-base.png

讀取 inspect-base.png 以驗證腳座乾淨地位於底板下方，且黃銅銘牌和尺在前面板上沒有被阻擋。

---

階段 3 — 結構 (structure.mjs)

建構固定的承重支架、主框架或剖面外殼、連接埠/歧管以及緊固件：

1. 將支撐基座或齒輪箱安裝到 base.plate 上，並帶有法蘭底座、螺栓細節、錐形柱和軸承鞍座。
2. 建構主外殼或框架（ramp: "mid"、outline: "hi"）。將前面（+Z）保持開放或配備剖面蓋板（cutawayHide: true），以便在啟用 features.cutaway 時，從標準等角攝影機可以完全看到內部機構。
3. 添加領域真實的連接埠、致動器外殼或指向外部的固定支架。使用其局部外向連接埠法線（reg.anchor("plug.leading.tip", 0, 0.68, 0, spGroup, { dir: [0, 1, 0] })）在每個局部子群組內註冊 3D 連接埠/端子錨點，以便階段 5 的管線能對齊到其精確的世界位置，並同軸進出。
4. 僅當 SPEC.features.explode 為 true 且裝置具有旨在軸向分離的封閉同心層時，才在可移除的子群組上設定 explode: [ex, ey, ez] 向量。

階段 3 關卡：

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate base,structure --ortho --out figures/<slug>/dist/inspect-structure.png

讀取 inspect-structure.png（TOP、FRONT、RIGHT、CANONICAL ISO）：驗證連接埠指向外部、基座接觸底板和外殼且無穿模，並且沒有零件懸空。

---

階段 4 — 主體 (subject.mjs)

建構主導視覺焦點的核心內部組件：

1. 將 ramp: "hi" 分配給主要移動體（例如轉子主體、旋翼頭軛），將 ramp: "lit" 分配給活動的工作元件（rotor.apexSeal.i、blade.airfoil.*），將 ramp: "brass" 分配給精密齒輪和樞軸。
2. 建立巢狀運動學群組（orbit -> spin，或 azimuth -> flap -> pitch），以便層級運動能乾淨組合而不會產生尤拉角鎖死。
3. 在穿過內孔移動的零件上傳遞 insideBoreOf 和 boreClearanceFn，以便 audit3d.mjs 能在每個稽核姿勢下以數學方式驗證零壁面穿透。
4. 添加加工凹槽、面溝槽、翼樑接縫或螺栓樣式，使運動一目了然。

階段 4 關卡：

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate subject --ortho --out figures/<slug>/dist/inspect-subject.png

讀取 inspect-subject.png 以確認主體的輪廓、倒角和接合處從各個角度都能清楚辨識。

---

階段 5 — 機構、自訂控制項與直接 3D 互動 (mechanism.mjs)

將主體連接到領域真實的操作員控制項、遙測儀器、直接 3D 拖曳互動和佈線：

1. 在階段 0/1 的 ANCHORS 處建構領域真實的控制項（例如：一個 2 軸萬向節循環操縱桿、一個帶槽口的集體螺距象限桿、一個游標導螺桿或一個滾花油門鼓）。當機器需要自己的控制硬體時，切勿複製其他圖表的滾花旋鈕或歧管塊。
2. 建構領域真實的遙測（例如：一個弧形葉片螺距量角器弧、線性行程刻度、壓力計柱或千分錶），將其定位在 +Z 方向的前方，或避開 CANONICAL ISO 主體輪廓的區域。
3. 透過 reg.interactable(targetId, { cursor, hint, onDrag }) 在主機構和/或物理槓桿上註冊直接 3D 操作，以便使用者即使在旋轉暫停時（RPM = 0 或 PAUSED），也可以透過 setParam(...) 直接在視口中拖曳 3D 零件。
4. 使用 reg.tube(id, fromAnchorId, waypoints, toAnchorId, opts) 佈設所有管道和電纜：
   • 查詢 reg.getAnchorWorldPos(anchorId) 和 reg.getAnchorWorldDir(anchorId)，以建構平滑的 3D 拱形路徑點（length / chord >= 1.12），這些路徑點能避開相鄰零件，並沿著每個連接埠的外向法線同軸進入。
5. 建構傳動系統和鉸接連桿。在前側外殼蓋板或遮蔽內部機構的護罩上傳遞 cutawayHide: true。

階段 5 關卡：

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --isolate base,structure,mechanism --ortho --out figures/<slug>/dist/inspect-mechanism.png

讀取 inspect-mechanism.png：驗證控制項位於其錨點、管線同軸進入、可互動元素顯示半透明 hint 環，且儀器在視覺上清晰可讀。如果需要，使用 __ANATOMY_DEBUG__ 標誌在瀏覽器中進行偵錯。

---

階段 6 — 自訂介質著色器 (shader.mjs)

在 figures/<slug>/shader.mjs 中定義自訂 GLSL 著色器，僅在當 SPEC.features.shader 為 true 且機器具備一個已定義的物理介質區域時進行：

1. 機器模具的 mediumVolume 邊界：一個簡單的軸向對齊邊界框（xMin, xMax, zMin, zMax, yMin, yMax），著色器在該框內計算物理（例如渦流、燃燒、光束、流線）。
2. 傳遞機器執行時間狀態（theta、params、effectiveRpm）作為著色器的 uniform 變數，並根據給定的相位驅動介質運動（例如配氣相位、轉子角度或節流閥位置）。
3. 在 shader.mjs 中對 SDF（有符號距離場）紋理進行取樣，這些紋理代表在 kit/ 範圍內建立的 3D 幾何形狀，以實現著色器與物理實體之間的精確遮擋。
4. 返回一個 SHA256 雜湊，用於快取和驗證套件的著色器輸出。

階段 6 關卡：

node figures/<slug>/build.mjs --audit
node scripts/inspect.mjs figures/<slug>/dist/<slug>.html --ortho --shader --out figures/<slug>/dist/inspect-shader.png

讀取 inspect-shader.png：驗證著色器精確地位於其 mediumVolume 邊界內，與機器結構正確遮擋，並且視覺上清晰（溢出物、燃燒產物或光束看起來符合物理且無偽影）。

最終驗證關卡：

node figures/<slug>/build.mjs  # 建立完整的 HTML 套件
node scripts/drive.mjs figures/<slug>/dist/<slug>.html --protractor --out figures/<slug>/dist/contact-sheet.png

建立完整的 HTML 套件，然後針對所有功能、主題和檢視模式執行互動式縮圖展示。確保 figures/<slug>/dist/<slug>.html 可以載入到任何現代瀏覽器中，並且完全可操作。

---

編輯器 MCP 整合

使用 Claude Code、Coder、Cursor、Codex 或其他 AI 編輯器時，請透過標準 MCP 協定整合此技能。初始化工作階段的方式：

# 在 anatomy-threejs 目錄中初始化一個新的圖表
mkdir -p figures/<slug>
# 從現有圖表複製 build.mjs 作為起點
# cp figures/wankel-engine/build.mjs figures/<slug>/
# 開始階段 1：根據已同意的簡報撰寫 model.mjs

編輯器 MCP 伺服器應將 SKILL.md 視為解釋工作流程、參考和約束的規範文件。

---

故障排除與偵錯

• --audit 中的 [COLLISION]：零件穿過另一個零件。檢查尺寸並在 audit3d.mjs 中使用 insideBoreOf 或 boreClearanceFn。
• [FLOATING]：零件距離其預期安裝面超過 FLOAT_TOLERANCE（0.001）。檢查 y 位置是否等於來自 model.mjs 的 topSurfaceY。
• [TUBE KINK]：管線的 length / chord 小於 1.12。添加更多平滑路徑點。
• __ANATOMY_DEBUG__：在 HTML 中將此旗標設定為 true，以查看軸對齊、邊界框和接合重疊。