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):

_ts<number> in both names (e.g. lc_ts254303092_... ↔ rc_ts254303092_...)
scan000001 style / IR_scan_000001
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.