|
| 1 | +"""Theme-invariant image normalisation so light templates match dark mode. |
| 2 | +
|
| 3 | +``match_template`` correlates raw pixel intensities, so a template captured in |
| 4 | +light mode scores terribly against the same control in dark mode — the polarity |
| 5 | +is inverted. The fix is to compare *structure* (edges, gradients), which is the |
| 6 | +same regardless of which way the colours run. ``theme_normalize`` turns an image |
| 7 | +into a polarity-invariant representation before matching: |
| 8 | +
|
| 9 | +* :func:`normalize_theme` — map an image to a normalised single-channel image. |
| 10 | + ``sobel`` (default) and ``laplacian`` use gradient magnitude, which is |
| 11 | + identical for an image and its inverse; ``zscore`` standardises intensity. |
| 12 | +* :func:`match_theme` — :func:`normalize_theme` both the template and the |
| 13 | + haystack (the screen by default), then locate the template — finding it across |
| 14 | + a light/dark theme flip that defeats raw matching. |
| 15 | +
|
| 16 | +cv2 / numpy are imported lazily, so importing this module never requires them |
| 17 | +(the package stays importable everywhere) and the locating logic reuses |
| 18 | +:func:`visual_match.match_template`. Imports no ``PySide6``. |
| 19 | +""" |
| 20 | +from typing import Any, Dict, Optional, Sequence |
| 21 | + |
| 22 | +# A normalisation method name. |
| 23 | +THEME_METHODS = ("sobel", "laplacian", "zscore") |
| 24 | + |
| 25 | + |
| 26 | +def _to_uint8(array: Any) -> Any: |
| 27 | + """Rescale a float array to a 0..255 uint8 image.""" |
| 28 | + import cv2 |
| 29 | + return cv2.normalize(array, None, 0, 255, cv2.NORM_MINMAX).astype("uint8") |
| 30 | + |
| 31 | + |
| 32 | +def _zscore(gray: Any) -> Any: |
| 33 | + """Standardise intensity to zero mean / unit variance (not inversion-safe).""" |
| 34 | + import numpy as np |
| 35 | + std = float(gray.std()) |
| 36 | + if std < 1e-9: |
| 37 | + return np.zeros_like(gray) |
| 38 | + return (gray - gray.mean()) / std |
| 39 | + |
| 40 | + |
| 41 | +def normalize_theme(source: Any, *, method: str = "sobel") -> Any: |
| 42 | + """Return ``source`` as a theme-normalised single-channel ``uint8`` image. |
| 43 | +
|
| 44 | + ``sobel`` / ``laplacian`` return gradient magnitude — identical for an image |
| 45 | + and its colour-inverted (dark-mode) twin — and ``zscore`` standardises |
| 46 | + intensity. Raises ``ValueError`` for an unknown ``method``. |
| 47 | + """ |
| 48 | + import cv2 |
| 49 | + import numpy as np |
| 50 | + from je_auto_control.utils.visual_match.visual_match import _to_gray |
| 51 | + gray = _to_gray(source).astype("float64") |
| 52 | + if method == "sobel": |
| 53 | + gx = cv2.Sobel(gray, cv2.CV_64F, 1, 0, ksize=3) |
| 54 | + gy = cv2.Sobel(gray, cv2.CV_64F, 0, 1, ksize=3) |
| 55 | + result = np.sqrt(gx * gx + gy * gy) |
| 56 | + elif method == "laplacian": |
| 57 | + result = np.abs(cv2.Laplacian(gray, cv2.CV_64F, ksize=3)) |
| 58 | + elif method == "zscore": |
| 59 | + result = _zscore(gray) |
| 60 | + else: |
| 61 | + raise ValueError(f"unknown theme-normalize method: {method!r}") |
| 62 | + return _to_uint8(result) |
| 63 | + |
| 64 | + |
| 65 | +def match_theme(template: Any, *, haystack: Optional[Any] = None, |
| 66 | + method: str = "sobel", min_score: float = 0.5, |
| 67 | + region: Optional[Sequence[int]] = None |
| 68 | + ) -> Optional[Dict[str, Any]]: |
| 69 | + """Locate ``template`` in ``haystack`` after theme-normalising both. |
| 70 | +
|
| 71 | + ``haystack`` defaults to a fresh screen grab (optionally clipped to |
| 72 | + ``region``). Returns ``{x, y, width, height, score}`` for the best match at |
| 73 | + or above ``min_score``, or ``None``. Robust to a light/dark theme flip that |
| 74 | + defeats raw :func:`visual_match.match_template`. |
| 75 | + """ |
| 76 | + from je_auto_control.utils.visual_match import match_template |
| 77 | + from je_auto_control.utils.visual_match.visual_match import _grab_gray |
| 78 | + raw_haystack = haystack if haystack is not None else _grab_gray(region) |
| 79 | + norm_template = normalize_theme(template, method=method) |
| 80 | + norm_haystack = normalize_theme(raw_haystack, method=method) |
| 81 | + match = match_template(norm_template, haystack=norm_haystack, |
| 82 | + min_score=float(min_score)) |
| 83 | + if match is None: |
| 84 | + return None |
| 85 | + return {"x": match.x, "y": match.y, "width": match.width, |
| 86 | + "height": match.height, "score": round(float(match.score), 4)} |
0 commit comments