Idol

Idol

把一张物体图片变成 3D 高斯点云，连图中看不到的侧面也一并生成。适合想从渲染图、生成图或照片得到 3D 文件的美术、研究者和开发者。

由 speridlabs 在 Hugging Face 上制作。这些说明是 Mindket 根据它的模型页面和模型卡写的，模型自己的文件和许可证在 Hugging Face 上。

简介

它是什么：
Idol 能从单张物体图片生成 3D 高斯点云。图片可以是渲染图、AI 生成图或照片。模型还会补全看不到的侧面，并把最多 1,048,576 个高斯点保存为标准的 3DGS .ply 文件。

一张消费级显卡就够用。峰值显存占用是 7.2 GB，一次运行最快可在 2 秒内完成。

适合谁：
Idol 适合想从一张图快速得到单个物体 3D 版本的人。包括 3D 美术、游戏开发者、做 3D 生成研究的人，以及想用 Python 脚本生成点云文件的开发者。

行业 | 谁在用 | 怎么用 | 例子
游戏与 3D 美术 | 美术和独立开发者 | 把概念图或生成图变成点云 | 一张扶手椅的渲染图变成可用查看器打开的点云
研究 | 3D 生成方向的研究者 | 在测试图上运行模型并调整采样参数 | 先用默认的 50 步跑一张照片，再用更少的步数跑一遍，对比细节
产品展示 | 设计师和小店 | 把物品照片变成 3D 物体 | 用 real 模式处理一张台灯的照片
软件开发 | 开发者 | 在脚本里调用流水线并保存点云文件 | 用几行 Python 把 photo.jpg 存成 photo.ply

如果你的对象是整个场景而不是单个物体，或者没有带 CUDA 的 NVIDIA 显卡，可以跳过它。

用在哪里：

• 命令行：对单张图片或一个图片文件夹运行 python -m idol.sample
• Python：在你自己的脚本里使用 IdolPipeline 类
• Hugging Face 演示：先在托管的演示 Space 里试一张图
• 高斯点云查看器：任何查看器都能打开保存好的 ply 文件

用例 | 适合谁 | 得到什么
单张渲染图转 3D | 3D 美术 | 物体的 ply 点云和裁剪后的输入图
照片转 3D | 有物体照片的人 | ply 点云，以及 Idol 为这张照片预测相机的 json 文件
整个文件夹的图片 | 开发者和研究者 | 每张图一组输出文件，保存到你指定的文件夹

如何设置：
你需要先准备：

• 一个已同意两个受限模型条款的 Hugging Face 账号：facebook/dinov3-vith16plus-pretrain-lvd1689m 和 black-forest-labs/FLUX.2-dev
• Python 3.10 或更新版本，以及 PyTorch 2.5 或更新版本
• 带 CUDA 的 NVIDIA 显卡，峰值显存约 7.2 GB
• 放权重的磁盘空间，约 3 GB，另加两个编码器

1. 用你的 Hugging Face 账号同意两个受限模型的条款。
2. 用 hf auth login 登录一次，或者把你的令牌放进 HF_TOKEN。
3. 从 speridlabs 的 GitHub 账号克隆 idol-sdk 代码仓库，再用 pip 安装。
4. 对一张图片运行示例命令。第一次运行会自动下载权重和两个编码器。

hf auth login

cd idol-sdk
pip install -e .          # Python 3.10+, PyTorch 2.5+, an NVIDIA GPU with CUDA

如何使用：
用一张图片和一个模式运行示例命令。每张图片会得到一个 ply 文件、裁剪后的输入图和一个相机 json 文件。用高斯点云查看器打开 ply 文件即可。

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

工具 | 作用
--mode | 默认是 synthetic，适合渲染图和生成图。real 适合照片，会在物体周围留出更多空间。
--seed | 重复使用同一个值就能得到同一个物体。默认是 42。
--steps | 设置采样步数，默认 50。步数越少越快，但会损失一些细节。
--cfg_strength | 控制物体与图片的贴合程度。默认是 3.0。
--rescale_t | 值越高，整体形状分到的步数越多，值越低，细节分到的步数越多。默认是 3.0。
--num_gaussians | 设置生成的高斯点数量，范围是 32,768 到 1,048,576，必须是 32 的倍数。默认是 262144。
--dinov3_dtype | 设为 fp32 会让 DINOv3 编码器以全精度运行，多占用 1.7 GB 内存。
--weights | 指定要加载的权重，可以是 Hugging Face 上的仓库，也可以是你磁盘上的文件夹。
--no_optimize | 关闭加速采样。

示例：
拍一张台灯的照片，存成 photo.jpg，然后运行上面的第一条命令。Idol 会抠掉背景，围着台灯裁剪，并写出 photo.ply，用高斯点云查看器就能打开。你还会得到裁剪后的输入图和一个相机文件。

新手与专家：
先拿一张只有单个物体的照片。用 real 模式运行第一条命令，再用点云查看器打开 ply 文件。换一个 seed 会得到物体的另一个版本，可以多试几个。

一次完整请求约有 1.80B 参数，分布在 DiT 去噪器、八叉树解码器、高斯解码器、负责去背景的 BiRefNet 和两个图像编码器上。多数模块用 FP16 或 bf16 运行，少部分用 FP32。在 GPU 上加速采样已经默认开启，采样速度约提高 1.7 倍，输出质量不变。它用 torch.compile 编译去噪器，把有引导和无引导的两次计算合成一个批次，并在采样时使用 cuDNN 注意力和 TF32 矩阵乘法。

输入一张物体图片
去掉背景并裁剪
用 DINOv3 和 FLUX.2 VAE 编码
用去噪器和解码器采样出高斯点
保存 ply 文件

注意事项：

• 需要带 CUDA 的 NVIDIA 显卡、Python 3.10 或更新版本，以及 PyTorch 2.5 或更新版本。
• 两个编码器模型是受限的。如果还没有访问权限，Idol 会在下载之前停下，并告诉你缺什么。
• 第一次运行会把约 3 GB 的权重和两个编码器拉取到你的 Hugging Face 缓存里。
• 在同一个进程里，第一张图会更慢，因为去噪器要先编译。
• 峰值占用是 7.2 GB 显存，DINOv3 用 fp32 会再加 1.7 GB。
• 默认值是 50 步、seed 42 和 262144 个高斯点。
• 每张图被当作一个物体处理。渲染图用 synthetic 模式，照片用 real 模式。
• 许可证：apache-2.0。

Title: Idol 各部分的参数量
DiT 去噪器: 370.6 百万
八叉树解码器: 50.8 百万
高斯解码器: 237.3 百万
BiRefNet: 220.7 百万
DINOv3 ViT-H+/16: 840.6 百万
FLUX.2 VAE: 84.1 百万

Hugging Face 上的数据（2026年11月10日）

• 任务：image to 3d
• 框架：idol
• 最近 30 天下载：24,747
• 点赞：1,664
• 许可证：apache-2.0
• Quantized versions: 5
• Fine-tunes: 6
• 标签：idol, gaussian-splatting, 3d, image-to-3d

链接

• 模型：https://huggingface.co/speridlabs/idol
• 文件：https://huggingface.co/speridlabs/idol/tree/main

获取模型

用 Hugging Face 的命令行下载它的文件：

pip install -U huggingface_hub
hf download speridlabs/idol

然后按它的模型卡使用它。这个工具包里没有会自己运行的东西。