RenderFormer是一种神经渲染管道,它能直接从基于三角形场景表征中渲染出具有完整全局光照效果的图像,且无需针对特定场景进行训练或微调。该方法摒弃了以物理为中心的渲染思路,将渲染过程建模为序列到序列的转换任务——将代表带有反射属性三角形的标记序列,转化为代表像素小块的输出标记序列。RenderFormer采用两阶段流程:第一阶段与视角无关,建模三角形间的光传输;第二阶段与视角相关,在前阶段生成的三角形序列引导下,将代表射线束的标记转换为对应像素值。两个阶段均基于Transformer架构,学习过程仅施加极少先验约束。我们在具备不同形状复杂度和光传输特性的场景中验证并评估了RenderFormer的性能。
安装指南
系统要求
- 操作系统: 代码已在Linux、MacOS和Windows系统上通过测试。
- 硬件配置: 代码支持NVIDIA CUDA显卡和Apple Metal显卡运行,最低需要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()" # Needed for HDR image IO
预训练模型
模型 | 参数数量 | 链接 | 模型ID |
---|---|---|---|
RenderFormer-V1-Base | 205M | Hugging Face | microsoft/renderformer-v1-base |
RenderFormer-V1.1-Large | 483M | Hugging Face | microsoft/renderformer-v1.1-swin-large |
我们在提交使用的训练数据中发现了一个着色器错误。现已使用修正后的着色器重新训练模型并发布了新版。因此模型性能与输出可能与论文中的结果存在差异。
使用方法
图像渲染
场景转换
示例场景配置的JSON文件存放在examples
目录下。要渲染一个场景,首先需要将场景配置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,脚本将自动回退使用torch缩放点积注意力。我们还提供了ATTN_IMPL
环境变量供你选择要使用的注意力实现方式:
# Use SDPA intentionally
ATTN_IMPL=sdpa python3 infer.py --h5_file tmp/cbox/cbox.h5 --output_dir output/cbox/
推理脚本的可用参数
--h5_file H5_FILE Path to the input H5 file
--model_id MODEL_ID Model ID on Hugging Face or local path
--precision {bf16,fp16,fp32}
Precision for inference (Default: fp16)
--resolution RESOLUTION
Resolution for inference (Default: 512)
--output_dir OUTPUT_DIR
Output directory (Default: same as input H5 file)
--tone_mapper {none,agx,filmic,pbr_neutral}
Tone mapper for inference (Default: none)
使用 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("Inference completed. Rendered Linear HDR images shape:", rendered_imgs.shape)
# Inference completed. Rendered Linear HDR images shape: 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
请查看 视频渲染脚本 获取更多示例。
推理脚本的可用参数
--h5_folder H5_FOLDER
Path to the folder containing input H5 files
--model_id MODEL_ID Model ID on Hugging Face or local path
--precision {bf16,fp16,fp32}
Precision for inference
--resolution RESOLUTION
Resolution for inference
--batch_size BATCH_SIZE
Batch size for inference
--padding_length PADDING_LENGTH
Padding length for inference
--num_workers NUM_WORKERS
Number of workers for data loading
--output_dir OUTPUT_DIR
Output directory for rendered images (default: same as input folder)
--save_video Merge rendered images into a video at video.mp4.
--tone_mapper {none,agx,filmic,pbr_neutral}
Tone mapper for inference
场景自备
场景定义JSON格式
RenderFormer采用基于JSON的场景描述格式,该格式定义了场景的几何结构、材质、光照和相机设置。场景配置通过以下关键组件构建层次化结构:
场景结构
scene_name
: 场景描述性名称version
: 场景描述格式版本号(当前为"1.0")objects
: 包含几何体和光源的场景对象字典cameras
: 用于渲染的相机配置列表
对象配置
场景中的每个对象需要包含以下参数:
mesh_path
: .obj网格文件的路径material
: 材质属性,包含:diffuse
: 漫反射RGB颜色值 [r, g, b]specular
: 镜面反射RGB颜色值 [r, g, b](目前仅支持白色镜面反射,且diffuse+specular总和不得超过1.0)roughness
: 表面粗糙度(0.01至1.0)emissive
: 自发光RGB颜色值 [r, g, b](目前仅支持白色自发光,且仅限光源三角面)smooth_shading
: 是否对该对象使用平滑着色rand_tri_diffuse_seed
: 随机三角面着色的可选种子值,如未指定则直接使用diffuse颜色random_diffuse_max
: 随机漫反射颜色分配的最大值(最大diffuse颜色+specular颜色总和不得超过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
: 视野角度(单位:度)
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转换器时请注意坐标系定义。
Blender扩展插件
我们提供了一个Blender扩展插件,用于简化RenderFormer的场景设置流程。更多详情请参阅Blender扩展插件。
场景设置技巧
- 始终从
examples/init-template.json
文件开始 - 请将场景限制在我们的训练数据范围内,虽然外推可能有效但不能保证效果
- 相机到场景中心的距离应在[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进行了简化。建议使用均匀分布的三角形。如果发现模型无法工作,请尝试使用我们提供的脚本或其他重网格化工具进行重新网格化
致谢
我们借鉴了以下代码库的部分内容,感谢原作者们的贡献:
代码
https://github.com/microsoft/renderformer