Hunyuan3d 1

🚀 腾讯混元3D-1.0：用于文本到3D和图像到3D生成的统一框架

腾讯混元3D-1.0是一个创新的统一框架，支持文本到3D和图像到3D的生成。它有效解决了现有3D生成扩散模型生成速度慢、泛化能力差的问题，在速度和质量之间取得了出色的平衡。

🚀 快速开始

克隆仓库

首先，克隆项目仓库到本地：

git clone https://github.com/tencent/Hunyuan3D-1
cd Hunyuan3D-1

Linux环境安装指南

我们提供了env_install.sh脚本文件来设置环境：

# 步骤1：创建conda环境
conda create -n hunyuan3d-1 python=3.9 or 3.10 or 3.11 or 3.12
conda activate hunyuan3d-1

# 步骤2：安装torch相关包
which pip # 检查pip是否对应python

# 根据你的机器修改cuda版本（推荐）
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# 步骤3：安装其他包
bash env_install.sh

pip install xformers --index-url https://download.pytorch.org/whl/cu121

pip install flash_attn

# python3.9
pip install torch==2.0.1 torchvision==0.15.2 --index-url https://download.pytorch.org/whl/cu118 

下载预训练模型

模型可在https://huggingface.co/tencent/Hunyuan3D-1获取：

• Hunyuan3D-1/lite：用于多视图生成的轻量级模型。
• Hunyuan3D-1/std：用于多视图生成的标准模型。
• Hunyuan3D-1/svrm：稀疏视图重建模型。

要下载模型，首先安装huggingface-cli。（详细说明可点击此处查看。）

python3 -m pip install "huggingface_hub[cli]"

然后使用以下命令下载模型：

mkdir weights
huggingface-cli download tencent/Hunyuan3D-1 --local-dir ./weights

mkdir weights/hunyuanDiT
huggingface-cli download Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers-Distilled --local-dir ./weights/hunyuanDiT

推理

文本到3D生成

我们支持中英文双语，你可以使用以下命令进行推理：

python3 main.py \
    --text_prompt "a lovely rabbit" \
    --save_folder ./outputs/test/ \
    --max_faces_num 90000 \
    --do_texture_mapping \
    --do_render

图像到3D生成

你可以使用以下命令进行推理：

python3 main.py \
    --image_prompt "/path/to/your/image" \
    --save_folder ./outputs/test/ \
    --max_faces_num 90000 \
    --do_texture_mapping \
    --do_render

我们列出了一些更有用的配置，方便使用：

我们还准备了不同配置的脚本供参考：

• 推理标准管道需要30GB显存（使用--save_memory时需要24GB显存）。
• 推理轻量级管道需要22GB显存（使用--save_memory时需要18GB显存）。
• 注意：--save_memory会增加推理时间。

bash scripts/text_to_3d_std.sh 
bash scripts/text_to_3d_lite.sh 
bash scripts/image_to_3d_std.sh 
bash scripts/image_to_3d_lite.sh 

如果你的GPU显存为16G，你可以尝试分别运行管道中的模块：

bash scripts/text_to_3d_std_separately.sh 'a lovely rabbit' ./outputs/test # >= 16G
bash scripts/text_to_3d_lite_separately.sh 'a lovely rabbit' ./outputs/test # >= 14G
bash scripts/image_to_3d_std_separately.sh ./demos/example_000.png ./outputs/test  # >= 16G
bash scripts/image_to_3d_lite_separately.sh ./demos/example_000.png ./outputs/test # >= 10G

使用Gradio

我们准备了标准和轻量级两个版本的多视图生成：

# 标准版本
python3 app.py
python3 app.py --save_memory

# 轻量级版本
python3 app.py --use_lite
python3 app.py --use_lite --save_memory

然后可以通过http://0.0.0.0:8080访问演示。需要注意的是，这里的0.0.0.0需要替换为你的服务器IP地址X.X.X.X。

✨ 主要特性

• 统一框架：支持文本到3D和图像到3D的生成，集成了文本到图像模型Hunyuan-DiT。
• 高效生成：采用两阶段方法，第一阶段使用多视图扩散模型在约4秒内高效生成多视图RGB图像；第二阶段使用前馈重建模型在约7秒内快速忠实地重建3D资产。
• 速度与质量平衡：标准版本的参数是轻量级版本和其他现有模型的3倍，在显著减少生成时间的同时，保持了生成资产的质量和多样性。
• 双语支持：在文本到3D生成中支持中英文双语。

📦 安装指南

见上述快速开始部分的环境安装和模型下载步骤。

💻 使用示例

基础用法

文本到3D生成

python3 main.py \
    --text_prompt "a lovely rabbit" \
    --save_folder ./outputs/test/ \
    --max_faces_num 90000 \
    --do_texture_mapping \
    --do_render

图像到3D生成

python3 main.py \
    --image_prompt "/path/to/your/image" \
    --save_folder ./outputs/test/ \
    --max_faces_num 90000 \
    --do_texture_mapping \
    --do_render

高级用法

使用不同配置的脚本进行推理，或在显存有限时分别运行管道中的模块，具体命令见快速开始部分。

📚 详细文档

🔥🔥🔥 最新消息！

• 2024年11月5日：💬 我们现在支持运行图像到3D生成的演示。请查看下面的脚本。
• 2024年11月5日：💬 我们现在支持运行文本到3D生成的演示。请查看下面的脚本。

📑 开源计划

• [x] 推理
• [x] 检查点
• [ ] 烘焙相关
• [ ] 训练
• [ ] ComfyUI
• [ ] 蒸馏版本
• [ ] TensorRT版本

🎉 混元3D-1架构

📈 对比

我们将混元3D-1.0与其他开源3D生成方法进行了评估，混元3D-1.0在5个指标上获得了最高的用户偏好。详情见左下角的图片。

轻量级模型在NVIDIA A100 GPU上从单张图像生成3D网格大约需要10秒，而标准模型大约需要25秒。右下角的图表显示，混元3D-1.0在质量和效率之间达到了最佳平衡。

相机参数

输出视图是一组固定的相机姿态：

• 方位角（相对于输入视图）：+0, +60, +120, +180, +240, +300。

🔧 技术细节

现有3D生成扩散模型存在生成速度慢、泛化能力差的问题。腾讯混元3D-1.0提出两阶段方法来解决这些问题：

• 第一阶段：采用多视图扩散模型，在约4秒内高效生成多视图RGB图像。这些多视图图像从不同视角捕捉3D资产的丰富细节，将任务从单视图重建转换为多视图重建。
• 第二阶段：引入前馈重建模型，在约7秒内根据生成的多视图图像快速忠实地重建3D资产。重建网络学习处理多视图扩散引入的噪声和不一致性，并利用条件图像中的可用信息有效恢复3D结构。

框架集成了文本到图像模型Hunyuan-DiT，成为支持文本和图像条件3D生成的统一框架。标准版本的参数是轻量级版本和其他现有模型的3倍，在速度和质量之间取得了出色的平衡。

📄 许可证

本项目采用tencent-hunyuan-community许可证，详情请见许可证链接。

引用

如果你觉得这个仓库有帮助，请引用我们的报告：

@misc{yang2024tencent,
    title={Tencent Hunyuan3D-1.0: A Unified Framework for Text-to-3D and Image-to-3D Generation},
    author={Xianghui Yang and Huiwen Shi and Bowen Zhang and Fan Yang and Jiacheng Wang and Hongxu Zhao and Xinhai Liu and Xinzhou Wang and Qingxiang Lin and Jiaao Yu and Lifu Wang and Zhuo Chen and Sicong Liu and Yuhong Liu and Yong Yang and Di Wang and Jie Jiang and Chunchao Guo},
    year={2024},
    eprint={2411.02293},
    archivePrefix={arXiv},
    primaryClass={cs.CV}
}