Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Calibration

The verdict rule is simple: a photo is sharp when its sharpness score is at least --threshold, BLURRY otherwise. Everything therefore hinges on choosing a threshold that matches your camera, lenses and idea of “sharp enough”.

The default (100, tuned for the default --long-edge 1600) is a reasonable starting point for modern cameras.

Procedure

  1. Take a folder you have already culled by hand — ideally a real shoot with both keepers and rejects.

  2. Score it and export the results:

    blurdetector my-culled-shoot --recursive --csv report.csv

  3. Open the CSV (or run with --sort and read the console) and look for the score that best separates your keepers from your rejects. That score is your threshold.

  4. Use it on future shoots: blurdetector new-shoot --threshold 137.

Raising the threshold rejects more photos; lowering it is more forgiving. There is no universally correct value — motion blur tolerance, subject matter and output size all play into it.

The companion script calibrate_blur.py (kept outside this repository) automates step 3 from the CSV report, which is why the CSV column set is a stable interface.

What invalidates a calibration

Any option that changes the score scale requires recalibrating:

  • --long-edge — scores depend on image scale; that is the very reason images are normalized.
  • --grid-size and --top-fraction — they define which tiles the score averages.
  • --pre-blur — smoothing lowers every score, blurry photos most of all.

Calibrate with the exact analysis options you plan to run with.

What does not invalidate a calibration is upgrading the tool: scores are byte-identical across versions by design, guarded by a golden test suite. In the exceptional case of a deliberate scoring change, the impact is measured and announced first — see Score Stability.

High-ISO noise and --pre-blur

Sensor noise is high-frequency and inflates the Laplacian variance, so a noisy-but-blurry night shot can outscore a clean-but-soft one. A light Gaussian pre-blur (--pre-blur 0.8 is a good starting value) evens the field by taming the noise before the measurement. If your shoots mix ISO ranges, calibrate with the same --pre-blur you will use day to day.