Idol Image to 3D

Idol Image to 3D

把一张物体图片变成可以旋转、缩放并下载为 PLY 文件的 3D Gaussian Splat。适合想尝试图片转 3D 的创作者和开发者，带 API 和 MCP 服务器。

由 AmandaCat 在 Hugging Face 上制作。这些说明是 Mindket 根据它的 Space 页面和 README 写的，应用自己的文件和许可证在 Hugging Face 上。

简介

它是什么：这个 Space 把一张主体完整的物体图片变成 3D Gaussian Splat。你可以在页面里旋转和缩放结果，并下载成 .ply 文件。它基于 Comfy-Org 发布的 Idol 模型和 Speridlabs 的官方运行时。

下载得到的是一个 splat，每个点都带有颜色、尺度、透明度和旋转信息。它不是多边形网格。

适合谁：适合想用一张照片或渲染图快速得到物体 3D 模型的人，也适合想把这一步放到 API 后面的开发者。

行业 | 使用者 | 使用方式 | 例子
游戏与 3D 艺术 | 3D 艺术家 | 从一张图片做出物体的初步 3D 视图 | 艺术家上传一张道具的渲染图，然后检查 splat
软件 | 开发者 | 在自己的代码里调用生成接口或 MCP 服务器 | 开发者把这个接口接进一个小工具
研究 | 计算机视觉研究人员 | 用 Idol 模型试验单张图片的 3D 生成 | 研究人员比较两种点数下的结果
教育 | 老师和学生 | 展示一张图片如何变成 3D 场景 | 全班在屏幕上旋转一个生成好的 splat

如果你需要多边形网格，或者需要物体隐藏背面的真实视图，可以跳过它。

用在哪里：你可以在下面这些地方使用它。

• 网页浏览器，打开 Hugging Face 上这个 Space 的页面，它运行在 ZeroGPU 上
• Windows、macOS 或 Linux 上的本地副本，需要 Python 3.12
• 用这些文件创建、配有 ZeroGPU 硬件的你自己的 Space
• Python 代码，通过 Gradio API
• MCP 客户端，通过应用启动的 MCP 服务器

使用场景 | 适合谁 | 得到什么
把图片变成 3D | 艺术家和开发者 | 一个 .ply 文件，每个点带颜色、尺度、透明度和旋转
查看模型看到了什么 | 研究人员 | 模型实际收到的图片的预处理预览
自动化生成 | 开发者 | PLY 路径、预处理后的图片、实际种子和元数据

如何设置：在线使用只需要浏览器。本地副本或你自己的 Space 需要更多准备。

• Python 3.12 和 requirements.txt 里的软件包，用于本地副本
• 为首次启动时下载的约 4 GB 模型文件留出空间
• 一个 Hugging Face 账号和 ZeroGPU 硬件，用于你自己的 Space
• 不需要 HF_TOKEN，因为公开的模型文件不需要它

1. 打开 Hugging Face 上这个 Space 的页面即可在线使用，无需安装任何东西。
2. 想要本地副本，先安装 Hugging Face Hub 软件包。
3. 把这个 Space 的文件下载到一个文件夹并进入该文件夹。
4. 安装 Gradio 6.31.0 和 requirements.txt 里的软件包。
5. 启动应用。首次启动会下载模型、运行时代码和四张示例图片。

pip install -U huggingface_hub
hf download AmandaCat/idol-image-to-3d --repo-type space --local-dir idol-image-to-3d
cd idol-image-to-3d
pip install gradio==6.31.0
pip install -r requirements.txt
python app.py

要把它部署成你自己的公开 ZeroGPU Space，来源给出了下面这些命令。把 YOUR_USERNAME 换成你的账号名。请在 Hugging Face 的硬件设置里选择 ZeroGPU，因为 README 里的硬件提示不能代替真正的硬件选择。

hf auth login
hf repos create YOUR_USERNAME/idol-image-to-3d --type space --space-sdk gradio --flavor zero-a10g --public
hf upload YOUR_USERNAME/idol-image-to-3d . --repo-type space --exclude '**/__pycache__/**'

如何使用：上传一张主体完整的物体图片，或者点击官方示例之一。PNG 会保留透明通道。选择合成图或实拍照片，一开始保留默认设置。点击生成，然后在右侧旋转和缩放结果。展开预处理预览，查看模型实际收到的图片，再下载 .ply。

默认值是 50 步、CFG 3、时间偏移 3 和 262,144 个高斯点。用 65,536 个点更适合较轻量的下载和预览。

工具 | 作用
/generate | Gradio API 接口。它返回 PLY 路径、预处理后的图片、实际种子和生成元数据。
view_api() | 显示 API 的完整参数列表
MCP 服务器 | 随应用启动。它的地址在页面的 API 信息里。

gradio_client.Client("YOUR_USERNAME/idol-image-to-3d").view_api()

示例：你上传一张单个物体的照片，整体形状都在画面里，保留默认设置，然后点击生成。右侧会出现一个 3D Gaussian Splat，你可以把它转一圈、查看预处理预览，再下载 .ply。

新手与专家：Gaussian Splat 是由许多彩色点组成的 3D 场景，你可以从不同角度查看它。先试试官方示例图片，并旋转结果。模型会推测背面和任何被遮挡的部分，因为一张图片无法确定真实的背面形状。

从底层看，Comfy-Org/Idol 的四个核心文件分别负责生成、图像编码、图像 VAE 和 3D 解码。配置和辅助的 BiRefNet 来自 speridlabs/idol。权重适配部分只适配封装，并对参数名和形状做严格校验。它使用 SDK 的 rectified-flow Euler 采样器，这与 ComfyUI 模板的采样器不同，所以相同的种子不保证得到相同的结果。

上传图片或选一个示例
对图片做预处理
模型生成高斯点
你旋转和缩放结果
你下载 .ply 文件

注意事项：文件只保存在临时存储里，来源还要求你自己检查部署后的副本。

• 来源说，模型加载和真实的 GPU 生成仍需要在部署后的 Space 中验证。
• 文件只保存在 Space 的临时磁盘和 Gradio 的临时缓存里，所以生成后请尽快下载结果。
• License: apache-2。来源指向 NOTICE.md 和 LICENSE。
• Cost to run: 未提及。使用免费 ZeroGPU 不需要按小时计费的专用 GPU，额度取决于账号。
• Data it reaches: 它从 Hugging Face 下载的模型和运行时代码。来源说图片不会转发给外部推理 API，也不会提交到模型仓库。
• Not for: 多边形网格输出，因为结果是 Gaussian Splat。

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

• 点赞：2
• 构建方式：gradio
• 许可证：apache-2.0

链接

• Space：https://huggingface.co/spaces/AmandaCat/idol-image-to-3d
• 文件：https://huggingface.co/spaces/AmandaCat/idol-image-to-3d/tree/main

试用

在浏览器里打开这个 Space，或在它的页面上把它复制到你自己的 Hugging Face 账号。这个工具包里没有会自己运行的东西。