ScanSlicer/docs/autotune.md

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.