Idol: el modelo open source que convierte una sola imagen en un objeto 3D (Gaussian Splatting) en tu GPU

Idol es un modelo open source que convierte una sola imagen de un objeto en un modelo 3D formado por *Gaussian splats*. Le das un render, una imagen generada con IA o una foto de producto; quita el fondo, encuadra el objeto y genera hasta 1.048.576 gaussianas, incluidas las caras que la imagen nunca mostró. Funciona en tu propia GPU, con un pico de 7,2 GB de VRAM, y el código y los pesos se publican bajo Apache-2.0.

En este análisis leemos el código del SDK (speridlabs/idol-sdk, versión 0.1.0, publicado el 29 de octubre de 2026) para contarte qué hace en cada paso, qué GPU necesitas de verdad, cómo instalarlo y usarlo desde la línea de comandos o desde Python, y qué letra pequeña tienen las licencias de los modelos de los que depende. Es para ti si haces tiendas online, webs 3D, prototipos de videojuegos o simplemente quieres dejar de pagar por modelo en servicios de imagen a 3D.

Qué es Idol y quién lo hace

• Repositorio: github.com/speridlabs/idol-sdk
• Pesos: speridlabs/idol en Hugging Face, unos 3 GB.
• Demo en línea: un Space de Hugging Face con 93 ejemplos listos y la opción de subir tu imagen.
• Autor: Speridlabs (speridlabs.com).
• Versión analizada: 0.1.0, el commit inicial del repositorio. El proyecto tiene un día de vida pública.
• Licencia: Apache-2.0 para el código y para los pesos de Idol. Las dependencias tienen las suyas (lo vemos más abajo).
• Base: el propio README dice que Idol parte de TripoSplat, de VAST AI Research.

Qué es un Gaussian splat (en dos párrafos)

Un modelo 3D clásico es una malla: triángulos con una textura encima. Un Gaussian splat (3DGS) es otra cosa: una nube de cientos de miles de "manchas" elipsoidales, cada una con su posición, tamaño, rotación, color y opacidad. Al dibujarlas superpuestas desde cualquier ángulo dan un resultado muy fotográfico, con reflejos y bordes suaves que a una malla le cuestan mucho.

La pega es que un splat no es una malla. Se ve muy bien en un visor web o en un motor que lo soporte, pero no lo puedes imprimir en 3D, ni riggear para animarlo, ni meterlo tal cual en la mayoría de pipelines de videojuegos. Tenlo presente antes de elegir Idol para tu caso.

Cómo funciona por dentro

El archivo clave es idol/pipeline.py. Cada vez que llamas al modelo pasa esto:

1. Preparar la imagen (preprocess.py). Si la imagen no trae canal alfa, BiRefNet quita el fondo. Luego erosiona el borde 1 px para que no quede halo, recorta un cuadrado alrededor del objeto y lo escala a 1024 × 1024 sobre negro. El margen del recorte depende del modo: 1,2 para imágenes sintéticas y 1,7 para fotos reales.
2. Codificar (conditioning.py). Dos codificadores de imagen convierten ese cuadrado en tokens: DINOv3 ViT-H+ (840 millones de parámetros) y la VAE de FLUX.2.
3. Muestrear (sampler.py). Un transformer de difusión (DiT) de 370 millones de parámetros parte de ruido y, en 50 pasos de Euler con *classifier-free guidance* 3,0, llega a un latente de 8192 × 16 más una predicción de la cámara desde la que se hizo la foto.
4. Colocar anclas. Un decodificador octree reparte N ÷ 32 puntos de anclaje dentro de un cubo de lado 1.
5. Generar gaussianas. Un segundo decodificador convierte cada ancla en 32 gaussianas con color, escala, rotación y opacidad.
6. Guardar. Escribe un .ply en el formato estándar de 3DGS (girado de z-arriba a y-arriba, que es lo que esperan los visores), la imagen recortada que vio el modelo y un JSON con la cámara estimada (yaw, pitch, radio y campo de visión).

Lo interesante es el paso 3: el modelo inventa las partes ocultas a partir de lo que ha aprendido de miles de objetos. En la galería oficial se ve bien con el ajolote, del que solo se ve el frente:

La espalda y la cola son coherentes con el frente, pero se nota que tienen menos detalle que la cara visible. Es lo esperable en cualquier modelo de una sola imagen.

Qué GPU necesitas

El README da tiempos medidos con el mismo código en distintas GPU, una imagen a 262.144 gaussianas y 50 pasos:

Tres cosas que salen del código y no están tan a la vista en el README:

• Solo CUDA o CPU. pipeline.py elige cuda si existe y si no cpu; no hay soporte para Apple Silicon (MPS). En CPU las optimizaciones se desactivan y el README no da tiempos, así que cuenta con que sea muy lento.
• La primera imagen tarda más. Con la optimización activada (por defecto en GPU), la primera generación de cada proceso compila el modelo con torch.compile. Si vas a procesar muchas imágenes, pásale una carpeta en una sola ejecución en lugar de lanzar el comando una vez por imagen.
• Más gaussianas no cuesta mucho más. El número de gaussianas solo afecta a los decodificadores (pasos 4 y 5); el muestreo, que es lo caro, es igual. Lo que crece es el tamaño del .ply.

Con 10 GB de VRAM (una RTX 3080) entra, porque el pico medido es de 7,2 GB. Con 8 GB irás muy justo.

Instalar Idol paso a paso

Necesitas Python 3.10 o superior, PyTorch 2.5 o superior con CUDA y una cuenta de Hugging Face.

1. Pide acceso a los dos codificadores

Los pesos de Idol son públicos, pero dos de las piezas que usa están detrás de una aceptación de condiciones en Hugging Face. Entra con tu cuenta y acepta los términos en:

• facebook/dinov3-vith16plus-pretrain-lvd1689m (DINOv3)
• black-forest-labs/FLUX.2-dev (de aquí solo descarga la VAE)

La aprobación puede tardar. Mientras tanto, crea un token de lectura en tu cuenta de Hugging Face.

2. Clona e instala

git clone https://github.com/speridlabs/idol-sdk.git
cd idol-sdk
python -m venv .venv
source .venv/bin/activate        # en Windows: .venv\Scripts\activate
pip install -e .
hf auth login                    # pega tu token

Si quieres la interfaz web de la demo en local, instala también el extra: pip install -e ".[demo]". Si tienes flash-attn instalado, Idol lo usa; si no, usa la atención nativa de PyTorch (mismo resultado, algo más lento). Lo puedes forzar con ATTN_BACKEND=sdpa o ATTN_BACKEND=flash_attn.

3. Genera tu primer objeto

python -m idol.sample --image foto.jpg --mode real
python -m idol.sample --image renders/ --mode synthetic --out salida

La primera ejecución descarga unos 3 GB de pesos de Idol más los dos codificadores. Por cada imagen obtienes nombre.ply, nombre_input.png y nombre_camera.json en la carpeta de salida (por defecto outputs).

Elige bien el modo: synthetic (el valor por defecto) es para renders e imágenes generadas con IA de un solo objeto; real es para fotos hechas con cámara o móvil. Lo único que cambia es el margen del recorte, pero se nota.

Opciones útiles

Usarlo desde Python

from idol import IdolPipeline

pipeline = IdolPipeline.from_pretrained("speridlabs/idol")
salida = pipeline("foto.jpg", mode="real", seed=42, num_gaussians=1_048_576)
salida.gaussian.save_ply("foto.ply")
salida.preprocessed_image.save("foto_input.png")
print(salida.camera)  # yaw, pitch, radius, fov

Si ya tienes el objeto recortado en un PNG con transparencia, Idol detecta el canal alfa y se salta BiRefNet. Si te falta ese paso, puedes quitar el fondo antes en el navegador con BG0, un quitafondos open source que no sube tu imagen.

Dónde ver y usar el .ply

El .ply sigue el formato estándar de 3D Gaussian Splatting, así que lo abre cualquier visor de splats: SuperSplat (de PlayCanvas, en el navegador) es la forma más rápida de comprobar el resultado. Para meterlo en una web hay librerías de splats para three.js y motores como PlayCanvas que los soportan.

Si lo que quieres es una web 3D con objetos generados por IA, compáralo con Dioramas, el framework para webs 3D con three.js: Dioramas genera mallas GLB con Meshy, a unos 1,20 USD por modelo; Idol genera splats gratis en tu máquina. Mallas si necesitas iluminación y sombras dinámicas, imprimir o animar; splats si buscas un aspecto fotográfico y el objeto va a estar quieto.

Cómo queda frente a otros modelos

Speridlabs publica una comparativa con TripoSplat, TRELLIS y LGM, evaluados en una H100. Resumen con las métricas más fáciles de leer:

Idol gana en casi todas las columnas, y es un 30 % más rápido que TripoSplat, el modelo del que parte. Dos matices: la tabla es del propio autor, sin una evaluación independiente todavía, y no dice sobre qué conjunto de imágenes se midió. LGM es mucho más rápido pero sus resultados son claramente más borrosos.

Licencias: lo que tienes que revisar antes de usarlo en un negocio

En codigoagente solemos cubrir proyectos MIT; Idol usa Apache-2.0, que es igual de permisiva para el uso comercial y además incluye una concesión explícita de patentes. Puedes usarlo, modificarlo y venderlo, conservando el aviso de licencia y de cambios.

El matiz está en las dos piezas de terceros que descarga en cada ejecución:

• DINOv3 tiene su propia licencia de Meta. Permite usar, modificar y redistribuir, pero si redistribuyes el modelo (por ejemplo, empaquetado dentro de tu producto) tienes que incluir la licencia y mostrar "Built with DINOv3" en la documentación o la web del producto. También prohíbe usos militares y de armamento.
• La VAE de FLUX.2. Black Forest Labs publicó la VAE de FLUX.2 bajo Apache-2.0, pero Idol la descarga del repositorio FLUX.2-dev, que está protegido y tiene su propia licencia. Para descargarla tienes que aceptar esos términos. Si vas a montar un servicio comercial, lee la licencia de ese repositorio y comprueba si te cubre o si te conviene apuntar a una copia de la VAE publicada bajo Apache-2.0 (la opción --weights te deja cargar los pesos de Idol desde una carpeta local, pero los codificadores se descargan de los repositorios indicados en su config.json).

Los objetos que generas no tienen restricciones de Idol. Si la imagen de entrada es de otra persona (la foto de un producto de un tercero, un personaje con derechos), el problema de derechos sigue siendo tuyo.

Lo que no probamos y por qué

No hemos ejecutado Idol para este artículo: necesita una GPU NVIDIA con al menos unos 8-10 GB libres y acceso a los repositorios protegidos de Hugging Face, y nuestro entorno de pruebas no tiene ninguna de las dos cosas. Todo lo anterior sale de leer el código del SDK línea a línea y del README. Las imágenes del objeto 3D son de la galería oficial del repositorio, con crédito.

Si lo pruebas en tu equipo, la forma más rápida de saber si te sirve es el Space de Hugging Face: sube la foto de un producto tuyo, gira el resultado y fíjate en la parte de atrás.

Errores frecuentes

• Idol needs two image encoders that are downloaded from Hugging Face: no has aceptado los términos de DINOv3 o de FLUX.2-dev, o no has iniciado sesión. Acepta en las dos páginas y ejecuta hf auth login. Si ya aceptaste, comprueba con hf auth whoami que el token es de esa misma cuenta.
• Your Hugging Face account does not have access yet: aceptaste pero la aprobación está pendiente. Espera y vuelve a probar.
• no object found in the image (the alpha channel is empty): BiRefNet no encontró ningún objeto, o tu PNG tiene un canal alfa totalmente transparente. Usa una imagen con un objeto claro y fondo distinguible, o quita el canal alfa.
• La primera imagen tarda mucho y las demás no: es la compilación de torch.compile. Normal. Desactívala con --no_optimize si solo vas a generar una imagen.
• El objeto sale cortado o muy pequeño: cambia el --mode o ajusta --crop_margin (más alto, más aire alrededor).
• La parte trasera es rara: prueba otras semillas con --seed. Cada semilla da una "interpretación" distinta de lo que no se ve.

Preguntas frecuentes

¿Idol es gratis? Sí. El código y los pesos son Apache-2.0 y se ejecutan en tu GPU. No hay pago por modelo ni cuenta en ningún servicio, aparte de la cuenta gratuita de Hugging Face para descargar los codificadores.

¿Funciona en Mac? No con aceleración. El código solo usa CUDA o CPU; Apple Silicon no está soportado.

¿Genera mallas para imprimir en 3D o para Unity y Unreal? No directamente. Genera Gaussian splats en .ply. Para una malla tendrías que convertirlo con otra herramienta o usar un modelo de imagen a malla.

¿Puedo usar fotos hechas con el móvil? Sí, con --mode real. Mejor con un solo objeto, bien iluminado y entero dentro del encuadre.

¿Puedo usar los objetos en un producto comercial? Idol no lo impide. Revisa las licencias de DINOv3 y de FLUX.2-dev si vas a redistribuir los modelos o montar un servicio, y los derechos de la imagen de entrada.

¿Cuánto ocupa un objeto? Depende del número de gaussianas: cada una son 17 valores de 4 bytes en el .ply, así que 262.144 gaussianas rondan los 18 MB y 1.048.576 unos 71 MB, sin comprimir.

Conclusión

Idol hace en tu propia GPU, en 14-46 segundos con una tarjeta de consumo y sin pagar por modelo, lo que hasta ahora te cobraban los servicios de imagen a 3D: pasar de una foto a un objeto que puedes girar. Su límite es el formato, splats en vez de mallas, y la letra pequeña de los dos codificadores de terceros. Si tienes una NVIDIA de 10 GB o más, el siguiente paso es acceder a los dos repositorios de Hugging Face, instalarlo con pip install -e . y probar con la foto de un producto tuyo en modo real.