ComfyUI Extension: ComfyUI HunyuanWorld - Complete 3D Generation Suite

Authored by A043-studios

Created

Updated

0 stars

ComfyUI custom nodes for Hunyuan3D - Complete 3D generation suite

Custom Nodes (0)

    README

    ComfyUI HunyuanWorld - Complete 3D Generation Suite

    CI License: MIT Python 3.8+ ComfyUI

    A comprehensive ComfyUI custom node package that provides multiple approaches to 3D generation using Hunyuan3D models. This package offers both simplified interfaces and advanced workflows for creating 3D models from images.

    šŸŒŸ Features

    Four Different Approaches:

    1. šŸ”„ Real Hunyuan3D Pipeline Implementation - Direct integration with official Hunyuan3D library
    2. šŸŽÆ Simplified Wrapper - Easy-to-use interface wrapping existing ComfyUI nodes
    3. āš™ļø Native ComfyUI Workflow - Using built-in ComfyUI Hunyuan3D nodes directly
    4. šŸ”€ Hybrid Approach - Combines custom functionality with existing infrastructure

    šŸ“¦ Installation

    šŸš€ Quick Install from GitHub (Recommended)

    Method 1: ComfyUI Manager (Easiest)

    1. Open ComfyUI Manager
    2. Search for "HunyuanWorld"
    3. Click Install
    4. Restart ComfyUI

    Method 2: Git Clone

    # Navigate to ComfyUI custom_nodes directory
cd ComfyUI/custom_nodes

# Clone the repository
git clone https://github.com/A043-studios/ComfyUI_HunyuanWorldnode.git

# Navigate to the cloned directory
cd ComfyUI_HunyuanWorldnode

# Run the installation script
python install.py

# Or install manually
pip install -r requirements.txt

    Method 3: Direct Download

    1. Download the latest release
    2. Extract to ComfyUI/custom_nodes/ComfyUI_HunyuanWorldnode
    3. Run python install.py or pip install -r requirements.txt
    4. Restart ComfyUI

    šŸ”§ Manual Installation

    Core Dependencies

    pip install torch>=2.0.0 transformers>=4.30.0 diffusers>=0.21.0
pip install trimesh>=3.15.0 numpy>=1.21.0 Pillow>=9.0.0

    Optional Dependencies

    # For enhanced functionality
pip install accelerate>=0.20.0 opencv-python>=4.5.0
pip install fastapi>=0.68.0 uvicorn>=0.15.0 gradio>=3.0.0

    Hunyuan3D from Source (Latest Features)

    git clone https://github.com/tencent/hunyuan3d-2.git
cd hunyuan3d-2
pip install -e .

    šŸ³ Docker Installation (Coming Soon)

    # Pull the Docker image
docker pull a043studios/comfyui-hunyuanworld:latest

# Run with GPU support
docker run --gpus all -p 8188:8188 a043studios/comfyui-hunyuanworld:latest

    šŸš€ Quick Start

    Method 1: Using Real Hunyuan3D Pipeline (Recommended)

    # 1. Load the model
model_loader = HunyuanWorldModelLoader()
pipeline = model_loader.load_model(
    model_name="tencent/Hunyuan3D-2mini",  # Faster, less VRAM
    precision="fp16",
    enable_texture=True,
    low_vram_mode=True
)

# 2. Generate 3D from image
generator = HunyuanWorldImageTo3D()
mesh_path, info, preview = generator.generate_3d(
    pipeline=pipeline,
    image=your_image,
    apply_texture=True,
    save_mesh=True,
    filename_prefix="my_3d_model"
)

    Method 2: Simplified Wrapper

    # One-click 3D generation
simple_wrapper = HunyuanWorldSimplifiedWrapper()
result_info, preview = simple_wrapper.simple_generate(
    image=your_image,
    model_variant="mini",  # or "standard", "multiview"
    resolution=1024,
    enable_texture=True,
    filename_prefix="simple_3d"
)

    šŸ“‹ Node Reference

    šŸ”„ Real Implementation Nodes

    HunyuanWorldModelLoader

    Purpose: Load Hunyuan3D models with proper memory management

    Inputs:

    • model_name: Choose from "tencent/Hunyuan3D-2", "tencent/Hunyuan3D-2mini", "tencent/Hunyuan3D-2mv"
    • precision: "fp16" (recommended) or "fp32"
    • enable_texture: Enable texture synthesis pipeline
    • low_vram_mode: Optimize for low VRAM systems

    Outputs:

    • pipeline: Loaded Hunyuan3D pipeline ready for generation

    HunyuanWorldImageTo3D

    Purpose: Generate 3D meshes from input images

    Inputs:

    • pipeline: Output from HunyuanWorldModelLoader
    • image: Input image (ComfyUI IMAGE format)
    • apply_texture: Whether to apply texture to the mesh
    • save_mesh: Save mesh as GLB file
    • filename_prefix: Prefix for saved files
    • seed (optional): Random seed for reproducible results

    Outputs:

    • mesh_path: Path to saved GLB file
    • info: Generation information
    • preview_image: Rendered preview of the 3D mesh

    šŸŽÆ Simplified Nodes

    HunyuanWorldSimplifiedWrapper

    Purpose: One-click 3D generation for beginners

    Inputs:

    • image: Input image
    • model_variant: "standard", "mini", or "multiview"
    • resolution: Output resolution (512-2048)
    • enable_texture: Apply texture
    • filename_prefix: File naming prefix

    Outputs:

    • result_info: Generation status and information
    • preview: Preview image of the result

    šŸ”€ Hybrid Nodes

    HunyuanWorldHybridNode

    Purpose: Flexible generation with multiple backend options

    Inputs:

    • mode: "direct_pipeline" or "comfyui_workflow"
    • image: Input image
    • model_name: Hunyuan3D model to use
    • use_texture: Enable texture synthesis
    • filename_prefix: File naming
    • existing_latent (optional): Use existing latent from ComfyUI workflow
    • existing_conditioning (optional): Use existing conditioning

    Outputs:

    • mesh_path: Path to generated mesh
    • preview: Preview image
    • method_info: Information about the method used

    šŸ”§ Using Native ComfyUI Hunyuan3D Nodes

    ComfyUI already includes powerful Hunyuan3D nodes. Here's how to use them:

    Basic Workflow:

    1. EmptyLatentHunyuan3Dv2 - Create latent space

      resolution: 3072 (or 1536 for faster generation)
batch_size: 1

    2. CLIPVisionLoader + CLIPVisionEncode - Process input image

      Load CLIP vision model ā†’ Encode your image

    3. Hunyuan3Dv2Conditioning - Create conditioning

      Connect CLIP vision output ā†’ Get positive/negative conditioning

    4. Load Hunyuan3D Model + KSampler - Generate

      Load model ā†’ Sample with conditioning ā†’ Get latent output

    5. VAEDecodeHunyuan3D - Decode to voxels

      latent ā†’ voxels (with octree_resolution: 256)

    6. VoxelToMesh - Convert to mesh

      voxels ā†’ mesh (with threshold: 0.5)

    7. SaveGLB - Save final result

      mesh ā†’ GLB file

    Advanced Multi-View Workflow:

    Use Hunyuan3Dv2ConditioningMultiView for better results:

    front_image ā†’ CLIP encode ā†’ front conditioning
left_image ā†’ CLIP encode ā†’ left conditioning
back_image ā†’ CLIP encode ā†’ back conditioning
right_image ā†’ CLIP encode ā†’ right conditioning
ā†’ Combine in MultiView node ā†’ Enhanced conditioning

    šŸŽ›ļø Model Variants

    tencent/Hunyuan3D-2

    • Best quality but requires more VRAM
    • Recommended for: High-quality final outputs
    • VRAM requirement: ~8GB+

    tencent/Hunyuan3D-2mini

    • Balanced quality and speed
    • Recommended for: Most users, development, testing
    • VRAM requirement: ~4GB+

    tencent/Hunyuan3D-2mv

    • Multi-view optimized
    • Recommended for: When you have multiple view images
    • VRAM requirement: ~6GB+

    šŸ’” Tips and Best Practices

    For Best Results:

    1. Use high-quality input images (512x512 or higher)
    2. Clear subject isolation - objects with clean backgrounds work better
    3. Good lighting - avoid harsh shadows or overexposure
    4. Single objects - works better than complex scenes

    Performance Optimization:

    1. Use fp16 precision for 2x speed improvement
    2. Enable low_vram_mode if you have limited GPU memory
    3. Start with mini model for testing, upgrade to full model for final output
    4. Use smaller resolutions (1536 instead of 3072) for faster iteration

    Troubleshooting:

    • Out of memory: Enable low_vram_mode, use fp16, or use mini model
    • Poor quality: Try full model, higher resolution, or better input image
    • Import errors: Install requirements with pip install -r requirements.txt

    šŸ”„ Workflow Examples

    Example 1: Quick 3D Generation

    LoadImage ā†’ HunyuanWorldModelLoader ā†’ HunyuanWorldImageTo3D ā†’ Preview3D

    Example 2: Advanced Pipeline

    LoadImage ā†’ CLIPVisionEncode ā†’ Hunyuan3Dv2Conditioning ā†’
EmptyLatentHunyuan3Dv2 ā†’ KSampler ā†’ VAEDecodeHunyuan3D ā†’
VoxelToMesh ā†’ SaveGLB

    Example 3: Hybrid Approach

    LoadImage ā†’ HunyuanWorldHybridNode (mode: direct_pipeline) ā†’ Preview

    šŸ†š Comparison: Custom vs Built-in Nodes

    | Feature | Custom Nodes | Built-in ComfyUI Nodes | |---------|--------------|-------------------------| | Ease of use | ā­ā­ā­ā­ā­ Simple | ā­ā­ā­ Complex workflow | | Flexibility | ā­ā­ā­ Good | ā­ā­ā­ā­ā­ Maximum | | Performance | ā­ā­ā­ā­ Direct | ā­ā­ā­ā­ā­ Optimized | | Memory usage | ā­ā­ā­ Standard | ā­ā­ā­ā­ā­ Efficient | | Customization | ā­ā­ā­ Limited | ā­ā­ā­ā­ā­ Full control |

    Recommendation:

    • Beginners: Use custom simplified wrapper
    • Advanced users: Use built-in ComfyUI workflow
    • Developers: Use hybrid approach for maximum flexibility

    šŸ› Troubleshooting

    Common Issues:

    1. "Hunyuan3D libraries not available"

      pip install -r requirements.txt

    2. CUDA out of memory

      # Use these settings:
low_vram_mode=True
precision="fp16"
model_name="tencent/Hunyuan3D-2mini"

    3. Slow generation

      # Optimize with:
resolution=1536  # instead of 3072
model_variant="mini"

    4. Poor mesh quality

      # Try:
model_name="tencent/Hunyuan3D-2"  # full model
resolution=3072
apply_texture=True

    šŸ“š Additional Resources

    šŸ¤ Contributing

    Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

    šŸ“„ License

    This project follows the same license as the original Hunyuan3D project. Please refer to the official repository for license details.

    Made with ā¤ļø for the ComfyUI community