إنتاج نماذج ثلاثية الأبعاد من الصور باستخدام Hunyuan3D 2.1: دليل التثبيت والاستخدام

Hunyuan3D الذي طوّرته شركة Tencent هو نظام مفتوح المصدر لتحويل الصورة إلى نموذج ثلاثي الأبعاد (image-to-3D)، يُنتج مجسمًا (mesh) ثلاثي الأبعاد بملمس كامل انطلاقًا من صورة مرجعية واحدة. يشرح هذا الدليل خطوة بخطوة كيفية تثبيت الإصدار 2.1 من النموذج وتشغيله عبر الكود أو من خلال واجهة Gradio. إنه دليل بدء عملي لكل من يريد إنتاج مجسمات سريعة لأثاث أو أجسام أو إكسسوارات على مستوى المفهوم (concept) ضمن عمليات التصور المعماري والتصميم الداخلي.

ماذا ستتعلم

في نهاية هذا الدليل، ستكون قد تعلّمت كيفية إنتاج مجسم (شكل) من صورة، وتطبيق ملمس (texture) على هذا المجسم، وتصدير النتيجة بصيغة glb/obj. كما ستكون قد تعرّفت على كيفية تشغيل واجهة محلية مبنية على Gradio على جهازك الخاص.

المتطلبات

• Python 3.10 و PyTorch 2.5.1 (تم الاختبار مع CUDA 12.4).

• كرت رسوميات NVIDIA: يُنصح بحد أدنى 10 جيجابايت VRAM لإنتاج الشكل فقط، و21 جيجابايت لإنتاج الملمس فقط، و29 جيجابايت لتشغيل العمليتين معًا.

• يتم تنزيل أوزان النموذجين Hunyuan3D-Shape-v2-1 (3.3 مليار معامل) وHunyuan3D-Paint-v2-1 (2 مليار معامل) من منصة Hugging Face.

• يعمل النظام على macOS وWindows وLinux.

خطوات التثبيت

1. قم بتثبيت PyTorch بالإصدار الداعم لـ 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. قم ببناء وحدة rasterizer المخصصة ووحدة الرندر القابلة للاشتقاق اللازمتين لإنتاج الملمس:

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

1. قم بتنزيل الأوزان الجاهزة المستخدمة لرفع جودة الملمس:

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

1. أنتج أولًا مجسمًا بلا ملمس من صورة، ثم طبّق الملمس باستخدام الصورة نفسها:

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

يقوم هذا المقطع البرمجي أولًا بتشغيل خط إنتاج الشكل للحصول على مجسم بلا ملمس، ثم يُمرّر الصورة المرجعية نفسها إلى خط إنتاج الملمس لتطبيق ملمس فيزيائي قائم على المادة (PBR). يُعاد المجسم الناتج ككائن trimesh ويمكن حفظه بصيغ مثل glb/obj.

1. إذا كنت تفضّل واجهة رسومية بدلًا من سطر الأوامر، يمكنك تشغيل تطبيق Gradio محليًا:

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

يقوم هذا الأمر بتحميل نموذجي الشكل والملمس معًا ويفتح واجهة عبر المتصفح تتيح لك رفع صورة وإنتاج مجسم؛ قد يساعد الخيار --low_vram_mode على الأنظمة ذات ذاكرة VRAM المحدودة.

ماذا يعني هذا بالنسبة للتصور المعماري

يُعد Hunyuan3D أداة عملية للفنانين ثلاثيي الأبعاد والمصممين الداخليين الراغبين في إنتاج سريع لمجسمات أثاث أو إكسسوارات أو أجسام شبيهة بالمنحوتات على مستوى المفهوم انطلاقًا من صورة فوتوغرافية أو رندر واحد. وبما أن المجسمات الناتجة بصيغة glb/obj، يمكن استيرادها إلى برامج مثل Blender وTds Max ووضعها داخل المشهد. ووفقًا للقياسات المقارنة التي نشرتها Tencent، يتفوّق Hunyuan3D على نماذج أخرى مفتوحة ومغلقة المصدر من حيث تفاصيل الهندسة ومطابقة الصورة الشرطية وجودة الملمس؛ غير أنه يجب التذكّر أن هذه النتائج مبنية على اختبارات الشركة المصنّعة نفسها ولم يتم التحقق منها بشكل مستقل. كما أن خط التشغيل الكامل (الشكل + الملمس) الذي يتطلب 29 جيجابايت VRAM يفوق إمكانيات معظم حواسيب المكاتب، لذا يلزم محطة عمل قوية أو إمكانية الوصول إلى GPU سحابي.

الأخطاء الشائعة

• محاولة تشغيل خطي الشكل والملمس معًا على كرت رسوميات بذاكرة VRAM غير كافية قد يؤدي إلى خطأ أو تعطّل؛ استخدم --low_vram_mode عند الحاجة.

• الصور المرجعية ذات الخلفيات المعقدة أو التي تحتوي على أكثر من جسم قد تجعل النموذج يستنتج هندسة خاطئة؛ يُفضَّل استخدام صور بجسم واحد وخلفية بسيطة.

• عدم مطابقة إصدار CUDA مع الإصدار المذكور في أمر تثبيت PyTorch (cu124) يؤدي إلى أخطاء في التثبيت.

الخطوات التالية

يمكنك استيراد ملف glb/obj الناتج إلى Blender أو 3ds Max لإجراء تعديلات على المقياس والمواد ووضعه في المشهد. كما سيكون من المفيد مقارنته بالإصدار السابق Hunyuan3D 2.0 لتحديد الإصدار الأنسب لإمكانيات جهازك.

المصدر والترخيص

تم إعداد هذا الدليل بالاستناد إلى تعليمات التثبيت والاستخدام الرسمية المنشورة من قبل Tencent على بطاقات نماذج Hunyuan3D-2 وHunyuan3D-2.1 على منصة Hugging Face. ووفقًا لبطاقة نموذج Hunyuan3D-2.1، فإن الترخيص هو "tencent-hunyuan-community" (ترخيص مجتمعي خاص)؛ وقد تم أخذ أمثلة الكود من هذه المصادر كما هي دون تعديل.