Génération de modèles 3D à partir d'images avec Hunyuan3D 2.1 : guide d'installation et d'utilisation

Hunyuan3D, développé par Tencent, est un système open source de génération d'images en 3D (image-to-3D) capable de produire un mesh texturé en trois dimensions à partir d'une seule image de référence. Ce guide explique pas à pas comment installer la version 2.1 du modèle et l'exécuter via le code ou l'interface Gradio. C'est un guide de démarrage pratique pour ceux qui souhaitent, dans leurs processus d'archviz et de visualisation d'intérieur, produire rapidement des mesh de meubles, d'objets ou d'accessoires conceptuels.

Ce que vous allez apprendre

À la fin de ce guide, vous saurez générer un mesh (forme) à partir d'une image, appliquer une texture à ce mesh et exporter le résultat au format glb/obj. Vous aurez également vu comment lancer une interface locale basée sur Gradio sur votre propre ordinateur.

Prérequis

• Python 3.10 et PyTorch 2.5.1 (testé avec CUDA 12.4).

• GPU NVIDIA : au moins 10 Go de VRAM pour la génération de forme seule, 21 Go pour la génération de texture seule, 29 Go recommandés pour exécuter les deux ensemble.

• Les poids des modèles Hunyuan3D-Shape-v2-1 (3,3 milliards de paramètres) et Hunyuan3D-Paint-v2-1 (2 milliards de paramètres) sont téléchargés via Hugging Face.

• Le système fonctionne sous macOS, Windows et Linux.

Étapes d'installation

1. Installez PyTorch avec la version compatible 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. Compilez le rasterizer personnalisé et le module de rendu différentiable nécessaires à la génération de texture :

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

1. Téléchargez le poids préentraîné utilisé pour l'amélioration de texture :

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

1. Générez d'abord un mesh non texturé à partir d'une image, puis appliquez la texture en utilisant la même image :

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')

Ce bloc de code exécute d'abord le pipeline de génération de forme pour obtenir un mesh non texturé, puis applique une texture physiquement basée (PBR) en fournissant la même image de référence au pipeline de génération de texture. Le mesh produit est retourné sous forme d'objet trimesh et peut être enregistré dans des formats comme glb ou obj.

1. Si vous préférez une interface plutôt que la ligne de commande, vous pouvez lancer l'application Gradio localement :

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

Cette commande charge à la fois le modèle de forme et de texture, et ouvre une interface dans le navigateur où vous pouvez charger une image et générer un mesh ; l'option --low_vram_mode peut aider sur les systèmes disposant de peu de VRAM.

Ce que cela signifie pour la visualisation architecturale

Hunyuan3D est un outil utilisable pour les artistes 3D et architectes d'intérieur souhaitant produire rapidement, à partir d'une seule photo ou image de rendu, des objets de niveau conceptuel tels que meubles, accessoires ou éléments sculpturaux. Les mesh produits étant au format glb/obj, ils peuvent être importés dans des logiciels comme Blender ou 3ds Max et placés dans une scène. Selon les benchmarks comparatifs publiés par Tencent, Hunyuan3D surpasse d'autres modèles open source et propriétaires en termes de détail géométrique, de fidélité à l'image de référence et de qualité de texture ; cependant, il convient de rappeler que ces résultats reposent sur les propres tests de l'éditeur et n'ont pas fait l'objet d'une vérification indépendante. De plus, le pipeline complet (forme+texture), nécessitant 29 Go de VRAM, représente une exigence matérielle supérieure à celle de la plupart des postes de bureau, ce qui requiert une station de travail puissante ou un accès GPU dans le cloud.

Erreurs courantes

• Tenter d'exécuter simultanément les pipelines de forme et de texture sur un GPU disposant d'une VRAM insuffisante peut entraîner des erreurs ou des plantages ; utilisez --low_vram_mode si nécessaire.

• Des images de référence avec un arrière-plan complexe ou contenant plusieurs objets peuvent amener le modèle à produire une géométrie incorrecte ; il est préférable de privilégier des images avec un seul objet et un arrière-plan simple.

• Ne pas faire correspondre la version CUDA avec celle indiquée dans la commande d'installation de PyTorch (cu124) entraîne des erreurs d'installation.

Étapes suivantes

Vous pouvez importer le fichier glb/obj généré dans Blender ou 3ds Max pour effectuer la mise à l'échelle, la correction des matériaux et le placement dans la scène. Il peut également être utile de comparer avec la version précédente, Hunyuan3D 2.0, pour déterminer laquelle convient le mieux à votre configuration matérielle.

Source et licence

Ce guide a été adapté en français à partir des instructions officielles d'installation et d'utilisation figurant sur les fiches modèles Hunyuan3D-2 et Hunyuan3D-2.1 publiées par Tencent sur Hugging Face. La fiche modèle Hunyuan3D-2.1 indique une licence « tencent-hunyuan-community » (licence communautaire propriétaire) ; les exemples de code sont repris tels quels à partir de ces sources.