媒体转Fusion 360三维重建技能

媒体（图像/视频/参考包）转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连接：

1. 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修复）

2. 金丝雀探针： 调用 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 application instance not found.")
       design = adsk.fusion.Design.cast(app.activeProduct)
       if not design:
           raise RuntimeError("No active Fusion 360 design document open.")
       print("FUSION_MCP_READY")
   

3. 快速失败规则：

   • 你可以在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。

1. 在模型的隔离工作区中对输入图像、视频或目录执行预处理和测量引擎：

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

2. 使用 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（双对比度100px主/50px次像素标尺网格）和 contours_preview.png（检测到的Canny轮廓以及槽/孔质心和中间同行像素间距）。
   • 分屏检查：检查 media_manifest.json 中的 viewport_layout.is_split（例如，单张图像中并排的前视图和右正视视图），以便在每个子视口内独立测量像素跨度。

---

阶段2：多层级比例校准（寻找“黄金基准”）

在建模之前，请使用以下严格优先级层级建立真实世界毫米比例（mm_per_px）：

1. 优先级1 — 媒体中的显式尺寸标注或构建平台约束：
   • 检查参考图像中的尺寸标注箭头（例如，总宽度 35 cm / 350 mm，高度 63 cm / 630 mm，深度 32 cm / 320 mm，或嵌入式内托盘标注如 330 x 100 x 70 mm）。
   • 检查3D打印机构建平台标注（例如，"FOR 220 x 220 mm PRINTERS" → 最大单件宽度/长度通常为 200–210 mm）。
2. 优先级2 — 画面中可见的标准生态系统与硬件特征：
   • 宜家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. 优先级3 — 人体工学/手部参考：
   • 如果人手持握零件且不存在硬件基准，则使用成人拇指平均宽度（~20.0 mm）或手掌宽度（~85.0 mm），并将总宽度作为主Fusion用户参数（Tray_Width）公开，以便用户一键重新缩放。

---

阶段3：运动学与结构分解（BOM）

在编写任何Fusion MCP脚本之前，将装配体分解为结构化的组件物料清单（BOM）：

1. 分类固定与运动部件：
   • 固定基础/框架组件：例如 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。
2. 强制执行运动学定律以对抗透视像素噪声：
   • 共面梯形多销平行四边形定律（非重叠单层连杆）： 在对任何联动装置进行建模之前，请在侧面正交/透视视图中计算每个连杆的精确连杆数和销数：
     • 如果参考显示平行、非重叠的共面连杆（例如，4根平行连杆排列成梯形：连杆 1 = 2销短连杆，连杆 2 = 3销长连杆，连杆 3 = 3销长连杆，连杆 4 = 2销短连杆），切勿假设联动连杆以重叠的横向层端对端共享销。
     • 在一个 $N$ 层级共面梯形联动装置中，每个托盘 $t \in {0, \dots, N-1}$ 沿托盘深度具有由 Pin_Station_Pitch $\Delta y_{\text{station}}$ 间隔的水平销站 $s \in {0, 1, 2}$（站 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根连杆保持在单个共面层中，且零共享销！
3. 打印平台模块化规则：
   • 如果平板（例如高大的Skådis背板）超过目标打印机平台高度（例如 > 210 mm），则将其水平拆分为 Upper_Panel 和 Lower_Panel，并生成匹配的侧面H形接合夹（0.20 mm 滑动间隙）。
4. 可选透视单应性去畸变（--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装配体：

1. 必选厘米转换（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。
2. 注册主用户参数（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）
3. 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：闭环视觉与干涉检查

切勿在盲目执行脚本后结束。执行视觉和数学双重验证：

1. 多角度视觉比较（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）并排比较。
2. 自动化时间轴与干涉检查： 通过 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, "No native sketches found!"
       assert root.features.extrudeFeatures.count > 0, "No extrude features found!"
       assert root.meshBodies.count == 0, "Forbidden MeshBody objects detected!"
   
       # 收集所有出现和根组件中的可见实体体
       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:
   
   ...
   
   [因翻译而截断]
   

}