idol - 单张图片生成 3D Gaussian splat 的开源模型

idol 是一个 image-to-3d 任务的开源模型，托管在 Hugging Face 的 speridlabs 组织下。按项目自述，它接收一张物体图片——渲染图、生成图或照片都可以——先去除背景、把物体框进画面，再生成最多 1,048,576 个 3D Gaussian，输出为标准 3DGS 格式的 .ply 文件，其中包含原图没有拍到的侧面。它适合需要从单张图片快速得到可查看三维表示的研究者、独立开发者与内容创作者，尤其是手头只有消费级显卡、希望本地跑通整条流程的人。

维护者与状态

项目由 speridlabs 维护，仓库创建于 2026-10-28，最后更新于 2026-10-29。事实表中没有给出正式 release 信息，因此这里不对版本号作任何推断。截至 2026-11-05，该仓库近 30 天被下载 14613 次，累计点赞 620。许可证为 apache-2.0。

主要能力

以下能力均来自项目自述（README / 模型卡），未经本站独立验证。

• 单图输入、端到端输出：据项目说明，模型自行完成背景去除与物体取景，用户不需要预先抠图或裁剪。
• 补全未见视角：README 中称，生成结果包含图片从未展示过的侧面，而不仅是正面重投影。
• 高斯数量可调：默认 262,144 个高斯，可调范围为 32,768 至 1,048,576，且须为 32 的倍数。
• 两种取景模式：synthetic（默认）面向渲染图与生成图，物体占画面 1/1.2；real 面向照片，物体占画面 1/1.7。
• 附带中间产物：每张图除 .ply 外，还会写出 _input.png（模型实际看到的、去背景并裁剪后的图像）与 _camera.json（预测的输入相机参数）。
• 采样参数可调：--seed 固定后可复现同一物体；--steps 默认 50，步数越少越快但细节减少；--cfg_strength 默认 3.0，控制跟随输入图像的程度；--rescale_t 默认 3.0，数值越高越把步数花在整体形状上。
• 默认开启加速采样：据项目说明，GPU 上默认启用优化采样，约 1.7 倍加速且输出质量不变，做法包括用 torch.compile 编译去噪器、把引导与非引导两遍合成一个 batch、采样时注意力走 cuDNN 并使用 TF32 矩阵乘。进程内第一张图会因编译而变慢。

项目自述给出的模型构成包括 DiT 去噪器（370.6M 参数）、八叉树解码器（50.8M）、高斯解码器（237.3M）、BiRefNet 背景去除（220.7M）、DINOv3 ViT-H+/16 图像编码器（840.6M）与 FLUX.2 VAE（84.1M），整次请求约 1.80B 参数，权重占用约 3.7–4.4 GB 显存，峰值 7.2 GB。

使用入口

模型仓库地址：speridlabs/idol。

据项目说明，使用前需要先在 Hugging Face 上接受两个门控模型的条款，并用 hf auth login 登录或设置 HF_TOKEN：facebook/dinov3-vith16plus-pretrain-lvd1689m 与 black-forest-labs/FLUX.2-dev（只下载其 VAE）。若编码器尚不可访问，模型会在下载任何内容前停下并提示缺失项。

代码安装与命令行调用（README 给出的方式，需要 Python 3.10+、PyTorch 2.5+ 与支持 CUDA 的 NVIDIA GPU）：

git clone https://github.com/speridlabs/idol-sdk.git
cd idol-sdk
pip install -e .

python -m idol.sample --image photo.jpg --mode real
python -m idol.sample --image renders/ --mode synthetic --out outputs

Python 调用示例：

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")

首次运行时，模型权重（约 3 GB，来自该仓库）与两个图像编码器会自动下载到 Hugging Face 缓存，没有单独的下载步骤。

许可与限制

许可证为 apache-2.0。需要注意的边界条件（据项目说明）：

• 硬件门槛：需要 NVIDIA GPU 与 CUDA，峰值显存 7.2 GB；项目自述称可在消费级 GPU 上运行。
• 前置授权：两个图像编码器为门控模型，未接受条款并完成登录时无法运行。
• 输入模式选择：synthetic 与 real 的裁剪留白不同，选错会影响取景效果。
• 精度选项：--dinov3_dtype fp32 会让 DINOv3 编码器以全精度运行，额外占用约 1.7 GB 内存。
• 首次延迟：启用优化采样时，进程内第一张图需等待编译。

项目自述中附有与其他方法的对比表格与多卡耗时数据，属于维护者自行给出的评测结果，本文不转述具体分数，读者如需引用请以原仓库内容为准。