Media-to-Fusion

Habilidad de Reconstrucción de Medios (Imagen/Video/Paquete de Referencia) a Fusion 360

Cuando el usuario proporcione una foto, una carpeta de referencia multiángulo o un video (.mp4, .mov, .png, .jpg, .webp) y pida recrear el objeto en Autodesk Fusion 360, siga este flujo de trabajo de ingeniería determinista de 6 fases.

MANDATO ESTRICTO DE CAD:

• Nunca pase directamente a escribir extrusiones MCP de Fusion sin ejecutar process_media.py, establecer un datum de escala en milímetros del mundo real y redactar una Lista de Materiales (BOM) cinemática.
• Cada componente debe reconstruirse usando Sketches nativos, Planos de Construcción, Líneas/Arcos/Círculos de Sketch, Parámetros de Usuario y Características de Extrusión/Redondeo/Articulación en la línea de tiempo de Fusion 360. Nunca genere cuerpos de malla en bruto (root.meshBodies.add).

---

Fase 0: Puerta de Seguridad Pre-Vuelo y Entorno de Monorepo (Obligatorio)

Antes de crear geometría CAD en Fusion 360, alinee su espacio de trabajo y verifique la conectividad MCP en vivo:

1. Alineación del Monorepo CAD:

   • Espacio de trabajo principal: Monorepo CAD activo o raíz del proyecto (ej., CAD_MONOREPO_ROOT o espacio de trabajo actual).
   • Garantía de Aislamiento Estricta: Nunca cree archivos temporales, scripts o renders en la raíz del repositorio ni mute shared/.
   • Almacene nuevos modelos bajo models/<NN>_<Nombre_Del_Modelo>/ (ej. models/02_Organizador_Escritorio_Modular/). Si comienza un nuevo modelo, andamie con scaffold_text_model.py "<Nombre_Del_Modelo>".
   • Importe ayudantes universales de CAD desde shared/ (fusion_client, cad_primitives, hardware_library, scene_animator).
   • Lea la memoria de referencia del dominio antes de escribir scripts:
     • references/kinematic-archetypes.md (ecuaciones de mecanismos verificadas)
     • references/fdm-hardware-tolerances.md (holguras de impresión y avellanados de sujetadores)
     • references/fusion-api-gotchas.md (animación de alta velocidad y correcciones de API)

2. Sonda Canaria: Llame a la herramienta fusion-mcp execute_api_script con:

   def run(context):
       import adsk.core, adsk.fusion
       app = adsk.core.Application.get()
       if not app:
           raise RuntimeError("No se encontró la instancia de la aplicación Autodesk Fusion 360.")
       design = adsk.fusion.Design.cast(app.activeProduct)
       if not design:
           raise RuntimeError("No hay ningún documento de diseño de Fusion 360 activo abierto.")
       print("FUSION_MCP_READY")
   

3. Regla de Fracaso Rápido:

   • Puede ejecutar las Fases 1–3 de metrología de medios mientras Fusion 360 está cerrado, pero si FUSION_MCP_READY falla antes de la Fase 4, DETÉNGASE antes de enviar scripts de construcción CAD e indique al usuario que abra Fusion 360 con un documento de diseño activo.

---

Fase 1: Ingesta de Medios y Extracción de Fotogramas Clave/Contornos

[!IMPORTANT] Regla de Aislamiento del Espacio de Trabajo: Nunca genere archivos de procesamiento de medios en la raíz principal del repositorio (ej., ./media_workspace está prohibido). Siempre asegúrese de que exista una carpeta de modelo dedicada bajo models/<NN>_<Nombre_Del_Modelo>/, y dirija todo el procesamiento de medios a models/<NN>_<Nombre_Del_Modelo>/workspace/media.

1. Ejecute el motor de preprocesamiento y metrología en la imagen, video o directorio de entrada en el espacio de trabajo aislado del modelo:

   python3 <ruta_a_habilidades>/media-to-fusion/scripts/process_media.py "<ruta_medio_o_carpeta_de_entrada>" --out-dir models/<NN>_<Nombre_Del_Modelo>/workspace/media
   

2. Inspeccione models/<NN>_<Nombre_Del_Modelo>/workspace/media/media_manifest.json y vea los artefactos visuales generados con read_file:
   • Para Carpetas de Referencia: Vea primero dataset_overview.png, luego inspeccione los sub-espacios de trabajo individuales (models/<NN>_<Nombre_Del_Modelo>/workspace/media/<slug>/).
   • Para Videos: Vea contact_sheet.png y archivos individuales keyframe_XX_grid.png (filtrados automáticamente para rechazar fundidos a negro, desenfoque de movimiento y limpiezas de mano mientras captura estados cinemáticos colapsados, en medio del balanceo y desplegados).
   • Para Imágenes: Vea annotated_grid.png (cuadrícula de regla de píxeles de contraste dual de 100px mayor / 50px menor) y contours_preview.png (contornos Canny detectados + centroides de ranuras/agujeros y paso de píxeles mediano de la misma fila).
   • Verificación de Pantalla Dividida: Verifique viewport_layout.is_split en media_manifest.json (ej., vistas ortográficas frontal y derecha lado a lado en una sola imagen) para que los tramos de píxeles se midan independientemente dentro de cada sub-viewport.

---

Fase 2: Calibración de Escala Multinivel (Encontrar el "Datum Dorado")

Antes de modelar cualquier cosa, establezca la escala en milímetros del mundo real (mm_per_px) usando esta jerarquía de prioridad estricta:

1. Prioridad 1 — Llamadas de Dimensión Explícitas o Restricciones de Plataforma de Construcción en los Medios:
   • Verifique las imágenes de referencia en busca de flechas de llamada de dimensión (ej., ancho total 35 cm / 350 mm, alto 63 cm / 630 mm, fondo 32 cm / 320 mm, o llamadas de bandeja interior como 330 x 100 x 70 mm).
   • Verifique las llamadas de la plataforma de construcción de la impresora 3D (ej., "PARA IMPRESORAS DE 220 x 220 mm" $\rightarrow$ el ancho/largo máximo de una sola pieza suele ser 200–210 mm).
2. Prioridad 2 — Ecosistema Estándar y Características de Hardware Visibles en el Fotograma:
   • Patrón de Tablero de Clavijas IKEA Skådis:
     • Paso horizontal de ranuras en la misma fila (centro a centro): 40.0 mm
     • Paso vertical de fila a fila: 20.0 mm (filas alternas escalonadas horizontalmente por 20.0 mm)
     • Dimensiones de la ranura: 5.0 mm de ancho $\times$ 15.0 mm de alto (ranura de estadio/forma de ojo de cerradura: 10.0 mm de centro a centro vertical recto con extremos de radio completo R = 2.5 mm)
     • Grosor estándar del tablero: 5.0 mm (3.2 mm – 4.0 mm en paneles de tablero de clavijas modulares impresos en 3D)
   • Electrónica y Hardware Mecánico:
     • Recorte de interruptor MX de teclado mecánico: 14.0 x 14.0 mm (paso de tecla 1u = 19.05 mm)
     • Ancho estándar de teléfono inteligente (ej., cuando se muestra apoyado en un soporte): ~71.5 mm
     • Abertura del receptáculo USB-C: 8.94 x 3.26 mm
     • Sujetadores: diámetro de cabeza de M3 = 5.5 mm (agujero de despeje = 3.2–3.4 mm), cabeza de M4 = 7.0 mm
3. Prioridad 3 — Referencia Ergonómica/De Mano:
   • Si las manos humanas sostienen la pieza y no existe un datum de hardware, use el ancho promedio del pulgar de un adulto (~20.0 mm) o la anchura de la palma (~85.0 mm), y exponga el ancho total como un Parámetro de Usuario maestro de Fusion (Tray_Width) para que el usuario pueda reescalar con un clic.

---

Fase 3: Descomposición Cinemática y Estructural (BOM)

Descomponga el ensamblaje en una Lista de Materiales (BOM) estructurada antes de escribir cualquier script de Fusion MCP:

1. Clasifique Componentes Fijos vs. Móviles:
   • Componentes de Base / Bastidor Fijos: ej., Top_Anchor_Tray, Rear_Support_Legs (extendiéndose hacia abajo al plano del suelo $Z = 0$), y Backboard_Pegboard_Panels.
   • Componentes Impulsados / Acopladores: ej., Stepped_Trays (Nivel 2..N), cajones deslizantes, o puertas giratorias.
   • Componentes de Eslabonamiento / Restricción: ej., Parallel_Link_Bars, Side_Joiner_Clips (clips en H que unen mitades de tableros de clavijas), Pivot_Pins.
   • Inserciones Modulares / Accesorios: ej., Divider_Sub_Trays (ancho $1/3$, $1/2$ o $1/1$ con 1–3 compartimentos), Skadis_Hooks.
2. Aplique Leyes Cinemáticas sobre el Ruido de Píxeles de la Perspectiva:
   • Ley del Paralelogramo de Pasador Múltiple Escalonado Coplanar (Barras de Una Sola Capa No Superpuestas): Antes de modelar cualquier eslabonamiento, cuente el número exacto de barras y pasadores por barra en las vistas ortográficas/de perspectiva laterales:
     • Nunca asuma que las barras de eslabonamiento comparten pasadores de extremo a extremo en capas laterales superpuestas si la referencia muestra barras coplanares no superpuestas paralelas (ej., 4 barras paralelas dispuestas en escalón: Barra 1 = barra corta de 2 pasadores, Barra 2 = barra larga de 3 pasadores, Barra 3 = barra larga de 3 pasadores, Barra 4 = barra corta de 2 pasadores).
     • En un eslabonamiento escalonado coplanar de $N$ niveles, cada bandeja $t \in {0, \dots, N-1}$ tiene estaciones de pasador horizontales $s \in {0, 1, 2}$ espaciadas por Pin_Station_Pitch $\Delta y_{\text{station}}$ a lo largo de la profundidad de la bandeja (Estación A frontal, Estación B media, Estación C trasera), y cada barra conecta (Bandeja $t$, Estación $s$) $\longrightarrow$ (Bandeja $t+1$, Estación $s+1$) con un paso de agujero de un solo nivel $L_{\text{step}} = \sqrt{\Delta y_{\text{station}}^2 + \Delta Z_{\text{collapsed}}^2}$:
       • Barra 1 (2 pasadores, longitud L_step): (Bandeja 0, Estación B) -> (Bandeja 1, Estación C)
       • Barra 2 (3 pasadores, longitud 2*L_step): (Bandeja 0, Estación A) -> (Bandeja 1, Estación B) -> (Bandeja 2, Estación C)
       • Barra 3 (3 pasadores, longitud 2*L_step): (Bandeja 1, Estación A) -> (Bandeja 2, Estación B) -> (Bandeja 3, Estación C)
       • Barra 4 (2 pasadores, longitud L_step): (Bandeja 2, Estación A) -> (Bandeja 3, Estación B)
     • En el ángulo de barra $\theta$ desde la vertical, la traslación de bandeja a bandeja es: $$\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)$$
       • En el Estado Colapsado ($\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}$ (las bandejas se apilan 100% verticalmente mientras las barras se sientan en $-\theta_{\text{col}}$, y las paredes traseras de las bandejas descansan al ras contra el frente de las patas de soporte traseras).
       • En el Estado Abierto ($\theta_{\text{open}} = +\arcsin(\Delta y_{\text{station}} / L_{\text{step}})$), las mismas barras oscilan a través de la vertical hasta $+\theta_{\text{open}}$, escalonando cada bandeja hacia adelante por $\Delta Y_{\text{tray}} = -2 \Delta y_{\text{station}}$ mientras mantiene las 4 barras en una capa coplanar única sin pasadores compartidos.
3. Regla de Modularidad de la Cama de Impresión:
   • Si un panel plano (como un tablero Skådis alto) excede la altura de la cama de la impresora objetivo (ej. > 210 mm), divídalo horizontalmente en Panel_Superior y Panel_Inferior y genere clips de unión de perfil en H laterales coincidentes (holgura deslizante de 0.20 mm).
4. Desanudado Opcional de Homografía de Perspectiva (--rectify):
   • Para fotos angulares de placas planas estampadas o siluetas 2D complejas, ejecute:

     ~/.gemini/antigravity/skills/media-to-fusion/scripts/process_media.py "<ruta_imagen>" \
       --out-dir ./media_workspace \
       --rectify "x1,y1,x2,y2,x3,y3,x4,y4" \
       --real-w <ancho_mm> --real-h <alto_mm>
     

   • process_media.py ordena automáticamente las 4 esquinas en sentido horario (SI, SD, BD, BI), desanuda el plano a rectified_ortho.png a 0.1 mm/px, exporta rectified_contour.dxf, y guarda bucles de polígono cerrados simplificados (points_xy_mm) dentro de media_manifest.json.

---

Fase 4: Modelado Paramétrico a través de Fusion 360 MCP

Construya el ensamblaje CAD limpiamente en Fusion 360 a través de execute_api_script:

1. Conversión Obligatoria a Centímetros (cm = mm / 10.0)":
   • La API interna de Fusion 360 (adsk.core.ValueInput.createByReal(), adsk.core.Point3D.create()) usa estrictamente centímetros (cm).
   • Siempre defina def cm(valor_mm): return valor_mm / 10.0 en la parte superior de cada execute_api_script.
2. Registre Parámetros de Usuario Maestros (design.userParameters): Cree parámetros editables en milímetros/grados primero para que el usuario pueda reconfigurar la escala, el número de niveles o el estado de plegado en cualquier momento:

   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
       )
   

   Parámetros recomendados para ensamblajes plegables/modulares:
   • Tray_Width, Tray_Depth, Tray_Height, Wall_Thickness (predeterminado 2.4 mm)
   • Link_Step_Pitch, Link_Width, Link_Thickness (predeterminado 3.5 mm)
   • Deploy_Angle_Deg (ej., 40 deg para estado Abierto/Desplegado, 0 deg para apilado vertical Colapsado)
   • Clearance (predeterminado 0.25 mm)
3. Holguras Mecánicas para Impresión 3D:
   • Pasadores de pivote rotativos / agujeros de eslabonamiento: Holgura radial de 0.25 mm (diametral 0.50 mm), con un labio 0.8 mm o taladro de sujetador M3 para que los eslabones permanezcan retenidos.
   • Clips de unión deslizantes / inserciones divisoras extraíbles: Holgura de 0.20 mm por lado (deducción total de ancho/profundidad de 0.40 mm en bandejas de inserción).
   • Ergonomía de la Bandeja Inferior y Patas de Soporte Traseras:
     • Incluya recortes de asa laterales oblongos redondeados en la bandeja más baja si son visibles en los medios de referencia.
     • Asegúrese de que Rear_Support_Legs alcancen desde la bandeja de anclaje superior hasta el plano del suelo ($Z = Z_{\text{piso_bandeja_inferior}}$) para que el ensamblaje se mantenga nivelado cuando esté desplegado.

---

Fase 5: Verificación Visual y de Interferencias de Bucle Cerrado

Nunca concluya después de una ejecución de script a ciegas. Realice tanto la verificación visual como matemática:

1. Comparación Visual Multiángulo (get_screenshot):
   • Llame a la herramienta fusion-mcp get_screenshot con:
     • view="iso-top-right", width=1024, height=1024
     • view="right", width=1024, height=1024 (crucial para inspeccionar la alineación de la barra de eslabonamiento, el ángulo de escalón y el contacto de la pata trasera con el suelo)
     • view="front", width=1024, height=1024 (crucial para inspeccionar la simetría de la cuadrícula de ranuras de Skådis y las proporciones del divisor)
   • Compare las capturas de pantalla renderizadas lado a lado con los fotogramas clave/fotos de referencia (keyframe_XX_grid.png / annotated_grid.png).
2. Verificación Automatizada de Línea de Tiempo e Interferencias: Ejecute un pase de verificación a través de execute_api_script para afirmar la geometría sólida nativa y verificar colisiones físicas entre componentes:

   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 se encontraron sketches nativos!"
       assert root.features.extrudeFeatures.count > 0, "¡No se encontraron características de extrusión!"
       assert root.meshBodies.count == 0, "¡Se detectaron objetos MeshBody prohibidos!"
   
       # Recolectar todos los cuerpos sólidos visibles en ocurrencias y raíz
       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)
   
       # Verificar interferencias
       if bodies.count > 1:
           interference_mgr = adsk.fusion.InterferenceManager.get()
           results = interference_mgr.calculateInterference(bodies)
           assert results.count == 0, f"¡Se detectaron {results.count} interferencias! Revise la geometría."
       print("VERIFICACIÓN SUPERADA: sin interferencias, solo geometría nativa.")
   

3. Regla de Rechazo de Mallas:
   • Si root.meshBodies.count > 0, debe FALLAR LA VERIFICACIÓN y reconstruir la geometría usando sketches nativos y extrusión. Las mallas no son editables paramétricamente y rompen el historial de diseño.

---

Fase 6: Documentación, Compromiso Git y Finalización

Antes de declarar que una tarea está completa, finalice el registro del proyecto:

1. Genere una Hoja de Especificaciones de Diseño: Ejecute python3 process_media.py <ruta_medio> --out-dir <ruta_modelo> --create-spec (si está disponible) para generar SPEC.md en la raíz del modelo con:
   • Lista de Materiales (BOM) cinemática final
   • Tolerancias mecánicas y holguras usadas
   • Tabla de parámetros de usuario con valores predeterminados
   • Marcas de tiempo de fotogramas clave de referencia mapeadas a estados cinemáticos
   • Notas de fabricación (configuración de cama de impresora, orientación, necesidades de soporte)
2. Registre el Progreso en Git:
   • Haga commit de todos los archivos de medios, artefactos procesados y scripts CAD en models/<NN>_<Nombre_Del_Modelo>/:

     git add models/<NN>_<Nombre_Del_Modelo>/
     git commit -m "feat(models): reconstrucción CAD de <Nombre_Del_Modelo> desde <tipo_medio>"
     

3. Resuma la Reconstrucción: Informe al usuario con:
   • Estado del modelo (completado, verificación superada, archivos commit)
   • Cualquier suposición hecha durante la estimación de escala (Prioridad 1/2/3)
   • Instrucciones para afinar: "Abra Fusion 360, haga doble clic en Deploy_Angle_Deg en el panel de Parámetros y cambie el valor de 40 a 0 para ver el estado colapsado."
   • Enlaces a los artefactos generados (media_manifest.json, SPEC.md, capturas de pantalla de verificación)

---

Resumen de Comandos de Script Auxiliares

Comando	Propósito
python3 <ruta>/process_media.py <ruta_entrada> --out-dir <ruta_salida>	Ingesta de medios + metrología + extracción de fotogramas clave/contornos
python3 <ruta>/process_media.py <ruta_imagen> --out-dir ./ --rectify "x1,y1,...x4,y4" --real-w <mm> --real-h <mm>	Desanudado de homografía de perspectiva para fotos angulares de objetos planos
fusion-mcp execute_api_script <script_cad.py>	Ejecutar script de construcción CAD en Fusion 360
fusion-mcp get_screenshot view="iso-top-right" width=1024 height=1024	Capturar vista renderizada de la escena actual de Fusion 360
git add models/<NN>_<Nombre>/ && git commit -m "feat: ..."	Comprometer reconstrucción completa en monorepo

---

Notas sobre la API de Fusion y Conversión de Unidades

Centímetros (no milímetros)

Todas las API geométricas de Fusion 360 (Point3D, ValueInput, extrude, move) requieren unidades internas de centímetros. Defina siempre un ayudante cm():

def cm(mm_val): return mm_val / 10.0

Manejo de Sketches y Perfiles

Cuando cree sketches de extrusión, use sketch.profiles.item(0) para seleccionar automáticamente el perfil cerrado más grande. Para perfiles múltiples, itere sketch.profiles y verifique el área de la superficie.

Articulaciones en Lugar de Restricciones de Ensamblaje

Para componentes móviles (bisagras, barras paralelas, cajones), siempre use adsk.fusion.AsBuiltJointBuilder con el tipo RevoluteJointType o SliderJointType en lugar de fijar ocurrencias. Esto preserva los grados de libertad para análisis cinemático.

Elevación de Errores

Siempre propague fallos levantando excepciones RuntimeError con mensajes descriptivos. Los errores de script silenciosos hacen que Fusion 360 entre en un estado inconsistente.

---

Referencias de Hardware Estándar (Memoria de Dominio)

Característica	Dimensión (mm)	Escenario de Uso Típico
Paso de ranura Skådis (fila)	40.0	Tableros de clavijas modulares
Paso de fila Skådis	20.0	Espaciado vertical de tableros de clavijas
Recorte de interruptor MX	14.0 x 14.0	Soportes/herramientas de teclado mecánico
Diámetro de cabeza M3	5.5	Agujeros para pasadores de pivote, taladros de sujetadores
Agujero de despeje M3	3.4	Piezas roscadas, inserciones
Ancho de teléfono estándar	~71.5	Soportes para teléfono, topes
Abertura USB-C	8.94 x 3.26	Recortes para concentradores/docks
Ancho de pulgar humano	~20.0	Suposición ergonómica cuando no hay datum