kesai-labs/py123d

py123d – 통합된 다중 모달 자율주행 데이터셋 라이브러리

무엇인가요 – py123d는 Argoverse 2, nuScenes, Waymo, nuPlan, KITTI‑360, PandaSet 등 주요 자율주행 데이터셋을 단일하고 일관된 API로 다룰 수 있게 해주는 Python 패키지입니다. 이 라이브러리는 원시 데이터를 다운로드하고, 열 기반의 Apache Arrow 형식으로 변환한 후, 카메라, 라이다, 지도, 주석에 대한 제로 코피, 메모리 매핑 접근을 제공합니다.

왜 중요한가요 – 자율주행 연구에서는 다양한 파일 구조, 센서 코덱, 라벨 스키마를 다뤄야 하는 경우가 많습니다. py123d는 이러한 복잡성을 제거하여 다음과 같은 가능성을 제공합니다:

• CLI를 통해 공식 소스에서 데이터를 직접 가져올 수 있습니다.
• 전체 데이터셋을 RAM에 로드하지 않고도 즉시 읽을 수 있는 컴팩트한 Arrow 파일에 모든 데이터를 저장할 수 있습니다.
• 학습 또는 평가 코드를 변경하지 않고도 데이터셋 간 전환 가능합니다.
• 내장된 Viser 3‑D 뷰어 또는 간단한 Matplotlib 플롯으로 즉시 장면을 시각화할 수 있습니다.

주요 기능

기능	세부 사항
데이터셋 다운로드 및 변환	한 줄 CLI (py123d-conversion …)로 원시 로그를 가져와 Arrow 형식으로 변환하고 원본을 정리합니다.
Hydra 기반 파이프라인	YAML 설정을 통해 복잡한 변환 단계를 정의하고 프로젝트 간에 재사용할 수 있습니다.
제로 코피 Arrow 저장	열 기반, 메모리 매핑 읽기로 수십억 개의 포인트나 프레임에 대해 빠르고 메모리 효율적인 접근이 가능합니다.
다중 센서 코덱 지원	카메라에는 MP4/JPEG/PNG, 라이다 포인트 클라우드에는 LAZ/Draco/Arrow IPC를 지원합니다.
센서 중복 없음	변환된 로그는 원본 파일에 대한 참조를 유지하여 중복 저장을 방지합니다.
통합 API	어떤 지원되는 데이터셋이든 동일한 Python 호출 (scene.cameras(), scene.lidar(), scene.map(), scene.labels())이 가능합니다.
내장 시각화 도구	인터랙티브 3‑D 뷰어(Viser)와 Matplotlib 헬퍼를 통해 빠르게 검토할 수 있습니다.
확장 가능한 모달리티	최신 릴리스에서는 깊이 카메라, 레이더, 픽셀 단위 세그멘테이션, 경로 정보, 자세 불확실성 필드를 추가했습니다.
다중 데이터셋 학습 지원	커플러 리포지토리 py123d_garage는 학습 루프, NAVSIM 메트릭, CARLA/AlpaSim로의 시뮬레이션 브리지 기능을 제공합니다.

설치

# 핵심 라이브러리
pip install py123d

# 특정 데이터셋용 확장 (필요한 것만 설치)
# 예: Argoverse 2 지원
pip install py123d[av2]

패키지는 표준 Python 버전 관리에 따라 관리되며 PyPI에 호스팅되어 있습니다.

빠른 데모 (Argoverse 2)

# 1️⃣ AV2 확장 설치
pip install py123d[av2]

# 2️⃣ 변환된 데이터가 저장될 위치 지정
export PY123D_DATA_ROOT=/my/py123d_data

# 3️⃣ 3개의 검증 로그를 다운로드하고 Arrow 형식으로 변환
py123d-conversion dataset=av2-sensor-stream \
  dataset.parser.splits='[av2-sensor_val]' \
  dataset.parser.downloader.num_logs=3

# 4️⃣ 인터랙티브 뷰어 실행
py123d-viser scene_filter=av2-sensor

브라우저에서 http://localhost:8080을 열어 장면을 탐색하세요.

지원되는 데이터셋 – 이 라이브러리는 수동, 자동 라벨링, 합성 데이터 컬렉션을 포함해 다양한 데이터셋을 다룹니다:

• 수동 라벨링: nuScenes, Waymo Open Perception, Argoverse 2 Sensor, PandaSet, KITTI‑360
• 자동 라벨링: Waymo Open Motion, nuPlan (및 mini), NVIDIA Physical AI AV, NCore
• 합성 데이터: CARLA, L3AD (CARLA 기반) 각 항목은 사용 가능한 센서(카메라, 라이다, 레이더)와 라벨 유형(3‑D 박스, 신호등, 지도, 세그멘테이션 등)을 나열합니다.

문서 및 커뮤니티 – 전체 API 참조, 변환 가이드, 기여 지침은 https://kesai.eu/py123d/ 에서 확인할 수 있습니다. 프로젝트는 Apache‑2.0 라이선스 하에 오픈소스이며, 새로운 데이터셋이나 모달리티 확장을 환영합니다.

---

인용 py123d를 연구에 사용할 경우, 다음 논문을 인용해 주세요:

@article{Dauner2026ARXIV,
  title={123D: Unifying Multi-Modal Autonomous Driving Data at Scale},
  author={Dauner, Daniel and Charraut, Valentin and Berle, Bastian and Li, Tianyu and Nguyen, Long and Wang, Jiabao and Jing, Changhui and Igl, Maximilian and Caesar, Holger and Ivanovic, Boris and Geiger, Andreas and Chitta, Kashyap},
  journal={arXiv preprint arXiv:2605.08084},
  year={2026}
}