dan 426a18f342 chore: prune boilerplate and refresh stale docs

- Remove 257 redundant per-definition comment stubs across the package
- Drop dead nonlocal declarations in autoslicer_detection.py
- Document the swapped flag and swap_left_right in architecture docs
- Remove unsupported 'legacy override' claims from autotune/runtime docs

2026-09-11 23:07:30 +02:00

3 KiB

Raw Blame History

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:

Deduplicated
Capped by profile runtime limits
Evenly sampled when over limit
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

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

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

3 KiB Raw Blame History