PolarSynth
收藏资源简介：
PolarSynth是一个用于生成大规模合成偏振数据集的工具链，结合Mitsuba 3（偏振路径追踪）和Blender（几何预处理、材质烘焙和AOV通道）。它生成Stokes向量EXR文件以及每视图几何/材质AOVs，并后处理为典型形状从偏振数据集中使用的每偏振器角度PNG和AOLP/DOLP图。
PolarSynth is a toolchain for generating large-scale synthetic polarization datasets, integrating Mitsuba 3 (for polarized path tracing) and Blender (for geometry preprocessing, material baking, and AOV channels). It generates Stokes vector EXR files and per-view geometry/material AOVs, and post-processes these outputs into per-polarizer-angle PNG files as well as AOLP and DOLP maps that are commonly used in shape-from-polarization datasets.
PolarSynth — 合成偏振数据集生成管线
PolarSynth 是一个用于大规模生成合成偏振数据集的工具包，通过结合 Mitsuba 3（偏振路径追踪）和 Blender（几何预处理、材质烘焙、AOV 通道），输出 Stokes 向量 EXR 格式数据以及逐视角的几何/材质 AOV 通道。
核心能力
- 多场景采样：随机组合网格（OBJ）、PBR 材质（置换/漫反射/粗糙度）、HDRI 环境光照和点/聚/投影/方向光、相机位姿（斐波那契螺旋、半球、平面等）。
- 后处理转换：将 EXR 转为偏振片角度 PNG（0°/45°/90°/135°）和 AOLP/DOLP 图。
- 四种管线模式：
render_sgl_obj.py：单物体，随机材质/光照。render_mult_obj.py：多物体场景（可带地面）。render_metal_dielec_obj.py：混合金属+电介质场景（两遍渲染用于材质分割掩码）。render_case_study.py：确定性参数扫描（材质/反照率/粗糙度/环境图）。
- 两种 Mitsuba 执行模式：子进程 CLI（默认）和进程内
mi.render()（--inprocess参数）。 - Blender Cycles AOV 通道：反照率、粗糙度、法线、深度、逐材质掩码（金属/电介质）。
- 12 个烟雾测试：无需安装 Mitsuba / Blender 即可运行。
系统要求
| 组件 | 测试版本 | 说明 |
|---|---|---|
| Python | 3.10 - 3.12 | |
| Mitsuba 3 | 3.3 - 3.5 | 需编译对应 ..._spectral_polarized 变体。 |
| Blender | 3.6 LTS | 需在 $PATH 中可用。 |
| numpy / opencv-python / matplotlib / tqdm | 见 requirements.txt | |
| OpenEXR + Imath | 1.3 / 0.0.3 | 多层 EXR 读写。 |
GPU 加速可选：Mitsuba 需 CUDA 变体，Blender 自动识别 GPU。
安装步骤
- 克隆仓库：
git clone https://github.com/youweilyu/PolarSynth.git - 安装 Python 依赖：
pip install -r requirements.txt - 加载 Mitsuba 环境：
source /path/to/mitsuba3/build/setpath.sh - 验证 Blender：
blender --version - 复制并编辑环境配置：
cp .env.example .env，调整资产路径。
资产布局
- 资产根目录（默认
./assets/3D_assets）：hdri/polyhaven/— 存放.exr环境图。materials/ambientcg/<MaterialName>/— 包含Color.jpg、Roughness.jpg、Displacement.jpg。models/— 存放.obj文件和配套的<mesh>_objinfo.npy文件（含包围盒中心、对称性、扁平性、顶点数等信息）。
- 路径列表文件（
.txt）：分别列出模型、材质、HDRI 路径，存放于txts/目录。
快速开始
-
烟雾测试渲染： bash python render_sgl_obj.py --model_txt_path txts/models_demo.txt --material_txt_path txts/materials_demo.txt --hdri_txt_path txts/hdri_demo.txt --num_rendered_per_obj 1 --pose_num_per_scene 1 --save_dir renderings/smoke --cache_dir tmp/smoke --workers 8 --debug
成功运行会生成每视角的
mi.exr（S0/S1/S2 Stokes、法线、反照率、深度）、bl.exr（Blender AOV）、JPG 预览及四个偏振角 PNG。 -
批量渲染：参考
run/目录下的驱动脚本。 -
EXR 转偏振 PNG：运行
python check_scripts/convert_renderings.py（需编辑内部路径）。
常用参数
--model_txt_path / --material_txt_path / --hdri_txt_path：指定资产列表。--save_dir / --cache_dir：输出/缓存路径。--mi_variant：Mitsuba 变体（scalar_rgb最快，cuda_spectral_polarized需 GPU）。--workers：线程数。--pose_num_per_scene：每场景视角数。--inprocess：跳过子进程直接渲染。--debug：DEBUG 日志级别。- 多物体管线额外参数：
--num_obj_per_scene、--num_scene、--mesh_superimpose、--fov等。
输出格式
每视角生成（<save_dir>/ 下）：
<scene>_<idx>_mi.exr— 多层 EXR（Stokes + AOV）。<scene>_<idx>_bl.exr— Blender Cycles 多层 EXR。<scene>_<idx>_img_mi.jpg— 色调映射预览。<scene>_<idx>_albedo_bl.png— 漫反射颜色。<scene>_<idx>_rough_bl.png— 粗糙度。<scene>_<idx>_normal_G_bl.png— 相机空间法线。<scene>_<idx>_normal_L_bl.png— 世界空间法线。<scene>_<idx>_mask_bl.png— 前景掩码。<scene>_<idx>_dielec_mask_bl.png / _metal_mask_bl.png— 多物体/混合场景专用。
经转换后，偏振角 PNG 存放于 <dst_dir>/pol000/、pol045/、pol090/、pol135/，掩码存于 mask/。
仓库结构
- 入口脚本：
render_sgl_obj.py、render_mult_obj.py、render_metal_dielec_obj.py、render_case_study.py。 - Blender 后处理：
blender_postprocess.py、blender_postprocess_multobj.py、blender_postprocess_common.py。 - 工具模块：
utils/下包含采样器、渲染器、文件工具、CLI 等。 - 独立工具：
tools/下包含 Objaverse 下载、EXR 转换、网格格式转换等脚本。 - 其他目录：
scenes/（标准 XML 场景片段）、xmls/（探索用 XML）、check_scripts/（后处理批处理）、run/（驱动脚本）、tests/（测试）。
性能建议
- 使用
--inprocess避免频繁进程启动，pose_num_per_scene较大时加速显著。 - 烟雾测试用
--mi_variant scalar_rgb最快。 - 利用 Blender 的平滑网格缓存（自动写入
<model>_smooth<level>.obj）。 - 将
MitsubaRenderer对象创建在场景循环外部，避免 LLVM/CUDA 后端重复预热。
引用
若用于研究，请引用以下论文及 Mitsuba 3、Blender： bibtex @inproceedings{lyu2024sfpuel, title={{SfPUEL}: Shape from Polarization under Unknown Environment Light}, author={Youwei Lyu and Heng Guo and Kailong Zhang and Si Li and Boxin Shi}, booktitle={NeurIPS}, year={2024}, }
