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 創建或擴展此類資料。它是任何需要深度、法線、語意或內在影像分解高品質真值的專案所倚賴的可靠研究級資源。