Repolode
提交项目
speridlabs

speridlabs/idol-sdk

从单张物体图片生成 3D Gaussian splat 模型的推理 SDK 与演示。

在 GitHub 查看
Star
863
Fork
83
未关闭 Issue
1
最近提交
9天前

这是什么？

Idol 是一个推理 SDK，输入一张物体图片（渲染图、生成图或照片），即可输出标准 3DGS 格式的 .ply 三维高斯溅射模型。它会先用 BiRefNet 去除背景并裁剪取景，再生成 32,768 到 1,048,576 个 Gaussian，包括输入图中看不到的背面。

模型基于 370M 参数的 DiT 扩散 Transformer，以 DINOv3 和 FLUX.2 VAE 作为图像条件，并配有独立的解码器。可以通过命令行区分合成图与真实照片模式进行推理，也可以使用 Python API 调用，权重从 Hugging Face 加载。每次运行会输出 .ply 文件、预处理后的输入图和相机参数 JSON。

仓库中的 demo/ 目录提供基于 Gradio 的演示应用，可在本地 GPU 上运行。DINOv3 与 FLUX.2-dev 的权重需要先在 Hugging Face 申请访问权限。

核心功能

  • 01从单张图片生成 3D Gaussian，最多可达 1,048,576 个。
  • 02输出标准 3DGS .ply 文件，可用任意 Gaussian splat 查看器打开。
  • 03自动去除背景并裁剪物体。
  • 04提供合成图与真实照片两种推理模式。
  • 05提供命令行工具、Python API 和本地 Gradio demo。
  • 06安装 flash-attn 时用于注意力计算，否则回退到 PyTorch SDPA。

适用场景

  • 将产品渲染图或 AI 生成图转换为可在查看器中浏览的 3D 资产。
  • 从单张真实照片重建三维物体。
  • 在本地消费级 GPU 上搭建图像到 3D 的原型流程。

快速上手

  1. 1

    使用 pip 安装包（需要 Python 3.10+ 和 PyTorch 2.5+）

    pip install -e .
  2. 2

    在 Hugging Face 申请 DINOv3 和 FLUX.2-dev 模型的访问权限，然后登录

    hf auth login
  3. 3

    对一张照片运行推理

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

使用前须知

  • 需要在 Hugging Face 获得门控模型 DINOv3 和 FLUX.2-dev 的访问批准。
  • 实际使用需要本地 GPU；在较弱的 GPU 上单次请求可能接近一分钟。
  • 每次请求峰值显存约 7.2 GB。

收录于专题

计算机视觉工具与库

标签

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

常见问题

idol-sdk 是什么？
从单张物体图片生成 3D Gaussian splat 模型的推理 SDK 与演示。 Idol 是一个推理 SDK，输入一张物体图片（渲染图、生成图或照片），即可输出标准 3DGS 格式的 .ply 三维高斯溅射模型。它会先用 BiRefNet 去除背景并裁剪取景，再生成 32,768 到 1,048,576 个 Gaussian，包括输入图中看不到的背面。
idol-sdk 可以免费使用吗？用的什么许可证？
idol-sdk 以 Apache-2.0 许可证开源。用于商业产品前，请先确认许可证条款。
idol-sdk 还在维护吗？
活跃维护中。idol-sdk 最近一次提交是在 2026年10月29日。
idol-sdk 适合用来做什么？
将产品渲染图或 AI 生成图转换为可在查看器中浏览的 3D 资产。 从单张真实照片重建三维物体。 在本地消费级 GPU 上搭建图像到 3D 的原型流程。
idol-sdk 怎么安装和运行？
使用 pip 安装包（需要 Python 3.10+ 和 PyTorch 2.5+）: pip install -e . 在 Hugging Face 申请 DINOv3 和 FLUX.2-dev 模型的访问权限，然后登录: hf auth login 对一张照片运行推理: python -m idol.sample --image photo.jpg --mode real
在哪里获取 idol-sdk？
源代码和安装说明在 GitHub 上：https://github.com/speridlabs/idol-sdk

概要由 AI 根据项目 README 生成；GitHub 数据每日更新。

相关项目