175 lines
5.3 KiB
Markdown
175 lines
5.3 KiB
Markdown
# 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`).
|
||
|