# Hunyuan3D-2.1 Integration for DigiPal

## Overview

The Hunyuan3D pipeline integrates Tencent's state-of-the-art Hunyuan3D-2.1 model into DigiPal, providing advanced 3D generation capabilities for monster creation. This pipeline offers multiple generation modes, high-quality outputs, and seamless integration with the existing DigiPal monster system.

## Features

### Core Capabilities

1. **Text-to-3D Generation**
   - Generate 3D models from text descriptions
   - Automatic concept image generation
   - Two-stage process: shape generation + texture generation

2. **Image-to-3D Generation**
   - Convert single images to 3D models
   - Automatic background removal
   - Foreground ratio control for optimal results

3. **Multi-View Generation**
   - Generate from front, back, left, and right views
   - Higher accuracy than single image input
   - Ideal for complex monster designs

### Generation Modes

- **Turbo Mode**: Fastest generation, suitable for prototypes and baby monsters
- **Fast Mode**: Balanced speed and quality, ideal for most use cases
- **Standard Mode**: Best quality, recommended for final assets

### Export Formats

- **GLB** (recommended): GLTF binary format with embedded textures
- **OBJ**: Wavefront format for compatibility
- **PLY**: Point cloud format
- **STL**: For 3D printing applications

### Texture Options

- **RGB**: Standard color textures
- **PBR**: Physically-based rendering with metallic, roughness, and normal maps

## Installation

1. Ensure you have the required dependencies:
```bash
pip install gradio_client>=0.8.0 trimesh>=4.0.0 aiohttp>=3.9.0
```

2. The pipeline is located at: `src/pipelines/hunyuan3d_pipeline.py`

## Configuration

Create a configuration file or use the default settings:

```python
from src.pipelines.hunyuan3d_pipeline import Hunyuan3DConfig, GenerationMode

config = Hunyuan3DConfig(
    space_id="Tencent/Hunyuan3D-2",  # Official HF Space
    default_mode=GenerationMode.FAST,
    texture_method=TextureMethod.RGB,
    export_format=ExportFormat.GLB,
    target_polycount=30000,
    enable_optimization=True
)
```

## Usage Examples

### Basic Text-to-3D Generation

```python
from src.pipelines.hunyuan3d_pipeline import Hunyuan3DPipeline, GenerationMode

# Initialize pipeline
pipeline = Hunyuan3DPipeline()

# Generate from text
result = await pipeline.generate_from_text(
    prompt="cute blue dragon with big eyes and small wings",
    name="BlueDragon",
    mode=GenerationMode.FAST
)

if result["success"]:
    print(f"Model saved at: {result['paths']['processed_model']}")
```

### Image-to-3D Generation

```python
# Generate from a single image
result = await pipeline.generate_from_image(
    image_path="dragon_concept.png",
    name="DragonFromImage",
    mode=GenerationMode.STANDARD
)
```

### Multi-View Generation

```python
# Generate from multiple views for better accuracy
views = {
    "front": "dragon_front.png",
    "back": "dragon_back.png",
    "left": "dragon_left.png",
    "right": "dragon_right.png"
}

result = await pipeline.generate_from_multi_view(
    image_paths=views,
    name="DragonMultiView",
    mode=GenerationMode.STANDARD
)
```

### DigiPal Monster Integration

```python
from src.pipelines.hunyuan3d_pipeline import DigiPalHunyuan3DIntegration

# Initialize integration
integration = DigiPalHunyuan3DIntegration()

# Generate model for a DigiPal monster
result = await integration.generate_monster_model(
    monster=my_monster,  # DW1Monster instance
    force_regenerate=False
)
```

## Integration with DigiPal System

### Automatic Monster Generation

The pipeline automatically creates appropriate prompts based on monster attributes:

- **Stage**: Determines model complexity (baby → ultimate)
- **Personality**: Influences visual style and pose
- **Species Type**: Affects color scheme and texture
- **Stats**: High offense adds claws, high defense adds armor, etc.

### Evolution Support

Generate complete evolution sequences:

```python
# Generate all evolution stages
results = await integration.generate_evolution_sequence(
    monster=my_monster,
    stages=["baby", "child", "adult", "perfect", "ultimate"]
)
```

### Caching System

- Models are automatically cached to avoid regeneration
- Cache key based on monster ID and evolution stage
- Force regeneration available when needed

## Performance Optimization

### Model Optimization

- Automatic mesh simplification to target polycount
- Geometry cleanup (degenerate faces, duplicates)
- UV optimization for efficient texture mapping
- Watertight mesh generation for rigging

### Generation Speed

- **Turbo Mode**: ~30-60 seconds
- **Fast Mode**: ~1-2 minutes
- **Standard Mode**: ~2-4 minutes

### Batch Processing

Generate multiple models concurrently:

```python
tasks = [
    {"prompt": "fire dragon", "name": "FireDragon"},
    {"prompt": "water turtle", "name": "WaterTurtle"},
    {"prompt": "electric mouse", "name": "ElectricMouse"}
]

results = await pipeline.batch_generate(
    tasks,
    max_concurrent=2  # Process 2 at a time
)
```

## Comparison with Other Pipelines

| Feature | Hunyuan3D | Meshy AI | Open Source |
|---------|-----------|----------|-------------|
| Text-to-3D | ✓ | ✓ | ✓ |
| Image-to-3D | ✓ | Limited | ✓ |
| Multi-View | ✓ | ✗ | ✓ |
| Speed | Fast | Medium | Slow |
| Quality | High | High | Medium |
| PBR Textures | ✓ | ✓ | Limited |
| API Cost | Free* | Paid | Free |
| Auto-Rigging | ✗ | ✓ | ✓ |

*Free via Hugging Face Spaces, subject to usage limits

## Best Practices

### Prompt Engineering

1. **Be Specific**: Include details about size, color, features
2. **Use T-Pose**: Add "T-pose" for better rigging compatibility
3. **Neutral Background**: Specify "neutral background" for cleaner results
4. **Game Asset**: Include "game character" or "game asset" for optimization

### Quality Settings

- Use **Turbo** mode for rapid prototyping
- Use **Fast** mode for development and testing
- Use **Standard** mode for final production assets

### Multi-View Tips

- Ensure consistent lighting across all views
- Use the same background for all images
- Maintain the same scale and position
- Remove shadows for better reconstruction

## Troubleshooting

### Common Issues

1. **Connection Failed**: Check internet connection and HF Space availability
2. **Generation Timeout**: Reduce quality settings or use Turbo mode
3. **Low Quality Output**: Use Standard mode or provide better input images
4. **Missing Textures**: Ensure texture_method is set correctly

### Error Handling

The pipeline includes comprehensive error handling:
- Automatic retries with exponential backoff
- Graceful fallbacks for failed generations
- Detailed error messages in results

## Future Enhancements

- [ ] Animation generation support
- [ ] Advanced rigging integration
- [ ] Real-time preview during generation
- [ ] Custom texture painting
- [ ] Physics simulation setup
- [ ] LOD (Level of Detail) generation

## API Reference

See the inline documentation in `src/pipelines/hunyuan3d_pipeline.py` for detailed API reference.

## Credits

This integration uses Tencent's Hunyuan3D-2.1 model, available through Hugging Face Spaces. Special thanks to the Tencent team for making this technology accessible.