---
license: apache-2.0
language:
  - zh
  - en
library_name: worldgen-vulkan
tags:
  - vulkan
  - amd
  - no-cuda
  - flux
  - worldgen
  - gaussian-splatting
  - 3d-generation
---

# WorldGen Vulkan

**中文** | [English](#english)

在 Windows + AMD RX 6900 XT 上，用 **Vulkan** 跑 WorldGen 的
text-to-360 / image-to-360 3DGS 流水线，不依赖 CUDA：

```text
prompt / image
  -> FLUX.1-dev / FLUX.1-Fill-dev（stable-diffusion.cpp, Vulkan）
  -> 1024x512 全景
  -> DA-2 depth（ncnn, Vulkan）
  -> Rust RGBD -> 3DGS PLY + mesh PLY
```

> 这不是官方 WorldGen 的逐字节复刻。默认 1024x512 路径已经跑通；
> 画质、`use_sharp` 仍未完成；1600x800 和简化的 `inpaint_bg` 已接。
> 详见 [docs/VALIDATION.md](docs/VALIDATION.md)。

## 性能（RX 6900 XT, 1024x512, 20 steps）

| 阶段 | 耗时 |
| --- | ---: |
| t2s 全流程 | 56.7 s |
| i2s 全流程 | 61.5 s |
| FLUX sampling | GPU 3D ~100% |
| VAE decode（tiling 512） | 1.35 s（未 tiling 9.0 s） |
| DA-2 Vulkan | 3.05 s（f32） |
| Rust RGBD→3DGS | 0.29 s |

DA-2 与 PyTorch 对拍（1024x512）：

```text
max abs   0.0161
mean abs  0.0027
cosine    0.9999994
```

## 环境

- Windows 11
- AMD RX 6900 XT 16GB（或其他支持 Vulkan 的 GPU）
- Vulkan 1.4 驱动
- Visual Studio 2022 + CMake/Ninja
- Rust stable
- Python 3.11+，仅用于编排/图像 I/O

不需要 CUDA，不需要 PyTorch 推理。

## 模型文件

把模型放到 `models/`（不要提交到 git）：

```text
models/
  flux-dev/
    flux1-dev-q4_k.gguf              # SHA256 962d536a...
    ae.safetensors
    clip_l.safetensors
    t5xxl_fp8_e4m3fn.safetensors
    worldgen_text2scene.safetensors
    worldgen_img2scene.safetensors
  flux-fill/
    flux-fill-official-q4.gguf       # 由官方 FLUX.1-Fill-dev 转换
  da2/
    da2_trace_1024.ncnn.param
    da2_trace_1024.ncnn.bin
```

FLUX.1-dev / FLUX.1-Fill-dev 权重受 Black Forest Labs 非商业许可证约束，
**本仓库不附带权重**。DA-2、WorldGen LoRA 请遵循各自上游许可证。

可用 `scripts/download_models.py` 查看下载地址和校验值；gated 模型需要
`HF_TOKEN`。

## 构建

```powershell
# 1. stable-diffusion.cpp（Vulkan）
scripts/build_sd.ps1
# 也可指定本地 source，跳过 clone：scripts/build_sd.ps1 -Source <dir>

# 2. ncnn + DA-2 runner
scripts/build_da2.ps1
# scripts/build_da2.ps1 -Source <ncnn-dir>

# 3. Rust 后处理
scripts/build_rust.ps1
```

## 运行

```powershell
# text -> 360 3DGS
py -3 worldgen\worldgen_t2s.py `
  --prompt "a cozy wooden bedroom with warm lamps" `
  --out output\bedroom --width 1024 --height 512 --steps 20

# image -> 360 3DGS
py -3 worldgen\worldgen_i2s.py `
  --image path\to\photo.jpg `
  --prompt "a lush rainforest with gorillas" `
  --out output\rainforest --width 1024 --height 512 --steps 20
# 可选：--inpaint-bg（GrabCut + OpenCV 背景 + splat merge）
# 可选：--keep-fg（保留前景物体参与 Fill；默认会先清掉前景，减少重复对象）

# 可选：Open3D/TSDF 重建；默认就是 TSDF，--mesh-shell 回到球壳
py -3 worldgen\worldgen_mesh.py `
  --pano output\rainforest\pano.png `
  --depth output\rainforest\depth.f32 `
  --out output\rainforest\scene\mesh.ply `
  --width 1024 --height 512 --method voxel --voxel-res 0.25 --voxel-stride 4 --median 5 --trim-poles 0.02 --voxel-smooth 2.5 --largest-component
```

输出：

```text
out/
  pano.png
  pano_fill.png        # i2s
  depth.f32
  scene/
    gaussians.ply      # 3DGS
    mesh.ply           # mesh
```

用任意 3DGS 查看器打开 `gaussians.ply`；mesh 可导入 Blender。

## OneFormer 权重

已下载 `shi-labs/oneformer_ade20k_swin_large` 到本地
`models/oneformer`（约 1.8GB）。本机 PyTorch 只有 CPU：

```text
load 19.8 s, infer 4.6 s
```

它还不能作为 Vulkan GPU 路径；需要 ONNX/ncnn 或 wgpu 移植。

## GPU geometry

`gpu-geom/` generates the 17-float RGBD gaussians with a wgpu compute shader,
replacing the CPU `worldgen-vk splat` step:

```powershell
scripts/build_gpu_geom.ps1
tools\gpu-geom\gpu-geom.exe `
  --pano output\rainforest\pano.png `
  --depth output\rainforest\depth.f32 `
  --width 1024 --height 512 `
  --out output\rainforest\scene\gaussians.ply
```

Confirmed on RX 6900 XT: `gpu-geom.exe` prints the Vulkan adapter and writes
524,288 17-float gaussians. `--cpu-mesh` still uses the CPU mesh path.

## GPU 3DGS

`gpu-splat/` is a wgpu/Vulkan 3DGS renderer (no CPU rendering):

```powershell
scripts/build_gpu_splat.ps1
tools\gpu-splat\gpu-splat.exe `
  output\rainforest\scene\gaussians14.ply 0 `
  output\rainforest\gpu_splat.png 0.2
```

`gaussians14.ply` is produced by `worldgen_make14.py --rgb` from the standard
17-float PLY. The GPU renderer uses Vulkan and a 90-degree inside-out camera.

![GPU 3DGS](docs/assets/splat_compare_gpu.png)

## 3DGS 预览 / 官方对比

带 covariance 的透视 3DGS 合成（90° FOV，与官方 demo 视角接近）：

```powershell
py -3 worldgen\render_splat_perspective.py `
  --ply output\rainforest\scene\gaussians.ply `
  --out output\rainforest\gauss_persp.png `
  --width 832 --height 480 --fov 90 --yaw 0 --scale-factor 0.7
```

左：官方 demo 首帧；右：`worldgen-vulkan` 的 3DGS 透视合成。

![3DGS comparison](docs/assets/splat_compare.png)

equirect 全景 3DGS：

```powershell
py -3 worldgen\render_splat_gaussian.py `
  --ply output\rainforest\scene\gaussians.ply `
  --out output\rainforest\gauss_equirect.png `
  --width 1024 --height 512 --scale-factor 0.5
```

![3DGS equirect](docs/assets/gauss_equirect.png)

点渲染仅用于快速检查：

```powershell
py -3 worldgen\render_splat_points.py `
  --ply output\rainforest\scene\gaussians.ply `
  --out output\rainforest\splat_inside.png `
  --inside --yaw 0 --fov 90 --radius 2
```

## DA-2 转换

DA-2 原始模型是 PyTorch。仓库提供：

- `patches/da2-export.patch`：去掉 `quantile`、分离 QKV，使 pnnx 可导出
- `scripts/export_da2.py`：trace + pnnx + ncnn
- `da2/main.cpp`：ncnn Vulkan runner

关键点：runner 必须用 `-DNCNN_VULKAN` 编译，并调用
`net.set_vulkan_device(0)`，否则 ncnn 会回退 CPU。
导出的 param 已把最后一个 `Squeeze` 换成 `Reshape`，当前 CPU-fallback
层数为 **0 / 581**。

## Official reference

Same input as the official demo (`assets/img2scene/painting.png`), left is the
official demo's first frame, right is this pipeline's i2s panorama:

![official comparison](docs/assets/official_compare.png)

This is a qualitative comparison, not a numeric reproduction: the official
demo uses the full PyTorch pipeline and a different prompt/seed.

## 限制

- 默认先清前景再 Fill，重复物体大幅减少；仍可能有残留和竖带边界
- 默认不再生成 CPU TSDF；`--cpu-mesh` 才生成，仍有左侧深度折叠和小 pole tab
- 1600×800 走 1024×512 生成后 LANCZOS 放大，再跑 1600 DA-2；
  噪点/网格明显少于原生 1600 VAE，但没有新增细节
- `use_sharp=True` 未接（需要 SHARP 模型和单独移植）
- `inpaint_bg` 是简化实现：GrabCut 前景 + OpenCV Telea 背景 + DA-2 + splat merge，
  不是官方 OneFormer + FLUX Fill 版本
- 没有官方 WorldGen 全链路视觉对拍
- 不是官方实现，不代表 BFL / WorldGen 作者背书

## License

代码：Apache-2.0，见 [LICENSE](LICENSE) 与 [NOTICE](NOTICE)。
模型权重：遵循各自上游许可证，不随仓库分发。

---

## English

A Vulkan-only WorldGen pipeline for Windows + AMD RX 6900 XT. No CUDA,
no PyTorch inference:

```text
prompt/image
  -> FLUX.1-dev / FLUX.1-Fill-dev (stable-diffusion.cpp, Vulkan)
  -> 1024x512 panorama
  -> DA-2 depth (ncnn, Vulkan)
  -> Rust RGBD -> 3DGS/mesh PLY
```

This is a functional port of the default WorldGen path, **not** a
quality-equivalent reproduction. See [docs/VALIDATION.md](docs/VALIDATION.md).

### Quick start

```powershell
scripts/build_sd.ps1
scripts/build_da2.ps1
scripts/build_rust.ps1
py -3 worldgen\worldgen_t2s.py --prompt "a cozy bedroom" --out output\t2s
py -3 worldgen\worldgen_i2s.py --image path\to\photo.jpg --prompt "a rainforest" --out output\i2s
```

Weights are not bundled. FLUX.1-dev / FLUX.1-Fill-dev are subject to the
Black Forest Labs non-commercial license; DA-2 and the WorldGen LoRAs follow
their upstream licenses.