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

Place your disparity files inside the ./data/ folder.
Output files will be saved in the ./output/ folder.
Install dependencies:

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

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

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

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

# 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).

5.3 KiB Raw Permalink Blame History Unescape Escape