# CubeComposer 4K 360° Video

> **CubeComposer** （CVPR 2026）是一种时空自回归扩散模型，可生成 **原生 4K 360° 全景视频** 来自标准透视视频输入。基于 Wan 视频基础模型，并在 11,832 个高分辨率片段上训练。这是首个能够进行原生 4K 360° 生成的开源模型——可在消费级 GPU 硬件上实现 VR 内容创作、虚拟导览和沉浸式媒体。

## 这为什么重要

传统上，360° 视频通常需要专用采集设备（多摄像头、拼接软件、昂贵的后期处理）。CubeComposer 改变了这一点：

* **输入**：任意标准摄像机视频（单镜头、手机摄像头、行车记录仪）
* **输出**：原生 4K 360° 等距矩形视频
* **方法**：将全景图分解为立方体贴图各面，并在保持空间一致性的情况下自回归生成每个面
* **质量**：显著优于以往的拼接和外延生成方法

## 硬件要求

| 配置            | 显存   | 分辨率            | 速度         |
| ------------- | ---- | -------------- | ---------- |
| RTX 4090 24GB | 24GB | 4K 360°（30 帧）  | 约 8 分钟/片段  |
| RTX 5090 32GB | 32GB | 4K 360°（60 帧）  | 约 6 分钟/片段  |
| 2× RTX 4090   | 48GB | 4K 360°（120 帧） | 约 9 分钟/片段  |
| A100 80GB     | 80GB | 4K 360°（240 帧） | 约 12 分钟/片段 |

**最低要求**：RTX 4090 24GB（或同等 24GB+ 显存的 GPU）

> 在 Clore.ai 上：RTX 4090 价格从 **约 $1.20/小时的抢占式实例** ——一个 2 分钟片段的成本约为 $0.40。

## 安装

```bash
# 克隆代码仓库
git clone https://github.com/TencentARC/CubeComposer
cd cubecomposer

# 安装依赖（Python 3.10+，CUDA 12.1+）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
pip install -r requirements.txt

# 下载模型权重（约 18GB）
python scripts/download_weights.py --model cubecomposer-4k-v1
```

### Docker（推荐用于 Clore.ai）

```bash
# 无官方 Docker 镜像——请从源码安装：
git clone https://github.com/TencentARC/CubeComposer /workspace/CubeComposer
cd /workspace/CubeComposer
pip install -r requirements.txt
python app.py --share --listen 0.0.0.0 --port 7860
```

## 快速开始

### CLI：透视视频 → 4K 360°

```bash
# 基本用法：输入透视视频，输出 4K 等距矩形视频
python generate_360.py \
  --input /workspace/input_video.mp4 \
  --output /workspace/output_360.mp4 \
  --resolution 4096x2048 \
  --frames 30 \
  --fps 30

# 更高质量：更多步数，更长片段
python generate_360.py \
  --input /workspace/walk_through_park.mp4 \
  --output /workspace/park_360_4k.mp4 \
  --resolution 4096x2048 \
  --frames 60 \
  --num_inference_steps 50 \
  --guidance_scale 7.5 \
  --fps 30
```

### Python API

```python
from cubecomposer import CubeComposerPipeline
import torch

# 加载流水线
pipe = CubeComposerPipeline.from_pretrained(
    "cubecomposer/cubecomposer-4k-v1",
    torch_dtype=torch.bfloat16
).to("cuda")

# 从透视输入生成 360° 视频
output = pipe(
    input_video_path="input.mp4",
    num_frames=30,
    resolution=(4096, 2048),  # 4K 等距矩形
    num_inference_steps=50,
    guidance_scale=7.5,
    cubemap_size=1024  # 每个立方体贴图面的尺寸
)

# 保存为标准等距矩形 MP4
output.save("output_360.mp4", fps=30)
print(f"已生成 4K 360° 视频：output_360.mp4")
```

### Gradio WebUI

```python
import gradio as gr
from cubecomposer import CubeComposerPipeline
import torch

pipe = CubeComposerPipeline.from_pretrained(
    "cubecomposer/cubecomposer-4k-v1",
    torch_dtype=torch.bfloat16
).to("cuda")

def generate_360(video, frames, steps):
    output = pipe(
        input_video_path=video,
        num_frames=int(frames),
        resolution=(4096, 2048),
        num_inference_steps=int(steps)
    )
    output.save("/tmp/output_360.mp4", fps=30)
    return "/tmp/output_360.mp4"

demo = gr.Interface(
    fn=generate_360,
    inputs=[
        gr.Video(label="输入透视视频"),
        gr.Slider(10, 120, value=30, label="帧数"),
        gr.Slider(20, 80, value=50, label="推理步数（质量）")
    ],
    outputs=gr.Video(label="4K 360° 输出"),
    title="CubeComposer —— 4K 360° 视频生成",
    description="上传任意透视视频 → 获取原生 4K 360° 全景视频"
)

demo.launch(server_name="0.0.0.0", server_port=7860, share=True)
```

## 在 Clore.ai 上部署：分步指南

### 1. 租用一张 RTX 4090

1. 前往 [clore.ai/marketplace](https://clore.ai/marketplace)
2. 筛选：GPU 具备 **24GB+ 显存** （推荐 RTX 4090）
3. 抢占式价格：约 $1.20–2.50/小时，取决于可用性
4. 选择 **自定义 Docker** 或 **Ubuntu** 镜像

### 2. 通过 SSH 设置

```bash
# 连接到你的 Clore 服务器
ssh root@<server-ip>

# 一行命令完成设置
git clone https://github.com/TencentARC/CubeComposer && \
  cd cubecomposer && \
  pip install -r requirements.txt && \
  python scripts/download_weights.py && \
  python app.py --port 7860 --host 0.0.0.0
```

### 3. 访问界面

打开 `http://<server-ip>:7860` 在浏览器中使用 Gradio 界面。

## 工作流程：手机视频 → 可用于 VR 的 4K 360°

```bash
# 第 1 步：将手机视频上传到服务器
scp ~/my_video.mp4 root@<server-ip>:/workspace/

# 第 2 步：生成 4K 360° 版本
ssh root@<server-ip> "cd cubecomposer && python generate_360.py \
  --input /workspace/my_video.mp4 \
  --output /workspace/my_video_360_4k.mp4 \
  --resolution 4096x2048 --frames 60"

# 第 3 步：为 YouTube/VR 头显添加 360° 元数据
ffmpeg -i my_video_360_4k.mp4 \
  -c copy \
  -metadata:s:v:0 spherical=equirectangular \
  my_video_360_4k_vr.mp4

# 第 4 步：下载结果
scp root@<server-ip>:/workspace/my_video_360_4k_vr.mp4 ~/
```

## Spectrum 集成：在 Wan2.1 上实现 4.79× 加速

这个 **Spectrum 加速器** （CVPR 2026）——一种使用切比雪夫多项式的免训练频谱扩散特征预测器——可以应用于 CubeComposer 底层的 Wan2.1 基座，从而显著提速：

```python
from cubecomposer import CubeComposerPipeline
from spectrum_accelerator import SpectrumAccelerator
import torch

pipe = CubeComposerPipeline.from_pretrained(
    "cubecomposer/cubecomposer-4k-v1",
    torch_dtype=torch.bfloat16
).to("cuda")

# 应用 Spectrum，在无质量损失的情况下实现 4.79× 加速
accelerator = SpectrumAccelerator(pipe.unet, order=8)  # 切比雪夫阶数
pipe.unet = accelerator

# 现在生成速度约为原始速度的 4.79×
output = pipe(
    input_video_path="input.mp4",
    num_frames=30,
    resolution=(4096, 2048),
    num_inference_steps=50  # 等效于约 240 步的质量
)
output.save("output_fast_360.mp4")
```

## 质量建议

1. **输入视频质量很重要** ——输入分辨率越高，360° 输出越好
2. **稳定的画面** ——手持抖动会降低立方体贴图各面之间的一致性
3. **良好的照明** ——避免极端反差（过曝的天空 + 昏暗的室内）
4. **更长的片段** ——30+ 帧可带来更好的时间一致性
5. **面分辨率** —— `--cubemap_size 1024` 是最佳平衡点（2048 适合关键工作，但需要 4× 更多显存）

## 使用场景

* **VR 内容创作** ——将任意素材转换为适用于 Meta Quest、Apple Vision Pro 的内容
* **虚拟房产导览** ——将 walkthrough 视频变成 360° 导览
* **旅行内容** ——分享沉浸式旅行体验
* **建筑可视化** ——360° 室内/室外漫游
* **活动记录** ——将活动录像转换为沉浸式回放
* **游戏素材** ——生成 360° 环境参考

## 生产工作流成本估算

| 任务                  | Clore.ai 成本           |
| ------------------- | --------------------- |
| 5 秒片段（30 帧，4K）      | 约 $0.30（RTX 4090 抢占式） |
| 10 秒片段（60 帧，4K）     | \~$0.50               |
| 30 秒片段（180 帧，4K）    | \~$1.20               |
| 批处理：100 个片段（每个 5 秒） | \~$30                 |

## 相关指南

* [Wan2.1 视频生成](https://docs.clore.ai/guides/guides_v2-zh/shi-pin-sheng-cheng/wan-video) ——CubeComposer 所基于的基础模型
* [FramePack](https://docs.clore.ai/guides/guides_v2-zh/shi-pin-sheng-cheng/framepack) ——高效的长视频生成（仅需 6GB 显存！）
* [LTX-2 Video](https://docs.clore.ai/guides/guides_v2-zh/shi-pin-sheng-cheng/ltx-video-2) ——快速潜空间视频生成
* [ComfyUI](https://docs.clore.ai/guides/guides_v2-zh/tu-xiang-sheng-cheng/comfyui) ——用于视频 + 图像的节点式工作流
* [RIFE 视频插帧](https://docs.clore.ai/guides/guides_v2-zh/shi-pin-chu-li/rife-interpolation) ——让生成的视频更平滑

***

*最后更新：2026 年 3 月 16 日 | 论文：arXiv:2603.04291（CVPR 2026） | 基于 Wan2.1 基础模型*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/shi-pin-sheng-cheng/cubecomposer-360-video.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.