RenderFormer：基于Transformer的三角网格全局光照神经渲染

曾冲 · 董岳 · 皮特·皮尔斯 · 吴洪志 · 佟欣

SIGGRAPH 2025 会议论文

项目主页 | arXiv | 论文 | 模型 | 官方代码

RenderFormer是一种神经渲染管线，能够直接从基于三角形的场景表示中渲染出包含完整全局光照效果的图像，且无需针对每个场景进行训练或微调。我们并未采用以物理为中心的渲染方法，而是将渲染建模为一种序列到序列的转换：将代表具有反射属性的三角形的标记序列转换为代表像素小块的输出标记序列。RenderFormer遵循两阶段流程：一个与视点无关的阶段，用于模拟三角形之间的光线传输；另一个与视点相关的阶段，根据前一阶段生成的三角形序列，将代表光线束的标记转换为对应的像素值。这两个阶段均基于Transformer架构，并在极少先验约束的情况下进行学习。我们在形状和光线传输复杂度各异的场景上展示了并评估了RenderFormer。

目录

• 安装
  • 先决条件
  • 环境设置
  • 预训练模型
• 使用
  • 图像渲染
    • 场景转换
    • 使用推理脚本渲染单张图像
      • 推理脚本可用参数
    • 使用RenderFormerRenderingPipeline进行推理
  • 视频渲染
    • 下载示例数据
    • 使用推理脚本渲染视频
      • 推理脚本可用参数
• 自定义场景！
  • 场景定义JSON
    • 场景结构
    • 对象配置
    • 相机配置
    • 示例场景
    • HDF5数据字段
    • 重新网格化对象
    • Blender渲染参考
  • Blender插件
  • 场景设置技巧
• 致谢
• 许可证
• 引用

安装

先决条件

• 系统：代码已在Linux、MacOS和Windows上测试通过。
• 硬件：代码已在NVIDIA CUDA GPU和Apple Metal GPU上测试过。最低GPU显存要求为8GB。

环境设置

首先搭建一个支持PyTorch 2.0+的环境。对于CUDA用户，可以从https://github.com/Dao-AILab/flash-attention安装Flash Attention。

其余依赖项可通过以下命令安装：

git clone https://github.com/microsoft/renderformer
cd renderformer
pip install -r requirements.txt
python3 -c "import imageio; imageio.plugins.freeimage.download()"  # 用于HDR图像输入输出

预训练模型

模型	参数量	链接	模型ID
RenderFormer-V1-Base	2.05亿	Hugging Face	microsoft/renderformer-v1-base
RenderFormer-V1.1-Large	4.83亿	Hugging Face	microsoft/renderformer-v1.1-swin-large

关于已发布模型的说明

我们在提交时使用的训练数据中发现了一个着色器错误。我们使用修正后的着色器重新训练了模型，并发布了新版本。因此，模型性能和输出可能与论文中的结果有所不同。

使用

图像渲染

场景转换

我们在examples目录下提供了示例场景配置JSON文件。要渲染场景，首先需将场景配置JSON文件转换为我们的HDF5场景格式：

python3 scene_processor/convert_scene.py examples/cbox.json --output_h5_path tmp/cbox/cbox.h5

使用推理脚本渲染单张图像

python3 infer.py --h5_file tmp/cbox/cbox.h5 --output_dir output/cbox/

此时，您应在输出文件夹中看到output/cbox/cbox_view_0.exr和output/cbox/cbox_view_0.png。.exr是RenderFormer输出的HDR线性图像，而.png则是渲染图像的LDR版本。您可以通过--tone_mapper参数启用不同的色调映射器，以获得更好的视觉效果。

如果系统中未找到Flash Attention，脚本会自动回退到使用PyTorch的缩放点积注意力。我们还提供了一个环境变量ATTN_IMPL，供您选择使用哪种注意力实现：

# 有意使用 SDPA
ATTN_IMPL=sdpa python3 infer.py --h5_file tmp/cbox/cbox.h5 --output_dir output/cbox/

更多示例请查看 图像渲染 Shell 脚本。

推理脚本可用参数

--h5_file H5_FILE     输入 H5 文件路径
--model_id MODEL_ID   Hugging Face 上的模型 ID 或本地路径
--precision {bf16,fp16,fp32}
                      推理精度（默认：fp16）
--resolution RESOLUTION
                      推理分辨率（默认：512）
--output_dir OUTPUT_DIR
                      输出目录（默认：与输入 H5 文件相同）
--tone_mapper {none,agx,filmic,pbr_neutral}
                      推理色调映射器（默认：无）

使用 RenderFormerRenderingPipeline 进行推理

通过提供一批输入场景和渲染相机参数，您可以使用 RenderFormerRenderingPipeline 实现批量渲染。

最小示例（无实际意义的输入，仅用于测试）：

import torch
from renderformer import RenderFormerRenderingPipeline

pipeline = RenderFormerRenderingPipeline.from_pretrained("microsoft/renderformer-v1.1-swin-large")
device = torch.device('cuda')
pipeline.to(device)

BATCH_SIZE = 2
NUM_TRIANGLES = 1024
TEX_PATCH_SIZE = 32
NUM_VIEWS = 4

triangles = torch.randn((BATCH_SIZE, NUM_TRIANGLES, 3, 3), device=device)
texture = torch.randn((BATCH_SIZE, NUM_TRIANGLES, 13, TEX_PATCH_SIZE, TEX_PATCH_SIZE), device=device)
mask = torch.ones((BATCH_SIZE, NUM_TRIANGLES), dtype=torch.bool, device=device)
vn = torch.randn((BATCH_SIZE, NUM_TRIANGLES, 3, 3), device=device)
c2w = torch.randn((BATCH_SIZE, NUM_VIEWS, 4, 4), device=device)
fov = torch.randn((BATCH_SIZE, NUM_VIEWS, 1), device=device)

rendered_imgs = pipeline(
    triangles=triangles,
    texture=texture,
    mask=mask,
    vn=vn,
    c2w=c2w,
    fov=fov,
    resolution=512,
    torch_dtype=torch.float16,
)
print("推理完成。渲染的线性 HDR 图像形状：", rendered_imgs.shape)
# 推理完成。渲染的线性 HDR 图像形状：torch.Size([2, 4, 512, 512, 3])

详细用法请参阅 infer.py 和 rendering_pipeline.py。

视频渲染

下载示例数据

我们已将示例视频输入数据放置在 Hugging Face 上。您可以通过 此脚本 下载并解压这些数据。

使用推理脚本渲染视频

python3 batch_infer.py --h5_folder renderformer-video-data/submission-videos/cbox-roughness/ --output_dir output/videos/cbox-roughness

更多示例请查看 视频渲染 Shell 脚本。

推理脚本可用参数

--h5_folder H5_FOLDER
                      包含输入 H5 文件的文件夹路径
--model_id MODEL_ID   Hugging Face 上的模型 ID 或本地路径
--precision {bf16,fp16,fp32}
                      推理精度
--resolution RESOLUTION
                      推理分辨率
--batch_size BATCH_SIZE
                      推理批次大小
--padding_length PADDING_LENGTH
                      推理填充长度
--num_workers NUM_WORKERS
                      数据加载的工作进程数
--output_dir OUTPUT_DIR
                      渲染图像的输出目录（默认：与输入文件夹相同）
--save_video          将渲染图像合并为 video.mp4 视频文件。
--tone_mapper {none,agx,filmic,pbr_neutral}
                      推理色调映射器

自定义场景！

场景定义 JSON

RenderFormer 使用基于 JSON 的场景描述格式，用于定义场景的几何、材质、光照和相机设置。场景配置采用分层结构，包含以下关键组件：

场景结构

• scene_name: 场景的描述性名称
• version: 场景描述格式的版本（当前为“1.0”）
• objects: 场景中对象的字典，包括几何和光源
• cameras: 渲染用相机配置列表

对象配置

场景中的每个对象需要：

• mesh_path: .obj 网格文件的路径
• material: 材质属性，包括：
  • diffuse: RGB 漫反射颜色 [r, g, b]
  • specular: RGB 镜面反射颜色 [r, g, b]（目前仅支持白色镜面反射，且漫反射 + 镜面反射之和不得超过 1.0）
  • roughness: 表面粗糙度（0.01 至 1.0）
  • emissive: RGB 发光颜色 [r, g, b]（目前仅支持白色发光，且仅限于光源三角形）
  • smooth_shading: 是否对此对象启用平滑着色
  • rand_tri_diffuse_seed: 随机三角形着色的可选种子，若未指定，则直接使用漫反射颜色
  • random_diffuse_max: 随机漫反射颜色的最大值（漫反射 + 镜面反射之和不得超过 1.0）
  • random_diffuse_type: 随机漫反射颜色分配类型，可按三角形或着色组分配
• transform: 对象变换，包括：
  • translation: [x, y, z] 位置
  • rotation: [x, y, z] 旋转角度
  • scale: [x, y, z] 缩放因子
  • normalize: 是否将对象归一化到单位球体
• remesh: 是否对对象进行重新网格化
• remesh_target_face_num: 重新网格化后的目标面数

相机配置

每个相机需要：

• position: [x, y, z] 相机位置
• look_at: [x, y, z] 目标点
• up: [x, y, z] 上方向量
• fov: 视场角（以度为单位）

示例场景

建议从 examples/init-template.json 开始，并根据需求进行修改。对于更复杂的场景，请参考 examples 目录中的场景配置。

HDF5 数据字段

HDF5 文件包含以下字段：

• triangles: [N, 3, 3] 三角形顶点数组
• texture: [N, 13, 32, 32] 纹理贴图数组
• vn: [N, 3, 3] 顶点法向量数组
• c2w: [N, 4, 4] 相机到世界矩阵数组
• fov: [N] 视场角数组

我们使用的相机坐标系与 Blender 一致（-Z = 观察方向，+Y = 上方，+X = 右侧），在实现自己的 HDF5 转换器时请注意坐标系问题。

更多详情请参阅 scene_processor/to_h5.py。

重新网格化对象

我们在 scene_processor/remesh.py 中提供了一个简单的重新网格化工具。您可以在将对象放入场景之前使用该工具对其进行重新网格化。

此外，场景配置 JSON 文件中还提供了 remesh 和 remesh_target_face_num 字段，允许您在场景转换过程中对对象进行重新网格化。

python3 scene_processor/remesh.py --input path/to/your/high_res_mesh.obj ----output remeshed_object.obj --target_face_num 1024

使用 Blender 渲染参考图像

我们提供了一个脚本 scene_processor/to_blend.py，用于使用 Blender 渲染参考图像。该脚本会将 JSON 描述的场景转换为 Blender 场景，这样你就可以用 Blender 渲染场景，或者将其保存为 Blend 文件以供后续使用。

示例用法：

python3 scene_processor/to_blend.py examples/cbox.json --output_dir tmp/cbox --dump_blend --save_img --spp 4096

有关详细用法，请查看该脚本。

Blender 扩展

我们提供了一个 Blender 扩展，以简化为 RenderFormer 设置场景的过程。更多详情请参阅 Blender 扩展。

场景设置提示

1. 始终从 examples/init-template.json 开始。
2. 请将场景限制在我们的训练数据范围内，外推虽然可能有效，但无法保证。
   • 相机到场景中心的距离在 [1.5, 2.0] 米之间，视场角在 [30, 60] 度之间。
   • 场景包围盒在 x、y、z 方向上的范围均为 [-0.5, 0.5]。
   • 光源：最多 8 个三角形（请使用 examples/templates/lighting/tri.obj 中的三角网格），每个光源的缩放比例在 [2.0, 2.5] 之间，到场景中心的距离在 [2.1, 2.7] 米之间，所有光源的总发光强度之和应在 [2500, 5000] 之间。
   • 三角形总数：训练数据涵盖最多 4096 个三角形，但在推理时扩展到 8192 个三角形通常仍然可行。
   • 所有训练对象都是水密且经过 QSlim 简化的。建议使用均匀的三角形大小。如果发现你的对象无法正常工作，可以尝试使用我们提供的脚本或其他网格重拓扑工具对其进行重新网格化。

致谢

我们借鉴了以下仓库中的一些代码，在此感谢作者们的贡献：

• DPT
• nerfstudio
• rotary-embedding-torch

除了来自 Objaverse 的 3D 模型外，我们还对我们在示例中使用的 3D 模型的贡献者表示深深的感谢：

• 着色球：由 Wenzel Jakob 来自 Mitsuba Gallery
• 斯坦福兔子与露西：来自 斯坦福 3D 扫描库
• 康奈尔盒子：来自 康奈尔大学计算机图形学项目中的康奈尔盒子数据
• 犹他茶壶：来自 犹他模型库
• Veach MIS：由 Eric Veach 和 Leonidas J. Guibas 提出。1995 年发表的论文《蒙特卡洛渲染中采样技术的最优组合》
• Spot：由 Keenan Crane 来自 Keenan 的 3D 模型库
• 克莱因瓶：由 Fausto Javier Da Rosa 创作
• 常宽体：原始网格来自 小体积常宽体。衍生网格来自 Keenan 的 3D 模型库
• 珠宝：由 elbenZ 创作
• 香蕉、复活节篮子、水瓶、野马车、心形拼图：均由 Microsoft 创作
• 低多边形狐狸：由 Vlad Zaichyk 创作
• 低多边形水晶：由 Mongze 创作
• 保龄球瓶：由 SINOFWRATH 创作
• 立方体瀑布、漫步立方体：由 Tycho Magnetic Anomaly 创作
• 跳舞的螃蟹：由 Bohdan Lvov 创作
• 魔法陀螺仪：由 reddification 创作
• 卡波耶拉立方体：由 mortaleiros 创作
• P.U.C. 安全机器人：由 Gouhadouken 创作

许可证

RenderFormer 模型及大部分代码采用 MIT 许可证授权。以下子模块可能有不同的许可证：

• renderformer-liger-kernel：为 RenderFormer 集成而重新分发的 Liger Kernel。它源自原始的 Liger Kernel，并采用 BSD 2-Clause “简化” 许可证授权（详见 LICENSE.txt）。
• simple-ocio：我们使用此工具来简化 OpenColorIO 在色调映射中的使用。该包重新分发了完整的 Blender 颜色管理目录。完整的许可证文本可在 ocio-license.txt 以及各配置文件的头部找到。该包本身仍采用 MIT 许可证授权（详见 LICENSE）。

引用

如果您觉得这项工作对您有所帮助，请引用我们的论文：

@inproceedings {zeng2025renderformer,
    title      = {RenderFormer: 基于 Transformer 的三角网格全局光照神经渲染},
    author     = {Chong Zeng 和 Yue Dong 和 Pieter Peers 和 Hongzhi Wu 和 Xin Tong},
    booktitle  = {ACM SIGGRAPH 2025 会议论文集},
    year       = {2025}
}

RenderFormer 快速上手指南

RenderFormer 是一个基于 Transformer 的神经渲染管线，能够直接从三角形网格场景生成包含全局光照（如镜面反射、复杂阴影、漫反射间接照明等）的图像，且无需针对特定场景进行训练或微调。

环境准备

系统要求

• 操作系统：Linux、macOS 或 Windows
• 硬件要求：
  • GPU：NVIDIA CUDA GPU 或 Apple Metal GPU
  • 显存：最低 8GB

前置依赖

• Python 环境
• PyTorch 2.0+
• (可选) Flash Attention：CUDA 用户建议安装以提升性能

安装步骤

1. 克隆仓库并进入目录

   git clone https://github.com/microsoft/renderformer
   cd renderformer
   

2. 安装依赖包

   pip install -r requirements.txt
   

   提示：国内用户可使用清华源加速安装： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 下载 FreeImage 插件（用于 HDR 图像读写）

   python3 -c "import imageio; imageio.plugins.freeimage.download()"
   

4. (可选) 安装 Flash Attention 如果是 NVIDIA GPU 用户，推荐安装：

   pip install flash-attn --no-build-isolation
   

5. 获取预训练模型 模型将自动从 Hugging Face 下载，也可手动指定本地路径。

   • 推荐模型：microsoft/renderformer-v1.1-swin-large (483M 参数)
   • 基础模型：microsoft/renderformer-v1-base (205M 参数)

基本使用

以下流程演示如何将一个示例场景转换为渲染格式并生成图像。

1. 场景转换

首先将示例场景配置文件（JSON）转换为 RenderFormer 所需的 HDF5 格式：

python3 scene_processor/convert_scene.py examples/cbox.json --output_h5_path tmp/cbox/cbox.h5

2. 渲染单张图像

使用推理脚本对转换后的场景进行渲染：

python3 infer.py --h5_file tmp/cbox/cbox.h5 --output_dir output/cbox/

输出说明：

• output/cbox/cbox_view_0.exr：线性 HDR 输出结果
• output/cbox/cbox_view_0.png：经过色调映射的 LDR 图片

常用参数：

• --model_id：指定模型 ID（默认自动加载）
• --resolution：渲染分辨率（默认 512）
• --tone_mapper：色调映射器，可选 none, agx, filmic, pbr_neutral

示例（使用 Filmic 色调映射）：

python3 infer.py --h5_file tmp/cbox/cbox.h5 --output_dir output/cbox/ --tone_mapper filmic

3. Python 代码调用（批量推理）

你也可以直接在 Python 代码中使用 RenderFormerRenderingPipeline 进行批量渲染：

import torch
from renderformer import RenderFormerRenderingPipeline

# 加载预训练模型
pipeline = RenderFormerRenderingPipeline.from_pretrained("microsoft/renderformer-v1.1-swin-large")
device = torch.device('cuda')
pipeline.to(device)

# 构造输入数据示例 (实际使用时请替换为真实的场景数据)
BATCH_SIZE = 2
NUM_TRIANGLES = 1024
TEX_PATCH_SIZE = 32
NUM_VIEWS = 4

triangles = torch.randn((BATCH_SIZE, NUM_TRIANGLES, 3, 3), device=device)
texture = torch.randn((BATCH_SIZE, NUM_TRIANGLES, 13, TEX_PATCH_SIZE, TEX_PATCH_SIZE), device=device)
mask = torch.ones((BATCH_SIZE, NUM_TRIANGLES), dtype=torch.bool, device=device)
vn = torch.randn((BATCH_SIZE, NUM_TRIANGLES, 3, 3), device=device)
c2w = torch.randn((BATCH_SIZE, NUM_VIEWS, 4, 4), device=device)
fov = torch.randn((BATCH_SIZE, NUM_VIEWS, 1), device=device)

# 执行渲染
rendered_imgs = pipeline(
    triangles=triangles,
    texture=texture,
    mask=mask,
    vn=vn,
    c2w=c2w,
    fov=fov,
    resolution=512,
    torch_dtype=torch.float16,
)

print("渲染完成。输出形状:", rendered_imgs.shape)
# 输出: torch.Size([2, 4, 512, 512, 3])