stl-repo/README.md

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

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

docker-compose up --build

Tests

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