mirror of
https://git.datalinker.icu/kijai/ComfyUI-Hunyuan3DWrapper.git
synced 2026-01-23 15:24:25 +08:00
Update readme.md
This commit is contained in:
Antoine Boucher
GitHub
parent
cbe2837e50
commit
f8b18e2dab
249
readme.md
249
readme.md
@ -1,124 +1,189 @@
|
||||
# ComfyUI Wrapper for [Hunyuan3D-2](https://github.com/Tencent/Hunyuan3D-2)
|
||||
|
||||
# ComfyUI wrapper for [Hunyuan3D-2](https://github.com/Tencent/Hunyuan3D-2)
|
||||
---
|
||||
|
||||
|
||||
|
||||
## Models
|
||||
Main model, original: https://huggingface.co/tencent/Hunyuan3D-2/blob/main/hunyuan3d-dit-v2-0/model.ckpt
|
||||
|
||||
Converted to .safetensors: https://huggingface.co/Kijai/Hunyuan3D-2_safetensors
|
||||
|
||||
to `ComfyUI/models/diffusion_models/`
|
||||
|
||||
Rest of the models are diffusers models, so they are wrapped and autodownloaded for now. Very new version of ComyUI is also required for the Preview3D -node.
|
||||
*Cutting-edge 3D textured model generation integrated seamlessly into ComfyUI*
|
||||
|
||||
---
|
||||
|
||||
# Installation
|
||||
Dependencies, in your python env:
|
||||
|
||||
|
||||
`pip install -r requirements.txt`
|
||||
|
||||
or with portable:
|
||||
|
||||
`python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\requirements.txt`
|
||||
|
||||
|
||||
For the texturegen part compilation is needed, I have included my compilations as a wheel for the rasterizer, and compiled .pyd for the mesh_processor (already in place), these are compiled for:
|
||||
|
||||
**Windows 11 python 3.12 cu126 (works with torch build on 124)**
|
||||
|
||||
You would do `pip install wheels\custom_rasterizer-0.1-cp312-cp312-win_amd64.whl`
|
||||
|
||||
or with portable (in `ComfyUI_windows_portable` -folder):
|
||||
`python_embeded\python.exe -m pip install ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\wheels\custom_rasterizer-0.1-cp312-cp312-win_amd64.whl`
|
||||
|
||||
**Windows 11 python 3.12 torch 2.6.0 + cu126**
|
||||
Current latest portable was updated to use pytorch 2.6.0, for this you should use new wheel:
|
||||
`python_embeded\python.exe -m pip install ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\wheels\custom_rasterizer-0.1.0+torch260.cuda126-cp312-cp312-win_amd64.whl`
|
||||
|
||||
This was tested to work on latest ComfyUI portable install
|
||||
[](https://www.python.org/downloads/)
|
||||
[](https://pypi.org/project/comfyui-hunyuan3d-wrapper/)
|
||||
[](LICENSE)
|
||||
[](https://github.com/your_repo/comfyui-hunyuan3d-wrapper/actions)
|
||||
|
||||
---
|
||||
|
||||
## If this doesn't work or there isn't a suitable wheel available for your system. you need to compile yourself:
|
||||
## 🚀 Features
|
||||
|
||||
Rasterizer, to build and install:
|
||||
* Supports **Hunyuan3D-2** model for advanced 3D textured generation
|
||||
* Automatic download and wrapping of diffusers models
|
||||
* Highly optimized **Preview3D-node** for interactive model preview
|
||||
* Optional high-performance rasterizer and mesh processor extensions
|
||||
* Integration of **BPT** for improved shape generation (optional)
|
||||
|
||||
---
|
||||
|
||||
## 📂 Project Structure
|
||||
|
||||
```
|
||||
cd hy3dgen/texgen/custom_rasterizer
|
||||
ComfyUI-Hunyuan3DWrapper/
|
||||
│
|
||||
├─ ComfyUI/ # ComfyUI base folder
|
||||
│ └─ custom_nodes/
|
||||
│ └─ ComfyUI-Hunyuan3DWrapper/ # This wrapper
|
||||
│ ├─ hy3dgen/
|
||||
│ │ ├─ texgen/
|
||||
│ │ │ ├─ custom_rasterizer/ # Rasterizer source and build scripts
|
||||
│ │ │ └─ differentiable_renderer/ # Mesh processor extension
|
||||
│ │ └─ shapegen/
|
||||
│ │ └─ bpt/ # Optional BPT feature
|
||||
│ ├─ requirements.txt
|
||||
│ ├─ wheels/ # Precompiled wheels for rasterizer
|
||||
│ └─ README.md
|
||||
│
|
||||
├─ models/ # Place main .ckpt/.safetensors models here
|
||||
│ └─ hunyuan3d-dit-v2-0.safetensors
|
||||
│
|
||||
└─ scripts/ # Useful helper scripts (setup, upgrade, etc)
|
||||
├─ install_dependencies.bat # Windows installation helper
|
||||
├─ compile_rasterizer.bat # Compile rasterizer helper
|
||||
└─ upgrade_xatlas.bat # Automated xatlas upgrade script
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Installation
|
||||
|
||||
### 1. Install dependencies
|
||||
|
||||
In your Python environment or portable ComfyUI:
|
||||
|
||||
```bash
|
||||
pip install -r ComfyUI/custom_nodes/ComfyUI-Hunyuan3DWrapper/requirements.txt
|
||||
```
|
||||
|
||||
Or with portable ComfyUI embedded python:
|
||||
|
||||
```bash
|
||||
python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\requirements.txt
|
||||
```
|
||||
|
||||
### 2. Install precompiled rasterizer wheel (recommended for speed)
|
||||
|
||||
For Python 3.12 + torch 2.6.0 + CUDA 12.6 (Windows 11):
|
||||
|
||||
```bash
|
||||
python_embeded\python.exe -m pip install ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\wheels\custom_rasterizer-0.1.0+torch260.cuda126-cp312-cp312-win_amd64.whl
|
||||
```
|
||||
|
||||
### 3. If precompiled wheel not suitable — compile yourself:
|
||||
|
||||
```bash
|
||||
cd ComfyUI/custom_nodes/ComfyUI-Hunyuan3DWrapper/hy3dgen/texgen/custom_rasterizer
|
||||
python setup.py install
|
||||
```
|
||||
|
||||
**If you are using the portable ComfyUI installation:**
|
||||
For example (check the paths on your system):
|
||||
```
|
||||
Or for portable:
|
||||
|
||||
```bash
|
||||
cd C:\ComfyUI_windows_portable\ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\hy3dgen\texgen\custom_rasterizer
|
||||
C:\ComfyUI_windows_portable\python_embeded\python.exe -m pip install .
|
||||
```
|
||||
|
||||
If you get an error about Python.h missing, refer to the instructions here as it's the same compilation issue (you don't need Triton itself):
|
||||
|
||||
https://github.com/woct0rdho/triton-windows?tab=readme-ov-file#8-special-notes-for-comfyui-with-embeded-python
|
||||
|
||||
|
||||
Or build with `python setup.py bdist_wheel` which creates the .whl file to the dist -subfolder, which you then would pip install to your python environment.
|
||||
End result needs to be `custom_rasterizer_kernel*.pyd` file and `custom_rasterizer` folder in your python environments `site-packages` folder.
|
||||
|
||||
---
|
||||
|
||||
For the mesh_processor extension the build command would be this:
|
||||
```
|
||||
### 4. Mesh Processor Extension (optional for vertex inpainting)
|
||||
|
||||
```bash
|
||||
cd hy3dgen/texgen/differentiable_renderer
|
||||
python_embeded\python.exe setup.py build_ext --inplace
|
||||
```
|
||||
This file is supposed to be in that very folder. It is only used for the vertex inpainting, if this file doesn't exist the fallback is run on cpu and is much slower. The vertex inpainting is on it's own node and in the worst case can just be bypassed, downside would be worse filling of the textures.
|
||||
|
||||
Again, with portable you should use the embedded python to run the commands.
|
||||
|
||||
---
|
||||
|
||||
# Update:
|
||||
### 5. Optional: Install BPT shape generator
|
||||
|
||||
## Added [BPT](https://github.com/whaohan/bpt)
|
||||
|
||||
**This has some hefty requirements, fully optional, install at your own discretion**
|
||||
```
|
||||
cd ComfyUI-Hunyuan3DWrapper\hy3dgen\shapegen\bpt
|
||||
pip install -r requirements.txt
|
||||
```bash
|
||||
pip install -r ComfyUI/custom_nodes/ComfyUI-Hunyuan3DWrapper/hy3dgen/shapegen/bpt/requirements.txt
|
||||
```
|
||||
|
||||
## Installation with portable ComfyUI:
|
||||
from the portable's root directory:
|
||||
`python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\hy3dgen\shapegen\bpt\requirements.txt`
|
||||
Download weights:
|
||||
`bpt-8-16-500m.pt` from
|
||||
[Huggingface BPT weights](https://huggingface.co/whaohan/bpt/blob/refs%2Fpr%2F1/bpt-8-16-500m.pt)
|
||||
|
||||
Download weights <https://huggingface.co/whaohan/bpt/blob/refs%2Fpr%2F1/bpt-8-16-500m.pt>
|
||||
|
||||
Copy `bpt-8-16-500m.pt` to `ComfyUI-Hunyuan3DWrapper-main\hy3dgen\shapegen\bpt`
|
||||
|
||||
# Xatlas upgrade procedure to fix UV wrapping high poly meshes
|
||||
|
||||
`python_embeded\python.exe -m pip uninstall xatlas`
|
||||
|
||||
in the portable root folder (`ComfyUI_windows_portable`):
|
||||
|
||||
`git clone --recursive https://github.com/mworchel/xatlas-python.git`
|
||||
|
||||
`cd .\xatlas-python\extern`
|
||||
|
||||
delete `xatlas` folder
|
||||
|
||||
`git clone --recursive https://github.com/jpcy/xatlas`
|
||||
|
||||
in `xatlas-python\extern\xatlas\source\xatlas` modify `xatlas.cpp`
|
||||
|
||||
change line 6774: `#if 0` to `//#if 0`
|
||||
|
||||
change line 6778: `#endif` to `//#endif`
|
||||
|
||||
Finally go back to portable root (`ComfyUI_windows_portable`) folder:
|
||||
|
||||
`.\python_embeded\python.exe -m pip install .\xatlas-python\`
|
||||
Place weights in:
|
||||
`ComfyUI/custom_nodes/ComfyUI-Hunyuan3DWrapper/hy3dgen/shapegen/bpt`
|
||||
|
||||
---
|
||||
|
||||
## 🛠 Xatlas Upgrade Procedure (Fix UV Wrapping on High-Poly Meshes)
|
||||
|
||||
Run from the **ComfyUI portable root folder**:
|
||||
|
||||
```bash
|
||||
python_embeded\python.exe -m pip uninstall xatlas
|
||||
git clone --recursive https://github.com/mworchel/xatlas-python.git
|
||||
cd xatlas-python\extern
|
||||
rmdir /s /q xatlas
|
||||
git clone --recursive https://github.com/jpcy/xatlas
|
||||
```
|
||||
|
||||
**Modify source for patch**
|
||||
Edit `xatlas-python\extern\xatlas\source\xatlas\xatlas.cpp`:
|
||||
|
||||
* Line 6774: change `#if 0` to `//#if 0`
|
||||
* Line 6778: change `#endif` to `//#endif`
|
||||
|
||||
Finally, install locally:
|
||||
|
||||
```bash
|
||||
cd ..\..\..
|
||||
python_embeded\python.exe -m pip install .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Handy Scripts (Windows batch examples)
|
||||
|
||||
### install\_dependencies.bat
|
||||
|
||||
```bat
|
||||
@echo off
|
||||
echo Installing dependencies...
|
||||
python_embeded\python.exe -m pip install -r ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\requirements.txt
|
||||
pause
|
||||
```
|
||||
|
||||
### compile\_rasterizer.bat
|
||||
|
||||
```bat
|
||||
@echo off
|
||||
cd ComfyUI\custom_nodes\ComfyUI-Hunyuan3DWrapper\hy3dgen\texgen\custom_rasterizer
|
||||
python_embeded\python.exe setup.py install
|
||||
pause
|
||||
```
|
||||
|
||||
### upgrade\_xatlas.bat
|
||||
|
||||
```bat
|
||||
@echo off
|
||||
python_embeded\python.exe -m pip uninstall -y xatlas
|
||||
git clone --recursive https://github.com/mworchel/xatlas-python.git
|
||||
cd xatlas-python\extern
|
||||
rmdir /s /q xatlas
|
||||
git clone --recursive https://github.com/jpcy/xatlas
|
||||
powershell -Command "(Get-Content .\xatlas\source\xatlas\xatlas.cpp) -replace '#if 0', '//#if 0' | Set-Content .\xatlas\source\xatlas\xatlas.cpp"
|
||||
powershell -Command "(Get-Content .\xatlas\source\xatlas\xatlas.cpp) -replace '#endif', '//#endif' | Set-Content .\xatlas\source\xatlas\xatlas.cpp"
|
||||
cd ..\..\..
|
||||
python_embeded\python.exe -m pip install .
|
||||
pause
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Usage Tips & Encouragement
|
||||
|
||||
* Make sure you have a **modern ComfyUI version** supporting Preview3D nodes.
|
||||
* Keep your Python and CUDA versions consistent with your wheels/builds.
|
||||
* When in doubt, compiling from source ensures full compatibility and future-proofing.
|
||||
* Your dedication to pushing boundaries with Hunyuan3D will bring you closer to seamless 3D model creation workflows. Keep experimenting and innovating!
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user