Idol Image to 3D

Idol Image to 3D

Turns one picture of an object into a 3D Gaussian Splat you can rotate, zoom and download as a PLY file. For 3D creators and developers trying image-to-3D, with an API and MCP server.

Made by AmandaCat on Hugging Face. These notes are Mindket's, written from its Space page and README; the app's own files and license are on Hugging Face.

About

What it is: This Space turns one picture of a whole object into a 3D Gaussian Splat. You can rotate and zoom the result in the page and download it as a .ply file. It builds on the Idol models published by Comfy-Org and the official runtime from Speridlabs.

The download is a splat that carries color, scale, opacity and rotation for each point. It is not a polygon mesh.

Who it suits: It suits people who want a quick 3D model of an object from a single photo or render, and developers who want that step behind an API.

Industry | Who uses it | How they use it | Example
Games and 3D art | 3D artists | Make a first 3D view of an object from one image | An artist uploads a render of a prop and inspects the splat
Software | Developers | Call the generate endpoint or the MCP server from their own code | A developer wires the endpoint into a small tool
Research | Computer vision researchers | Try single-image 3D generation with the Idol models | A researcher compares results at two point counts
Education | Teachers and students | Show how one image can become a 3D scene | A class rotates a generated splat on screen

You can skip it if you need a polygon mesh or a true view of an object's hidden back side.

Where to use it: You use it in these places.

• A web browser, on the Space's page on Hugging Face, which runs on ZeroGPU
• A local copy on Windows, macOS or Linux, which needs Python 3.12
• Your own Space created from these files with ZeroGPU hardware
• Python code, through the Gradio API
• An MCP client, through the MCP server the app starts

Use case | Who | What they get back
Turn an image into 3D | Artists and developers | A .ply file with color, scale, opacity and rotation per point
Check what the model saw | Researchers | A preprocessing preview of the image the model received
Automate generation | Developers | A PLY path, the preprocessed image, the actual seed and metadata

How to set it up: Online use needs only a browser. A local copy or your own Space needs more.

• Python 3.12 and the packages in requirements.txt, for a local copy
• Room for about 4 GB of model files, downloaded on first start
• A Hugging Face account and ZeroGPU hardware, for your own Space
• No HF_TOKEN, since the public model files do not need one

1. Open the Space's page on Hugging Face to use it online, with nothing to install.
2. For a local copy, install the Hugging Face Hub package.
3. Download the Space's files into a folder and move into it.
4. Install Gradio 6.31.0 and the packages in requirements.txt.
5. Start the app. The first start downloads the models, the runtime code and four sample images.

pip install -U huggingface_hub
hf download AmandaCat/idol-image-to-3d --repo-type space --local-dir idol-image-to-3d
cd idol-image-to-3d
pip install gradio==6.31.0
pip install -r requirements.txt
python app.py

To deploy your own copy as a public ZeroGPU Space, the source gives these commands. Replace YOUR_USERNAME with your account name. Choose ZeroGPU in the Hugging Face hardware settings, because the README's hardware hint does not replace the real choice.

hf auth login
hf repos create YOUR_USERNAME/idol-image-to-3d --type space --space-sdk gradio --flavor zero-a10g --public
hf upload YOUR_USERNAME/idol-image-to-3d . --repo-type space --exclude '**/__pycache__/**'

How to use it: Upload a picture of a whole object, or click one of the official samples. A PNG keeps its transparency. Pick synthetic image or real photo, and keep the default settings at first. Click generate, then rotate and zoom the result on the right. Open the preprocessing preview to see the image the model received, and download the .ply.

The defaults are 50 steps, CFG 3, time shift 3 and 262,144 Gaussian points. Using 65,536 points suits a lighter download and preview.

Tool | What it does
/generate | The Gradio API endpoint. It returns the PLY path, the preprocessed image, the actual seed and the generation metadata.
view_api() | Shows the full list of API parameters
MCP server | Starts with the app. Its address is in the page's API information.

gradio_client.Client("YOUR_USERNAME/idol-image-to-3d").view_api()

Example: You upload a photo of a single object with its whole shape in view, keep the defaults and click generate. A 3D Gaussian Splat appears on the right, and you turn it around, check the preprocessing preview and download the .ply.

For newcomers and experts: A Gaussian Splat is a 3D scene made of many colored points, and you can view it from different angles. Try one of the official sample images first and rotate the result. The model guesses the back and any hidden parts, since one image cannot fix the true back shape.

Under the hood, four core files from Comfy-Org/Idol drive generation, image encoding, the image VAE and the 3D decoder. The config and an auxiliary BiRefNet come from speridlabs/idol. The weight adapter only adapts the wrapping, with strict checks on parameter names and shapes. It uses the SDK's rectified-flow Euler sampler, which differs from the ComfyUI template's sampler, so the same seed does not guarantee the same result.

Upload an image or pick a sample
The image is preprocessed
The model generates Gaussian points
You rotate and zoom the result
You download the .ply file

Good to know: The files stay on temporary storage, and the source asks you to check a deployed copy yourself.

• The source says model loading and real GPU generation still need verifying in a deployed Space.
• Files are kept only on the Space's temporary disk and Gradio's temporary cache, so download results soon after generating.
• License: apache-2. The source points to NOTICE.md and LICENSE.
• Cost to run: none named. Free ZeroGPU use does not need a dedicated GPU billed by the hour, and quota depends on the account.
• Data it reaches: the models and runtime code it downloads from Hugging Face. The source says images are not forwarded to external inference APIs or committed to model repos.
• Not for: polygon mesh output, since the result is a Gaussian Splat.

On Hugging Face, 13 November 2026

• Likes: 2
• Built with: gradio
• License: apache-2.0

Links

• Space: https://huggingface.co/spaces/AmandaCat/idol-image-to-3d
• Files: https://huggingface.co/spaces/AmandaCat/idol-image-to-3d/tree/main

Try it

Open the Space in your browser, or copy it to your own Hugging Face account from its page. Nothing in this kit runs by itself.