3D Printing CAD AI Framework

Framework para diseñar piezas paramétricas imprimibles en 3D de forma rápida y reproducible mediante el uso de IA, FreeCAD, Python y OrcaSlicer/BambuStudio.

Stack del Proyecto

• IDE: VS Code + agente de IA (Claude Code / Codex / Antigravity)
• CAD: FreeCAD (v0.19+)
• Laminador (Slicer): BambuStudio (por defecto en macOS) / OrcaSlicer (por defecto en Linux)
• Impresora: configurable en printer.yaml — por defecto BambuLab P1S (FDM, volumen 256x256x256 mm)
• Lenguaje: Python 3 + trimesh (para validación de mallas)

Impresora configurable

Los límites físicos de la impresora (volumen de impresión, boquilla, altura de capa) se definen en printer.yaml, en la raíz del repo. Los scripts de validación (validate_mesh.py) y la plantilla de piezas (part_template.py) leen ese perfil a través de framework/printer.py.

Para usar otra impresora FDM basta con editar printer.yaml. Ten en cuenta que la documentación de docs/ (en particular bambulab-p1s.md) está escrita para la impresora por defecto: si usas otra, genera tu propia documentación equivalente.

---

Estructura del Repositorio

• docs/: Documentación de referencia y buenas prácticas.
  • freecad-python-rules.md: Reglas de modelado en Python y prevención de Topological Naming.
  • design-principles.md: Principios de diseño funcional para FDM.
  • bambulab-p1s.md: Parámetros físicos e imprimibilidad FDM en la impresora por defecto (BambuLab P1S).
  • tolerances.md: Holguras de ensamblaje (0.2 mm a 0.5 mm) y contracción de agujeros.
  • design-review-checklist.md: Lista de comprobación previa a la impresión.
• framework/: Biblioteca Python reusable (geometría, fasteners, exportación).
• templates/: Plantillas reutilizables para nuevas piezas y metadatos.
• examples/: Ejemplos prácticos paramétricos (cajas, bandejas con divisiones, paneles reforzados, soportes de bridas y snaps).
• scripts/: Herramientas de automatización, validación y el servidor MCP.
• parts/: Directorio donde se almacenan las piezas finales diseñadas por el framework.

Nota: los directorios output/ (STL/STEP/FCStd generados) no se versionan. Toda pieza es regenerable ejecutando su macro.

---

Configuración Inicial

1. Entorno de Python (validación de mallas)

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. FreeCAD y Slicer

| SO | FreeCAD | Slicer | | :--- | :--- | :--- | | macOS | App oficial (/Applications/FreeCAD.app); se usa su binario interno freecadcmd | BambuStudio | | Linux | Paquete nativo (freecadcmd en el PATH), Flatpak org.freecad.FreeCAD o AppImage en ~/Applications/ | OrcaSlicer (PATH, Flatpak io.github.softfever.OrcaSlicer o AppImage en ~/Applications/) |

El script scripts/run_freecad_macro.py autodetecta estas instalaciones en ese orden.

Variables de Entorno

Puedes forzar los ejecutables mediante variables de entorno (admiten comandos con argumentos):

• FREECAD_COMMAND: Comando CLI de FreeCAD (ej: freecadcmd, o flatpak run --command=freecadcmd org.freecad.FreeCAD).
• SLICER_COMMAND: Comando o ruta al ejecutable del slicer.

Ejemplo en macOS para usar OrcaSlicer en lugar de BambuStudio:

export SLICER_COMMAND="/Applications/OrcaSlicer.app/Contents/MacOS/OrcaSlicer"

---

Guía de Uso del Framework

Modo 1: Ejecución Headless (Automatizada por CLI)

Si has escrito o modificado una macro Python de FreeCAD (por ejemplo, en examples/simple_box.py) y deseas generar el archivo STEP/STL y cargarlo directamente en tu Slicer:

1. Ejecuta el script de automatización desde la terminal:

   ./scripts/run_freecad_macro.py examples/simple_box.py --open
   

2. ¿Qué ocurre por debajo?

   • FreeCAD se ejecuta en segundo plano (freecadcmd) con la raíz del repo en PYTHONPATH (para poder importar framework/).
   • Procesa la macro y exporta simple_box.step y simple_box.stl en examples/output/.
   • Con --open, se abre tu laminador (BambuStudio u OrcaSlicer) con el STL ya cargado.

3. Para validar si la malla generada es físicamente hermética (manifold) y cumple los límites de tamaño de tu impresora:

   .venv/bin/python3 scripts/validate_mesh.py examples/output/simple_box.stl --material PLA
   

Modo 2: Edición Interactiva en Tiempo Real (Mediante MCP)

Si deseas interactuar con FreeCAD GUI mientras escribes o refinas la pieza en VS Code con asistencia de la IA en tiempo real:

1. Paso 1: Arrancar el Servidor XML-RPC en FreeCAD

   • Opción automática (recomendada): ejecuta una vez python3 scripts/install_rpc_autostart.py. A partir de entonces el puente arranca solo cada vez que abres FreeCAD GUI.
   • Opción manual: abre la consola de Python de FreeCAD (Ver > Paneles > Consola Python) y ejecuta/carga el script freecad_rpc_server.py.
   • En ambos casos verás un mensaje confirmando que el puente está escuchando en el puerto 9875.

2. Paso 2: Conectar VS Code con el Servidor MCP

   • Configura mcp_server.py como servidor MCP en tu cliente (VS Code, Claude Code o Claude Desktop), usando la ruta absoluta del repo en tu máquina:

     "freecad-mcp": {
       "command": "python3",
       "args": ["<ruta_al_repo>/scripts/mcp_server.py"]
     }
     

3. Paso 3: Diseñar por IA

   • Ahora, desde tu chat de VS Code, puedes pedirle a la IA: "Crea una caja de 50x40 mm con 2 mm de pared".
   • La IA utilizará la herramienta run_macro para enviar instrucciones a FreeCAD, o run_macro_file para re-ejecutar una macro del repo (cierra los documentos previos, mantiene la cámara y devuelve un resumen geométrico).
   • Verás la pieza dibujarse e interactuar en tiempo real en la pantalla de FreeCAD.
   • Una vez satisfecho, la IA podrá llamar a export_active_part y validate_stl_mesh para guardar y certificar los modelos para impresión.

4. Alternativa sin IA: watcher de macros (hot-reload)

   • Si prefieres editar la macro a mano y ver el resultado al guardar:

     ./scripts/watch_macro.py parts/<nombre>/macro.py
     

   • Cada vez que guardes la macro (o cualquier .py de framework/, o el params.yaml de la pieza), se re-ejecuta en FreeCAD GUI manteniendo el encuadre de cámara, y el terminal muestra validez, volumen y bounding box de cada objeto.

---

Licencia

© 2026 Alberto Pozo Esteban. Este proyecto se distribuye bajo la licencia CC BY-NC 4.0 (ver LICENSE): puedes usarlo, modificarlo y compartirlo libremente citando al autor y sin fines comerciales.