关键字 · OBJECT
One photo in, a 3D object out: the open-source project Idol turns a single picture into a Gaussian splat you can spin
Idol is open source: upload one photo and get a 3D object you can turn and view from every side. Try it free in your browser, then run it on your GPU.
Take one photo of a mug, a toy or a houseplant and get back a 3D object you can turn around and look at from every side, even the back the camera never saw. That's Idol, an open-source project from Speridlabs, released under the Apache-2.0 license. This guide shows you how to try it free in your browser first (nothing to install), then how to run it on your own computer with the exact commands from the README. You don't need to know anything about 3D. If you can upload a picture, you can do this.
01What you get: what Idol does with your picture
You can give Idol a photo, a render or a generated image. It does three things on its own:
- It removes the background, using a model called BiRefNet to cut the object out;
- It frames the object, cropping and placing it, and saves that prepared picture so you can check it;
- It fills in the sides you can't see: the back, the underside and hidden corners, so you get a whole object.
The result is a 3D Gaussian splat (3DGS), saved as a standard .ply file with 32,768 to 1,048,576 Gaussians (262,144 by default). Gaussians are lots of small soft blobs, and more of them means more detail. Any Gaussian splat viewer can open it. The README says it peaks at about 7.2 GB of video memory, so a consumer graphics card is enough.
02Try it in your browser first (no install)
- Open the demo on Hugging Face. A backpack example is already loaded. Drag inside the viewer on the right to spin it;
- Click Input image and upload your own picture. One object per picture works best, and you don't need to remove the background;
- Under Input type, pick Real photo for a camera or phone picture, or Synthetic for a computer-generated image;
- Press Generate, then spin your object. To tweak things, open Settings to change the number of Gaussians, steps or seed, or tick Random seed.
03Run it on your own computer
You need an NVIDIA graphics card, Python 3.10 or newer, and PyTorch 2.5 or newer.
- Download the idol-sdk code from GitHub and open a terminal in its folder;
- Run the install commands below;
- Sign in to Hugging Face and request access to the two gated models: facebook/dinov3-vith16plus-pretrain-lvd1689m and black-forest-labs/FLUX.2-dev;
- Run hf auth login in the terminal. The weights download on first use, so the first run takes longer;
- Run one of the commands below on your picture, then open the .ply it writes in a Gaussian splat viewer.
pip install -e . # Python >= 3.10, PyTorch >= 2.5 pip install -e ".[demo]" # + Gradio, to run the demo locally
python -m idol.sample --image photo.jpg --mode real python -m idol.sample --image renders/ --mode synthetic --out outputs
Each image gives you three files: <name>.ply (the 3D model), <name>_input.png (what the model actually saw; look here first if a result looks odd) and <name>_camera.json (where Idol thinks the photo was taken from). Handy flags: --seed (default 42; same seed, same object), --num_gaussians (default 262144, must be a multiple of 32) and --steps (default 50).
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")
output.preprocessed_image.save("photo_input.png")
04Which graphics card do you need?
From the README's timing table (262,144 Gaussians, 50 steps): an RTX 4090 takes about 19.1 seconds, an RTX 5090 about 14.1 seconds, a 10 GB RTX 3080 about 46.2 seconds and an H100 about 6.7 seconds. The peak is about 7.2 GB of video memory, so a 10 GB card is enough.
05Links
Sources
What is the next useful tool?
Every video has a full guide. Follow @serrinion to see new ones first.