|
| 1 | +"""Score image quality before OCR / template matching. |
| 2 | +
|
| 3 | +OCR and template matching quietly fail on a blurry, washed-out or too-dark |
| 4 | +capture — the locate returns nothing and the caller can't tell a *missing* |
| 5 | +element from an *unreadable* one. ``image_quality`` measures the three things |
| 6 | +that wreck recognition and gates on them: |
| 7 | +
|
| 8 | +* **sharpness** — variance of the Laplacian (low = blurry / out of focus), |
| 9 | +* **contrast** — standard deviation of the grayscale (low = washed out), |
| 10 | +* **brightness** — mean grayscale 0–255 (too low = dark, too high = blown out). |
| 11 | +
|
| 12 | +:func:`image_quality` returns the raw metrics, :func:`is_blurry` is the common |
| 13 | +one-liner, and :func:`quality_gate` turns the metrics into a pass / fail verdict |
| 14 | +with named issues so a script can refuse to OCR a bad frame (or pre-process it |
| 15 | +first). It reuses ``visual_match``'s grayscale loader, so the source is any |
| 16 | +ndarray / path / PIL image (or the live screen when omitted); ``region`` applies |
| 17 | +to a live-screen grab. cv2 / numpy are lazily imported. Imports no ``PySide6``. |
| 18 | +""" |
| 19 | +from typing import Any, Dict, Optional, Sequence, Tuple |
| 20 | + |
| 21 | +ImageSource = Any |
| 22 | + |
| 23 | + |
| 24 | +def _gray(source: Optional[ImageSource], region: Optional[Sequence[int]]): |
| 25 | + from je_auto_control.utils.visual_match.visual_match import _haystack_gray |
| 26 | + return _haystack_gray(source, region) |
| 27 | + |
| 28 | + |
| 29 | +def image_quality(source: Optional[ImageSource] = None, *, |
| 30 | + region: Optional[Sequence[int]] = None) -> Dict[str, float]: |
| 31 | + """Return ``{sharpness, contrast, brightness}`` for an image (or live screen). |
| 32 | +
|
| 33 | + ``sharpness`` is the variance of the Laplacian, ``contrast`` the grayscale |
| 34 | + standard deviation, ``brightness`` the mean grayscale (0–255). |
| 35 | + """ |
| 36 | + import cv2 |
| 37 | + gray = _gray(source, region) |
| 38 | + return {"sharpness": float(cv2.Laplacian(gray, cv2.CV_64F).var()), |
| 39 | + "contrast": float(gray.std()), |
| 40 | + "brightness": float(gray.mean())} |
| 41 | + |
| 42 | + |
| 43 | +def is_blurry(source: Optional[ImageSource] = None, *, |
| 44 | + region: Optional[Sequence[int]] = None, |
| 45 | + threshold: float = 100.0) -> bool: |
| 46 | + """Return True if the image's Laplacian variance is below ``threshold``.""" |
| 47 | + return image_quality(source, region=region)["sharpness"] < float(threshold) |
| 48 | + |
| 49 | + |
| 50 | +def quality_gate(source: Optional[ImageSource] = None, *, |
| 51 | + region: Optional[Sequence[int]] = None, |
| 52 | + min_sharpness: float = 100.0, min_contrast: float = 12.0, |
| 53 | + brightness_range: Tuple[float, float] = (40.0, 220.0), |
| 54 | + ) -> Dict[str, Any]: |
| 55 | + """Grade an image for OCR readability: ``{..., passed, issues}``. |
| 56 | +
|
| 57 | + ``issues`` flags ``blurry`` / ``low_contrast`` / ``too_dark`` / ``too_bright``; |
| 58 | + ``passed`` is True only when no issue fires. |
| 59 | + """ |
| 60 | + metrics = image_quality(source, region=region) |
| 61 | + low, high = brightness_range |
| 62 | + issues = [] |
| 63 | + if metrics["sharpness"] < float(min_sharpness): |
| 64 | + issues.append("blurry") |
| 65 | + if metrics["contrast"] < float(min_contrast): |
| 66 | + issues.append("low_contrast") |
| 67 | + if metrics["brightness"] < float(low): |
| 68 | + issues.append("too_dark") |
| 69 | + elif metrics["brightness"] > float(high): |
| 70 | + issues.append("too_bright") |
| 71 | + return {**metrics, "passed": not issues, "issues": issues} |
0 commit comments