# Auto-Tune and Feedback

## Purpose

Auto-tune searches parameter combinations for the current image and applies the best-performing set automatically.

It is designed to:

- Find usable boxes quickly on difficult scans.
- Improve ranking using prior saved user outcomes (feedback learning).

## Profiles

Supported profiles:

- `Fast`
- `Balanced` (default)
- `Thorough`
- `Exhaustive`

Each profile controls:

- candidate breadth (`thresholds`, adaptive settings, morphology combinations)
- runtime limits (`max_candidates_*`, `seed_limit`)
- convergence limits (`early_stop_*`)
- refinement depth (`finalists_*`)

Higher profiles evaluate more candidates and typically take longer.

## Candidate Generation

Candidate sets are built from:

- Baseline current parameter values
- Threshold-based combinations
- Adaptive threshold combinations
- Otsu combinations
- Bounded permutations of bbox/aspect windows

Then candidates are:

1. Deduplicated
2. Capped by profile runtime limits
3. Evenly sampled when over limit
4. Ranked before evaluation

## Candidate Ranking (Pre-Evaluation)

Ranking prefers:

- candidates closer to current parameter values
- candidates similar to successful feedback entries from visually similar images

Similarity components:

- image feature similarity (`mean`, `std`, `p50`, edge density)
- normalized parameter distance over each parameter range
- optional alignment to `expected_count`

## Two-Phase Search

### Coarse pass

- Runs many candidates quickly using:
  - downscaled image (max dimension 1400)
  - `fast_mode=True`
- Uses early-stop when score stagnates and convergence conditions are met.

### Fine pass

- Re-runs only top finalists at full resolution and full detection path.
- Best final candidate is applied to live parameters.

## Box Scoring Heuristics

Detected box sets are scored by:

- plausible count range
- multi-photo preference
- total area coverage
- uniformity of box area proportions
- penalty for too many tiny boxes
- optional `expected_count` alignment bonuses/penalties
- feedback similarity bonus

If no boxes are found, score is strongly negative.

## Feedback Learning

Feedback is recorded when slices are saved:

- source image path
- parameter values used
- image features
- detected boxes
- final locked/saved boxes
- final box signature and count
- timestamp

Duplicate feedback entries (same image path + final signature) are replaced with latest.

## Feedback File

Default path:

- `~/.config/scanslicer/autotune-feedback.json`

Container path (`/.dockerenv` and `/work` exists):

- `/work/.scanslicer/autotune-feedback.json`

Override:

- `SCANSLICER_FEEDBACK_PATH`

Legacy override names are still accepted for backward compatibility.

Maximum retained entries:

- `500` (latest entries kept)

## Clearing Feedback

UI action `Clear auto-tune history`:

- empties in-memory feedback list
- removes persisted feedback file if present

## Related Settings

- `expected_count` strongly influences scoring and early-stop decisions.
- area/aspect parameters can dominate candidate success when scene geometry is constrained.