Idol-GGUF

An 8-bit, mixed-precision GGUF build of Idol by SperiD Labs. Idol takes one image and reconstructs a three-dimensional Gaussian point cloud. This one 967 MB file holds all four Idol components, and idol.cpp runs it with a local server, a browser interface and a mesh extractor.

On a 32-object test, meshes from this file differ from original Idol's by a median of 0.09% of the object's bounding-box diagonal (see How close is it to original Idol?). Run in stages, the Idol step peaked at 1,955 MiB of PyTorch-allocated graphics memory (2,754 MiB for the whole process under a 2.5 GiB allocator cap); kept resident, it allocated 4.4 to 4.9 GB. idol.cpp measures the free graphics memory and picks between them (see Memory and speed). A further lean mode keeps the waiting models on disk instead of in host memory: in a container limited to 4 GB of memory it finished two generations where staged mode was killed (details).

At a glance

Eligible matrices use eight-bit Q8_0 blocks, so the name does not mean every tensor has the same precision. The denoiser's eligible block matrices use covariance-calibrated codes; other eligible matrices use plain Q8_0 rounding.

Use it

Build idol.cpp as its README describes, accept the encoders' terms and authenticate with Hugging Face, then:

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

Open http://127.0.0.1:8127 to upload an image and inspect the point cloud and an extracted mesh. The same file works from the command line (tools/idol_generate.py) and through the server's HTTP interface.

The image encoders are Idol's original-precision DINOv3 and the autoencoder of FLUX.2-dev. Access requires accepting their terms. Their weights and licenses are separate from this repository's Apache 2.0 license.

Idol accepts images, not text. A separately configured generator can supply the image. The tested one is Iris-3B with Qwen3-VL-4B for text encoding (files Sakura-Iris-3B-Q4_K_M-3.14GiB.gguf and Qwen3VL-4B-Instruct-Q4_K_M.gguf), both Apache 2.0 and downloaded separately. The interface shows the configured filenames, which are labels and not independent verification of the weights. Whether Idol was trained on Iris-generated images is not established by the Idol project page, which also shows Iris images as inputs.

How close is it to original Idol?

The idol.cpp browser extracts an untextured mesh and compares it with a reference. A fixed challenge cohort of 32 household objects and three matched seeds gave 96 comparisons of original Idol against this file, using original-precision encoders, 50 steps and 262,144 Gaussians.

F1 is the harmonic mean of surface precision and recall within the stated distance. The worst case was Lego Friends Mia at seed 2026, and it is a real difference that the averages hide. A post-hoc probe found 1.715% mean mesh distance on the fused replay, 1.395% when reusing the original prepared image, and 0.0378% when the eight-bit decoders were given the original latent. That is one selected case and does not prove a general cause (details).

This measures agreement with original Idol, not ground-truth 3D accuracy. The cohort is a selected challenge set rather than a random sample, smoothing and component filtering can hide mesh defects, and the approximate views are not upstream rendering. The original model's own variation across seeds is context, not an allowance to subtract from the quantization error. The full protocol, figures and limitations are in the idol.cpp repository.

Is this the best Q8 build?

The denoiser calibration is what separates this file from plain Q8_0 rounding. A local build identical to this file except for plain rounding of 96 denoiser matrices was scored on 36 of the same cases: its latent error was 0.19 percentage points higher on average, worse in 23 of 36 cases, but not significantly, and its mesh distances and F1 scores were statistically indistinguishable. It was not better, so it was not published. The run stopped at 36 cases, covered three of the eight object strata, and did not include the larger float16-denoiser variants (record).

Memory and speed

All measurements below are individual runs on Windows with an NVIDIA GeForce RTX 4090 (24,564 MiB), PyTorch 2.10.0 with CUDA 12.8 and triton-windows 3.5.0.post21, using 50 denoising steps, seed 42 and 262,144 Gaussians. GB means one billion bytes and MiB means 1,048,576 bytes. GPU figures are PyTorch allocated memory unless stated, so they exclude the CUDA context, unused reserved memory, the separate image generator and other processes. They do not establish a minimum memory requirement or a latency distribution.

Staged mode: the low-memory path

idol.cpp chooses its memory mode itself. It asks nvidia-smi how much graphics memory is free and, with at least 6,488 MiB, keeps every model resident (batched guidance and cuDNN attention on, the fastest configuration measured). With less it runs in stages: every model is built on the CPU and moved onto the GPU only while its stage runs, and the two image encoders run one after the other. --memory-mode, --vram-budget-gib and tools/idol_generate_staged.py override or reproduce the choice. This is on the idol.cpp main branch and is not in the 0.1.0 release.

Whole-process peaks with this file (the server's session with the GPU decoders, two generations, original encoders, no allocator cap):

These figures set the automatic thresholds (record), which keep a 512 MiB headroom.

Command-line runs of this file on the axolotl image with original encoders and the GPU decoders, with PyTorch's allocator limited to the stated cap (one run each):

The staged point clouds at 6, 3.5 and 2.5 GiB, and the previous construction's at 6 GiB, were byte-identical; the previous construction's at 3.5 GiB differed, so results can depend on memory pressure. A separate staged run at the 2.5 GiB cap with the native CPU decoder measured the whole process at 2,754 MiB. Staged inference needs host memory for every model (lean mode, below, avoids that) and is slower than resident inference. These are Idol-stage figures for one image and one seed: a full prompt-to-3D run on a 4 GB card was not performed (record).

Lean mode: the low-RAM path

Staged mode still keeps every waiting model in system memory. Lean mode (--memory-mode lean, or tools/idol_generate_lean.py from the command line) writes each model to a temporary file as soon as it is built and reads it back only while its stage runs, so the host holds one model at a time. It needs about 3.7 GB of free disk space (--lean-directory chooses where) and supports neither --packed-denoiser nor --fused-kernels. idol.cpp chooses it itself when staging is needed, the computer has less than 6,207 MiB of free memory and 4,728 MiB of disk is free. Like the automatic mode choice, it is on the idol.cpp main branch and not in the 0.1.0 release.

Host memory of the process on Windows, as private working set (memory that is not a memory-mapped file, so the system cannot just drop it and read it again), for the same session with this file, original encoders, one image and two denoising steps, two runs each:

The point cloud was byte-identical to staged mode's in every run. What remains in lean mode is held by PyTorch, CUDA and the graphics driver rather than by the models: a bare PyTorch and CUDA process takes 0.7 GB, and essentially no tensor data was left in host memory after a generation. Each generation reads about 3.7 GB back from disk, which took 3.5 s in a restore measurement while the graphics device was busy.

In a Linux container with a hard memory limit and no swap, the server in lean mode finished two generations at a 4 GB limit and at 6 GB; the process's own memory peaked at about 2.3 GB and the rest of the limit was reclaimable file cache. Staged mode was killed for running out of memory at 4 GB and, during its second generation, at 6 GB. That limit covers the process alone, not an operating system beside it, and the graphics side was a stated 4 GiB budget on a 24 GB card, so a real 4 GB computer was not tested. A text prompt also needs the image generator, which is the larger host-memory user: alone it held about 6.8 GB of private memory at graphics budgets of 4 GiB and below (1.1 GB with every weight resident), and a complete text-to-3D request with a stated 4 GiB budget peaked at 7.0 GB in staged and lean mode alike. The runner's --mmap option kept its private memory at 1.2 to 1.4 GB with a byte-identical image. idol.cpp (main branch, not the 0.1.0 release) now passes it when the free system memory is below what the generator holds at the budget in use, and a whole request in lean mode with mapping peaked at 3.8 GB of private memory instead of 7.0 GB and returned the same point cloud. The mapped pages are read back from disk when memory is short, which was not tested, so neither the speed cost nor a real 4 to 6 GB computer is established (record; Idol alone: record).

Resident mode and earlier staged rows

The resident rows also used batched guidance and optimized attention; staged rows disabled both. Warm requests followed a one-step warmup, and operating-system caches could be warm.

The quantized file did not consistently beat original Idol on time: across the 32-object run the median model-resident call took 25.57 s with original weights and 28.82 s with this file, and median peak PyTorch allocation was 5.37 GB and 4.72 GB. Model loading was excluded, execution order was fixed, and the workstation was shared, so this does not establish a speed saving or its cause (runtime observations).

The third-party DINOv3 Q4 file (revision 7fbb86b66bbb1dd483c94c179d35c969c76467e6, SHA-256 cf80ee6e3c2d4044b3214c0ccde5e416cb999b799f35b699f4edaa4059d83d71) is an experimental compatibility result and not a quality recommendation: for the axolotl image its latent differed by 34.17% in relative Euclidean norm from the run with the original encoder. One image and seed cannot establish general behavior. The FLUX.2 autoencoder stayed at original precision.

CPU and GPU decoders

idol.cpp decodes the latent into Gaussians either with a native CPU decoder or with GPU decoders (--decoder-backend gpu; the server uses the GPU ones). On three saved latents of this file, both produced meshes that agree with original Idol equally well, differing from each other by 0.04% to 0.05% of the diagonal. The GPU decoders took 0.3 to 1.2 s with 523 MiB of device memory; the native decoder took 37 to 62 s with 8 or 4 threads and about 820 MiB of host memory. Three objects at one seed on a shared machine show an order of magnitude, not a benchmark (record).

Text prompts

Image generation and Idol can run one after the other, so their memory peaks need not be added. idol.cpp sizes the generator's --max-vram budget for each image from the free graphics memory: at full size (every weight resident, fastest) when at least 7,222 MiB are free, otherwise the largest measured budget that fits, down to 2 GiB. On the same GPU one 1,024 × 1,024 Iris-3B image peaked at 6,710 MiB at a budget of 16 or 8 GiB, about 4,400 MiB at 6, 5 or 4 GiB, 3,287 MiB at 3 GiB and 2,272 MiB at 2 GiB. A budget of 1 GiB failed. The images were pixel-identical at every budget for that prompt. In an earlier run on a quieter machine the image took 24.7 s at 16 GiB, 75.5 s at 3 GiB and 93.2 s at 2 GiB. Only the Vulkan runner was measured (budget record, peaks). When both fit together, the server also keeps Idol loaded instead of releasing it around each prompt. Host memory for the generator was not measured.

A full text-to-3D request with a stated 4 GiB budget (Idol staged, generator at 3 GiB) completed with the server and the generator together peaking at 3,332 MiB of graphics memory. That ran on a 24 GB card with other work on it, so it shows the choices fit a 4 GiB budget, not that an actual 4 GB card was tested.

Two end-to-end browser prompt trials (Iris-3B Q4, Qwen3-VL-4B Q4, this file, original encoders, the 16 GiB generator budget) took 100.16 s and 72.74 s from browser launch to result, including page load but not server start. Peak total-device GPU use, which includes the display and other applications, was 12.85 GB and 13.12 GB, with 5.56 to 5.76 GB already in use beforehand (record).

Docker

A locally built Dockerfile image loaded this file with original encoders and served one 50-step request in 58.29 s including loading, producing 262,144 finite points and an 80,660-triangle mesh, with 3.51 GB peak PyTorch allocation (record). The release tree was also built and tested through the documented download path: from an empty Idol cache it downloaded and checked this file and produced 262,144 finite points in one request (74.88 s). The gated encoder weights came from an existing read-only cache, and image layers may have been cached (release-verification.json).

Limitations

• The original model used dense operations and this file uses fused packed operations, so differences cannot be attributed to the weights alone.
• Fidelity is measured against original Idol on a selected cohort, not against ground-truth geometry, and says nothing about quality on other objects.
• All timings and memory figures are from one shared RTX 4090 workstation. They are not a latency distribution or a hardware minimum.
• Lean-mode host-memory figures come from one 64 GiB Windows computer and a memory-limited Linux container on it; no real small-memory computer was tested. The same holds for the image generator's host-memory figures.
• ComfyUI-GGUF compatibility has not been established.
• Idol's training data and its overlap with the test objects are unknown.

Files and provenance

The original model, use conditions and research are described at speridlabs/idol and the Idol project page. The idol.cpp source is available under the Apache License 2.0; separately distributed components keep their own terms. This card was last updated on 2026-11-07.