WorldGen：几秒钟内生成任意3D场景

作者 👨‍💻：Ziyang Xie 联系邮箱 📧：ziyangxie01@gmail.com
如有任何问题或合作需求，欢迎随时联系我！

🌟 简介

🌏 WorldGen 可以根据文本提示和图像在几秒钟内生成3D场景。它是一款功能强大的工具，适用于为游戏、模拟、机器人技术和虚拟现实应用创建3D环境和场景。

• 即时3D生成 ⚡️ ：只需几秒钟即可从输入数据中创建完整的3D场景
• 360°自由探索 🧭 ：WorldGen支持对生成的3D场景进行自由的360°一致探索，并实现闭环闭合。
• 多样场景支持 🌈 ：WorldGen支持室内和室外场景，以及任何风格的真实与非真实场景。
• 灵活渲染 📸 ：WorldGen支持以任意分辨率、任意相机设置和轨迹进行实时渲染。

只需两行代码，即可在几秒钟内生成一个3D场景

# 使用我们的API生成3D场景
worldgen = WorldGen()
worldgen.generate_world("<描述场景的文本提示>")

文本到场景生成

图像到场景生成

---

最新消息与待办事项

• 04.12.2026 🔧 [改进Sharp] 重构ml-sharp流程：使用立方体贴图深度来对齐Sharp的每面高斯分布，以获得更好的全局一致性。将视图数量从8个以上减少到6个立方体面。
• 04.11.2026 🔄 [更新深度] 用DA-2替换UniK3D，以实现更优质的360°深度估计。
• 03.17.2026 🔧 [提升质量] 通过修复投影尺度问题来提高GS质量。使ml-sharp依赖项变为可选。
• 01.10.2026 🔥 [新功能] 添加对ml-sharp的支持（已修改为可在360度图像上运行），以更好地生成GS（目前处于实验模式）。
• 05.10.2025 🤖 添加对低显存生成的支持（仅需约10GB显存即可完成生成）。
• 04.26.2025 📄 新增 发布WorldGen项目页面。
• 04.22.2025 🏡 添加对网格场景生成的支持（预计将比点云渲染效果更好）。
• 04.21.2025 🎉 开源WorldGen代码库。
• 04.19.2025 🖼️ 添加对图像到场景生成的支持。
• 04.17.2025 📝 添加对文本到场景生成的支持。
• 发布技术报告和视频。
• 支持更优秀的背景修复（不可见区域修复）。

📦 安装

开始使用WorldGen非常简单！

# 克隆仓库 
git clone --recursive https://github.com/ZiYang-xie/WorldGen.git 
cd WorldGen

# 创建一个新的conda环境
conda create -n worldgen python=3.11
conda activate worldgen

# 安装torch和torchvision（支持GPU）
pip3 install torch torchvision

# 安装WorldGen
pip install .

# 安装DA-2（360度深度估计）——使用--no-deps选项以避免版本冲突
pip install git+https://github.com/EnVision-Research/DA-2.git#subdirectory=src --no-deps

# 安装pytorch3d的依赖项
pip install git+https://github.com/facebookresearch/pytorch3d.git --no-build-isolation

# 🔥 [新功能]：如果想使用ml-sharp的实验性功能，需要安装ml-sharp的相关依赖
pip install -e submodules/ml-sharp

# 此外，您还需要接受受限制模型（FLUX.1-dev）的许可协议。
# https://huggingface.co/black-forest-labs/FLUX.1-dev
# 登录Hugging Face并接受许可协议。
# huggingface-cli login

🕹️ 快速入门 / 演示

我们提供了一个演示脚本，帮助您快速入门并在网页浏览器中可视化3D场景。该脚本由Viser驱动。

# 根据文本提示生成3D场景
python demo.py -p "一片美丽的风景，有河流和山脉"
# 室内场景示例
python demo.py -p "一间设计精美的舒适卧室"

# 🔥 新功能：使用ml-sharp实验性功能生成3D场景（可能比默认模式效果更好）
python demo.py -p "<描述场景的文本提示>" --use_sharp

# 根据图像生成3D场景
python demo.py -i "您图片的路径.jpg" -p "<可选：描述场景的文本提示>" --use_sharp

# 在网格模式下生成3D场景
# 请确保您已安装我定制的viser，以便正确显示网格而不会出现背面剔除问题
# pip install git+https://github.com/ZiYang-xie/viser.git

python demo.py -p "一片美丽的风景，有河流和山脉" --return_mesh

运行演示脚本后，本地Viser服务器将在http://localhost:8080启动，您可以在其中实时探索生成的3D场景。

🎮 高级用法

WorldGen API

快速开始使用WorldGen（模式为t2s或i2s），并在几秒钟内生成您的第一个3D场景：

• 📝 文本到场景：根据文本提示生成3D场景

# 使用 Python API 的示例
from worldgen import WorldGen
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

worldgen = WorldGen(mode="t2s", device=device, low_vram=False) # 如果你的 GPU 显存小于 24GB，请将 low_vram 设置为 True。
splat = worldgen.generate_world("<描述场景的文本提示>")
splat.save("输出文件路径.ply") # 将点云文件保存为 .ply 格式，可以使用标准的高斯点云查看器加载和可视化

• 🖼️ 图像转场景：从图像生成 3D 场景

worldgen = WorldGen(mode="i2s", device=device, low_vram=False) # 如果你的 GPU 显存小于 24GB，请将 low_vram 设置为 True。
image = Image.open("你的图像路径.jpg")
splat = worldgen.generate_world(
    image=image,
    prompt="<可选：用于描述图像和场景的文本提示>",
)

• 🏡 以网格模式生成 3D 场景

mesh = worldgen.generate_world("<描述场景的文本提示>", return_mesh=True)
o3d.io.write_triangle_mesh("输出文件路径.ply", mesh) # 将网格保存为 .ply 文件

[!Tip] 我们还支持背景修复功能，以提升场景生成效果，但目前该功能仍处于实验阶段，可能并非适用于所有场景。
可通过设置 WorldGen(inpaint_bg=True) 来启用此功能。

# 如果需要使用背景修复功能，请安装 iopaint
pip install iopaint --no-dependencies

3D 场景中的自由视角探索

---

[!Note] WorldGen 内部支持从 360° 全景图像生成 3D 场景 📸，这与 WorldGen 的工作原理有关： 如果你恰好拥有一张 360° 全景（等距柱状投影）图像，可以尝试一下。全景图像的宽高比应为 2:1。

pano_image = Image.open("你的全景图像路径.jpg")
splat = worldgen._generate_world(pano_image=pano_image)

⭐️ 星标历史

如果你喜欢 WorldGen，请给它点个星吧！

📚 引用

如果你觉得这个项目有用，请参考以下引用格式：

@misc{worldgen2025ziyangxie,
  author = {Ziyang Xie},
  title = {WorldGen：几秒钟内生成任意 3D 场景},
  year = {2025},
  publisher = {GitHub},
  journal = {GitHub 仓库},
  howpublished = {\url{https://github.com/ZiYang-xie/WorldGen}},
}

---

🤝 致谢

本项目基于以下开源项目构建，如果你觉得它们有用，请一并引用：

• DA-2
• UniK3D
• Layerpano3D
• Viser
• FLUX.1
• OneFormer
• LaMa
• ml-sharp

本项目中的一些核心方法和思路受到以下项目的启发，特此致谢：

• WonderWorld [RGBD 到高斯点云的转换]
• WorldSheet [网格生成]

WorldGen 快速上手指南

WorldGen 是一个强大的开源工具，能够在几秒钟内根据文本提示或图片生成完整的 3D 场景。它支持室内外多种风格，并允许用户在生成的场景中进行 360° 自由探索和实时渲染。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐) 或 macOS
• Python 版本: 3.11
• GPU: 支持 CUDA 的 NVIDIA 显卡
  • 标准模式：建议显存 ≥ 24GB
  • 低显存模式：仅需约 10GB 显存（启动时设置 low_vram=True）
• 前置依赖:
  • Git
  • Conda (推荐使用 Miniconda 或 Anaconda)
  • Hugging Face 账号 (需接受 FLUX.1-dev 模型许可)

2. 安装步骤

请按顺序执行以下命令来配置环境和安装依赖。

第一步：克隆项目并创建环境

# 克隆仓库（包含子模块）
git clone --recursive https://github.com/ZiYang-xie/WorldGen.git 
cd WorldGen

# 创建并激活 Python 3.11 虚拟环境
conda create -n worldgen python=3.11
conda activate worldgen

第二步：安装核心依赖

# 安装 PyTorch 和 torchvision (请根据您的 CUDA 版本调整，此处为通用命令)
pip3 install torch torchvision

# 安装 WorldGen 主程序
pip install .

第三步：安装特定组件

# 安装 DA-2 (用于 360° 深度估计)，使用 --no-deps 避免版本冲突
pip install git+https://github.com/EnVision-Research/DA-2.git#subdirectory=src --no-deps

# 安装 PyTorch3D 依赖
pip install git+https://github.com/facebookresearch/pytorch3d.git --no-build-isolation

第四步：可选功能安装

• 实验性功能 (ml-sharp): 如果需要更高质量的生成效果，可安装此模块。

  pip install -e submodules/ml-sharp
  

• 背景修复功能: 如果需要启用背景补全（实验性），需安装 iopaint。

  pip install iopaint --no-dependencies
  

第五步：模型授权登录

本项目依赖 gated model FLUX.1-dev，必须先登录 Hugging Face 并接受许可协议。

huggingface-cli login
# 按提示输入您的 Access Token (可在 Hugging Face 设置中获取)

3. 基本使用

安装完成后，您可以通过命令行脚本快速生成并预览 3D 场景，或使用 Python API 进行集成开发。

方式一：命令行快速演示 (推荐)

运行以下命令将启动一个本地 Web 服务器 (http://localhost:8080)，您可以在浏览器中实时查看和探索生成的 3D 场景。

从文本生成场景：

# 生成户外风景
python demo.py -p "A beautiful landscape with a river and mountains"

# 生成室内卧室
python demo.py -p "A well-designed cozy bedroom"

# [可选] 使用 ml-sharp 实验模式以获得更好效果
python demo.py -p "A futuristic city street" --use_sharp

从图片生成场景：

python demo.py -i "path/to/your/image.jpg" -p "Optional description of the scene"

生成网格模型 (Mesh) 而非高斯泼溅 (Splat)：

# 注意：可能需要安装定制版的 viser: pip install git+https://github.com/ZiYang-xie/viser.git
python demo.py -p "A beautiful landscape with a river and mountains" --return_mesh

方式二：Python API 调用

您可以在自己的代码中直接调用 WorldGen 生成场景并保存文件。

文本转 3D 场景 (Text-to-Scene):

import torch
from worldgen import WorldGen

# 初始化设备
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

# 初始化 WorldGen
# 如果显存小于 24GB，请将 low_vram 设置为 True
worldgen = WorldGen(mode="t2s", device=device, low_vram=False)

# 生成场景
splat = worldgen.generate_world("A magical forest with glowing mushrooms")

# 保存为 .ply 文件 (可用于其他高斯泼溅查看器)
splat.save("output_scene.ply")

图片转 3D 场景 (Image-to-Scene):

from PIL import Image
from worldgen import WorldGen
import torch

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
worldgen = WorldGen(mode="i2s", device=device, low_vram=False)

image = Image.open("input_image.jpg")
splat = worldgen.generate_world(
    image=image,
    prompt="A cyberpunk street view based on the image", # 可选的描述提示词
)
splat.save("output_from_image.ply")

生成网格模型 (Mesh Mode):

# 需要安装 open3d: pip install open3d
import open3d as o3d

mesh = worldgen.generate_world("A simple wooden house", return_mesh=True)
o3d.io.write_triangle_mesh("output_mesh.ply", mesh)