media-to-fusion

미디어(이미지 / 비디오 / 참조 팩)를 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 애플리케이션 인스턴스를 찾을 수 없습니다.")
       design = adsk.fusion.Design.cast(app.activeProduct)
       if not design:
           raise RuntimeError("활성 Fusion 360 설계 문서가 열려 있지 않습니다.")
       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. models/<NN>_<Model_Name>/workspace/media/media_manifest.json을 검사하고 read_file로 생성된 시각적 아티팩트를 확인하십시오:
   • 참조 폴더의 경우: 먼저 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 프린터 빌드 플레이트 지시선을 확인하십시오(예: "220 x 220 mm 프린터용" $\rightarrow$ 최대 단일 조각 너비/길이는 일반적으로 200–210 mm).
2. 우선순위 2 — 프레임 내에 보이는 표준 에코시스템 및 하드웨어 특징:
   • IKEA Skådis 페그보드 패턴:
     • 가로 동일 행 슬롯 피치(중심 간): 40.0 mm
     • 세로 행 간 피치: 20.0 mm(교대 행은 가로로 20.0 mm 엇갈림)
     • 슬롯 치수: 5.0 mm 너비 $\times$ 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. 고정 구성 요소 vs. 이동 구성 요소 분류:
   • 고정 베이스/프레임 구성 요소: 예: Top_Anchor_Tray, Rear_Support_Legs(접지 평면 $Z = 0$까지 확장), Backboard_Pegboard_Panels.
   • 구동/커플러 구성 요소: 예: Stepped_Trays(Tier 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개의 평행 바: Bar 1 = 2핀 짧은 바, Bar 2 = 3핀 긴 바, Bar 3 = 3핀 긴 바, Bar 4 = 2핀 짧은 바)가 표시되면 링키지 바가 끝에서 끝으로 중첩되는 측면 레이어에서 핀을 공유한다고 가정하지 마십시오.
     • $N$단 동일 평면 에셜론 링키지에서 각 트레이 $t \in {0, \dots, N-1}$는 트레이 깊이를 따라 Pin_Station_Pitch $\Delta y_{\text{station}}$ 만큼 간격을 둔 수평 핀 스테이션 $s \in {0, 1, 2}(Station A앞,Station B중간,Station C` 뒤)을 가지며, 모든 바는 **(Tray $t$, Station $s$) $\longrightarrow$ (Tray $t+1$, Station $s+1$)**를 단일 단 홀 피치 $L_{\text{step}} = \sqrt{\Delta y_{\text{station}}^2 + \Delta Z_{\text{collapsed}}^2}$로 연결합니다:
       • Bar 1 (2핀, 길이 L_step): (Tray 0, Station B) -> (Tray 1, Station C)
       • Bar 2 (3핀, 길이 2*L_step): (Tray 0, Station A) -> (Tray 1, Station B) -> (Tray 2, Station C)
       • Bar 3 (3핀, 길이 2*L_step): (Tray 1, Station A) -> (Tray 2, Station B) -> (Tray 3, Station C)
       • Bar 4 (2핀, 길이 L_step): (Tray 2, Station A) -> (Tray 3, Station 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개의 모서리를 시계 방향(TL, TR, BR, BL)으로 정렬하고, 평면을 0.1 mm/px로 rectified_ortho.png로 왜곡 보정하며, 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, "네이티브 스케치를 찾을 수 없습니다!"
       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)
       print(f"검증할 {bodies.count}개의 솔리드 바디")
       return True
   

3. 선택적 충돌 감지: 동일한 스크립트 내에서 adsk.fusion.ToolsInterferenceAnalysis를 사용하여 간섭을 분석할 수 있지만 get_screenshot 시각적 비교가 충분해야 합니다.

---

6단계: 문서화, 패키징 및 내보내기

최종 단계는 모델을 문서화하고 패키징하는 것입니다.

1. 스크린샷 캡처: "미디어 재구성 자산" 표준에 따라 다음과 같이 Fusion 360 뷰포트를 캡처하십시오:
   • models/<NN>_<Model_Name>/assets/screenshot_iso.png (등측 투영)
   • models/<NN>_<Model_Name>/assets/screenshot_front.png
   • models/<NN>_<Model_Name>/assets/screenshot_side.png
2. 사용자 매개변수 JSON 내보내기: 모델 매개변수를 사람이 읽을 수 있는 JSON 파일로 내보내십시오:

   python3 <path_to_skills>/media-to-fusion/scripts/export_parameters.py models/<NN>_<Model_Name>/model.f3d
   

   이렇게 하면 models/<NN>_<Model_Name>/parameters.json이 생성됩니다.
3. README.md 생성: 모델 디렉토리에 README.md를 생성하십시오:
   • 스크린샷, 참조 소스 링크, 사용자 매개변수 요약, 3D 인쇄 권장 사항을 포함하십시오.
4. git 상태 확인: 새 파일이 추적되고 있는지 확인하십시오:

   cd models/<NN>_<Model_Name>
   git add .
   git status