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）

```bash
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 取樣的顏色）

```bash
# 指定 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` 檔案，例如：

```bash
# 使用轉好的 .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。**