apple-aiml-research/ml-hypersim

Hypersim: A Photorealistic Synthetic Dataset for Holistic Indoor Scene Understanding

📚 什么是 Hypersim 数据集与工具包？

Hypersim 是一个大型、逼真的合成数据集，旨在实现 全面的室内场景理解。它提供：

77,400 张渲染图像（约 1.9TB）来自 461 个室内场景，每张图像均带有密集的像素级真值标签。
每张图像均包含完整的 几何、材质、光照、相机位姿和内参。
图像通道分解——颜色、漫反射反射率、漫反射光照和残差项，使研究人员可以分别研究阴影、反照率和光照。
丰富的 语义和实例注释（NYU-40 类别标签）以及每个物体的 9-DOF 3D 边界框。
基于 V‑Ray 的 工具包，可生成类似数据集、编辑场景、脚本化相机轨迹，并添加自定义镜头效果。

该项目是计算机视觉和图形学研究的真正研究级资源，适用于深度估计、语义分割、材质估计和神经渲染等任务。

🔑 核心组件

组件	包含内容	重要性
图像文件 (`scene_cam_XX_final_hdf5`)	HDR 颜色、漫反射光照、漫反射反射率、残差（无色调映射）	支持内在图像分解和基于物理的渲染任务学习
几何文件 (`scene_cam_XX_geometry_hdf5`)	深度（米）、世界空间位置、表面法线（含/不含凹凸）、语义/实例 ID、渲染实体 ID、纹理坐标	为深度、法线和分割模型提供真值
元数据 (`_detail/…`)	相机轨迹（位置与朝向）、场景尺度、物体到节点映射、每场景 CSV 文件	可重建精确相机位姿，并将资产单位转换为米
网格注释 (`mesh_objects_*.hdf5`, `metadata_objects.csv`)	每个物体的 NYU-40 类别和实例 ID、物体名称	提供分割和实例感知学习所需的语义标签
边界框数据 (`metadata_semantic_instance_bounding_box_*.hdf5`)	每个实例的 9-DOF（位置、朝向、尺寸）边界框	适用于 3D 物体检测和姿态估计
工具包代码 (`code/python/tools/…`)	下载、色调映射、可视化边界框、生成新轨迹等脚本	提供开箱即用的管道，用于创建新合成数据或调整现有场景

🎯 典型应用场景

室内深度估计、表面法线预测和语义/实例分割网络的 训练数据。
内在图像分解研究——分离的反射率/光照通道可测试恢复反照率和光照的算法。
神经渲染 / 逆图形学——完整的 V‑Ray 场景信息（材质、光照、几何）支持基于学习的渲染流程。
基准测试——提供的 train/val/test 分割（v1）支持论文间的可复现评估。
数据集生成——Hypersim 工具包可用于合成新场景，或通过自定义相机路径或镜头畸变增强现有数据。

🚀 快速入门

下载数据

python code/python/tools/dataset_download_images.py \
    --downloads_dir /path/to/downloads \
    --decompress_dir /path/to/evermotion_dataset/scenes

完整发布版约 1.9TB；也可使用 contrib/99991 中的社区贡献脚本获取子集。

安装 Python 依赖项（Anaconda 快速启动）：
```
conda env create -f environment.yml   # 拉取 h5py、numpy、pandas 等
conda activate hypersim
```
（README 继续详细说明系统级前提条件——仅当你计划渲染新场景时才需要 V‑Ray Standalone/AppSDK。）

探索数据

import h5py, numpy as np
f = h5py.File('ai_001_001/images/scene_cam_00_final_hdf5/frame.0000.color.hdf5', 'r')
color = np.array(f['data'])   # HDR 颜色图像

使用提供的 scene_generate_images_tonemap.py 应用色调映射算子以进行可视化。

运行演示——仓库包含示例脚本，如：
- scene_generate_images_bounding_box.py —— 渲染叠加 3D 实例框的图像。
- scene_generate_images_tonemap.py —— 将原始 HDR 通道转换为可显示的 PNG。

📄 许可与引用

数据集 – 创作共用署名-相同方式共享 3.0（CC-BY-SA 3.0）。
代码 – 请参阅仓库的 LICENSE 文件（主要为宽松许可，部分组件关联 GPL，可选择性排除）。

引用 – 若使用 Hypersim，请引用 ICCV 2021 论文：

@inproceedings{roberts:2021,
    author = {Mike Roberts and Jason Ramapuram and Anurag Ranjan and Atulit Kumar and
              Miguel Angel Bautista and Nathan Paczan and Russ Webb and Joshua M. Susskind},
    title  = {{Hypersim}: A Photorealistic Synthetic Dataset for Holistic Indoor Scene Understanding},
    booktitle = {International Conference on Computer Vision (ICCV) 2021},
    year = {2021}
}

🛠️ Hypersim 工具包（简要）

低级工具包 – 直接操作单个 V‑Ray 场景文件（添加几何、设置自定义镜头模型、导出像素级真值）。
高级工具包 – 批量处理多个场景（自动生成无碰撞相机路径、应用语义标签、协调大规模渲染）。
依赖项 – V‑Ray Standalone/AppSDK（商业），以及开源库（NumPy、h5py、OpenCV 等）。
免责声明 – 部分可选组件包含 GPL 许可代码；核心工具包无需它们仍可使用。

TL;DR

Hypersim 数据集 为研究人员提供了一个大规模、丰富标注的室内合成图像集合，而配套的 工具包 则允许使用 V‑Ray 创建或扩展此类数据。它是任何需要深度、法线、语义或内在图像分解高质量真值的项目所依赖的可靠研究级资源。