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로 변환.

📄 라이선스 및 인용

데이터셋 – 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를 사용해 이러한 데이터를 생성하거나 확장할 수 있게 해줍니다. 깊이, 법선, 세마틱, 또는 내재 이미지 분해에 대한 고품질 진짜 레이블이 필요한 모든 프로젝트에 있어 신뢰할 수 있는 연구용 자원입니다.