项目预览
项目数据
项目介绍
Star 增长趋势
本站每日记录该项目 GitHub 星标变化,观测越久曲线越完整
数据来源:GitHub API 逐日快照 · 收录于 2026-08-09 · 当前星标 ★ 2977
使用教程
ℹ 本教程由 AI 依据该项目 README 整理,个别步骤可能需要按你的环境微调。
环境要求
- Python 3 环境(需能运行 pip 与 python3)
- NVIDIA GPU,且命令行可用 CUDA_VISIBLE_DEVICES 指定显卡
- 编译工具链:cmake、make、gcc/g++(用于编译 draco)
- 网络可访问 GitHub 与 huggingface.co(下载仓库与 onnx 权重)
- 磁盘空间用于存放 Real-ESRGAN、ZIM、draco 及生成的 3D 结果
安装与启动步骤
-
1克隆主仓库
从 GitHub 拉取 HunyuanWorld-1.0 源码,之后所有命令都在该目录下执行。
git clone https://github.com/Tencent-Hunyuan/HunyuanWorld-1.0.git cd HunyuanWorld-1.0 -
2安装 Real-ESRGAN
超分辨率前处理依赖,按 README 依次安装 basicsr-fixed、facexlib、gfpgan 并执行 develop 安装。
git clone https://github.com/xinntao/Real-ESRGAN.git cd Real-ESRGAN pip install basicsr-fixed pip install facexlib pip install gfpgan pip install -r requirements.txt python setup.py develop -
3安装 ZIM 与权重
安装 ZIM 包并以可编辑模式安装,再新建目录下载 encoder.onnx 与 decoder.onnx 两个模型文件。
cd .. git clone https://github.com/naver-ai/ZIM.git cd ZIM pip install -e . mkdir zim_vit_l_2092 cd zim_vit_l_2092 wget https://huggingface.co/naver-iv/zim-anything-vitl/resolve/main/zim_vit_l_2092/encoder.onnx wget https://huggingface.co/naver-iv/zim-anything-vitl/resolve/main/zim_vit_l_2092/decoder.onnx -
4编译安装 draco
导出 draco 格式网格时必须安装,用 cmake 构建后执行 sudo make install 写入系统。
cd ../.. git clone https://github.com/google/draco.git cd draco mkdir build cd build cmake .. make sudo make install -
5快速开始测试
回到项目根目录运行官方测试脚本,用官方 examples 跑通完整流程,验证环境是否装好。
cd ../.. bash scripts/test.sh -
6图像生成全景图
用 demo_panogen.py 由图片生成全景图,开启 fp8 量化与缓存降低显存占用并加速推理。
python3 demo_panogen.py --prompt "" --image_path examples/case2/input.png --output_path test_results/case2_quant --fp8_gemm --fp8_attention -
7全景图生成3D场景
用 demo_scenegen.py 把上一步输出的 panorama.png 转成可交互 3D 世界,可指定前景标签与场景类别。
CUDA_VISIBLE_DEVICES=0 python3 demo_scenegen.py --image_path test_results/case2_quant/panorama.png --labels_fg1 stones --labels_fg2 trees --classes outdoor --output_path test_results/case2_quant --fp8_gemm --fp8_attention
关键配置
| 配置项 | 必填 | 说明 | 示例 |
|---|---|---|---|
--image_path | 是 | 输入图片路径,图像到世界的起点 | examples/case2/input.png |
--output_path | 是 | 结果输出目录,全景图与 3D 场景写在这里 | test_results/case2_quant |
--prompt | 否 | 文本提示词,留空则仅依据输入图片生成 | At the moment of glacier collapse, giant ice walls collapse |
--fp8_gemm | 否 | 开启 fp8 矩阵运算量化,降低显存占用 | --fp8_gemm |
--fp8_attention | 否 | 开启 fp8 注意力量化,进一步节省显存 | --fp8_attention |
CUDA_VISIBLE_DEVICES | 否 | 指定使用的 GPU 编号,多卡机器上常用 | 0 |
如何确认成功
运行 bash scripts/test.sh 无报错结束,并在 test_results 目录下看到生成的全景图与 3D 场景结果文件。
常见问题
Q:显存不够、推理很慢怎么办?
A:README 建议使用量化与缓存,即在命令中加上 --fp8_gemm 与 --fp8_attention,可同时优化显存占用和推理速度。
Q:必须编译安装 draco 吗?
A:只有需要导出 draco 格式时才必须。README 明确说明要导出 draco 格式必须先克隆 google/draco 并 cmake 编译、sudo make install。
Q:如何只用文字生成 3D 世界?
A:可参照示例,在 demo_panogen.py 中传入 --prompt 文本并给出 --output_path,再用 demo_scenegen.py 处理生成的全景图。
Q:demo_scenegen.py 里的前景标签怎么填?
A:--labels_fg1、--labels_fg2 填写想强调的前景物体英文名,例如 stones、trees;--classes 填场景类别如 outdoor。
注意事项
- 仓库与模型权重来自 GitHub、huggingface.co,国内网络可能较慢,建议提前配置代理或镜像。
- 编译安装 draco 需要 sudo 权限,无 root 权限的机器请改用自定义安装前缀。
- 运行推理前请确认 CUDA 可用,否则 fp8 相关参数无法生效。
- 示例命令中的路径(examples/、test_results/)为相对项目根目录,请先切换回 HunyuanWorld-1.0 根目录再执行。
核心亮点
- 支持文本和图像双模态输入,生成完整3D场景,降低创作门槛
- 生成的世界具备物理交互性,用户可自由漫游和操作物体
- 基于腾讯混元大模型技术,效果在同类中领先,且代码开源
不足之处
- 项目较新,文档和社区生态待观察
- 对计算资源要求高,普通用户难以本地部署
适用场景
- 游戏开发中快速生成3D关卡原型
- 影视制作中辅助场景概念设计
- 虚拟现实内容创作,快速搭建可交互环境
替代项目
WorldGen、3D-GPT、SceneScape
上一篇:DreamCraft3D
下一篇:PartCrafter
同类项目推荐
dreamtalk
开源
一张照片加段语音,生成自然表情的说话视频
Official implementations for paper: DreamTalk: When Expressive Talking Head Generati···
ChatVRM
开源
浏览器里让 VRM 虚拟人开口和你聊天
Chat with VRM avatar via LLM
ai-office
开源
走进 3D 办公室,AI 同事工作开会全程现场直击
Explore a 3D AI office where agents work, walk, talk, and meet in a React and Three.···
OmniX
开源
全景图一键生成可渲染的 PBR 3D 场景
Official implementation of "OmniX: From Unified Panoramic Generation and Perception ···
LiveTalking
开源
让数字人边听边说,口型跟得上,直播聊天不冷场
Real time interactive streaming digital human
PartCrafter
开源
一句话生成带部件结构的3D网格,可编辑可重组
[NeurIPS 2025] PartCrafter: Structured 3D Mesh Generation via Compositional Latent D···
SOMA-X
开源
一套API统一所有人体模型,告别格式混乱
SOMA: Unifying Parametric Human Body Models
CityDreamer
开源
一键生成无限大的逼真3D城市,告别手工建模
The official implementation of "CityDreamer: Compositional Generative Model of Unbou···
MoDA
开源
一张照片加一段语音,生成口型同步的数字人视频
MoDA: Multi-modal Diffusion Architecture for Talking Head Generation
