Content
# 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`](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`](printer.yaml), en la raíz del repo. Los scripts de validación ([`validate_mesh.py`](scripts/validate_mesh.py)) y la plantilla de piezas ([`part_template.py`](templates/part_template.py)) leen ese perfil a través de [`framework/printer.py`](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`](docs/bambulab-p1s.md)) está escrita para la impresora por defecto: si usas otra, genera tu propia documentación equivalente.
---
## Estructura del Repositorio
- [`docs/`](docs/): Documentación de referencia y buenas prácticas.
- [`freecad-python-rules.md`](docs/freecad-python-rules.md): Reglas de modelado en Python y prevención de Topological Naming.
- [`design-principles.md`](docs/design-principles.md): Principios de diseño funcional para FDM.
- [`bambulab-p1s.md`](docs/bambulab-p1s.md): Parámetros físicos e imprimibilidad FDM en la impresora por defecto (BambuLab P1S).
- [`tolerances.md`](docs/tolerances.md): Holguras de ensamblaje (0.2 mm a 0.5 mm) y contracción de agujeros.
- [`design-review-checklist.md`](docs/design-review-checklist.md): Lista de comprobación previa a la impresión.
- [`framework/`](framework/): Biblioteca Python reusable (geometría, fasteners, exportación).
- [`templates/`](templates/): Plantillas reutilizables para nuevas piezas y metadatos.
- [`examples/`](examples/): Ejemplos prácticos paramétricos (cajas, bandejas con divisiones, paneles reforzados, soportes de bridas y snaps).
- [`scripts/`](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)
```bash
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`](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:
```bash
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:
```bash
./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:
```bash
.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`](scripts/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`](scripts/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:
```json
"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:
```bash
./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](https://creativecommons.org/licenses/by-nc/4.0/deed.es) (ver [LICENSE](LICENSE)): puedes usarlo, modificarlo y compartirlo libremente **citando al autor** y **sin fines comerciales**.
