3D-Modellierung aus Bildern mit Hunyuan3D 2.1: Installations- und Nutzungsanleitung

Das von Tencent entwickelte Hunyuan3D ist ein Open-Source-System zur Bild-zu-3D-Umwandlung, das aus einem einzigen Referenzbild ein dreidimensionales, texturiertes Mesh erzeugt. In dieser Anleitung wird Schritt für Schritt erklärt, wie Sie Version 2.1 des Modells installieren und entweder über Code oder die Gradio-Oberfläche ausführen können. Es handelt sich um eine praktische Einstiegsanleitung für alle, die im Rahmen von Archviz- und Innenraumvisualisierungsprozessen schnell Konzept-Meshes für Möbel, Objekte oder Accessoires erstellen möchten.

Was Sie lernen werden

Am Ende dieser Anleitung haben Sie gelernt, aus einem Bild ein Mesh (Form) zu erzeugen, dieses Mesh mit einer Textur zu versehen und das Ergebnis im glb/obj-Format zu exportieren. Außerdem haben Sie gesehen, wie Sie eine lokale, Gradio-basierte Oberfläche auf Ihrem eigenen Computer starten.

Voraussetzungen

• Python 3.10 und PyTorch 2.5.1 (getestet mit CUDA 12.4).

• NVIDIA-GPU: mindestens 10 GB VRAM nur für die Formgenerierung, 21 GB nur für die Texturgenerierung, 29 GB VRAM werden empfohlen, um beides gemeinsam auszuführen.

• Die Modellgewichte Hunyuan3D-Shape-v2-1 (3,3 Milliarden Parameter) und Hunyuan3D-Paint-v2-1 (2 Milliarden Parameter) werden über Hugging Face heruntergeladen.

• Das System läuft unter macOS, Windows und Linux.

Installationsschritte

1. Installieren Sie PyTorch in der Version mit CUDA-12.4-Unterstützung:

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. Kompilieren Sie den speziellen Rasterizer und das differenzierbare Render-Modul, die für die Texturgenerierung benötigt werden:

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

1. Laden Sie das vortrainierte Gewicht für das Textur-Upscaling herunter:

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

1. Erzeugen Sie zunächst aus einem Bild ein unteexturiertes Mesh und wenden Sie anschließend mit demselben Bild die Textur an:

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

Dieser Codeblock führt zunächst die Form-Pipeline aus, um ein untexturiertes Mesh zu erhalten, und übergibt dann dasselbe Referenzbild an die Textur-Pipeline, um eine physikalisch basierte (PBR) Textur anzuwenden. Das erzeugte Mesh wird als trimesh-Objekt zurückgegeben und kann in Formaten wie glb/obj gespeichert werden.

1. Wenn Sie statt der Kommandozeile eine Oberfläche bevorzugen, können Sie die Gradio-Anwendung lokal starten:

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

Dieser Befehl lädt sowohl das Form- als auch das Texturmodell und öffnet eine browserbasierte Oberfläche, über die Sie Bilder hochladen und Meshes erzeugen können; die Option --low_vram_mode kann auf Systemen mit begrenztem VRAM hilfreich sein.

Was bedeutet das für die Architekturvisualisierung

Hunyuan3D ist ein nutzbares Werkzeug für 3D-Künstler und Innenarchitekten, die aus einem einzigen Foto oder Render-Bild schnell konzeptionelle Möbel, Accessoires oder skulpturähnliche Objekte erzeugen möchten. Da die erzeugten Meshes im glb/obj-Format vorliegen, können sie in Software wie Blender oder 3ds Max importiert und in die Szene eingefügt werden. Laut den von Tencent veröffentlichten Vergleichsmessungen übertrifft Hunyuan3D andere Open-Source- und proprietäre Modelle in Bezug auf Geometriedetails, Übereinstimmung mit dem Referenzbild und Texturqualität; es sollte jedoch beachtet werden, dass diese Ergebnisse auf internen Tests des Herstellers beruhen und keine unabhängige Überprüfung stattgefunden hat. Zudem erfordert die vollständige Pipeline (Form+Textur) mit 29 GB VRAM eine Hardwareanforderung, die über der Kapazität der meisten Büro-Computer liegt, weshalb eine leistungsstarke Workstation oder Cloud-GPU-Zugang notwendig ist.

Häufige Fehler

• Der Versuch, sowohl die Form- als auch die Texturpipeline gleichzeitig auf einer GPU mit unzureichendem VRAM auszuführen, kann zu Fehlern oder Abstürzen führen; verwenden Sie bei Bedarf --low_vram_mode.

• Referenzbilder mit komplexem Hintergrund oder mehreren Objekten können dazu führen, dass das Modell eine falsche Geometrie ableitet; bevorzugen Sie Bilder mit einem einzelnen Objekt und einfachem Hintergrund.

• Wenn die CUDA-Version nicht mit der im PyTorch-Installationsbefehl angegebenen Version (cu124) übereinstimmt, führt dies zu Installationsfehlern.

Nächste Schritte

Sie können die erzeugte glb/obj-Datei in Blender oder 3ds Max importieren, um Skalierung, Materialkorrektur und Platzierung in der Szene vorzunehmen. Es lohnt sich auch, einen Vergleich mit der vorherigen Version Hunyuan3D 2.0 durchzuführen, um zu testen, welche Version besser zu Ihrer Hardware passt.

Quelle und Lizenz

Diese Anleitung wurde aus den offiziellen Installations- und Nutzungsanweisungen der von Tencent auf Hugging Face veröffentlichten Modellkarten von Hunyuan3D-2 und Hunyuan3D-2.1 ins Deutsche übertragen. Auf der Modellkarte von Hunyuan3D-2.1 wird die Lizenz als „tencent-hunyuan-community“ (spezielle Community-Lizenz) angegeben; die Codebeispiele wurden im Original aus diesen Quellen übernommen.