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自由度の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自由度（位置、向き、サイズ）のボックス	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 – ハードウェアで表示可能なPNGにRAW HDRチャンネルを変換。

📄 ライセンスと引用

データセット – Creative Commons Attribution-ShareAlike 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を使ってデータの作成または拡張が可能です。深度、法線、セマンティクス、または内在画像分解の高品質真値が必要なすべてのプロジェクトに、信頼できる研究用リソースです。