Repolode
Submit
speridlabs

speridlabs/idol-sdk

Turns a single image of an object into a 3D Gaussian splat model, with the unseen sides generated, as an inference SDK and demo.

View on GitHub
Stars
885
Forks
86
Open issues
1
Last commit
9 days ago

What is it?

Idol is an inference SDK that takes one picture of an object, such as a render, a generated image or a photo, and produces a 3D Gaussian splat in standard 3DGS .ply format. It removes the background with BiRefNet, crops and frames the object, then generates between 32,768 and 1,048,576 Gaussians, including sides not visible in the input.

The model is a 370M-parameter diffusion transformer conditioned on DINOv3 and FLUX.2 VAE features, with a separate decoder. Inference is available through a command-line tool with a synthetic or real photo mode, or through a Python API that loads weights from Hugging Face. Each run writes the .ply file, the preprocessed input image and the predicted camera JSON.

The repository includes a Gradio demo in demo/ that can run locally on a GPU. Weights are gated: access to the DINOv3 and FLUX.2-dev repositories on Hugging Face must be requested before first use.

Key features

  • 01Generates 3D Gaussians from one image, with up to 1,048,576 Gaussians.
  • 02Outputs standard 3DGS .ply files viewable in any Gaussian splat viewer.
  • 03Removes the background and crops the object automatically.
  • 04Offers separate synthetic and real photograph modes.
  • 05Provides a command-line tool, a Python API and a local Gradio demo.
  • 06Uses flash-attn when installed, with PyTorch SDPA as fallback.

Use cases

  • Turning product renders or generated images into 3D assets for a viewer.
  • Reconstructing a 3D object from a single real-world photo.
  • Prototyping image-to-3D pipelines on a local consumer GPU.

Quick start

  1. 1

    Install the package with pip (Python 3.10+, PyTorch 2.5+)

    pip install -e .
  2. 2

    Request access to the gated DINOv3 and FLUX.2-dev models on Hugging Face, then log in

    hf auth login
  3. 3

    Run inference on a photo

    python -m idol.sample --image photo.jpg --mode real

Things to know

  • Needs access approval for gated DINOv3 and FLUX.2-dev models on Hugging Face.
  • Needs a local GPU for practical speed; on weaker GPUs requests can take close to a minute.
  • Uses about 7.2 GB of peak VRAM per request.

In collections

Computer vision libraries & tools

Topics

#3d-gaussian-splatting#image-to-3d#diffusion#computer-vision#pytorch#gradio

FAQ

What is idol-sdk?
Turns a single image of an object into a 3D Gaussian splat model, with the unseen sides generated, as an inference SDK and demo. Idol is an inference SDK that takes one picture of an object, such as a render, a generated image or a photo, and produces a 3D Gaussian splat in standard 3DGS .ply format. It removes the background with BiRefNet, crops and frames the object, then generates between 32,768 and 1,048,576 Gaussians, including sides not visible in the input.
Is idol-sdk free to use? What license does it have?
idol-sdk is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is idol-sdk still maintained?
Actively maintained. The last commit to idol-sdk was on Oct 29, 2026.
What can I use idol-sdk for?
Turning product renders or generated images into 3D assets for a viewer. Reconstructing a 3D object from a single real-world photo. Prototyping image-to-3D pipelines on a local consumer GPU.
How do I install idol-sdk?
Install the package with pip (Python 3.10+, PyTorch 2.5+): pip install -e . Request access to the gated DINOv3 and FLUX.2-dev models on Hugging Face, then log in: hf auth login Run inference on a photo: python -m idol.sample --image photo.jpg --mode real
Where can I get idol-sdk?
The source code and installation instructions are on GitHub: https://github.com/speridlabs/idol-sdk

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects