"""Image-quality checks on a picture of a QR code: diagnostics shown beside its place on the scale. They never change the difficulty, the level or the confidence. Each check is measured on the largest staged frame (long side at most 1920 px; the picture itself if smaller), from the code's four outer corners as the scanners that read it found them. All are deterministic: numpy and OpenCV only. Statuses are set on QR Scan Difficulty's one-factor ladders (80 synthetic captures per step, read by all eight scanners at the 1280 frame; base 8 camera pixels per square, version 3, tilt 5 degrees, blur 0.3 px), pixels per square on the version x size grid's good-light scene, the ladders' base at versions 2-21 and 1.6-6 px (quality_limits.py): "ok" all eight scanners read at least 72 of 80 at that value "watch" the three phone scanners (Apple's, Google's, Huawei's) read at least 72 of 80; another scanner doesn't "problem" a phone scanner reads fewer than 72 of 80 None not measured Each cut sits midway between the medians measured here, the Space's way, at the last step of one status and the first step of the next; where two ladders set one cut, in the middle of the range both allow, so a value between two steps may take the farther step's status on one of them. Values are graded as the page shows them, so no shown number has two statuses: shares (the shadow as 1 - ratio) in whole percent and the angle in whole degrees, halves up as JavaScript rounds (web/util.js pctText; "<1%" is 0%, ">99%" 100%), so a cut acts at most half a shown unit from its value; pixels per square at 2 decimals, the margin in quarter squares. One status is not the ladders': the margin's "watch" under the QR standard's 4 squares (all eight read margins down to half a square). Framing is a note, never a status. measure(gray, quad, modules, scale) returns, rounded and JSON-safe (None where a value can't be measured): "modules", "version" squares per side and QR version; "modules_from": "scanner" | "estimate" | None "quad" the code's outer corners in the picture's own pixels (top-left, top-right, bottom-right, bottom-left of the code as drawn, not as the picture is turned) "ppm" at1280: camera pixels per square at the 1280 frame, the square's size before foreshortening where the code is smallest (the status's value; the angle is perspective's); narrow1280: the same along the direction the tilt shortens most; native: at1280 in the picture as sent; mean1280: code width / squares at the 1280 frame; ok_from, problem_below: the status's cuts for this version "size" px1280, native: code width in pixels; share: code width / the picture's long side; area: the code's share of the picture's area; edge: the code comes within a square of the picture's edge (the margin judges it); tight: a framing note, the code is at least 0.3 of the long side, closer than in any simulated print, so it may land easier than a photo from where people stand "quiet" modules: clear margin in squares, the least of the four sides, capped at 4; under: only known to be under modules (the lines nearer the code couldn't be told from its own squares); side: that side as the picture shows it ("top" | "right" | "bottom" | "left"); edge: the picture's edge, not something printed, ends it; capped: a 4 that may be 3.5 or 3.75 (below); sides: per side as the picture shows them, None where the code's own patterns didn't pin both ends (only "problem" is told then): the finder patterns pin three corners; the alignment pattern, or else the three finder patterns' centres and widths, pin the bottom-right. A mark at the code, with no clear line between, that doesn't reach a quarter square past its edge (a design's art crossing it) counts as the code's edge; under 4 pixels a square, a margin the picture's edge ends 3.5 squares or more out reads 4, capped (quality_fit) "blur" modules: blur as a Gaussian sigma in squares, root-mean-square over the code's two axes (so a shake counts the same in any direction, and a focus blur is its sigma); px1280: the same in pixels of the 1280 frame; fits: how many of the six finder-pattern profiles passed the fit check "contrast" value: (light - dark) / 255 at the best-lit finder pattern, standing for the print (shadow and glare over the others are lighting's); min: at the worst-lit finder; inverted: light squares on dark. The fitted levels can overshoot 0-255, so value and min are capped at 1 "lighting" ratio: light level where the code is darkest / where it is brightest; worst: (light - dark) / 255 where it is lowest; clipped: share of the code washed out by a highlight, where a square and its neighbours average 250 or brighter, above the code's light squares (a graphic's pure white is not). "ok": no washed-out patch or deep shadow found; a small reflection off a gloss or screen isn't seen "perspective" tilt: degrees, from the corners' perspective at the code's centre; keystone: longest / shortest side Each check also has "status" and "why": the reasons behind a status other than "ok", from "small" (squares too few camera pixels; for blur, a blur that is the camera's own at that size), "dense" (version), "margin", "edge" (the picture's edge ends the margin), "blur", "contrast", "inverted", "shadow", "glare", "tilt"; and with status None, "unpinned" (the margin: the code's own patterns didn't pin where all its edges are, and no pinned side has next to no margin, so it isn't judged). """ from __future__ import annotations import math import cv2 import numpy as np from . import quality_geom as geom from .quality_fit import finder_fits, module_values, nanmean, quiet_margins, regions, to_image from .quality_geom import HALF_PIXEL, SOURCES, corners_from, pick_geometry from .quality_limits import ppm_cuts # pixels per square: the grid's good-light limits, from web/data/sizes.json __all__ = ["HALF_PIXEL", "SOURCES", "corners_from", "measure", "measure_staged", "pick_geometry", "ppm_cuts"] # ---- thresholds ----------------------------------------------------------------------------------------------------- # Measured the Space's way at the last ladder step of one status and the first of the next (80 captures a step; reads # of 80 at the 1280 frame; measured medians in brackets). DENSE_VERSION = 14 # bigger-print ladder at 6 px (5.87): all eight read up to version 13; at 15 # Android Settings' ZXing reads 70 QUIET_STANDARD = 4.0 # the QR standard's 4 squares: "watch" below it by design, though the margin # ladder's 3 to 0.5 squares (measured 3 to 0.5) all eight read QUIET_PROBLEM = 0.25 # margin ladder: half a square (0.5) all eight read; none, clutter beyond # (0), Google's scanner reads 7. Re-rendered at 3-8 px a square and blur # 0-1.5 px, no margin still measures 0 and half a square 0.25-0.5 BR_FIT, BR_FAR = 0.005, 1.5 # a bottom-right corner no alignment pattern pins (version 1 always): the # three finder patterns pin it where one perspective fits their centres and # their six widths to 0.5% rms, within 1.5 squares of the scanner's corner. # Fresh versions 1-4 (1,728 scenes, the four scanners' corners): 3,108 of # 3,118 such corners pinned, the furthest 0.24 squares off (median 0.02); the # scanners' own: 0.15-0.32 at the median, up to 1.26 (false margin problems) BLUR_OK, BLUR_WATCH = 0.271, 0.40 # sigma in squares (root-mean-square of the two axes), so the ladders' 8 px # per square carry over to other sizes. Focus ladder: 2.0 px (0.254) all # eight, 2.5-3.0 px (0.315-0.377) the phones, 3.5 px (0.437) Google's 49; # shake ladder: 8 px streak (0.234) all eight, 10-12 px (0.288-0.354) the # phones, 14 px (0.424) Google's 54. Each cut: mid-way in what both allow BLUR_SHARP_PX = 1.0 # under this many pixels at 1280 a blur is the camera's own: the squares are # small, not out of focus (the ladders' in-focus base captures: 0.42 px) CONTRAST_OK, CONTRAST_WATCH = 0.303, 0.102 # contrast ladder: 31% (0.323) all eight, 27-11% (0.284-0.115) the # phones, 8% (0.088) Google's 40 SHADOW_OK, SHADOW_WATCH = 0.314, 0.192 # light ratio, shadow ladder: 60% (0.387) all eight, 75% (0.241) the phones, # 85% (0.143) Google's 33 CLIP_OK, CLIP_WATCH = 0.007, 0.028 # washed-out share, glare ladder: 80% (0.000) all eight, 90% (0.014) the # phones, 100% (0.041) Google's 68 TILT_OK, TILT_WATCH = 35.0, 57.5 # degrees, tilt ladder: 30 (30.0) all eight, 40-55 (40.0-55.0) the phones, # 60 (60.0) Apple's 49 CLIP_LEVEL, CLIP_ABOVE = 250, 12 # washed out: at 250 or brighter, and 12 above the light squares' median def _r(x, nd: int): return None if x is None or not np.isfinite(x) else round(float(x), nd) def _round_half_up(x): """JavaScript's Math.round, which the page shows its numbers with: the nearest whole number, halves up.""" return None if x is None else math.floor(x) + (x - math.floor(x) >= 0.5) def _shown(x: float | None, darker: bool = False) -> float | None: """A share as the page shows it, in whole percent, as a share again; darker: a light ratio, shown as 1 - x.""" p = _round_half_up(None if x is None else 100 * (1 - x if darker else x)) return None if p is None else (100 - p) / 100 if darker else p / 100 def _status(bad: list[tuple[str, str]]) -> dict: worst = "problem" if any(s == "problem" for s, _ in bad) else "watch" if bad else "ok" return {"status": worst, "why": [w for _, w in bad]} def _grade(x: float | None, ok, watch, why: str, higher_is_better: bool = False) -> list[tuple[str, str]]: if x is None: return [] if higher_is_better: return [] if x >= ok else [("watch", why)] if x >= watch else [("problem", why)] return [] if x <= ok else [("watch", why)] if x <= watch else [("problem", why)] def _empty() -> dict: none = {"status": None, "why": []} return {"modules": None, "version": None, "modules_from": None, "quad": None, "ppm": {"at1280": None, "narrow1280": None, "native": None, "mean1280": None, "ok_from": None, "problem_below": None, **none}, "size": {"px1280": None, "native": None, "share": None, "area": None, "edge": None, "tight": None, **none}, "quiet": {"modules": None, "under": None, "side": None, "edge": None, "capped": None, "sides": None, **none}, "blur": {"modules": None, "px1280": None, "fits": 0, **none}, "contrast": {"value": None, "min": None, "inverted": None, **none}, "lighting": {"ratio": None, "worst": None, "clipped": None, **none}, "perspective": {"tilt": None, "keystone": None, **none}} def _frame(out: dict, q, n: int | None, version: int | None, shape, to1280: float, to_native: float) -> float: """Fill in the corners, the code's size and framing, and the keystone; return the code's width in frame pixels.""" f = geom.framing(q, n, shape) out["quad"] = [[_r((x + 0.5) * to_native, 1), _r((y + 0.5) * to_native, 1)] for x, y in q] out["size"].update(px1280=_r(f["width"] * to1280, 0), native=_r(f["width"] * to_native, 0), share=_r(f["share"], 3), area=_r(f["area"], 4), edge=f["edge"], tight=f["tight"], **(_status([("watch", "dense")] if version >= DENSE_VERSION else []) if version is not None else {"status": None, "why": []})) out["perspective"]["keystone"] = _r(f["keystone"], 3) return f["width"] def measure(gray, quad, modules: int | None, scale: dict) -> dict: """The checks for one code: gray is the frame (uint8, 2-D), quad its four outer corners in that frame's pixels with the pixel edges at whole numbers (zxing-cpp's order: top-left, top-right, bottom-right, bottom-left of the code), modules its squares per side or None, scale {"to1280": f, "to_native": g} the factors from the frame's pixels to the 1280 frame's and to the picture's own. Never raises: what can't be measured is None.""" try: return _measure(gray, quad, modules, scale) except Exception: # diagnostics never cost a reading: whatever fails leaves nothing measured return _empty() def measure_staged(path: str, found: dict, sizes: list, scale: dict) -> dict | None: """measure on the largest staged frame, by pick_geometry's corners from found; None for none, or on a failure.""" try: pick = pick_geometry(found, sizes) return None if pick is None else measure(cv2.imread(path, cv2.IMREAD_GRAYSCALE), pick[0], pick[1], scale) except Exception: # noqa: BLE001 - diagnostics only: a failure leaves them out return None def _measure(gray, quad, modules, scale) -> dict: out = _empty() if not isinstance(gray, np.ndarray) or gray.ndim != 2 or gray.dtype.kind not in "biuf" or min(gray.shape) < 16: return out try: to1280, to_native = float(scale["to1280"]), float(scale["to_native"]) except (TypeError, KeyError, ValueError, IndexError): return out q = geom.valid_quad(quad, gray.shape) if q is None or not (math.isfinite(to1280 * to_native) and to1280 > 0 and to_native > 0) or \ (gray.dtype.kind == "f" and not np.isfinite(gray).all()): return out hgt, wid = gray.shape cx, cy = q.mean(0) if not (0 <= cx <= wid and 0 <= cy <= hgt): # the code's centre lies off the picture return out q = q - 0.5 # pixel edges to pixel centres, as OpenCV samples img = np.ascontiguousarray(gray, dtype=np.float32) # OpenCV would copy any other layout at every sampling n, source = modules, "scanner" if isinstance(n, bool) or not (isinstance(n, int | np.integer) and 21 <= n <= 177 and n % 4 == 1): n, source = geom.estimate_modules(img, q), "estimate" if n is None: # no squares to measure by: only the framing _frame(out, q, None, None, (hgt, wid), to1280, to_native) return out # finder patterns first: their profiles also say where the finders are, which corrects the corners n = int(n) h0, square = geom.homography(q, n), math.sqrt(geom.area(q)) / n fits = finder_fits(img, h0, n, square) alt = geom.estimate_modules(img, q) if source == "scanner" and sum(r["ok"] for *_, r in fits) < 2 else None if alt is not None and alt != n: # a count the finder patterns don't bear out: the estimate's, if they bear it h1, square1 = geom.homography(q, alt), math.sqrt(geom.area(q)) / alt fits1 = finder_fits(img, h1, alt, square1) if sum(r["ok"] for *_, r in fits1) >= 2: n, source, h0, square, fits = alt, "estimate", h1, square1, fits1 version = (n - 17) // 4 out.update(modules=n, version=version, modules_from=source) h, centres, aligned = geom.refine(img, h0, n, fits) moved = np.array(to_image(h, np.array([0.0, n, n, 0]), np.array([0.0, 0, n, n]))).T trusted = geom.valid_quad(moved, (hgt, wid)) is not None and np.abs(moved - q).max() <= 4 * square if not trusted: # a rebuild that bends the code out of shape, or moves a corner 4 squares, is not trusted h, moved = h0, q q = moved width = _frame(out, q, n, version, (hgt, wid), to1280, to_native) # square size and perspective grid = (0.5, n / 2, n - 0.5) stretches = [geom.stretch(h, u, v) for u in grid for v in grid] ppm, narrow = min(s[0] for s in stretches), min(s[1] for s in stretches) big, small = geom.stretch(h, n / 2, n / 2) tilt = _r(math.degrees(math.acos(min(1.0, small / big))), 1) at1280, (ok_from, problem_below) = _r(ppm * to1280, 2), (_r(c, 2) for c in ppm_cuts(version)) out["ppm"].update(at1280=at1280, narrow1280=_r(narrow * to1280, 2), native=_r(ppm * to_native, 2), mean1280=_r(width / n * to1280, 2), ok_from=ok_from, problem_below=problem_below, **_status([] if at1280 >= ok_from else [("watch", "small")] if at1280 >= problem_below else [("problem", "small")])) out["perspective"].update(tilt=tilt, **_status(_grade(_round_half_up(tilt), TILT_OK, TILT_WATCH, "tilt"))) # blur, contrast, polarity from the finder profiles good = [(f, a, r) for f, a, r in fits if r["ok"]] inverted = None if fits: votes = [r["dark"] > r["light"] for _, _, r in (good or fits)] inverted = bool(sum(votes) * 2 > len(votes)) spread = None if len(good) >= 2: per_axis = [np.median([r["s"] for _, a, r in good if a == axis]) for axis in (0, 1) if any(a == axis for _, a, _ in good)] sigma = float(np.sqrt(np.mean(np.square(per_axis)))) # the same for a shake in any direction blur, px1280 = _r(sigma, 3), _r(sigma * width / n * to1280, 2) spread = float(max(per_axis)) # how far the blur reaches, for the quiet zone out["blur"].update(modules=blur, px1280=px1280, fits=len(good), **_status(_grade( _shown(blur), BLUR_OK, BLUR_WATCH, "blur" if px1280 >= BLUR_SHARP_PX else "small"))) if good: # the best-lit finder stands for the print; shadow and glare over the others are lighting's per_finder = [np.mean([abs(r["light"] - r["dark"]) for g, _, r in good if g == f]) / 255 for f in sorted({f for f, _, _ in good})] value = _r(min(1.0, max(per_finder)), 3) # a share of the step from white to black: the fit can overshoot out["contrast"].update(value=value, min=_r(min(1.0, min(per_finder)), 3), inverted=inverted, **_status(_grade(_shown(value), CONTRAST_OK, CONTRAST_WATCH, "contrast", True) + ([("watch", "inverted")] if inverted else []))) # the code's squares: lighting m = nanmean(module_values(img, h, n).reshape(n, n, 9), 2) reg, _ = regions(m, n) if inverted is None: # no finder fit: the finder's outer ring against the separator inside it ring, separator = nanmean(m[0, :7], 0), nanmean(m[7, :8], 0) inverted = bool(ring > separator) if np.isfinite(ring) and np.isfinite(separator) else None out["contrast"]["inverted"] = inverted lit = reg[..., 0][np.isfinite(reg[..., 0])] if len(lit): # else no part of the code shows two levels: nothing to judge the light by # glare: squares whose 3 x 3 neighbourhood is washed out, at 250 or brighter and brighter than the code's # own light squares (so a graphic's pure white is not glare, nor bright noise) seen = np.isfinite(m) hood = cv2.blur(np.where(seen, m, 0.0), (3, 3), borderType=cv2.BORDER_CONSTANT) / np.maximum( cv2.blur(seen.astype(float), (3, 3), borderType=cv2.BORDER_CONSTANT), 1e-9) clipped = _r(np.mean(hood[seen] >= max(CLIP_LEVEL, float(np.median(lit)) + CLIP_ABOVE)), 4) ratio = _r(lit.min() / lit.max(), 3) if len(lit) >= 2 and lit.max() > 0 else None worst = float(np.nanmin(reg[..., 0] - reg[..., 1]) / 255) out["lighting"].update(ratio=ratio, worst=_r(worst, 3), clipped=clipped, **_status(_grade(_shown(ratio, darker=True), SHADOW_OK, SHADOW_WATCH, "shadow", True) + _grade(_shown(clipped), CLIP_OK, CLIP_WATCH, "glare"))) # the quiet zone, judged only where the code's own patterns pinned its edges found = np.isfinite(reg[..., 0]) if found.any(): levels = reg[found] elif good: levels = np.array([[max(r["light"], r["dark"]), min(r["light"], r["dark"])] for *_, r in good]) else: return out if inverted is None: # no telling the background from the squares return out # a side is judged where both its ends are pinned: the bottom-right corner by the alignment pattern (the grid as # rebuilt), or else by the grid the finder patterns complete, measured on it (a scanner's own may be a square off) hq, corner = h, aligned if trusted and not aligned and len(centres) == 3: done = geom.complete(h0, n, fits, centres, square, (hgt, wid)) if done is not None and done[1] <= BR_FIT and done[2] <= BR_FAR: hq, corner = done[0], True pinned = [trusted and {0, 1} <= set(centres), trusted and 1 in centres and corner, # top, right, bottom, left trusted and 2 in centres and corner, trusted and {0, 2} <= set(centres)] # as drawn if not any(pinned) or spread is None: out["quiet"]["why"] = ["unpinned"] return out # the least margin of the pinned sides; with a side not pinned, only a problem is certain (that side may be the # least). A margin known only as a bound (under) is graded by its bound mq = m if hq is h else nanmean(module_values(img, hq, n).reshape(n, n, 9), 2) margins, names = quiet_margins(img, hq, n, mq, levels, inverted, spread, ppm), geom.side_names(h, n) k = min((i for i in range(4) if pinned[i]), key=lambda i: margins[i][:2]) margin, edge, under, _ = margins[k] if not all(pinned) and margin >= QUIET_PROBLEM: out["quiet"]["why"] = ["unpinned"] return out capped = margin >= QUIET_STANDARD and any(pinned[i] and margins[i][3] for i in range(4)) # any side's 4 counts out["quiet"].update(modules=_r(margin, 2), under=under, side=names[k], edge=edge, capped=capped, sides={names[i]: _r(margins[i][0], 2) if pinned[i] else None for i in range(4)}, **_status([] if margin >= QUIET_STANDARD else [("watch" if margin >= QUIET_PROBLEM else "problem", "edge" if edge else "margin")])) return out