devmandan's picture
Claude Opus 5.5
Slants and cans, what a phone sees, a test sheet, SVG files and more
378f397 verified
Raw History Blame Contribute Delete
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