Initial commit: Speckle-Scanner 3D pipeline with setup README
This commit is contained in:
@@ -0,0 +1,204 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user