Генерация 3D-моделей из изображения с Hunyuan3D 2.1: руководство по установке и использованию

Hunyuan3D, разработанная компанией Tencent, — это открытая система image-to-3D, создающая из одного референсного изображения текстурированный трёхмерный меш. В этом руководстве пошагово описано, как установить версию 2.1 модели и запустить её через код или интерфейс Gradio. Это практическое руководство для тех, кто занимается archviz и визуализацией интерьеров и хочет быстро получать концептуальные меши мебели, объектов или аксессуаров.

Чему вы научитесь

К концу этого руководства вы научитесь генерировать меш (форму) из изображения, применять к нему текстуру и экспортировать результат в формате glb/obj. Вы также увидите, как запустить локальный интерфейс на базе Gradio на своём компьютере.

Требования

• Python 3.10 и PyTorch 2.5.1 (протестировано с CUDA 12.4).

• NVIDIA GPU: минимум 10 ГБ VRAM только для генерации формы, 21 ГБ только для генерации текстуры, рекомендуется 29 ГБ VRAM для совместного запуска обоих модулей.

• Веса моделей 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. Соберите специальный растеризатор и модуль дифференцируемого рендеринга, необходимые для генерации текстур:

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 — полезный инструмент для 3D-художников и дизайнеров интерьеров, которым нужно быстро получать концептуальные меши мебели, аксессуаров или скульптурных объектов из одной фотографии или рендера. Поскольку сгенерированные меши сохраняются в формате glb/obj, их можно импортировать в такие программы, как Blender или 3ds Max, и разместить в сцене. Согласно опубликованным Tencent сравнительным метрикам, Hunyuan3D превосходит другие открытые и закрытые модели по детализации геометрии, соответствию условному изображению и качеству текстур; однако стоит помнить, что эти результаты основаны на внутренних тестах производителя и не прошли независимую проверку. Кроме того, полный пайплайн (форма+текстура), требующий 29 ГБ VRAM, предъявляет требования к оборудованию, превышающие возможности большинства офисных компьютеров, поэтому понадобится мощная рабочая станция или облачный GPU.

Частые ошибки

• Попытка одновременно запустить пайплайны формы и текстуры на GPU с недостаточным объёмом VRAM может привести к ошибке или сбою; при необходимости используйте --low_vram_mode.

• Референсные изображения со сложным фоном или несколькими объектами могут привести к тому, что модель извлечёт неверную геометрию; предпочтительны изображения с одним объектом и простым фоном.

• Несовпадение версии CUDA с версией, указанной в команде установки PyTorch (cu124), приводит к ошибкам установки.

Следующие шаги

Импортировав полученный файл glb/obj в Blender или 3ds Max, вы можете выполнить масштабирование, коррекцию материалов и размещение в сцене. Также будет полезно сравнить результаты с предыдущей версией Hunyuan3D 2.0, чтобы определить, какая версия подходит под ваше оборудование.

Источник и лицензия

Это руководство адаптировано на русский язык на основе официальных инструкций по установке и использованию из карточек моделей Hunyuan3D-2 и Hunyuan3D-2.1, опубликованных Tencent на Hugging Face. В карточке модели Hunyuan3D-2.1 указана лицензия «tencent-hunyuan-community» (специальная общественная лицензия); примеры кода взяты из этих источников в оригинальном виде.