Hunyuan3D 2.1 ile görselden 3D model üretimi: kurulum ve kullanım rehberi

Tencent'in geliştirdiği Hunyuan3D, tek bir referans görselden üç boyutlu, dokulu bir mesh üreten açık kaynaklı bir görüntüden-3D'ye (image-to-3D) sistemdir. Bu rehberde, modelin 2.1 sürümünü kurup kod üzerinden veya Gradio arayüzüyle nasıl çalıştırabileceğiniz adım adım anlatılıyor. Archviz ve iç mekan görselleştirme süreçlerinde hızlı konsept mobilya, obje veya aksesuar mesh'i üretmek isteyenler için pratik bir başlangıç rehberidir.

Ne öğreneceksiniz

Bu rehberin sonunda, bir görselden mesh (şekil) üretmeyi, bu mesh'e doku (texture) uygulamayı ve sonucu glb/obj formatında dışa aktarmayı öğrenmiş olacaksınız. Ayrıca kendi bilgisayarınızda Gradio tabanlı yerel bir arayüz başlatmayı da görmüş olacaksınız.

Gereksinimler

• Python 3.10 ve PyTorch 2.5.1 (CUDA 12.4 ile test edilmiştir).

Kurulum adımları

1. PyTorch'u CUDA 12.4 destekli sürümle kurun:

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. Doku üretimi için gereken özel rasterizer ve fark edilebilir render modülünü derleyin:

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

1. Doku yükseltme için kullanılan hazır ağırlığı indirin:

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

1. Bir görselden önce dokusuz mesh üretin, ardından aynı görseli kullanarak doku uygulayın:

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

Bu kod bloğu, önce şekil üretim hattını çalıştırıp dokusuz bir mesh elde ediyor, ardından doku üretim hattına aynı referans görseli vererek fiziksel tabanlı (PBR) bir doku uyguluyor. Üretilen mesh bir trimesh nesnesi olarak döner ve glb/obj gibi formatlara kaydedilebilir.

1. Komut satırı yerine arayüz tercih ederseniz, Gradio uygulamasını yerel olarak başlatabilirsiniz:

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

Bu komut, hem şekil hem doku modelini yükleyip tarayıcı üzerinden görsel yükleyip mesh üretebileceğiniz bir arayüz açar; --low_vram_mode seçeneği sınırlı VRAM'li sistemlerde yardımcı olabilir.

Bu, mimari görselleştirme için ne anlama geliyor

Hunyuan3D, tek bir fotoğraf veya render görselinden hızlıca konsept düzeyinde mobilya, aksesuar veya heykel benzeri objeler üretmek isteyen 3D sanatçılar ve iç mimarlar için kullanılabilir bir araçtır. Üretilen mesh'ler glb/obj formatında olduğundan Blender, 3ds Max gibi yazılımlara aktarılıp sahneye yerleştirilebilir. Tencent'in yayınladığı karşılaştırmalı ölçümlere göre Hunyuan3D, geometri detayı, koşul görseline uyum ve doku kalitesi bakımından diğer açık ve kapalı kaynaklı modelleri geride bırakıyor; ancak bu sonuçlar üreticinin kendi testlerine dayandığından bağımsız doğrulama yapılmadığı unutulmamalıdır. Ayrıca 29 GB VRAM gerektiren tam hat (şekil+doku), çoğu ofis bilgisayarının üzerinde bir donanım talebi olduğundan, güçlü bir iş istasyonu veya bulut GPU erişimi gerekir.

Yaygın hatalar

• Yetersiz VRAM'li bir GPU'da hem şekil hem doku hattını aynı anda çalıştırmaya çalışmak hata veya çökmeye yol açabilir; gerekirse --low_vram_mode kullanın.

• Karmaşık arka planlı veya birden fazla nesne içeren referans görseller, modelin yanlış geometri çıkarmasına neden olabilir; tek nesneli, sade arka planlı görseller tercih edilmelidir.

• CUDA sürümünü PyTorch kurulum komutundaki sürümle (cu124) eşleştirmemek kurulum hatalarına yol açar.

Sonraki adımlar

Üretilen glb/obj dosyasını Blender veya 3ds Max'e aktararak ölçeklendirme, malzeme düzeltmesi ve sahneye yerleştirme yapabilirsiniz. Daha önceki sürüm olan Hunyuan3D 2.0 ile karşılaştırma yaparak hangi sürümün donanımınıza uygun olduğunu test etmeniz de faydalı olacaktır.

Kaynak ve lisans

Bu rehber, Tencent tarafından Hugging Face üzerinde yayınlanan Hunyuan3D-2 ve Hunyuan3D-2.1 model kartlarındaki resmi kurulum ve kullanım talimatlarından Türkçeye uyarlanmıştır. Hunyuan3D-2.1 model kartında lisans "tencent-hunyuan-community" (özel topluluk lisansı) olarak belirtilmiştir; kod örnekleri bu kaynaklardan orijinal haliyle alınmıştır.