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,145 @@
+# Point Cloud Colouring Pipeline
+
+Colours 3D point clouds by projecting each point onto the calibrated RGB and IR
+cameras and sampling pixel colours. Each output PLY carries **dual texture**:
+RGB colours (from `rg_*.bmp`) and IR colours (from `ir_*.png`), stored as separate
+per-vertex properties so both can be visualised in CloudCompare or any PLY viewer.
+
+---
+
+## Core module: `colour_ply.py`
+
+| Function | Purpose |
+|----------|---------|
+| `load_ascii_ply(ply_path)` | Read ASCII PLY, return Nx3 float32 xyz array |
+| `colorize_combined_pointcloud(pts, rgb_img, ir_img, lc_rgb_yaml, lc_ir_yaml, lc_rc_yaml, out_ply)` | Un-rotate points using R1 from stereo rectification, project to RGB + IR cameras, save dual-texture binary PLY |
+| `save_master_ply(filename, points, rgb_colors, ir_colors)` | Write binary_little_endian PLY with x,y,z,red,green,blue,ir_red,ir_green,ir_blue |
+
+---
+
+## Folder structure assumed
+
+```
+~/Speckle-Scanner_Processing_data/
+└── <project>/
+    └── <date>/
+        └── <session>/
+            ├── params_link/
+            │   ├── lc-rc_stereo_cam_model.yaml   ← stereoRectify R1 (un-rotate 3D points)
+            │   ├── lc-rg_stereo_cam_model.yaml   ← project to RGB camera
+            │   └── lc-ir_stereo_cam_model.yaml   ← project to IR camera
+            └── <ScanXXXXXX>/
+                ├── 02_rect_images/
+                │   ├── ir_*.png                  ← one IR image (input)
+                │   └── rg_*.bmp                  ← one RGB image (input)
+                ├── 05_sgm_pcl/
+                │   └── Point_cloud.ply           ← SGM point cloud (input)
+                ├── 06_zncc_pcl/
+                │   └── Point_cloud.ply           ← ZNCC point cloud (input)
+                ├── 07_sgm_pcl_col/
+                │   └── Point_cloud_colored.ply   ← SGM coloured output (created)
+                └── 08_zncc_pcl_col/
+                    └── Point_cloud_colored.ply   ← ZNCC coloured output (created)
+```
+
+---
+
+## Pipeline commands
+
+```bash
+cd ~/Speckle-Scanner/09_coloring
+
+# Both SGM + ZNCC — all scans in a session
+python run_coloring_pipeline.py \
+  --project Olsen_wings \
+  --date    2026-05-12 \
+  --session session1
+
+# Both SGM + ZNCC — all sessions on a date (omit --session)
+python run_coloring_pipeline.py \
+  --project Olsen_wings \
+  --date    2026-05-12
+
+# Single scan, both modes
+python run_coloring_pipeline.py \
+  --project Olsen_wings \
+  --date    2026-05-12 \
+  --session session1 \
+  --scan    Scan000001
+
+# Single scan, SGM only
+python run_coloring_pipeline.py \
+  --project Olsen_wings \
+  --date    2026-05-12 \
+  --session session1 \
+  --scan    Scan000001 \
+  --mode    sgm
+
+# Single scan, ZNCC only
+python run_coloring_pipeline.py \
+  --project Olsen_wings \
+  --date    2026-05-12 \
+  --session session1 \
+  --scan    Scan000001 \
+  --mode    zncc
+```
+
+---
+
+## 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 point cloud to colour: `sgm`, `zncc`, or `both` |
+
+---
+
+## What gets saved
+
+| File | Description |
+|------|-------------|
+| `07_sgm_pcl_col/Point_cloud_colored.ply` | SGM cloud with RGB + IR dual texture (binary PLY) |
+| `08_zncc_pcl_col/Point_cloud_colored.ply` | ZNCC cloud with RGB + IR dual texture (binary PLY) |
+
+The output PLY has the following vertex properties:
+
+```
+x, y, z          — 32-bit float (metres)
+red, green, blue  — 8-bit uchar  (from rg_*.bmp camera)
+ir_red, ir_green, ir_blue — 8-bit uchar (from ir_*.png camera)
+```
+
+To visualise the IR texture in CloudCompare, select the `ir_red/ir_green/ir_blue`
+scalar fields or load the file and choose the IR colour attribute.
+
+---
+
+## Skip conditions
+
+The runner prints `[SKIP]` and moves to the next scan if any required file is absent:
+
+- `02_rect_images/ir_*.png` — no IR image found
+- `02_rect_images/rg_*.bmp` — no RGB image found
+- `params_link/lc-rc_stereo_cam_model.yaml` — missing RC YAML
+- `params_link/lc-rg_stereo_cam_model.yaml` — missing RG YAML
+- `params_link/lc-ir_stereo_cam_model.yaml` — missing IR YAML
+- `05_sgm_pcl/Point_cloud.ply` — SGM cloud not generated yet (run `run_pcl_pipeline.py --mode sgm` first)
+- `06_zncc_pcl/Point_cloud.ply` — ZNCC cloud not generated yet (run `run_pcl_pipeline.py --mode zncc` first)
+
+---
+
+## Dependencies
+
+```bash
+# This step only
+pip install -r ~/Speckle-Scanner/09_coloring/requirements.txt
+
+# Or install everything for the full pipeline
+pip install -r ~/Speckle-Scanner/requirements.txt
+```
+
+Packages: `numpy`, `opencv-python`.