# Multi-Format Disparity to Point Cloud Converter

This script converts disparity maps in various formats into 3D point clouds and saves them in the `.ply` format for easy visualization.

---

## 📌 Features

- Supports disparity map files in `.xml`, `.png`, and `.npy` formats.
- Automatically detects file type and processes accordingly.
- Uses OpenCV's `cv2.reprojectImageTo3D()` with a Q matrix for 3D reconstruction.
- Applies a color map (`jet`) based on depth (Z-value).
- Saves the generated point cloud as `.ply` files (`.txt` only with `--troubleshooting`).

---

## Troubleshooting flag

| `--troubleshooting` | Output |
|---------------------|--------|
| **False** (default) | `Point_cloud.ply` only |
| **True** | `Point_cloud.ply` + `Point_cloud.txt` (ASCII XYZ-RGB) |

---

## ▶️ How to Run

1. Place your disparity files inside the `./data/` folder.

2. Output files will be saved in the `./output/` folder.

3. Install dependencies:

```bash
pip install -r ~/Speckle-Scanner/06_Pointcloud/requirements.txt
```

4. Run the standalone script or the pipeline runner (see **Pipeline runner** below):

```bash
python pointcloud_genration.py --disparity <path> --q <path>
```

## 📁 Supported Input Types

You can place any of the following file types inside the ./data folder:

- .xml – OpenCV format with disparity stored under the key "disparity".

- .png – 16-bit grayscale or float disparity maps.

- .npy – NumPy arrays containing disparity values.


## 📄 Output Naming Convention

The point cloud file name is generated based on the disparity filename, with the following rules:

| Input Disparity Filename      | Output Point Cloud Filename    |
|------------------------------|---------------------------------|
| disparity_0001.xml           | Pointcloud_0001.ply             |
| horizontal_disparity.png     | Pointcloud_disparity.ply        |
| lr_sgm01.npy                 | Pointcloud_sgm01.ply            |

---

## Pipeline Usage (Automated Path Resolution)

Use `run_pcl_pipeline.py` to generate point clouds across the project folder structure.
It reads disparity maps from `03_sgm_disp_map/` and/or `04_zncc_disp_map/`, takes the Q matrix
from each session's own `params_link/lc-rc_Q.cvstore`, and saves results to `05_sgm_pcl/`
and/or `06_zncc_pcl/`.

### Folder structure

```
<project>/<date>/<session>/
  params_link/
    lc-rc_Q.cvstore              ← Q matrix (per session, used automatically)
  <ScanXXXXXX>/
    03_sgm_disp_map/
      disparity.xml              ← SGM input
    04_zncc_disp_map/
      disparity.npy              ← ZNCC input
    05_sgm_pcl/
      Point_cloud.ply            ← SGM output (always)
      Point_cloud.txt            ← only with --troubleshooting
    06_zncc_pcl/
      Point_cloud.ply            ← ZNCC output (always)
      Point_cloud.txt            ← only with --troubleshooting
```

### Commands

```bash
cd ~/Speckle-Scanner/06_Pointcloud

# Both SGM + ZNCC — all scans in a session
python run_pcl_pipeline.py \
  --project Olsen_wings \
  --date    2026-05-12 \
  --session session1

# Both SGM + ZNCC — all sessions on a date (omit --session)
python run_pcl_pipeline.py \
  --project Olsen_wings \
  --date    2026-05-12

# Single scan, both modes
python run_pcl_pipeline.py \
  --project Olsen_wings \
  --date    2026-05-12 \
  --session session1 \
  --scan    Scan000001

# Single scan, SGM only
python run_pcl_pipeline.py \
  --project Olsen_wings \
  --date    2026-05-12 \
  --session session1 \
  --scan    Scan000001 \
  --mode    sgm

# Single scan, ZNCC only
python run_pcl_pipeline.py \
  --project Olsen_wings \
  --date    2026-05-12 \
  --session session1 \
  --scan    Scan000001 \
  --mode    zncc

# Also save ASCII .txt point clouds
python run_pcl_pipeline.py \
  --project Olsen_wings \
  --date    2026-05-12 \
  --session session1 \
  --scan    Scan000001 \
  --troubleshooting
```

### Parameters

| Parameter   | Default | Description                                                                        |
|-------------|---------|------------------------------------------------------------------------------------|
| `--project` | —       | Project name (e.g. `Olsen_wings`)                                                  |
| `--date`    | —       | Date string (e.g. `2026-05-12`)                                                    |
| `--session` | all     | Session name (e.g. `session1`); omit to process **all sessions** on that date      |
| `--scan`    | all     | Single scan (e.g. `Scan000001`); omit to process all scans in the session          |
| `--mode`    | `both`  | Which disparity source to convert: `sgm`, `zncc`, or `both`                       |
| `--troubleshooting` | off | When set, also saves `Point_cloud.txt` ASCII export; default writes `.ply` only |

### What gets saved

| File | Default | `--troubleshooting` |
|------|---------|---------------------|
| `05_sgm_pcl/Point_cloud.ply` | yes | yes |
| `05_sgm_pcl/Point_cloud.txt` | no | yes |
| `06_zncc_pcl/Point_cloud.ply` | yes | yes |
| `06_zncc_pcl/Point_cloud.txt` | no | yes |

---

## Dependencies

```bash
# This step only
pip install -r ~/Speckle-Scanner/06_Pointcloud/requirements.txt

# Or install everything for the full pipeline
pip install -r ~/Speckle-Scanner/requirements.txt
```

Packages: `numpy`, `opencv-python`, `matplotlib`. `open3d` is optional (only for `plot_ASCII.py`).