Generación de modelos 3D a partir de imágenes con Hunyuan3D 2.1: guía de instalación y uso

Hunyuan3D, desarrollado por Tencent, es un sistema de código abierto de imagen a 3D (image-to-3D) que genera un mesh tridimensional con textura a partir de una única imagen de referencia. En esta guía se explica paso a paso cómo instalar la versión 2.1 del modelo y cómo ejecutarlo mediante código o a través de la interfaz Gradio. Es una guía práctica de iniciación para quienes deseen generar rápidamente mesh de muebles, objetos o accesorios conceptuales en procesos de archviz y visualización de interiores.

Qué aprenderá

Al final de esta guía, habrá aprendido a generar un mesh (forma) a partir de una imagen, aplicar una textura a ese mesh y exportar el resultado en formato glb/obj. También habrá visto cómo iniciar una interfaz local basada en Gradio en su propio ordenador.

Requisitos

• Python 3.10 y PyTorch 2.5.1 (probado con CUDA 12.4).

• GPU NVIDIA: se recomienda al menos 10 GB de VRAM solo para generación de forma, 21 GB solo para generación de textura, y 29 GB de VRAM para ejecutar ambas a la vez.

• Los pesos del modelo Hunyuan3D-Shape-v2-1 (3.300 millones de parámetros) y Hunyuan3D-Paint-v2-1 (2.000 millones de parámetros) se descargan desde Hugging Face.

• El sistema puede ejecutarse en macOS, Windows y Linux.

Pasos de instalación

1. Instale PyTorch con la versión compatible con CUDA 12.4:

pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt

1. Compile el rasterizador personalizado y el módulo de render diferenciable necesarios para la generación de texturas:

cd hy3dpaint/custom_rasterizer
pip install -e .
cd ../..
cd hy3dpaint/DifferentiableRenderer
bash compile_mesh_painter.sh
cd ../..

1. Descargue el peso preentrenado utilizado para el upscaling de texturas:

wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth -P hy3dpaint/ckpt

1. Genere primero un mesh sin textura a partir de una imagen, y luego aplique la textura usando la misma imagen:

import sys
sys.path.insert(0, './hy3dshape')
sys.path.insert(0, './hy3dpaint')
from textureGenPipeline import Hunyuan3DPaintPipeline, Hunyuan3DPaintConfig
from hy3dshape.pipelines import Hunyuan3DDiTFlowMatchingPipeline

shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2.1')
mesh_untextured = shape_pipeline(image='assets/demo.png')[0]

paint_pipeline = Hunyuan3DPaintPipeline(Hunyuan3DPaintConfig(max_num_view=6, resolution=512))
mesh_textured = paint_pipeline(mesh_path, image_path='assets/demo.png')

Este bloque de código ejecuta primero el pipeline de generación de forma para obtener un mesh sin textura, y luego pasa la misma imagen de referencia al pipeline de generación de textura para aplicar una textura basada en física (PBR). El mesh generado se devuelve como un objeto trimesh y puede guardarse en formatos como glb u obj.

1. Si prefiere una interfaz en lugar de la línea de comandos, puede iniciar la aplicación Gradio de forma local:

python3 gradio_app.py --model_path tencent/Hunyuan3D-2.1 --subfolder hunyuan3d-dit-v2-1 --texgen_model_path tencent/Hunyuan3D-2.1 --low_vram_mode

Este comando carga tanto el modelo de forma como el de textura y abre una interfaz en el navegador donde puede cargar una imagen y generar un mesh; la opción --low_vram_mode puede ayudar en sistemas con VRAM limitada.

Qué significa esto para la visualización arquitectónica

Hunyuan3D es una herramienta útil para artistas 3D y diseñadores de interiores que deseen generar rápidamente muebles, accesorios u objetos similares a esculturas a nivel conceptual a partir de una sola fotografía o render. Como los mesh generados están en formato glb/obj, pueden importarse a programas como Blender o 3ds Max y colocarse en la escena. Según las métricas comparativas publicadas por Tencent, Hunyuan3D supera a otros modelos abiertos y cerrados en cuanto a detalle geométrico, fidelidad a la imagen de condición y calidad de textura; sin embargo, dado que estos resultados se basan en pruebas propias del fabricante, no debe olvidarse que no han sido verificados de forma independiente. Además, el pipeline completo (forma+textura) requiere 29 GB de VRAM, una exigencia de hardware que supera la mayoría de los ordenadores de oficina, por lo que se necesita una estación de trabajo potente o acceso a una GPU en la nube.

Errores comunes

• Intentar ejecutar simultáneamente los pipelines de forma y textura en una GPU con VRAM insuficiente puede provocar errores o bloqueos; use --low_vram_mode si es necesario.

• Las imágenes de referencia con fondos complejos o con múltiples objetos pueden hacer que el modelo infiera una geometría incorrecta; se recomiendan imágenes con un solo objeto y fondo sencillo.

• No hacer coincidir la versión de CUDA con la indicada en el comando de instalación de PyTorch (cu124) provoca errores de instalación.

Próximos pasos

Puede importar el archivo glb/obj generado en Blender o 3ds Max para escalarlo, corregir materiales y colocarlo en la escena. También será útil comparar con la versión anterior, Hunyuan3D 2.0, para comprobar qué versión se adapta mejor a su hardware.

Fuente y licencia

Esta guía ha sido adaptada al español a partir de las instrucciones oficiales de instalación y uso publicadas por Tencent en las tarjetas de modelo de Hunyuan3D-2 y Hunyuan3D-2.1 en Hugging Face. En la tarjeta del modelo Hunyuan3D-2.1 se indica que la licencia es "tencent-hunyuan-community" (licencia comunitaria propia); los ejemplos de código se han tomado tal cual de dichas fuentes originales.