# STL Repository

Aplicacion web completa para gestionar, organizar, visualizar y compartir modelos 3D en formato STL y 3MF.

## Caracteristicas principales

### Gestion de modelos
- **Subida multi-archivo**: STL, 3MF e imagenes de referencia (JPG/PNG)
- **Importacion desde URL**: Descarga directa de archivos .stl/.3mf desde cualquier URL
- **Subida masiva ZIP**: Procesa automaticamente todos los STL/3MF dentro de un ZIP
- **Deteccion de duplicados**: Por hash SHA256
- **Metadatos enriquecidos**: Titulo, autor, descripcion, categoria, tags (autocompletado)
- **Templates de licencia**: CC0, CC-BY, CC-BY-SA, CC-BY-NC, GPL-3.0, MIT

### Galeria y busqueda
- **Galeria responsive** con grid animado y glassmorphism
- **Busqueda avanzada**: Por texto, categoria, tag, rango de caras, dimensiones
- **Ordenamiento**: Mas nuevos, mas descargados, mas grandes, mejor valorados
- **Historial de busqueda**: Persistido en localStorage
- **Nube de tags** con conteo
- **Paginacion** con "cargar mas"

### Visualizacion 3D (Three.js)
- **Viewer interactivo** multi-parte con controles orbitales
- **Modos de vista**: Solido, wireframe, ejes, bounding box
- **Vistas rapidas**: Frontal, superior, lateral, isometrica
- **Herramienta de medicion**: Click en dos puntos para distancia en mm
- **Corte transversal**: Plano de clipping con slider interactivo
- **Mapa de voladizos**: Heatmap de angulos de impresion (verde/amarillo/rojo)
- **Animacion de capas**: Simulacion de construccion capa por capa
- **Modo comparacion**: Abrir dos modelos lado a lado

### Social y organizacion
- **Valoraciones**: 1-5 estrellas con promedio calculado
- **Comentarios**: Con nombre de autor y fecha
- **Colecciones**: Crear listas y agregar/quitar modelos
- **QR Code**: Compartir modelo escaneando codigo
- **Descarga batch**: Seleccionar multiples modelos y descargar ZIP

### Analisis y validacion
- **Validacion de malla** (trimesh): Watertight, volumen, area, Euler, agujeros
- **Estimador de impresion**: Volumen, peso en gramos, costo y tiempo estimado
- **Thumbnails automaticos** generados server-side

### Infraestructura
- **Backup completo**: Endpoint que exporta DB + archivos + metadatos JSON como ZIP
- **Docker**: Dockerfile + docker-compose.yml listos
- **Tests automatizados**: 24 tests pytest (API + parsers)

## Stack tecnologico

- **Backend**: Python 3.12 + FastAPI + SQLAlchemy + SQLite + trimesh
- **Frontend**: HTML5 + Vanilla JS + Tailwind CSS (CDN) + Three.js r128
- **Procesamiento**: numpy + Pillow
- **Empaquetado**: uv (gestor de dependencias)

## Instalacion y uso

### Requisitos
- Python 3.12+
- `uv` instalado (`pip install uv` o ver https://docs.astral.sh/uv/)

### Iniciar servidor
```bash
cd /root/stl-repo
export PATH="$HOME/.local/bin:$PATH"
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

Abrir en navegador: `https://3d.consultoria-as.com` (o `http://localhost:8000` en desarrollo)

### Docker
```bash
docker-compose up --build
```

### Tests
```bash
uv run pytest tests/ -v
```

## Estructura del proyecto

```
app/
  main.py           # Punto de entrada FastAPI
  models.py         # Modelos SQLAlchemy (ORM)
  schemas.py        # Esquemas Pydantic
  database.py       # Conexion SQLite
  parsers.py        # Parser STL/3MF + generacion de thumbnails
  routers/
    models.py       # Endpoints principales (CRUD, busqueda, descargas, etc.)
  migrate.py        # Migraciones de DB
static/
  index.html        # Galeria
  upload.html       # Formulario de subida (archivos/URL/ZIP)
  detail.html       # Vista detalle con viewer 3D
  css/style.css
  js/
    app.js          # Logica de galeria
    upload.js       # Logica de subida
    detail.js       # Viewer 3D + herramientas avanzadas
    api.js          # Cliente HTTP
    theme.js        # Tema oscuro/claro
uploads/            # Archivos 3D subidos
thumbnails/         # Thumbnails PNG generados
images/             # Imagenes de referencia subidas
tests/
  test_api.py       # Tests de API (24 tests)
  test_parsers.py   # Tests de parsing y thumbnails
```

## API Endpoints principales

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | `/api/models/` | Listar modelos (con filtros y paginacion) |
| POST | `/api/models/` | Subir modelo nuevo |
| POST | `/api/models/import-url` | Importar desde URL |
| POST | `/api/models/bulk-zip` | Subir ZIP con multiples modelos |
| POST | `/api/models/batch-download` | Descargar seleccionados como ZIP |
| GET | `/api/models/{id}` | Detalle completo de modelo |
| PUT | `/api/models/{id}` | Actualizar metadatos |
| DELETE | `/api/models/{id}` | Eliminar modelo |
| GET | `/api/models/{id}/validate` | Validar malla (trimesh) |
| GET | `/api/models/{id}/estimate` | Estimar costo/tiempo de impresion |
| GET | `/api/models/{id}/download` | Descargar archivo principal |
| GET | `/api/models/{id}/download-all` | Descargar todas las partes en ZIP |
| GET | `/api/models/{id}/thumbnail` | Thumbnail PNG |
| GET | `/api/models/{id}/qr` | Codigo QR para compartir |
| POST | `/api/models/{id}/ratings` | Valorar modelo |
| POST | `/api/models/{id}/comments` | Comentar |
| GET | `/api/models/tags` | Listar tags con conteo |
| GET/POST | `/api/models/collections/...` | CRUD de colecciones |
| GET | `/api/models/system/backup` | Backup completo ZIP |

## Version

v2.2.0 — Abril 2026