# Parameter Reference

This page documents the detection parameters defined in `scanslicer/params.py` (`AutoslicerParams.SPECS`).

## Notes

- All values are integer-backed.
- Some parameters are context-sensitive and only apply to specific detection modes.
- Internal safeguards:
  - `aspect_ratio_max` is clamped to be `>= aspect_ratio_min`
  - `canny_high` is clamped to be `>= canny_low`

## Choice Parameters

- `detect_pipeline`
  - `0`: Threshold pipeline
  - `1`: Canny pipeline
- `bw_method` (threshold pipeline only)
  - `0`: Simple threshold
  - `1`: Adaptive Gaussian threshold
  - `2`: Otsu threshold
- `invert_mode`
  - `0`: Auto (try normal polarity, then inverted fallback)
  - `1`: Off (normal polarity only)
  - `2`: On (force inverted polarity)
- `morph_op`
  - `0`: None
  - `1`: Dilate
  - `2`: Erode
  - `3`: Open
  - `4`: Close

## Full Table

| Parameter | Default | Range | Step | Used In | Effect |
|---|---:|---|---:|---|---|
| `detect_pipeline` | `0` | `0..1` | `1` | global | Select threshold or Canny detection pipeline. |
| `clahe_clip` | `0` | `0..40` | `1` | preprocessing | CLAHE contrast boost (`0` disables). Effective clip limit is `value/10`. |
| `gaussian` | `0` | `0..100` | `1` | preprocessing | Gaussian blur kernel size (`0` disables). Even values are bumped to odd. |
| `bw_method` | `0` | `0..2` | `1` | threshold pipeline | Selects Simple, Adaptive Gaussian, or Otsu thresholding. |
| `bw_thresh` | `210` | `0..255` | `5` | threshold+simple | Binary threshold cutoff. |
| `bw_gauss` | `64` | `0..1000` | `2` | threshold+adaptive | Adaptive block size basis. Converted to odd and at least `3`. |
| `bw_adaptive_c` | `2` | `-20..20` | `1` | threshold+adaptive | Adaptive threshold subtraction constant. |
| `canny_low` | `50` | `0..255` | `5` | Canny pipeline | Lower Canny hysteresis threshold. |
| `canny_high` | `150` | `0..255` | `5` | Canny pipeline | Upper Canny hysteresis threshold. |
| `invert_mode` | `0` | `0..2` | `1` | global | Controls polarity inversion behavior before contour extraction. |
| `morph_op` | `1` | `0..4` | `1` | global | Morphological operation on mask/edges. |
| `contour_approx_pct` | `0` | `0..50` | `1` | contour extraction | Polygon approximation epsilon percentage (`value/1000`). |
| `bbox_min_size` | `2` | `0..100` | `1` | contour filtering | Minimum candidate area as % of full image area. |
| `bbox_max_size` | `90` | `1..100` | `1` | contour filtering | Maximum candidate area as % of full image area. |
| `bbox_fill_thresh` | `10` | `0..100` | `1` | contour filtering | Minimum contour fill ratio within min-area box (%). |
| `expected_count` | `0` | `0..20` | `1` | scoring/autotune | Expected number of photos (`0` means auto/unbounded heuristics). |
| `aspect_ratio_min` | `100` | `100..1000` | `5` | contour filtering | Minimum long/short aspect ratio, scaled by `x100`. |
| `aspect_ratio_max` | `400` | `100..1000` | `5` | contour filtering | Maximum long/short aspect ratio, scaled by `x100`. |
| `border_ignore` | `0` | `0..20` | `1` | contour filtering | Ignore candidates touching image edges within this margin (%). |
| `iou_merge_thresh` | `30` | `0..100` | `1` | contour dedup | Merge overlap threshold as IoU percentage. |
| `dilate_kernel` | `30` | `0..500` | `1` | morphology | Morph kernel size for selected morph operation (`0` disables morphology). |

## Advanced Parameters in UI

The UI can hide/show advanced controls. Advanced set:

- `detect_pipeline`
- `clahe_clip`
- `gaussian`
- `bw_adaptive_c`
- `invert_mode`
- `contour_approx_pct`
- `bbox_max_size`
- `aspect_ratio_min`
- `aspect_ratio_max`
- `border_ignore`
- `iou_merge_thresh`

## Practical Tuning Guidance

- Too many tiny false positives:
  - Increase `bbox_min_size`
  - Increase `bbox_fill_thresh`
  - Increase `iou_merge_thresh`
- Missed photos:
  - Lower `bbox_min_size`
  - Broaden `aspect_ratio_min/max`
  - Try `detect_pipeline=1` (Canny)
  - Try `invert_mode=2`
- Border/frame artifacts:
  - Increase `border_ignore`
  - Switch morphology operation/kernel
- Uneven illumination:
  - Use adaptive mode (`bw_method=1`)
  - Enable modest `clahe_clip`