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:

```text
$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):

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

Calibration params (once per project/date):

```text
$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

```bash
pip install numpy opencv-python tqdm
```

Use a Python environment where `import cv2` works.

---

## How to run

From anywhere:

```bash
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.

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

One line:

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

### One session only

```bash
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:

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

### Override paths (any project/machine)

```bash
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:

```text
[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

```bash
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

```bash
# 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`.