kesai-labs/py123d

py123d – 統一的多模態自動駕駛資料集程式庫

是什麼 – py123d 是一個 Python 套件，可透過單一且一致的 API 使用多個主要自動駕駛資料集（Argoverse 2、nuScenes、Waymo、nuPlan、KITTI‑360、PandaSet 等）。它下載原始資料，轉換為欄式 Apache Arrow 格式，並提供對相機、雷達、地圖和標註的零複製、記憶體對映存取。

為何重要 – 自動駕駛研究經常需處理不同的檔案結構、感測器編碼與標註架構。py123d 消除此障礙，讓您能：

• 透過 CLI 直接從官方來源取得資料。
• 將所有內容儲存在緊湊的 Arrow 檔案中，無需將整個資料集載入 RAM 即可立即讀取。
• 在不更動訓練或評估程式碼的情況下切換資料集。
• 使用內建的 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}
}