Skip to content
ahuertamPublic

About

Convierte una imagen en un mundo 3D interactivo: Gaussian Splat + modelo GLB en paralelo. React 19 + React Three Fiber + Three.js + Express 5

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

21 Commits

Folders and files

Repository files navigation

ImageTron logo

ImageTron

Sube una imagen y conviértela automáticamente en un mundo 3D interactivo: un entorno navegable como Gaussian Splat (.spz) generado por World Labs, más un modelo 3D del objeto (.glb) generado por el proveedor que elijas.

Stack Stack CI Licencia

💡 ¿Cómo funciona por dentro? En FAQ.md explico paso a paso cómo monta la escena React Three Fiber, el flujo de SSE, el sistema de caché por hash y las decisiones de diseño. El detalle técnico (tipos, endpoints, particularidades de SparkRenderer) está en docs/ARCHITECTURE.md.

▶️ Probarlo

Demo de ImageTron: una imagen se convierte en un mundo 3D

El flujo real de la app: la imagen entra por el drop zone, el backend lanza los dos jobs en paralelo y el progreso llega por SSE. El entorno 3D es un Gaussian Splat generado por World Labs. El segundo job —el modelo del objeto (.glb)— necesita la API key de su proveedor, por eso en el GIF aparece en rojo.

No hay demo hospedada — cada proveedor de modelos 3D necesita sus propias credenciales. Para levantarlo en local:

./start.sh

Con Local TRELLIS self-hosted no hace falta API key para el modelo 3D, pero el entorno (.spz) lo genera siempre World Labs, así que sí necesitas WORLD_LABS_API_KEY.

La escena 3D que genera World Labs a partir de la imagen del GIF:

Escena 3D: entorno Gaussian Splat generado por World Labs


Cómo funciona

  1. Subes una imagen desde el navegador y eliges el proveedor de modelo 3D
  2. El backend lanza dos jobs en paralelo:
    • World Labs → genera el entorno 3D completo como Gaussian Splat (.spz)
    • Proveedor de modelo → genera el objeto 3D (.glb) con el proveedor elegido
  3. El frontend muestra el progreso en tiempo real vía Server-Sent Events
  4. En cuanto cada asset está listo, aparece en la escena 3D — sin esperar al otro
  5. Cuando ambos terminan, la escena ocupa toda la pantalla con OrbitControls para rotar y explorar
  6. Si subes la misma imagen otra vez, los assets se sirven desde caché local — sin rellamar a las APIs

Caché por hash de imagen

Cada imagen genera un hash SHA-256 (16 chars) que es el nombre de la carpeta de caché. El ID del job añade el provider (<hash>-<provider>), porque la misma imagen con otro provider es otro job:

backend/outputs/
└── acf548744b89fc02/
    ├── source.jpeg            ← imagen original (la extensión sale del mimeType)
    ├── environment.spz        ← entorno World Labs (se comparte entre providers)
    ├── model.meshy.glb        ← modelo 3D de Meshy (uno por provider)
    ├── model.tripo.glb        ← modelo 3D de Tripo
    └── metadata.json          ← assets y providers que han generado cada asset
  • Misma imagen + mismo provider → ambos assets desde caché, instantáneo
  • Misma imagen + distinto provider → reutiliza el .spz, regenera solo el .glb de ese provider
  • Imagen nueva → genera todo y lo guarda

Proveedores de modelo 3D

Proveedor Estado Velocidad Registro
Local TRELLIS ✅ Gratis (self-hosted) Depende del hardware —
Meshy ❌ API de pago ~60 s meshy.ai
Replicate TRELLIS ⚠️ Requiere billing ~25 s replicate.com/account/api-tokens
Tripo3D ❌ Free wallet no sirve para API ~30 s platform.tripo3d.ai
Stable Fast 3D ❌ Créditos agotados rápido < 1 s platform.stability.ai
FAL Hunyuan3D ❌ De pago ~2 min fal.ai

El entorno World Labs (.spz) siempre se genera independientemente del proveedor elegido y funciona correctamente.

Nota sobre Replicate: los tokens de sesión que genera el dashboard expiran en horas. Para uso en la app crea un token permanente en replicate.com/account/api-tokens.


Local TRELLIS (servidor propio)

Puedes montar TRELLIS en una máquina con GPU y apuntar la app a ella — sin coste por llamada a API.

Contrato REST esperado

El backend envía POST /predictions con la imagen en base64:

{ "image": "data:image/jpeg;base64,..." }

El servidor puede responder de dos formas:

Síncrona (resultado inmediato):

{ "output": "http://tu-servidor/model.glb" }

o

{ "glb_url": "http://tu-servidor/model.glb" }

Asíncrona (procesamiento en background, polling cada 3 s):

// POST /predictions → devuelve id
{ "id": "abc123", "status": "processing" }

// GET /predictions/abc123
{ "status": "succeeded", "output": "http://tu-servidor/model.glb" }

El campo output puede ser string o array de strings — se elige automáticamente el primer .glb.

Configurar la URL en la UI

Selecciona Local TRELLIS en el selector de provider y aparece un campo de texto donde puedes cambiar la URL (por defecto http://localhost:8000). La URL se envía al backend en cada petición, no hace falta reiniciar nada.


Requisitos

  • Node.js 18.17+ para la app (sharp no baja de ahí) y 20.6+ para npm test (node --import). Recomendado: Node 22, la versión que usa CI
  • API keys en backend/.env

Instalación y arranque

Un solo comando instala todo y levanta ambos servidores:

./start.sh

Importante: después de editar .env reinicia los servidores — tsx watch recarga el código pero no las variables de entorno.


Configuración de API keys

Edita backend/.env:

WORLD_LABS_API_KEY=      # worldlabs.ai → API settings
FAL_KEY=                 # fal.ai/dashboard → API keys
TRIPO_API_KEY=           # platform.tripo3d.ai → API keys
STABILITY_API_KEY=       # platform.stability.ai → API keys
REPLICATE_API_TOKEN=     # replicate.com/account/api-tokens (token permanente, no de sesión)
MESHY_API_KEY=           # meshy.ai → requiere plan de pago
PORT=3001

Solo necesitas las keys de los proveedores que vayas a usar. Si una key está vacía, ese proveedor falla con un error claro en la UI. Local TRELLIS no necesita key para el modelo 3D, pero World Labs siempre necesita la suya para el entorno.

Límites (para que nadie te vacíe la cuota)

Cada generación llama a World Labs y a un proveedor de pago, así que el backend se protege solo:

Env Por defecto Qué hace
RATE_LIMIT_MAX 10 subidas por IP cada 10 min (429 al superarlas)
MAX_ACTIVE_JOBS 4 generaciones simultáneas (503 al superarlas)
OUTPUTS_DIR backend/outputs raíz de la caché en disco

Si lo expones a internet, ponlo detrás de algo que autentique (Cloudflare Access, un proxy con Basic Auth…). La API no tiene autenticación propia: una SPA de navegador no puede guardar un secreto, así que el límite por IP es lo que protege tu cuota. Con un proxy delante, el problema desaparece.


Stack técnico

Backend — Express 5 + TypeScript

  • POST /api/generate — recibe imagen, calcula hash, comprueba caché, lanza jobs en paralelo (con rate limit por IP y tope de jobs simultáneos)
  • GET /api/status/:jobId — Server-Sent Events con progreso en tiempo real
  • GET /api/assets/:jobId/spz|glb — sirve assets desde buffer en memoria (sin CORS)
  • Las imágenes se ajustan a un máximo de 1024×1024 px (conservando la relación de aspecto) sólo si superan 1 MP; por debajo de ese tamaño se envían sin modificar (usando sharp). La API de World Labs recibe la imagen original sin redimensionar
  • La URL del servidor TRELLIS local se valida antes de pedirla (esquema y rangos link-local bloqueados, y cada redirección se revalida) para que el backend no se convierta en un proxy hacia la red interna

Frontend — Vite + React 19 + TypeScript + Tailwind CSS

  • useJobSSE — hook que abre un EventSource y actualiza el estado reactivamente
  • SplatEnvironment — renderiza el .spz con @sparkjsdev/spark (integración imperativa en R3F, rotación X corregida para World Labs)
  • GlbObject — carga el .glb con useGLTF y lo auto-centra/escala en la escena
  • Viewer3D — Canvas de React Three Fiber con OrbitControls

Estructura del proyecto

imageTron/
├── start.sh                     ← instala todo y arranca ambos servidores
├── docs/
│   ├── ARCHITECTURE.md          ← arquitectura, tipos, flujo SSE, particularidades de Spark
│   ├── demo.gif                 ← demo del flujo (imagen → mundo 3D)
│   └── scene-3d.jpg             ← captura de la escena 3D generada
├── backend/
│   ├── .env                     ← tus API keys (no en git)
│   ├── .env.example             ← plantilla
│   ├── outputs/                 ← assets generados, organizados por hash de imagen (no en git)
│   ├── test/
│   │   ├── outputStore.test.ts  ← tests de hash y caché (node --test)
│   │   ├── jobStore.test.ts     ← tests del estado de job y del evento SSE
│   │   ├── rateLimit.test.ts    ← tests del límite por IP
│   │   └── safeUrl.test.ts      ← tests de la validación de URL (SSRF)
│   └── src/
│       ├── index.ts
│       ├── types.ts
│       ├── routes/
│       │   ├── generate.ts      ← POST /api/generate (hash + caché + dispatch)
│       │   ├── status.ts        ← GET  /api/status/:jobId (SSE)
│       │   └── assets.ts        ← GET  /api/assets/:jobId/:type
│       └── services/
│           ├── jobStore.ts      ← estado en memoria + broadcast SSE (con TTL y topes)
│           ├── outputStore.ts   ← caché en disco (hash → carpeta, .glb por provider)
│           ├── rateLimit.ts     ← límite de subidas por IP
│           ├── safeUrl.ts       ← validación de URL (anti-SSRF)
│           ├── imageResize.ts   ← ajusta a máx. 1024×1024 (fit inside) si supera 1 MP
│           ├── worldLabs.ts     ← World Labs API + polling 15s
│           ├── falApi.ts        ← FAL queue API + polling 10s
│           ├── tripoApi.ts      ← Tripo3D API + polling 10s
│           ├── stabilityApi.ts  ← Stability AI (respuesta directa)
│           ├── replicateApi.ts  ← Replicate TRELLIS + polling 5s
│           ├── meshyApi.ts      ← Meshy API + polling 8s
│           └── localTrellisApi.ts ← TRELLIS self-hosted + polling 3s
└── frontend/
    ├── public/
    │   └── terminator2.png      ← logo (servido por Vite desde frontend/public)
    └── src/
        ├── App.tsx
        ├── types.ts
        ├── hooks/
        │   ├── useJobSSE.ts
        │   └── useImageUpload.ts
        ├── components/
        │   ├── UploadZone.tsx       ← drag-drop + selector de provider + URL campo local
        │   ├── ProgressPanel.tsx    ← barras de progreso en tiempo real
        │   └── Viewer3D.tsx         ← canvas 3D
        └── three/
            ├── SplatEnvironment.tsx ← Gaussian splat (Y-flip corregido)
            └── GlbObject.tsx        ← modelo GLB auto-centrado

📄 Licencia

MIT. Ver LICENSE.

👤 Autor

Alejandro Huerta — Senior Frontend / Tools Engineer. Madrid (remoto). github.com/ahuertam · linkedin.com/in/alejandrohuertaengineer

About

Convierte una imagen en un mundo 3D interactivo: Gaussian Splat + modelo GLB en paralelo. React 19 + React Three Fiber + Three.js + Express 5

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages