Idol-GGUF

Idol-GGUF

An 8-bit GGUF build of SperiD Labs' Idol that turns one image into a 3D Gaussian point cloud and a mesh, run locally with idol.cpp. For developers working on image to 3D.

Made by TimeLordRaps 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-GGUF is an 8-bit, mixed-precision GGUF build of Idol from SperiD Labs. Idol turns one picture into a 3D shape stored as a cloud of Gaussian points. A single 967 MB file packs four of Idol's parts. The idol.cpp runtime then offers a local server, a web page on your own machine and a mesh extraction tool.

Who it suits: Developers and researchers who want to turn single images into 3D shapes on their own machine. Memory use is a main concern here, and the build offers a staged mode and a lean mode for smaller setups.

Industry | Who uses it | How they use it | Example
3D and graphics | Graphics developers | Reconstruct a 3D shape from one photo and extract a mesh | Upload an object photo and inspect the point cloud in the browser
Research | Image to 3D researchers | Compare this quantized build against original Idol | Check mesh distance on a test set of household objects
Tooling | Developers of local AI apps | Call the model through the server's HTTP interface | Send an image to the local server from another program
Game prototyping | Prototype artists | Get a rough untextured mesh from a single picture | Extract a mesh and open it in a 3D tool

You can skip it if you want to start from a text prompt alone. Idol accepts images, not text.

Where to use it:

• Windows, macOS and Linux with Python, through idol.cpp
• A browser interface served from your own computer
• The command line, using the generate script
• Programs that call the local server over HTTP

Use case | Who | What they get back
Image to point cloud | Developers | A Gaussian point cloud you can inspect in the browser
Mesh extraction | 3D artists | An untextured mesh taken from the reconstruction
Quality comparison | Researchers | Measurements against the original Idol on a 32-object set

How to set it up: Several pieces sit outside this repository, and two of them are gated.

• Python and a build of idol.cpp
• A Hugging Face account that has accepted the terms for the two image encoders
• The two encoders, which are Idol's original-precision DINOv3 and the FLUX.2-dev autoencoder

1. Build idol.cpp as its README describes.
2. Agree to the encoders' usage terms, then sign in to Hugging Face from your machine.
3. Download this model's file if you want a local copy.
4. Start the server with the command below.

pip install -U huggingface_hub
hf download TimeLordRaps/Idol-GGUF

python tools/idol_server.py --repo TimeLordRaps/Idol-GGUF --file Idol-Q8_0.gguf

How to use it: Start the server, then open its local address on port 8127 in a browser. Send in a picture, then look at the resulting point cloud and the mesh pulled from it. The same file also works from the command line and through HTTP.

Tool | What it does
tools/idol_server.py | Starts the local server and its browser interface
tools/idol_generate.py | Runs the same file from the command line
HTTP interface | Lets other programs send images to the running server
Mesh extractor | Pulls an untextured mesh out of the reconstruction

Example: You open the browser interface and upload a picture of a single household object. The page shows the Gaussian point cloud it reconstructs and lets you extract a mesh to inspect.

For newcomers and experts: Think of it as a tool that guesses the 3D shape of an object from one picture. A first small try is to run the server command, open the page and upload one clear photo of a single object.

The file keeps the denoiser, octree decoder, Gaussian decoder and background remover, mostly in Q8_0 blocks, so not every tensor has the same precision. The two image encoders are not inside it. On a 32-object test, median mesh difference from original Idol was 0.09 percent of the bounding-box diagonal. In staged mode the Idol step used at most 1,955 MiB of PyTorch graphics memory. The runtime checks how much graphics memory is free and chooses a mode. A lean mode parks idle models on disk. In a container capped at 4 GB it completed two generations, while staged mode was terminated.

Start the local server with the GGUF file
Upload one image in the browser
Idol reconstructs a Gaussian point cloud
Inspect it or extract an untextured mesh

Title: Mesh agreement with original Idol, mean over 96 comparisons
F1 within 0.1% of diagonal: 68.49%
F1 within 0.5% of diagonal: 96.74%
Silhouette overlap: 98.63%

Good to know:

• The worst observed case was much further from original Idol than the averages suggest, and the card says one case does not prove a general cause.
• Idol takes images only. A separate generator, set up on your own, can supply the image from text.
• The encoders' weights and licenses are separate from this repository.
• License: apache-2.0 for this repository.
• Cost to run: no paid service is named, but you need a Hugging Face account to accept the encoders' terms.
• Data it reaches: the images you upload to your own local server, plus files fetched from Hugging Face.
• Not for: turning text into 3D without a separate image generator.

On Hugging Face, 13 November 2026

• Task: image to 3d
• Library: idol
• Parameters: 879M
• Weights: about 440 MB at 4-bit (estimate)
• Formats: GGUF
• Downloads in the last 30 days: 3,896
• Likes: 9
• License: apache-2.0
• Based on: speridlabs/idol
• Tags: idol, gguf, gaussian-splatting, image-to-3d, 8-bit, idol.cpp

Links

• Model: https://huggingface.co/TimeLordRaps/Idol-GGUF
• Files: https://huggingface.co/TimeLordRaps/Idol-GGUF/tree/main

Get the model

Download its files with Hugging Face's command line:

pip install -U huggingface_hub
hf download TimeLordRaps/Idol-GGUF

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