媒體（圖片 / 影片 / 參考包）轉換至Fusion 360重建技能

當使用者提供一張照片、一個多角度參考資料夾或一段影片（.mp4、.mov、.png、.jpg、.webp），並要求在Autodesk Fusion 360中重建該物體時，請遵循此6階段確定性工程工作流程。

嚴格的CAD命令：

切勿在未執行 process_media.py、建立真實世界的毫米尺度基準以及寫出運動學物料清單 (BOM) 之前，直接撰寫Fusion MCP擠出特徵。
每個零件都必須使用Fusion 360時間軸中的原生草圖、建構平面、草圖線/弧/圓、使用者參數以及擠出/圓角/接合特徵進行重建。絕不產生原始網格體（root.meshBodies.add）。

階段 0：前置安全閘門與單一儲存庫環境（必要）

在於Fusion 360中建立CAD幾何之前，請先對齊您的工作區並驗證即時MCP連線：

CAD單一儲存庫對齊：
- 主要工作區：啟用中的CAD單一儲存庫或專案根目錄（例如 CAD_MONOREPO_ROOT 或目前工作區）。
- 嚴格隔離保證： 切勿在儲存庫根目錄建立暫存檔案、腳本或渲染檔，也切勿變更 shared/。
- 將新模型儲存在 models/<NN>_<Model_Name>/ 下（例如 models/02_Modular_Desk_Organizer/）。如果開始一個新模型，請使用 scaffold_text_model.py "<Model_Name>" 建立骨架。
- 從 shared/ 匯入通用CAD輔助工具（fusion_client、cad_primitives、hardware_library、scene_animator）。
- 在撰寫腳本之前，請閱讀領域參考記憶體：
  - references/kinematic-archetypes.md（已驗證的機構方程式）
  - references/fdm-hardware-tolerances.md（列印間隙與緊固件沉頭孔）
  - references/fusion-api-gotchas.md（高速動畫與API修復）

金絲雀探測：使用 fusion-mcp 工具的 execute_api_script 呼叫：

def run(context):
    import adsk.core, adsk.fusion
    app = adsk.core.Application.get()
    if not app:
        raise RuntimeError("Autodesk Fusion 360 應用程式實例未找到。")
    design = adsk.fusion.Design.cast(app.activeProduct)
    if not design:
        raise RuntimeError("未開啟啟用中的Fusion 360設計文件。")
    print("FUSION_MCP_READY")

快速失敗規則：
- 您可以在Fusion 360關閉時執行階段1到3的媒體度量學，但如果在階段4之前 FUSION_MCP_READY 失敗，請停止傳送CAD建構腳本，並指示使用者開啟Fusion 360並載入啟用中的設計文件。

階段 1：媒體攝入與關鍵影格/輪廓提取

[!IMPORTANT] 工作區隔離規則：切勿將媒體處理檔案輸出到主要儲存庫根目錄（例如禁止使用 ./media_workspace）。務必確保在 models/<NN>_<Model_Name>/ 下存在專用的模型資料夾，並將所有媒體處理路由至 models/<NN>_<Model_Name>/workspace/media。

對輸入圖片、影片或目錄執行前處理與度量學引擎，並將結果輸出至模型隔離的工作區：

python3 <path_to_skills>/media-to-fusion/scripts/process_media.py "<input_media_or_folder_path>" --out-dir models/<NN>_<Model_Name>/workspace/media

使用 read_file 檢查 models/<NN>_<Model_Name>/workspace/media/media_manifest.json 並檢視產生的視覺化圖稿：
- 對於參考資料夾：首先檢視 dataset_overview.png，然後檢查個別子工作區（models/<NN>_<Model_Name>/workspace/media/<slug>/）。
- 對於影片：檢視 contact_sheet.png 和個別的 keyframe_XX_grid.png 檔案（自動過濾，剔除黑色淡入、動態模糊和手部遮擋，同時捕捉收合、中間擺動和展開的運動學狀態）。
- 對於圖片：檢視 annotated_grid.png（雙對比度100像素主/50像素次像素尺規網格）和 contours_preview.png（偵測到的Canny輪廓 + 槽孔/圓孔中心點以及同一行的中位數像素間距）。
- 分割畫面檢查：檢查 media_manifest.json 中的 viewport_layout.is_split（例如，單張圖片中並排的前視圖和右視正交視圖），以便在每個子視埠內獨立測量像素跨度。

階段 2：多層級尺度校準（尋找「黃金基準」）

在建模任何東西之前，請使用此嚴格優先順序層級來建立真實世界的毫米尺度（mm_per_px）：

優先級 1 — 媒體中的明確尺寸標註或列印平台限制：
- 檢查參考圖片中是否有尺寸標註箭頭（例如，總寬 35 cm / 350 mm、高 63 cm / 630 mm、深 32 cm / 320 mm，或內嵌托盤的標註如 330 x 100 x 70 mm）。
- 檢查是否有3D列印機的列印平台標註（例如，"適用於 220 x 220 mm 列印機" → 單件最大寬度/長度通常為 200–210 mm）。
優先級 2 — 影格中可見的標準生態系統與硬體特徵：
- IKEA Skådis 洞洞板模式：
  - 同一行水平槽孔間距（中心到中心）：40.0 mm
  - 垂直行與行間距：20.0 mm（交替行水平錯開 20.0 mm）
  - 槽孔尺寸：5.0 mm 寬 × 15.0 mm 高（跑道形/長圓形槽孔：10.0 mm 直線垂直中心距，兩端為 R = 2.5 mm 的全圓）
  - 標準板厚：5.0 mm（3D列印模組化洞洞板面板為 3.2 mm – 4.0 mm）
- 電子與機械硬體：
  - 機械鍵盤MX開關開孔：14.0 x 14.0 mm（1u鍵帽間距 = 19.05 mm）
  - 標準智慧型手機寬度（例如，當顯示放在支架上時）：~71.5 mm
  - USB-C 插座開口：8.94 x 3.26 mm
  - 緊固件：M3內六角螺絲頭直徑 = 5.5 mm（貫穿孔 = 3.2–3.4 mm），M4頭 = 7.0 mm
優先級 3 — 人體工學/手部參考：
- 如果有人手拿著零件且沒有硬體基準，請使用成人拇指平均寬度（~20.0 mm）或手掌寬度（~85.0 mm），並將總寬度以主要Fusion使用者參數（Tray_Width）公開，以便使用者一鍵重新縮放。

階段 3：運動學與結構分解（BOM）

在撰寫任何Fusion MCP腳本之前，先將組合件分解為結構化的零件物料清單 (BOM)：

分類固定與移動零件：
- 固定底座/框架零件：例如 Top_Anchor_Tray、Rear_Support_Legs（向下延伸至地面平面 $Z = 0$）和 Backboard_Pegboard_Panels。
- 從動/連桿零件：例如 Stepped_Trays（第2..N層）、滑動抽屜或旋轉門。
- 連桿/約束零件：例如 Parallel_Link_Bars、Side_Joiner_Clips（連接分開洞洞板兩半的H型夾）、Pivot_Pins。
- 模組化插件/配件：例如 Divider_Sub_Trays（$1/3$、$1/2$ 或 $1/1$ 寬度，帶有1–3個隔間）、Skadis_Hooks。
強制執行運動學定律以克服透視像素雜訊：
- 共面梯形多銷平行四邊形定律（非重疊單層桿）：在對任何連桿進行建模之前，請從側視正交/透視圖中計算桿的精確數量和每根桿的銷數量：
  - 如果參考圖顯示的是平行、非重疊的共面桿（例如，4根平行桿排列成梯形：桿 1 = 2銷短桿，桿 2 = 3銷長桿，桿 3 = 3銷長桿，桿 4 = 2銷短桿），切勿假設連桿的銷在重疊的橫向層中首尾相連。
  - 在 $N$ 層共面梯形連桿機構中，每個托盤 $t \in {0, \dots, N-1}$ 都有水平銷站 $s \in {0, 1, 2}$，間距為 Pin_Station_Pitch $\Delta y_{\text{station}}$，沿托盤深度方向排列（站 A 前端，站 B 中部，站 C 後端），每根桿連接 (托盤 $t$，站 $s$) $\longrightarrow$ (托盤 $t+1$，站 $s+1$)，單層孔距為 $L_{\text{step}} = \sqrt{\Delta y_{\text{station}}^2 + \Delta Z_{\text{collapsed}}^2}$：
    - 桿 1（2銷，長度 L_step）：(托盤 0, 站 B) -> (托盤 1, 站 C)
    - 桿 2（3銷，長度 2*L_step）：(托盤 0, 站 A) -> (托盤 1, 站 B) -> (托盤 2, 站 C)
    - 桿 3（3銷，長度 2*L_step）：(托盤 1, 站 A) -> (托盤 2, 站 B) -> (托盤 3, 站 C)
    - 桿 4（2銷，長度 L_step）：(托盤 2, 站 A) -> (托盤 3, 站 B)
  - 在與垂直線夾角 $\theta$ 處，托盤與托盤之間的平移量為： $$\Delta Y_{\text{tray}}(\theta) = -L_{\text{step}}\sin(\theta) - \Delta y_{\text{station}}, \qquad \Delta Z_{\text{tray}}(\theta) = -L_{\text{step}}\cos(\theta)$$
    - 在收合狀態 ($\theta_{\text{col}} = -\arcsin(\Delta y_{\text{station}} / L_{\text{step}})$) 下，$\Delta Y_{\text{tray}} = + \Delta y_{\text{station}} - \Delta y_{\text{station}} = 0\text{ mm}$（托盤100%垂直堆疊，而桿位於 $-\theta_{\text{col}}$ 處，且托盤後壁與後支撐腳的前端齊平）。
    - 在展開狀態 ($\theta_{\text{open}} = +\arcsin(\Delta y_{\text{station}} / L_{\text{step}})$) 下，完全相同的桿通過垂直方向擺動至 $+\theta_{\text{open}}$，使每個托盤向前移動 $\Delta Y_{\text{tray}} = -2 \Delta y_{\text{station}}$，同時將所有4根桿保持在單一共面層中，且不共享任何銷！
列印床模組化規則：
- 如果一個平板（例如一個高的Skådis背板）超過目標列印機床高（例如 > 210 mm），則將其水平分割為 Upper_Panel 和 Lower_Panel，並產生匹配的側面H型連接夾（0.20 mm 滑動間隙）。
可選透視單應性去扭曲（--rectify）：
- 對於有角度的平板圖案照片或複雜的2D輪廓，請執行：
```
~/.gemini/antigravity/skills/media-to-fusion/scripts/process_media.py "<image_path>" \
  --out-dir ./media_workspace \
  --rectify "x1,y1,x2,y2,x3,y3,x4,y4" \
  --real-w <width_mm> --real-h <height_mm>
```
- process_media.py 會自動將4個角點依順時針排序（左上、右上、右下、左下），將平面去扭曲為 rectified_ortho.png（解析度 0.1 mm/px），匯出 rectified_contour.dxf，並將簡化的封閉多邊形迴路（points_xy_mm）儲存在 media_manifest.json 內。

階段 4：透過Fusion 360 MCP進行參數化建模

透過 execute_api_script 在Fusion 360中乾淨地建構CAD組合件：

必要公釐轉公分轉換（cm = mm / 10.0）：
- Fusion 360的內部API（adsk.core.ValueInput.createByReal()、adsk.core.Point3D.create()）嚴格使用公分 (cm)。
- 務必在每個 execute_api_script 的頂部定義 def cm(mm_val): return mm_val / 10.0。
註冊主要使用者參數（design.userParameters）：先建立可編輯的公釐/度參數，以便使用者隨時重新設定縮放、層數或折疊狀態：
```
def set_user_param(design, name, expr_str, units="mm", comment=""):
    existing = design.userParameters.itemByName(name)
    if existing:
        existing.expression = expr_str
        return existing
    return design.userParameters.add(
        name, adsk.core.ValueInput.createByString(expr_str), units, comment
    )
```
對於可折疊/模組化組合件，建議的參數：
- Tray_Width、Tray_Depth、Tray_Height、Wall_Thickness（預設 2.4 mm）
- Link_Step_Pitch、Link_Width、Link_Thickness（預設 3.5 mm）
- Deploy_Angle_Deg（例如，展開/部署狀態為 40 deg，收合垂直堆疊為 0 deg）
- Clearance（預設 0.25 mm）
3D列印機械間隙：
- 旋轉樞軸銷/連桿孔：徑向間隙 0.25 mm（直徑間隙 0.50 mm），帶有 0.8 mm 凸緣或M3緊固件孔，以便連桿保持固定。
- 滑動連接夾/可拆卸隔板插件：每側間隙 0.20 mm（在插入托盤上總共減少 0.40 mm 寬度/深度）。
- 底部托盤人體工學與後支撐腳：
  - 如果參考媒體中可見，請在最底層托盤上包含圓角長方形側把手開孔。
  - 確保 Rear_Support_Legs 從頂部錨定托盤一直延伸至地面平面（$Z = Z_{\text{bottom_tray_floor}}$），以便組合件在展開時能平穩站立。

階段 5：閉環視覺與干涉驗證

切勿在盲目執行腳本後就結束。請同時進行視覺和數學驗證：

多角度視覺比較（get_screenshot）：
- 呼叫 fusion-mcp 工具的 get_screenshot，並設定：
  - view="iso-top-right", width=1024, height=1024
  - view="right", width=1024, height=1024（對於檢查連桿對齊、階梯角度和後腳接地至關重要！）
  - view="front", width=1024, height=1024（對於檢查Skådis槽孔網格對稱性和隔板比例至關重要！）
- 將渲染的螢幕截圖與參考關鍵影格/照片（keyframe_XX_grid.png / annotated_grid.png）並排比較。

自動化時間軸與干涉驗證：透過 execute_api_script 執行驗證程序，以斷言原生實體幾何並檢查零件之間的物理碰撞：

def run(context):
    import adsk.core, adsk.fusion
    app = adsk.core.Application.get()
    design = adsk.fusion.Design.cast(app.activeProduct)
    root = design.rootComponent

    assert root.sketches.count > 0, "未找到原生草圖！"
    assert root.features.extrudeFeatures.count > 0, "未找到擠出特徵！"
    assert root.meshBodies.count == 0, "偵測到禁止的 MeshBody 物件！"

    # 收集所有出現和根節點中的可見實體本體
    bodies = adsk.core.ObjectCollection.create()
    for b in root.bRepBodies:
        if b.isVisible:
            bodies.add(b)
    for occ in root.allOccurrences:
        for b in occ.bRepBodies:
            if b.isVisible:
                bodies.add(b)
    
    # 如果超過一個本體，執行碰撞檢查
    if bodies.count > 1:
        # 使用 Fusion 360 的干擾分析
        interferences = root.analyzeInterference(bodies) if hasattr(root, 'analyzeInterference') else []
        for idx, inter in enumerate(interferences):
            print(f"干涉 #{idx+1}: {inter.interferenceBody.name} - 體積 = {inter.volume} cm³")
        
        if interferences:
            print("警告：偵測到物理干涉！")
        else:
            print("通過：未偵測到干涉。")
    else:
        print("跳過干涉檢查：組裝體中只有一個或零個可見本體。")
    print("驗證完成。")

幾何尺寸驗證：使用 get_screenshot 上的量測工具或直接在Fusion 360中檢查關鍵尺寸（例如總寬度、托盤深度、連桿角度）是否與參考媒體中的估計值相符。

階段 6：最終輸出與使用者交付

模型組織與文件：
- 確保所有模型檔案都儲存在 models/<NN>_<Model_Name>/ 下。
- 在模型目錄中產生 README.md，解釋：
  - 關鍵使用者參數及其作用。
  - 如何變更部署/收合狀態（修改 Deploy_Angle_Deg）。
  - 組裝說明（如果需要）。
  - 任何已知的限制或假設。
匯出選項（可選）：
- 如果使用者要求，可從Fusion 360匯出為 .step、.stl 或 .3mf 格式。
最終檢查清單：
- 使用 process_media.py 建立了媒體工作區。
- 確定了黃金基準比例（毫米/像素）。
- 建立了運動學BOM並分類了零件。
- 在Fusion 360中建立了原生草圖和特徵。
- 使用者參數已註冊且可編輯。
- 已套用機械間隙。
- 螢幕截圖經視覺驗證與參考相符。
- 干涉檢查已通過（無碰撞）。
- 最終模型文件已準備就緒。

媒體轉換至Fusion 360重建技能