Speckle-Scanner/04_Rectification/README.md

04 Rectification

Stereo rectification for multi-camera scan sessions. Reads raw images from 3D-Scans, applies calibration from Calib-data, and writes results into Speckle-Scanner_Processing_data.

Supported stereo pairs (per scan):

Pair	Left	Right	Params file
lc-rc	lc_*	rc_*	lc-rc_parameters.npz
lc-rg	lc_*	rg_*	lc-rg_parameters.npz
lc-ir	lc_*	ir_*	lc-ir_parameters.npz

Rectified LC frames are taken from the lc-rc run only (one LC set in 02_rect_images). Partner cameras (rc, rg, ir) are saved from their own pair calibration.

---

Folder layout (general paths)

All paths use $HOME — replace with your home directory on any machine.

Role	Path pattern
Source scans (RAW)	$HOME/3D-Scans/<raw_project>/<date>/sessionN/Scan00000X/01_raw_images/
Calibration params	$HOME/Calib-data/<project>/<date>/<calib_name>/params/
Processing output	$HOME/Speckle-Scanner_Processing_data/<project>/<date>/

Example naming:

• project (Calib + processing): Olsen_wings (underscore)
• raw_project (3D-Scans): Olsen-wings (often hyphen; default = project with _ → -)
• date: 2026-05-12
• calib_name: calib1

Per session under processing output:

$HOME/Speckle-Scanner_Processing_data/<project>/<date>/
  session53/
    params_link/          # copied lc-rc, lc-rg, lc-ir params
    Scan000001/
      01_raw_images/      # copy of source images
      02_rect_images/       # rectified lc_*, rc_*, rg_*, ir_* (single folder)
    Scan000002/
      ...

Source side (same session/scan names):

$HOME/3D-Scans/<raw_project>/<date>/session53/Scan000001/01_raw_images/

Calibration params (once per project/date):

$HOME/Calib-data/<project>/<date>/<calib_name>/params/
  lc-rc_parameters.npz
  lc-rc_stereo_cam_model.yaml
  lc-rc_Q.cvstore
  lc-rg_*
  lc-ir_*

---

Requirements

pip install numpy opencv-python tqdm

Use a Python environment where import cv2 works.

---

How to run

From anywhere:

cd "$HOME/Speckle-Scanner/04_Rectification"
python main.py [options]

All sessions under one date (full batch)

Processes every session*/Scan*/01_raw_images under the date folder.

python main.py \
  --project Olsen_wings \
  --raw_project Olsen-wings \
  --date 2026-05-12 \
  --calib_name calib1

One line:

python main.py --project Olsen_wings --raw_project Olsen-wings --date 2026-05-12 --calib_name calib1

One session only

python main.py \
  --project Olsen_wings \
  --raw_project Olsen-wings \
  --date 2026-05-12 \
  --calib_name calib1 \
  --session session53

Custom pairs

Default: lc-rc,lc-rg,lc-ir. Example — RC and IR only:

python main.py --project Olsen_wings --date 2026-05-12 --pairs lc-rc,lc-ir

Override paths (any project/machine)

python main.py \
  --source_date_root "$HOME/3D-Scans/MyProject/2026-05-12" \
  --calib_params_dir "$HOME/Calib-data/MyProject/2026-05-12/calib1/params" \
  --processing_date_root "$HOME/Speckle-Scanner_Processing_data/MyProject/2026-05-12"

---

CLI reference

Option	Default	Meaning
--project	required	Project name in Calib-data and Processing_data (e.g. Olsen_wings)
--date	required	Date subfolder (e.g. 2026-05-12)
--raw_project	<project> with _ → -	Project folder name under 3D-Scans
--session	(all)	Only this session, e.g. session53
--calib_name	calib1	Calibration run folder
--pairs	lc-rc,lc-rg,lc-ir	Comma-separated stereo pairs
--keep_lc_from_pair	lc-rc	Which pair defines rectified LC in 02_rect_images
--source_date_root	auto	Override RAW scan root
--calib_params_dir	auto	Override params folder
--processing_date_root	auto	Override output root

---

Pairing notes

Images are matched by filename key (in order):

1. _ts<number> in both names (e.g. lc_ts254303092_... ↔ rc_ts254303092_...)
2. scan000001 style / IR_scan_000001
3. Prefix + suffix (lc_123 ↔ ir_123)

If no key match for lc-rg or lc-ir, the script may use index fallback (first LC with first RG/IR). Check logs for:

[WARN] No key match for lc-rg; using index fallback with N pairs.

lc-rc usually matches on _ts when both cameras captured the same timestamps.

---

What gets created

For each processed scan:

• Copies 01_raw_images into processing tree (does not delete source RAW data)
• Writes rectified images to 02_rect_images/
• Creates params_link/ once per session with all calibration files

Does not modify files under 3D-Scans.

---

Quick check after a run

PROJECT=Olsen_wings
DATE=2026-05-12
SESSION=session53
SCAN=Scan000001

ls "$HOME/Speckle-Scanner_Processing_data/$PROJECT/$DATE/$SESSION/params_link"
ls "$HOME/Speckle-Scanner_Processing_data/$PROJECT/$DATE/$SESSION/$SCAN/02_rect_images" | head

---

Dependencies

# This step only
pip install -r ~/Speckle-Scanner/04_Rectification/requirements.txt

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

Packages: numpy, opencv-python, tqdm.