Idol by speridlabs

Idol by speridlabs

Turns one picture of an object into a 3D Gaussian splat, building the hidden sides too. Made for artists, researchers and developers who want a 3D file from a render, a generated image or a photo.

Made by speridlabs on Hugging Face. These notes are Mindket's, written from its model page and model card; the model's own files and license are on Hugging Face.

About

What it is: Idol builds a 3D Gaussian splat from a single picture of an object. The picture can be a render, an AI-generated image or a photo. The model also fills in the hidden sides, and it saves as many as 1,048,576 Gaussians as a standard 3DGS .ply file.

A consumer GPU is enough. Peak VRAM use is 7.2 GB, and one run can finish in under 2 seconds.

Who it suits: Idol suits people who want a quick 3D version of a single object from one image. That covers 3D artists, game makers, researchers working on 3D generation and developers who want splat files from a Python script.

Industry | Who uses it | How they use it | Example
Games and 3D art | Artists and indie developers | Turn concept art or a generated image into a splat | An armchair render becomes a splat that a viewer can open
Research | Researchers in 3D generation | Run the model on test images and tune the sampling flags | Run a photo at the default 50 steps, then with fewer steps, and compare detail
Product visuals | Designers and small shops | Turn a photo of an item into a 3D object | A photograph of a lamp run in real mode
Software | Developers | Call the pipeline from a script and save a splat file | Save photo.ply from photo.jpg in a few lines of Python

You can skip it if your subject is a whole scene rather than one object, or if you have no NVIDIA GPU with CUDA.

Where to use it:

• Command line: python -m idol.sample on one image or a folder of images
• Python: the IdolPipeline class inside your own scripts
• Hugging Face demo: a hosted demo Space for trying an image first
• Gaussian splat viewers: any viewer can open the saved ply file

Use case | Who | What they get back
Single render to 3D | 3D artists | A ply splat of the object and the cropped input image
Photo to 3D | Anyone with a photo of an object | A ply splat and a json file with the camera Idol predicts for the photo
Folder of images | Developers and researchers | One set of output files per image, saved to the folder you name

How to set it up: What you need first:

• A Hugging Face account that has accepted the terms of two gated models: facebook/dinov3-vith16plus-pretrain-lvd1689m and black-forest-labs/FLUX.2-dev
• Python 3.10 or newer with PyTorch 2.5 or newer
• An NVIDIA GPU with CUDA and about 7.2 GB of VRAM at peak
• Disk room for the weights, about 3 GB, plus the two encoders

1. Accept the terms of both gated models with your Hugging Face account.
2. Authenticate by running hf auth login once, or put your token in HF_TOKEN.
3. Clone the idol-sdk code repository from the speridlabs GitHub account, then install it with pip.
4. Run the sample command on an image. The first run downloads the weights and both encoders on its own.

hf auth login

cd idol-sdk
pip install -e .          # Python 3.10+, PyTorch 2.5+, an NVIDIA GPU with CUDA

How to use it: Run the sample command with an image and a mode. Each image gives you a ply file, the cropped input image and a camera json file. Open the ply file in a Gaussian splat viewer.

python -m idol.sample --image photo.jpg --mode real
python -m idol.sample --image renders/ --mode synthetic --out outputs

From Python, the same job looks like this.

from idol import IdolPipeline

pipeline = IdolPipeline.from_pretrained("speridlabs/idol")
output = pipeline("photo.jpg", mode="real", seed=42, num_gaussians=1_048_576)
output.gaussian.save_ply("photo.ply")

Tool | What it does
--mode | synthetic is the default and suits renders and generated images. real suits photographs and leaves more room around the object.
--seed | Reuse the same value to repeat an object. The default is 42.
--steps | Sets the sampling steps, 50 by default. Fewer steps run faster and lose some detail.
--cfg_strength | Controls how closely the object sticks to the image. The default is 3.0.
--rescale_t | Higher values give the overall shape more steps, lower values give fine detail more steps. The default is 3.0.
--num_gaussians | Sets how many Gaussians to make, from 32,768 to 1,048,576 in multiples of 32. The default is 262144.
--dinov3_dtype | Setting it to fp32 runs the DINOv3 encoder at full precision and costs 1.7 GB of extra memory.
--weights | Names the weights to load, either a repo on Hugging Face or a folder on your disk.
--no_optimize | Turns off the faster sampling.

Example: Take one photo of a lamp, save it as photo.jpg and run the first command above. Idol cuts out the background, crops around the lamp and writes photo.ply, which a Gaussian splat viewer can open. You also get the cropped input image and a camera file.

For newcomers and experts: Start with one photo of a single object. Run the first command with the real mode, then open the ply file in a splat viewer. A different seed gives a different version of the object, so try a few.

A full request holds about 1.80B parameters across a DiT denoiser, an octree decoder, a Gaussian decoder, BiRefNet for background removal and two image encoders. Most blocks run in FP16 or bf16, with some FP32. On GPU the faster sampling is already on, and it speeds sampling up by about 1.7x with no change in output quality. It compiles the denoiser with torch.compile, runs the guided and unguided passes as one batch, and uses cuDNN attention with TF32 matmuls.

Input image of one object
Remove the background and crop
Encode with DINOv3 and the FLUX.2 VAE
Sample the Gaussians with the denoiser and decoders
Save a ply file

Good to know:

• It needs an NVIDIA GPU with CUDA, Python 3.10 or newer and PyTorch 2.5 or newer.
• The two encoder models are gated. With no access yet, Idol halts before any download and names what is missing.
• The first run pulls about 3 GB of weights, plus both encoders, into your Hugging Face cache.
• Within one process, the first image is slower because the denoiser has to compile.
• Peak VRAM use is 7.2 GB, and DINOv3 in fp32 adds 1.7 GB.
• Defaults are 50 steps, seed 42 and 262144 Gaussians.
• Each image is treated as one object. Pick synthetic mode for renders and real mode for photographs.
• License: apache-2.0.

Title: Parameters in each part of Idol
DiT denoiser: 370.6 million
Octree decoder: 50.8 million
Gaussian decoder: 237.3 million
BiRefNet: 220.7 million
DINOv3 ViT-H+/16: 840.6 million
FLUX.2 VAE: 84.1 million

On Hugging Face, 10 November 2026

• Task: image to 3d
• Library: idol
• Downloads in the last 30 days: 24,747
• Likes: 1,664
• License: apache-2.0
• Quantized versions: 5
• Fine-tunes: 6
• Tags: idol, gaussian-splatting, 3d, image-to-3d

Links

• Model: https://huggingface.co/speridlabs/idol
• Files: https://huggingface.co/speridlabs/idol/tree/main

Get the model

Download its files with Hugging Face's command line:

pip install -U huggingface_hub
hf download speridlabs/idol

Then follow the usage in its model card. Nothing in this kit runs by itself.