0. 说明

这是论文 "LVSM: A Large View Synthesis Model with Minimal 3D Inductive Bias" 的官方仓库。

这里的代码是重新实现的，与Adobe开发的原始版本不同。不过，我们提供的检查点来自Adobe的原始实现，并且是在Adobe内部训练得到的。

我们已经验证过，重新实现的版本在性能上与原始版本一致。如有任何疑问或问题，请联系金海安，邮箱地址为 haianjin0415@gmail.com。

---

1. 准备工作

环境

conda create -n LVSM python=3.11
conda activate LVSM
pip install -r requirements.txt

由于我们使用了 xformers 的 memory_efficient_attention，因此GPU设备的计算能力需要大于8.0。否则会报错。请在 CUDA GPUs 页面 上查看你的GPU计算能力。

数据

从这个链接下载RealEstate10K数据集，该数据集由pixelSplat提供。解压zip文件后，将数据放入 YOUR_RAW_DATAPATH 目录中。然后运行以下命令，将数据预处理为我们所需的格式。

python process_data.py --base_path YOUR_RAW_DATAPATH --output_dir YOUR_PROCESSED_DATAPATH --mode ['train' or 'test']

检查点

场景级别的评估是在由pixelSplat预处理过的RealEstate10K数据集上进行的。模型检查点托管在HuggingFace上。

模型	PSNR	SSIM	LPIPS
LVSM 解码器-only 场景级 res256×256（完整）	29.67	0.906	0.098
LVSM 编码器-解码器 场景级 res256×256（完整）	28.60	0.893	0.114
LVSM 解码器-only 场景级 res512×512	N/A	N/A	N/A
LVSM 编码器-解码器 场景级 res512×512	N/A	N/A	N/A

正如我们在论文的局限性部分所讨论的：

当输入图像的宽高比和分辨率与训练时使用的不同，我们的模型性能会下降。

因此，如果你计划在不同于我们提供的检查点训练分辨率和宽高比（256×256或512×512）的情况下使用该模型进行推理，我们建议针对特定的分辨率和宽高比对模型进行微调。

2. 训练

在开始训练之前，你需要按照这里的说明生成Wandb密钥文件用于日志记录，并将其保存到 configs 文件夹中，命名为 api_keys.yaml。你可以以 configs/api_keys_example.yaml 作为模板。

原始训练命令：

torchrun --nproc_per_node 8 --nnodes 8 \
    --rdzv_id 18635 --rdzv_backend c10d --rdzv_endpoint localhost:29502 \
    train.py --config configs/LVSM_scene_decoder_only.yaml

训练将在8个GPU和8个节点上分布式进行，总批量大小为512。LVSM_scene_decoder_only.yaml 是场景级Decoder-Only LVSM模型的配置文件。你也可以使用 LVSM_scene_encoder_decoder.yaml 来训练场景级Encoder-Decoder LVSM模型。

如果你的资源有限，可以使用以下命令来训练一个更小的模型，采用较小的批量：

torchrun --nproc_per_node 8 --nnodes 1 \
    --rdzv_id 18635 --rdzv_backend c10d --rdzv_endpoint localhost:29502 \
    train.py --config configs/LVSM_scene_decoder_only.yaml \
    model.transformer.n_layer = 12 \
    training.batch_size_per_gpu = 16

在这里，我们将总批量从512减少到128，同时将Transformer层数从24层减少到12层。你还可以将patch-size从8增加到16，以提高训练速度，但性能会有所降低。我们在论文中也讨论了高效的设置（单/双GPU训练）。

3. 推理

torchrun --nproc_per_node 8 --nnodes 1 \
--rdzv_id 18635 --rdzv_backend c10d --rdzv_endpoint localhost:29506 \
inference.py --config "configs/LVSM_scene_decoder_only.yaml" \
training.dataset_path = "./preprocessed_data/test/full_list.txt" \
training.batch_size_per_gpu = 4 \
training.target_has_input =  false \
training.num_views = 5 \
training.square_crop = true \
training.num_input_views = 2 \
training.num_target_views = 3 \
inference.if_inference = true \
inference.compute_metrics = true \
inference.render_video = true \
inference_out_dir = ./experiments/evaluation/test

我们使用 ./data/evaluation_index_re10k.json 来指定输入和目标视图的索引。这个json文件最初是由pixelSplat提供的。

推理完成后，代码会在 inference_out_dir 文件夹中生成一个html文件。你可以打开该html文件查看结果。

4. 引用

如果你的研究中使用了这项工作，请考虑引用以下内容：

@inproceedings{
jin2025lvsm,
title={LVSM: A Large View Synthesis Model with Minimal 3D Inductive Bias},
author={Haian Jin and Hanwen Jiang and Hao Tan and Kai Zhang and Sai Bi and Tianyuan Zhang and Fujun Luan and Noah Snavely and Zexiang Xu},
booktitle={The Thirteenth International Conference on Learning Representations},
year={2025},
url={https://openreview.net/forum?id=QQBPWtvtcn}
}

5. 致谢

我们感谢Kalyan Sunkavalli提供的有益讨论和支持。本工作完成时，金海安、蒋翰文和张天元均为Adobe Research的研究实习生。此外，本研究还得到了美国国家科学基金会的部分资助（项目编号：IIS-2211259、IIS-2212084）。

LVSM 快速上手指南

LVSM (Large View Synthesis Model) 是一个具有最小 3D 归纳偏置的大型视图合成模型，适用于从少量输入图像生成新视角的场景级渲染任务。

1. 环境准备

系统要求

• Python: 3.11
• GPU: 计算能力 (Compute Capability) 必须 > 8.0 (如 RTX 3090, A100 等)，因为模型依赖 xformers 的 memory_efficient_attention。
• 显存: 建议单卡显存充足，分布式训练需多卡支持。

前置依赖

确保已安装 CUDA 和对应的 NVIDIA 驱动。

2. 安装步骤

创建虚拟环境并安装依赖

conda create -n LVSM python=3.11
conda activate LVSM
pip install -r requirements.txt

提示: 如果 pip 下载速度慢，可添加国内镜像源加速： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

数据准备

1. 从 RealEstate10K 数据集链接 下载数据（由 pixelSplat 提供）。
2. 解压文件至自定义路径 YOUR_RAW_DATAPATH。
3. 运行以下命令预处理数据：

python process_data.py --base_path YOUR_RAW_DATAPATH --output_dir YOUR_PROCESSED_DATAPATH --mode 'train'
# 测试集请将 mode 改为 'test'

下载预训练模型

从 HuggingFace 下载检查点。推荐场景级解码器模型 (Decoder-Only)：

• 256x256 分辨率: 下载链接
• 512x512 分辨率: 下载链接

注意: 模型对分辨率和长宽比敏感。若需使用非训练分辨率（非 256 或 512），建议先进行微调。

3. 基本使用 (推理示例)

以下命令演示如何使用预训练模型在测试集上进行推理、评估指标计算并生成可视化视频。

前提: 确保已配置好预处理后的数据路径，并修改命令中的 training.dataset_path 指向你的测试列表文件（如 ./preprocessed_data/test/full_list.txt）。

torchrun --nproc_per_node 8 --nnodes 1 \
--rdzv_id 18635 --rdzv_backend c10d --rdzv_endpoint localhost:29506 \
inference.py --config "configs/LVSM_scene_decoder_only.yaml" \
training.dataset_path = "./preprocessed_data/test/full_list.txt" \
training.batch_size_per_gpu = 4 \
training.target_has_input =  false \
training.num_views = 5 \
training.square_crop = true \
training.num_input_views = 2 \
training.num_target_views = 3 \
inference.if_inference = true \
inference.compute_metrics = true \
inference.render_video = true \
inference_out_dir = ./experiments/evaluation/test

结果查看: 运行完成后，会在 inference_out_dir 指定目录生成一个 HTML 文件。直接在浏览器中打开该文件即可查看渲染结果对比和视频。

资源受限用户: 若显存不足，可减少 --nproc_per_node 数量（如改为 1 或 2），并相应调小 training.batch_size_per_gpu。