3RScan/SONATA_INPUT_README.md

3RScan → Sonata feature 的 input point cloud 說明

Sonata extract_features.py 接受的 input 格式

根據 Sonata_run/sonata/code/extract_features.py，input point cloud 支援以下檔案格式：

副檔名	內容規格
.ply	Open3D 可讀的點雲：points（必要）、colors（可選）、normals（可選）
.pcd	同上，Open3D 讀取
.npy	N×3（僅座標）或 N×6（座標 + RGB），無 normal
.npz	需有 key "coord" (N×3 float32)；可選 "color" (N×3)、"normal" (N×3)

欄位說明

• coord（必要）：(N, 3) float32，點座標 (x, y, z)。
• color（可選）：(N, 3) float32，RGB；0–1 或 0–255 皆可（程式會把 >1.1 的除以 255）。
• normal（可選）：
  • 可放在檔案內（.ply/.pcd/.npz），或
  • 用 --preprocessed-dir 指向內含 normal.npy 的目錄；
    若都沒有，後續會用 zeros。

呼叫範例（ScanNet）

python extract_features.py \
  --input /path/to/scene0024_00_vh_clean_2.ply \
  --preprocessed-dir /path/to/sonata_preprocessed/scene0024_00 \
  --output /path/to/scene0024_00_down_zeros.npz

---

你目前的 3RScan 資料結構

• 點雲位置：scan_data/pcd_with_global_alignment/<scan_id>.pth
• 格式：PyTorch .pth，內容為 tuple：
  1. coord：(N, 3) float64，全域對齊後的座標
  2. color：(N, 3) float32，RGB 0–255
  3. 第三項：(N,) int，instance/segment ID（Sonata 不需）

Sonata 不支援直接讀 .pth，所以要先把 3RScan 的 .pth 轉成 Sonata 可讀的格式。

---

作法：先轉成 .ply 或 .npz 再跑 Sonata

使用同目錄下的 convert_3rscan_pth_to_ply.py，把 3RScan 的 .pth 轉成 Sonata 可讀的格式：

• .ply：--format ply（需安裝 open3d），含 coord + color
• .npz：--format npz，存成 coord + color，Sonata 可直接讀，不需 open3d

單檔：
python convert_3rscan_pth_to_ply.py -i scan_data/pcd_with_global_alignment/<id>.pth -o out.ply

整批：
python convert_3rscan_pth_to_ply.py -i scan_data/pcd_with_global_alignment -o converted/ --batch --format npz

---

作法二：從官方下載的 mesh + texture 產生 raw 點雲

若你是用 3rscan_download.py 下載的 scan（有 mesh.refined.v2.obj 和 mesh.refined_0.png），要的是 mesh 頂點 + 貼圖顏色 的 raw 點雲，用：

mesh_obj_texture_to_ply.py（同目錄）

• 輸入：scan 目錄或直接給 mesh.refined.v2.obj 路徑（同目錄需有 mesh.refined_0.png）
• 輸出：帶 RGB 的 .ply（頂點座標 + 從 texture 取樣的顏色）

# 指定 scan 目錄（會自動找 mesh.refined.v2.obj + mesh.refined_0.png）
python mesh_obj_texture_to_ply.py -i data/19f1a892-a988-2bf8-8c91-0705cf396888 -o converted/

# 或直接指定 .obj
python mesh_obj_texture_to_ply.py -i data/19f1a892-.../mesh.refined.v2.obj -o converted/19f1a892.ply

需要：numpy, Pillow。產出的 .ply 可當 Sonata 的 input。

---

轉完後，Sonata 的 input point cloud 就是該 .ply 或 .npz 檔案，例如：

# 使用轉好的 .ply
python extract_features.py \
  --input /path/to/3rscan_converted/00d42bed-778d-2ac6-86a7-0e0e5f5f5660.ply \
  --output /path/to/sonata_feat/00d42bed-778d-2ac6-86a7-0e0e5f5f5660_down.npz

# 若有預先算好的 normal
python extract_features.py \
  --input /path/to/00d42bed-778d-2ac6-86a7-0e0e5f5f5660.ply \
  --preprocessed-dir /path/to/3rscan_preprocessed/00d42bed-778d-2ac6-86a7-0e0e5f5f5660 \
  --output /path/to/sonata_feat/00d42bed-778d-2ac6-86a7-0e0e5f5f5660_down.npz

總結：對 Sonata 來說，input point cloud 就是上述任一種格式的單一檔案（.ply / .pcd / .npy / .npz），內容需包含至少 N×3 的座標，建議一併提供 color（與可選的 normal）；3RScan 需先從 .pth 轉成其中一種格式再當成 Sonata 的 input。