中文版本

日本語版

Unique3D

Unique3D 的官方实现：从单张图像高效生成高质量 3D 网格。

Kailu Wu, Fangfu Liu, Zhihan Cai, Runjie Yan, Hanyang Wang, Yating Hu, Yueqi Duan, Kaisheng Ma

论文 | 项目主页 | Huggingface 演示 | 在线演示

• 演示推理速度：Gradio 演示 > Huggingface 演示 > Huggingface 演示2 > 在线演示

如果 Gradio 演示过于拥挤或无法产生稳定结果，您可以使用免费试用的在线演示 aiuni.ai（获取注册邀请码，请加入 Discord：https://discord.gg/aiuni）。不过，在线演示与 Gradio 演示略有不同，其推理速度较慢，但生成效果更加稳定。

Unique3D 在 30 秒内从单视角自然场景图像中生成高保真且纹理多样的网格模型。

更多功能

本仓库仍在建设中，感谢您的耐心等待。

• 上传权重。
• 本地 Gradio 演示。
• 详细教程。
• Huggingface 演示。
• 详细的本地演示。
• ComfyUI 支持。
• Windows 支持。
• Docker 支持。
• 使用法线进行更稳定的重建。
• 发布训练代码。

推理前准备

• 详细的 Linux 安装指南。

Linux 系统设置。

适用于 Ubuntu 22.04.4 LTS 和 CUDA 12.1。

conda create -n unique3d python=3.11
conda activate unique3d

pip install ninja
pip install diffusers==0.27.2

pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu121/torch2.3.1/index.html

pip install -r requirements.txt

oak-barry 提供了另一个针对 torch210+cu121 的设置脚本，详见 这里。

Windows 设置。

• 非常感谢 jtydhr88 提供的 Windows 安装方法！详情请参阅 issues/15。

根据 issues/15，我们实现了一个用于运行命令的 bat 脚本，因此您可以：

1. 可能仍然需要 Visual Studio Build Tools，您可以从 Visual Studio Build Tools 下载。
2. 创建并激活 conda 环境
   1. conda create -n unique3d-py311 python=3.11
   2. conda activate unique3d-py311
3. 下载适用于 py311 的 triton whl，并将其放入该项目中。
4. 运行 install_windows_win_py311_cu121.bat
5. 当提示卸载 onnxruntime 和 onnxruntime-gpu 时，回答 y。
6. 在驱动器根目录下创建输出文件夹 tmp\gradio，例如我的 F:\tmp\gradio。
7. 运行 python app/gradio_local.py --port 7860。

更多细节请参考 issues/15。

交互式推理：运行您的本地 Gradio 演示。

1. 从 huggingface spaces 或 清华大学云盘 下载权重，并将其解压到 ckpt/* 目录下。

Unique3D
    ├──ckpt
        ├── controlnet-tile/
        ├── image2normal/
        ├── img2mvimg/
        ├── realesrgan-x4.onnx
        └── v1-inference.yaml

2. 在本地运行交互式推理。

python app/gradio_local.py --port 7860

ComfyUI 支持

感谢 jtydhr88 实现的 ComfyUI-Unique3D！

获取更好结果的技巧

重要提示：由于网格在训练时按 xyz 最长边进行归一化处理，因此在推理时，输入图像最好包含物体的最长边，否则可能会导致结果被错误地压缩。

1. Unique3D 对输入图像的朝向非常敏感。由于训练数据的分布特点，正视图且处于静止姿态的图像通常能带来较好的重建效果。
2. 存在遮挡的图像会导致较差的重建效果，因为四个视角无法覆盖整个物体。遮挡较少的图像通常能获得更好的结果。
3. 如果分辨率是一个重要因素，尽量使用尽可能高分辨率的图像作为输入。

致谢

我们大量借鉴了以下仓库中的代码。非常感谢这些作者分享他们的代码。

• Stable Diffusion
• Wonder3d
• Zero123Plus
• Continues Remeshing
• Depth from Normals

合作机会

我们的目标是构建一个基于 3D 概念的 4D 生成模型。这只是我们的第一步，未来的路还很长，但我们充满信心。我们诚挚邀请您参与讨论，并以任何形式探讨潜在的合作机会。如果您有意与我们联系或合作，请随时通过电子邮件 (wkl22@mails.tsinghua.edu.cn) 与我们取得联系。

• 关注我们的 Twitter 以获取最新动态：https://x.com/aiuni_ai
• 加入 Discord 上的 AIGC 3D/4D 生成社区：https://discord.gg/aiuni
• 如需科研合作，请联系：ai@aiuni.ai

引用

如果您觉得 Unique3D 有所帮助，请引用我们的报告：

@misc{wu2024unique3d,
      title={Unique3D: High-Quality and Efficient 3D Mesh Generation from a Single Image}, 
      author={Kailu Wu and Fangfu Liu and Zhihan Cai and Runjie Yan and Hanyang Wang and Yating Hu and Yueqi Duan and Kaisheng Ma},
      year={2024},
      eprint={2405.20343},
      archivePrefix={arXiv},
      primaryClass={cs.CV}
}

Unique3D 快速上手指南

Unique3D 是一个能够从单张图像高效生成高质量 3D 网格模型的开源工具。本指南将帮助开发者在本地快速部署并运行该工具。

环境准备

系统要求

• 操作系统:
  • 推荐：Ubuntu 22.04.4 LTS (Linux)
  • 支持：Windows (需额外配置)
• GPU: 支持 CUDA 的 NVIDIA 显卡
• CUDA 版本: 推荐 12.1
• Python 版本: 3.11

前置依赖

• Conda (用于管理虚拟环境)
• Git (用于克隆代码库)
• Visual Studio Build Tools (仅 Windows 用户需要)

安装步骤

方案一：Linux 环境安装 (推荐)

1. 创建并激活 Conda 环境

   conda create -n unique3d python=3.11
   conda activate unique3d
   

2. 安装基础依赖

   pip install ninja
   pip install diffusers==0.27.2
   

3. 安装 MMCV (适配 CUDA 12.1 + Torch 2.3.1)

   pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu121/torch2.3.1/index.html
   

4. 安装项目其余依赖

   pip install -r requirements.txt
   

方案二：Windows 环境安装

1. 安装构建工具 下载并安装 Visual Studio Build Tools。

2. 创建并激活 Conda 环境

   conda create -n unique3d-py311 python=3.11
   conda activate unique3d-py311
   

3. 下载 Triton Wheel 包 下载适用于 Python 3.11 的 triton whl 文件，并将其放入项目根目录。

4. 执行一键安装脚本 运行项目提供的批处理文件：

   install_windows_win_py311_cu121.bat
   

   注意：当脚本询问是否卸载 onnxruntime 和 onnxruntime-gpu 时，请输入 y 确认。

5. 创建输出目录 在磁盘根目录下创建临时文件夹（例如 F 盘）：

   F:\tmp\gradio
   

基本使用

1. 下载模型权重

从以下任一来源下载权重文件，并解压到项目根目录下的 ckpt 文件夹中，确保目录结构如下：

• HuggingFace Spaces
• 清华大学云盘 (国内加速)

预期目录结构：

Unique3D
├── ckpt
│   ├── controlnet-tile/
│   ├── image2normal/
│   ├── img2mvimg/
│   ├── realesrgan-x4.onnx
│   └── v1-inference.yaml

2. 启动本地 Gradio 演示

在终端中运行以下命令启动交互式界面：

Linux/Mac:

python app/gradio_local.py --port 7860

Windows:

python app/gradio_local.py --port 7860

(确保已激活对应的 conda 环境)

启动后，浏览器会自动打开或访问 http://localhost:7860，上传一张图片即可生成 3D 模型。

💡 获取更好效果的建议

• 视角选择：输入图片最好是正交的正视图（物体处于静止姿态），避免大角度侧视。
• 遮挡处理：尽量减少物体自身的遮挡，四个视图可能无法完全覆盖严重遮挡的物体。
• 分辨率：在显存允许的情况下，尽量输入高分辨率图片。
• 构图关键：由于训练时网格是按 XYZ 最长边归一化的，输入图片必须包含物体的最长边，否则生成的模型可能会被错误地压扁。