133 lines
3 KiB
Markdown
133 lines
3 KiB
Markdown
|
# 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.
|