Download server/quality.py from devmandan/qr-scan-difficulty-check: direct link, hf CLI and curl.
- Browser
- Download file 22.9 kB
-
https://huggingface.co/spaces/devmandan/qr-scan-difficulty-check/resolve/main/server/quality.py
- Command line
-
hf download hf://spaces/devmandan/qr-scan-difficulty-check/server/quality.py
-
curl -L -o quality.py https://huggingface.co/spaces/devmandan/qr-scan-difficulty-check/resolve/main/server/quality.py
22.9 kB
| """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 | |