HunyuanWorld-1.0：从文字或图像生成可交互的360° 3D世界

HunyuanWorld-1.0 是腾讯混元团队开发的一个开源项目，旨在通过文字描述或单张图像生成可交互的360° 3D世界。它采用全景代理生成、语义分层和层次化3D重建技术，生成高质量、可探索的3D场景。项目基于 Flux 框架，支持与 Stable Diffusion 等图像生成模型兼容。用户可通过简单的文字或图像输入，快速生成支持虚拟现实、游戏开发和影视制作的3D环境。生成结果可导出为 .obj 或 .glb 格式，兼容 Blender、Unity 和 Unreal 引擎。官方提供完整代码、模型权重和详细文档，方便开发者使用和扩展。

功能列表

• 文本到3D世界 ：输入文字描述，生成360°全景3D场景。
• 图像到3D世界 ：基于单张图像，生成可交互的3D环境。
• 语义分层 ：自动分离前景和背景对象，支持独立编辑。
• 网格导出 ：生成 .obj 和 .glb 文件，兼容主流3D软件和游戏引擎。
• 高视觉与几何一致性 ：生成结果在视觉质量和几何结构上优于其他开源模型。
• 全景代理生成 ：通过全景图像作为代理，确保360°沉浸式体验。
• 开源支持 ：提供模型权重、推理代码和技术报告，支持社区定制。
• 浏览器预览 ：通过 modelviewer.html 在浏览器中实时查看3D场景。

使用帮助

安装流程

要运行 HunyuanWorld-1.0，需配置 Python 3.10 和 PyTorch 2.5.0+cu124 环境，推荐使用 NVIDIA GPU（显存至少 33GB，如 A100）。以下是详细安装步骤。

1. 克隆代码库
   在终端运行以下命令，获取项目代码：

   git clone https://github.com/Tencent-Hunyuan/HunyuanWorld-1.0.git
   cd HunyuanWorld-1.0
   

2. 创建虚拟环境
   使用 conda 创建隔离环境：

   conda env create -f docker/HunyuanWorld.yaml
   conda activate hunyuanworld
   

3. 安装 Real-ESRGAN
   Real-ESRGAN 用于图像增强，需单独安装：

   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
   cd ..
   

4. 安装 ZIM 依赖
   ZIM 提供语义分割支持，需下载检查点文件：

   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
   cd ../..
   

5. 安装 Draco（可选）
   为支持 .glb 文件的 Draco 压缩，安装 Draco 库：

   git clone https://github.com/google/draco.git
   cd draco
   mkdir build
   cd build
   cmake ..
   make
   sudo make install
   cd ../..
   

6. 登录 Hugging Face
   下载模型权重需登录 Hugging Face：

   huggingface-cli login --token $HUGGINGFACE_TOKEN
   

7. 验证环境
   检查 GPU 可用性：

   python3 -c "import torch; print(torch.cuda.is_available())"
   

   输出 True 表示环境配置成功。

使用方法

HunyuanWorld-1.0 支持文本到3D和图像到3D两种生成方式。以下是具体操作流程。

文本到3D世界

1. 编写提示词
   准备简洁的文字描述，例如“一片热带雨林，阳光穿过树冠”。避免复杂语句，确保描述清晰。
2. 生成全景图像
   使用以下命令生成全景图像：

   python3 demo_panogen.py --prompt "一片热带雨林，阳光穿过树冠" --output_path test_results/rainforest
   

3. 生成3D场景
   使用全景图像生成3D世界，支持语义分层：

   CUDA_VISIBLE_DEVICES=0 python3 demo_scenegen.py --image_path test_results/rainforest/panorama.png --labels_fg1 trees --labels_fg2 rocks --classes outdoor --output_path test_results/rainforest
   

4. 查看结果
   生成的3D场景保存在 test_results/rainforest 目录，包含 .obj 或 .glb 文件。打开 modelviewer.html 在浏览器中预览。

图像到3D世界

1. 准备输入图像
   提供一张高质量图像（PNG/JPG），分辨率至少 512×512，内容清晰。
2. 生成全景图像
   使用输入图像生成全景：

   python3 demo_panogen.py --image_path examples/input.png --output_path test_results/scene
   

3. 生成3D场景
   使用全景图像生成3D世界：

   CUDA_VISIBLE_DEVICES=0 python3 demo_scenegen.py --image_path test_results/scene/panorama.png --labels_fg1 sculptures --labels_fg2 trees --classes outdoor --output_path test_results/scene
   

4. 导出与编辑
   生成的网格文件可导入 Blender、Unity 或 Unreal 引擎，支持实时编辑。

特色功能操作

• 语义分层 ：通过 --labels_fg1 和 --labels_fg2 参数指定前景对象（如“树木”“石头”），模型自动分离前景和背景，便于编辑。例如，生成森林场景时，可设置 --labels_fg1 trees --labels_fg2 rocks。
• 全景代理生成 ：生成360°全景图像作为3D世界的中间代理ezers
• 网格导出 ：支持 .obj 和 .glb 格式，兼容主流3D工具和游戏引擎。
• 浏览器预览 ：使用 modelviewer.html 文件，上传 .glb 文件即可在浏览器中查看3D场景。
• 模型兼容性 ：基于 Flux 框架，支持 Hunyuan Image、Stable Diffusion 等模型扩展。

注意事项

• 硬件要求 ：推荐 NVIDIA A100（33GB 显存）。低显存 GPU 可能导致生成失败。
• 提示优化 ：文字提示应简洁，描述场景和物体。图像输入需高分辨率。
• 社区支持 ：加入官方 Wechat 或 Discord 群组，获取技术支持。

应用场景

1. 游戏开发
   快速生成游戏场景，如森林、城市或科幻世界，导出网格文件后在 Unity 或 Unreal 引擎中优化，缩短开发时间。
2. 虚拟现实
   生成360° 3D世界，用于虚拟旅游、展示或培训，增强沉浸式体验。
3. 影视制作
   制作团队可生成虚拟场景，用于预可视化或数字布景，降低拍摄成本。
4. 数字艺术
   艺术家可生成3D模型，结合 Blender 调整细节，创作独特的数字作品。

QA

1. 需要多大显存运行 HunyuanWorld-1.0？
   推荐 33GB 显存的 GPU（如 NVIDIA A100）。低配 GPU 可能无法运行完整流程。
2. 支持哪些输入格式？
   支持文字（中英文）和图像（PNG/JPG）。文字需简洁，图像需清晰。
3. 生成结果可否用于商业项目？
   可以，生成文件支持 .obj 和 .glb 格式，兼容商业用途，需遵守 Apache 2.0 协议。
4. 如何提高生成质量？
   使用清晰的文字提示或高质量图像，设置 --labels_fg1 和 --labels_fg2 参数优化分层。