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}
}