Initial commit: Speckle-Scanner 3D pipeline with setup README

2026-06-10 03:09:05 +05:00
commit 1765934846
375 changed files with 123081 additions and 0 deletions
@@ -0,0 +1,174 @@
+# 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`).
+