Hunyuan3D 2.1 ilə şəkildən 3D model yaratmaq: quraşdırma və istifadə təlimatı

Tencent tərəfindən hazırlanan Hunyuan3D, tək bir istinad şəklindən üç ölçülü, toxumalı mesh yaradan açıq mənbəli şəkildən-3D-yə (image-to-3D) sistemdir. Bu təlimatda modelin 2.1 versiyasını necə quraşdırıb kod vasitəsilə və ya Gradio interfeysi ilə işlədə biləcəyiniz addım-addım izah olunur. Archviz və interyer vizuallaşdırma proseslərində sürətlə konsept mebel, obyekt və ya aksesuar mesh-i yaratmaq istəyənlər üçün praktik başlanğıc bələdçisidir.

Nə öyrənəcəksiniz

Bu bələdçinin sonunda bir şəkildən mesh (forma) yaratmağı, həmin mesh-ə toxuma (texture) tətbiq etməyi və nəticəni glb/obj formatında ixrac etməyi öyrənmiş olacaqsınız. Həmçinin öz kompüterinizdə Gradio əsaslı yerli interfeys başlatmağı da görmüş olacaqsınız.

Tələblər

• Python 3.10 və PyTorch 2.5.1 (CUDA 12.4 ilə test edilib).

• NVIDIA GPU: yalnız forma yaratmaq üçün ən azı 10 GB VRAM, yalnız toxuma yaratmaq üçün 21 GB, ikisini birlikdə işlətmək üçün 29 GB VRAM tövsiyə olunur.

• Hunyuan3D-Shape-v2-1 (3,3 milyard parametr) və Hunyuan3D-Paint-v2-1 (2 milyard parametr) model çəkiləri Hugging Face üzərindən endirilir.

• Sistem macOS, Windows və Linux üzərində işləyə bilir.

Quraşdırma addımları

1. PyTorch-u CUDA 12.4 dəstəkli versiya ilə quraşdırın:

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. Toxuma yaratmaq üçün lazım olan xüsusi rasterizer və fərqlənə bilən render modulunu kompilyasiya edin:

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

1. Toxuma yüksəltmək üçün istifadə olunan hazır çəkini endirin:

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

1. Bir şəkildən əvvəlcə toxumasız mesh yaradın, sonra eyni şəkli istifadə edərək toxuma tətbiq edin:

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 bloku əvvəlcə forma yaratma xəttini işə salıb toxumasız mesh əldə edir, sonra toxuma yaratma xəttinə eyni istinad şəklini verərək fiziki əsaslı (PBR) toxuma tətbiq edir. Yaradılan mesh trimesh obyekti kimi qaytarılır və glb/obj kimi formatlara saxlanıla bilər.

1. Əmr sətri əvəzinə interfeys üstünlük verirsinizsə, Gradio tətbiqini yerli olaraq başlada bilərsiniz:

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 əmr həm forma, həm də toxuma modelini yükləyib brauzer üzərindən şəkil yükləyib mesh yarada biləcəyiniz interfeys açır; --low_vram_mode seçimi məhdud VRAM-lı sistemlərdə kömək edə bilər.

Bu, memarlıq vizuallaşdırması üçün nə deməkdir

Hunyuan3D, tək bir fotoşəkil və ya render görüntüsündən sürətlə konsept səviyyəli mebel, aksesuar və ya heykəl bənzəri obyektlər yaratmaq istəyən 3D sənətçilər və interyer dizaynerləri üçün istifadə oluna bilən bir alətdir. Yaradılan mesh-lər glb/obj formatında olduğundan Blender, 3ds Max kimi proqramlara daxil edilib səhnəyə yerləşdirilə bilər. Tencent-in dərc etdiyi müqayisəli ölçmələrə görə Hunyuan3D geometriya detalı, şərt şəklinə uyğunluq və toxuma keyfiyyəti baxımından digər açıq və qapalı mənbəli modelləri geridə qoyur; lakin bu nəticələrin istehsalçının öz testlərinə əsaslandığı və müstəqil yoxlamanın aparılmadığı unudulmamalıdır. Həmçinin 29 GB VRAM tələb edən tam xətt (forma+toxuma) əksər ofis kompüterlərinin imkanlarından üstün avadanlıq tələbidir, buna görə güclü iş stansiyası və ya bulud GPU girişi lazımdır.

Tez-tez rastlanan xətalar

• Kifayət qədər VRAM-ı olmayan GPU-da həm forma, həm toxuma xəttini eyni anda işlətməyə çalışmaq xəta və ya çökməyə səbəb ola bilər; lazım gələrsə --low_vram_mode istifadə edin.

• Mürəkkəb fonlu və ya birdən çox obyekt olan istinad şəkilləri modelin yanlış geometriya çıxarmasına səbəb ola bilər; tək obyektli, sadə fonlu şəkillər seçilməlidir.

• CUDA versiyasını PyTorch quraşdırma əmrindəki versiya (cu124) ilə uyğunlaşdırmamaq quraşdırma xətalarına yol açır.

Növbəti addımlar

Yaradılan glb/obj faylını Blender və ya 3ds Max-a daxil edərək miqyaslama, material düzəlişi və səhnəyə yerləşdirmə edə bilərsiniz. Əvvəlki versiya olan Hunyuan3D 2.0 ilə müqayisə edərək hansı versiyanın avadanlığınıza uyğun olduğunu test etmək də faydalı olacaq.

Mənbə və lisenziya

Bu bələdçi Tencent tərəfindən Hugging Face üzərində dərc edilən Hunyuan3D-2 və Hunyuan3D-2.1 model kartlarındakı rəsmi quraşdırma və istifadə təlimatlarından Azərbaycan dilinə uyğunlaşdırılıb. Hunyuan3D-2.1 model kartında lisenziya "tencent-hunyuan-community" (xüsusi icma lisenziyası) olaraq göstərilib; kod nümunələri bu mənbələrdən orijinal halında götürülüb.