项目预览
项目数据
项目介绍
Star 增长趋势
本站每日记录该项目 GitHub 星标变化,观测越久曲线越完整
数据来源:GitHub API 逐日快照 · 收录于 2026-08-09 · 当前星标 ★ 4483
使用教程
环境要求
- Python 3.10(README 实测版本)
- PyTorch 2.5.1 + cu124(NVIDIA CUDA 环境)
- 能执行 git clone / wget 的网络环境
- 具备 C++ 编译环境(README 要求编译自定义光栅化与渲染扩展)
安装与启动步骤
-
1克隆项目代码
把仓库拉到本地,后续所有相对路径命令都要在仓库根目录执行。
git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1.git cd Hunyuan3D-2.1 -
2安装 PyTorch
按 README 指定的 cu124 源安装 2.5.1 版本的 torch 系列,避免版本不匹配。
pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124 -
3安装项目依赖
在仓库根目录安装 requirements.txt 中的 Python 依赖,建议先用虚拟环境隔离。
pip install -r requirements.txt -
4编译自定义光栅化
进入 hy3dpaint/custom_rasterizer 以可编辑模式安装,完成后回到仓库根目录。
cd hy3dpaint/custom_rasterizer pip install -e . cd ../.. -
5编译可微渲染器
执行官方编译脚本 build_mesh_painter.sh,编译失败通常是缺少 C++/CUDA 编译工具。
cd hy3dpaint/DifferentiableRenderer bash compile_mesh_painter.sh cd ../.. -
6下载超分权重
下载 Real-ESRGAN 的 x4plus 权重到 hy3dpaint/ckpt 目录,供纹理阶段使用。
wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth -P hy3dpaint/ckpt -
7调用 Python API
README 提供类 diffusers 的接口,需先把两个子目录加入 sys.path 再导入管线类。
import sys sys.path.insert(0, './hy3dshape') sys.path.insert(0, './hy3dpaint') from textureGenPipeline import Hunyuan3DPaintPipeline, Hunyuan3DPaintConfig from hy3dshape.pipelines import Hunyuan3DDiTFlowMatchingPipeline
如何确认成功
在仓库根目录执行上述 Python 导入语句,无 ModuleNotFoundError 或编译报错即表示环境安装完成。
常见问题
Q:必须用 Python 3.10 吗?
A:README 的实测环境为 Python 3.10 与 PyTorch 2.5.1+cu124,其他版本可能因依赖或扩展编译不兼容而失败。
Q:GPU 是必需的吗?
A:README 安装命令使用 cu124 版 PyTorch,面向 CUDA 环境;纯 CPU 环境未在文档中说明支持情况。
Q:custom_rasterizer 和 DifferentiableRenderer 安装失败怎么办?
A:这两步是编译自定义扩展,报错多为缺少 C++/CUDA 编译工具链,请先补齐编译环境后重新执行对应命令。
Q:RealESRGAN_x4plus.pth 是做什么的?
A:它是纹理生成阶段用到的超分权重,README 要求放到 hy3dpaint/ckpt 目录下。
注意事项
- 安装步骤必须在克隆后的仓库根目录执行,因为命令使用相对路径切换子目录。
- 建议在独立虚拟环境中安装,避免与已有 torch 版本冲突。
- 项目同时提供官网 https://3d.hunyuan.tencent.com 与 HuggingFace Demo,可先在线体验再本地部署。
核心亮点
- 单图生成高精度几何,细节还原度高,适合复杂物体
- 直接输出PBR材质贴图,省去手动调材质的繁琐步骤
- 开源且提供完整推理代码,支持自定义训练和二次开发
不足之处
- 生成速度较慢,高分辨率输出需要较强GPU资源
- 对复杂拓扑和透明/半透明物体支持有限
- 文档/社区待观察
适用场景
- 游戏开发中快速生成道具和场景资产
- 电商产品展示图快速建模
- 影视特效中的概念设计快速原型
替代项目
TripoSR、Stable Fast 3D、Zero123
上一篇:Wonder3D
下一篇:DreamCraft3D
同类项目推荐
ICCV2023-MCNET
开源
用一张照片生成身份一致的说话头视频
The official code of our ICCV2023 work: Implicit Identity Representation Conditioned···
ScrumSurvivor
开源
摄像头交给 AI 分身,开会走神也看不出破绽。
Survive mandatory camera-on meetings with a photorealistic AI avatar
DreamScene
开源
输入一句话,自动生成多物体 3D 场景,布局合理不打架
[ECCV2024] DreamScene: 3D Gaussian-based Text-to-3D Scene Generation via Formation P···
HunyuanWorld-1.0
开源
一句话或一张图,生成可探索交互的3D世界
Generating Immersive, Explorable, and Interactive 3D Worlds from Words or Pixels wit···
3d-model-anything
开源
手机扫房间,浏览器里编辑三维模型
Capture iPhone LiDAR and photos, reconstruct editable Three.js rooms, and explore th···
reality-engine
开源
用 AI 快速搭建会演变的虚拟世界和故事
Top Dynamic AI World Simulation & Storytelling Tools 2026
Hunyuan3D-1
开源
一句话或一张图,快速生成可用 3D 模型
Tencent Hunyuan3D-1.0: A Unified Framework for Text-to-3D and Image-to-3D Generation
CVPR2022-DaGAN
开源
用深度信息让说话头视频生成更逼真、姿态更可控
Official code for CVPR2022 paper: Depth-Aware Generative Adversarial Network for Tal···
aafactory-prototype
开源
一键生成并管理你的 AI 虚拟形象
⚡ AI Avatar Factory is an interface for creating and managing AI avatars. ⚡
