qr-scan-difficulty-check / server /quality_geom.py
devmandan's picture
Claude Opus 5.5
Add levels, confidence and picture checks
6f28f9e verified
Raw History Blame Contribute Delete
15.1 kB
"""Where the code lies in the picture, for quality.py: the corners from the scanners that read it, checks on them, the
squares' size along the code, the grid rebuilt and completed from the code's own patterns, how the code is framed, and
its squares per side when no scanner gave them. Pure functions, numpy and OpenCV only.
Module coordinates (u, v) run along the code as drawn, in squares: (0, 0) its outer top-left corner, (n, n) the
bottom-right. A homography h maps them to the frame's pixels (pixel centres at whole numbers).
"""
from __future__ import annotations
import math
import cv2
import numpy as np
from .quality_fit import finder_width, sample, to_image
# ---- the corners to measure by, from the scanners that read the agreed content ------------------------------------
# All four give the code's corners in zxing-cpp's order. Against the generator's corners on synthetic captures (worst
# corner at the 1920 frame, median / 90th percentile, in squares): zxing-cpp 0.07 / 0.18; WeChat's 0.20 / 0.43;
# OpenCV's 0.21 / 0.66 and its newer detector 0.30 / 1.07, whose bottom-right corner is an estimate. measure() then
# rebuilds the grid from the finder and alignment patterns where they are found off those corners.
SOURCES = ("zxing-cpp", "wechat", "opencv", "opencv-aruco")
HALF_PIXEL = {"opencv": 0.5, "opencv-aruco": 0.5} # OpenCV puts pixel centres at whole numbers, the others edges
SAME_CODE = 1.5 # squares: another read whose four corners all lie this close is of the same code
FAR = 10 # corners further off than this many times the picture's long side are refused
TIGHT_SHARE = 0.30 # code width / the picture's long side from which the framing is noted as tight: above every
# simulated print the Space measures (at most 0.244). A note, never a status
REFINE_MIN = 0.1 # squares: finder or alignment patterns found this far off where the corners put them: rebuild
ALIGN_MIN = 0.6 # the alignment pattern counts where the template matches this well
def corners_from(scanner: str, *raw) -> tuple[list[list[float]], int | None] | None:
"""One scanner's own output for one code as (corners with pixel edges at whole numbers, squares per side or None):
zxing-cpp (position, extra), WeChat's (points,), OpenCV's (points, straight_qrcode). None if malformed."""
try:
if scanner == "zxing-cpp":
pos, extra = raw
c = np.array([[p.x, p.y] for p in (pos.top_left, pos.top_right, pos.bottom_right, pos.bottom_left)], float)
version = int(extra.get("Version") or 0)
n = 17 + 4 * version if 1 <= version <= 40 else None
else:
c = np.asarray(raw[0], float).reshape(4, 2) + HALF_PIXEL.get(scanner, 0.0)
side = np.shape(raw[1]) if scanner in HALF_PIXEL and raw[1] is not None else ()
n = int(side[0]) if len(side) == 2 and side[0] == side[1] and 21 <= side[0] <= 177 and side[0] % 4 == 1 \
else None
except (TypeError, ValueError, AttributeError, IndexError):
return None
return (c.round(2).tolist(), n) if np.isfinite(c).all() else None
def pick_geometry(found: dict, sizes: list[tuple[int, int]]) -> tuple[list[list[float]], int | None, str] | None:
"""The corners to measure by, in the largest staged frame's pixels: from the most accurate scanner that read the
agreed content, at the largest frame it read it in; the squares per side from that read, else from the first
other read (in the same order) whose corners all lie within SAME_CODE of its squares from these, so that a
second code in the picture never lends its count. found: {(scanner, frame index): (corners, squares or None)}
for those reads; sizes: (w, h) of each staged frame, the largest first."""
quads = {}
for k, v in found.items():
try:
c = np.asarray(v[0], float).reshape(4, 2) * (sizes[0][0] / sizes[k[1]][0], sizes[0][1] / sizes[k[1]][1])
except (TypeError, ValueError, IndexError, KeyError, ZeroDivisionError):
continue
if k[0] in SOURCES and np.isfinite(c).all():
quads[k] = (c, v[1] if isinstance(v[1], int) and 21 <= v[1] <= 177 else None)
if not quads:
return None
order = sorted(quads, key=lambda k: (SOURCES.index(k[0]), k[1]))
quad, n = quads[order[0]]
width = math.sqrt(area(quad))
for k in order[1:]:
if n is not None:
break
c, m = quads[k]
if m is not None and np.linalg.norm(c - quad, axis=1).max() <= SAME_CODE * width / m:
n = m
return quad.tolist(), n, order[0][0]
# ---- the quad -------------------------------------------------------------------------------------------------------
def area(q) -> float:
return 0.5 * abs(float(np.dot(q[:, 0], np.roll(q[:, 1], -1)) - np.dot(q[:, 1], np.roll(q[:, 0], -1))))
def valid_quad(quad, shape: tuple[int, int]) -> np.ndarray | None:
"""The quad as a 4 x 2 array, or None: not four finite corners, one further off the picture than FAR times its
long side (refused before any arithmetic on them), not a convex quadrilateral, or a side under 4 px."""
try:
q = np.asarray(quad, float).reshape(4, 2)
except (TypeError, ValueError):
return None
if not np.isfinite(q).all() or np.abs(q).max() > FAR * max(shape):
return None
e = np.roll(q, -1, 0) - q
cross = e[:, 0] * np.roll(e, -1, 0)[:, 1] - e[:, 1] * np.roll(e, -1, 0)[:, 0]
if not ((cross > 0).all() or (cross < 0).all()) or np.linalg.norm(e, axis=1).min() < 4:
return None
return q
def homography(quad, n: int):
return cv2.getPerspectiveTransform(np.float32([[0, 0], [n, 0], [n, n], [0, n]]), np.float32(quad))
def jacobian(h, u: float, v: float) -> np.ndarray:
"""Image pixels per square at module point (u, v): its columns are the code's axes, d(x, y)/du and d(x, y)/dv."""
w = h[2, 0] * u + h[2, 1] * v + h[2, 2]
x, y = (h[0, 0] * u + h[0, 1] * v + h[0, 2]) / w, (h[1, 0] * u + h[1, 1] * v + h[1, 2]) / w
j = np.array([[h[0, 0] - x * h[2, 0], h[0, 1] - x * h[2, 1]], [h[1, 0] - y * h[2, 0], h[1, 1] - y * h[2, 1]]])
return j / w
def stretch(h, u: float, v: float) -> tuple[float, float]:
"""Largest and smallest stretch of the code (image pixels per square) at module point (u, v): the square's size
before foreshortening, and along the direction the tilt shortens most."""
s = np.linalg.svd(jacobian(h, u, v), compute_uv=False)
return float(s[0]), float(s[1])
# ---- the grid from the code's own patterns ----------------------------------------------------------------------
def _alignment(img, h, n: int) -> tuple[float, float] | None:
"""Offset in squares of the bottom-right alignment pattern (versions 2 and up) from where h puts it, searched
within 1.5 squares; None if no clear match."""
step = 0.125
g = np.arange(-4, 4 + step / 2, step)
u, v = np.meshgrid(n - 6.5 + g, n - 6.5 + g)
patch = sample(img, *to_image(h, u, v)).astype(np.float32)
if not np.isfinite(patch).all():
return None
t = np.arange(-2.5, 2.5 + step / 2, step)
ring = np.maximum(*np.meshgrid(np.abs(t), np.abs(t)))
template = np.where((ring > 0.5) & (ring <= 1.5), 1.0, -1.0).astype(np.float32)
score = np.abs(cv2.matchTemplate(patch, template, cv2.TM_CCOEFF_NORMED))
i, j = np.unravel_index(int(np.argmax(score)), score.shape)
if score[i, j] < ALIGN_MIN:
return None
return (j - (score.shape[1] - 1) / 2) * step, (i - (score.shape[0] - 1) / 2) * step
def refine(img, h, n: int, fits) -> tuple[np.ndarray, dict, bool]:
"""h rebuilt from where the code's own patterns are, as a scanner builds its grid: each finder pattern's centre
where both its profiles fit (else its corner as given) and the bottom-right alignment pattern's centre (else the
bottom-right corner as given), when a pattern lies REFINE_MIN squares or more from where h put it; the centres of
the finder patterns found, in the frame's pixels ({0 top-left, 1 top-right, 2 bottom-left, as drawn: (x, y)}),
and whether the alignment pattern was found."""
off = {(f, a): (-r["d"] if (f, a) in ((1, 0), (2, 1)) else r["d"]) for f, a, r in fits if r["ok"]}
src, dst, shift, centres = [], [], 0.0, {}
for f, ((x, y), corner) in enumerate((((3.5, 3.5), (0, 0)), ((n - 3.5, 3.5), (n, 0)), ((3.5, n - 3.5), (0, n)))):
if (f, 0) in off and (f, 1) in off:
src.append([x, y])
dst.append([x + off[(f, 0)], y + off[(f, 1)]])
shift = max(shift, abs(off[(f, 0)]), abs(off[(f, 1)]))
centres[f] = tuple(float(c) for c in to_image(h, *dst[-1]))
else:
src.append(list(corner))
dst.append(list(corner))
align = _alignment(img, h, n) if n >= 25 else None
if align is None:
src.append([n, n])
dst.append([n, n])
else:
src.append([n - 6.5, n - 6.5])
dst.append([n - 6.5 + align[0], n - 6.5 + align[1]])
shift = max(shift, abs(align[0]), abs(align[1]))
if shift < REFINE_MIN:
return h, centres, align is not None
x, y = to_image(h, np.array(dst)[:, 0], np.array(dst)[:, 1])
if not (np.isfinite(x).all() and np.isfinite(y).all()):
return h, centres, align is not None
return cv2.getPerspectiveTransform(np.float32(src), np.float32(np.stack([x, y], 1))), centres, align is not None
def complete(h, n: int, fits, centres: dict, square: float, shape) -> tuple[np.ndarray, float, float] | None:
"""The code's grid from its three finder patterns alone: the homography through their centres whose scale along
each axis at each pattern best matches the pattern's width (finder_width, against h, the grid its profiles were
sampled on), up to one factor common to all six (ink spread or a resized picture widens or narrows every
pattern alike), solved for the bottom-right corner by Gauss-Newton from h's. Returns it, the rms of the log
misfit and how far its bottom-right corner lies from h's, in squares; None without all three patterns, if the
solve fails, or if the grid's corners are no quad on the picture (valid_quad)."""
if len(centres) < 3:
return None
at = {0: (3.5, 3.5), 1: (n - 3.5, 3.5), 2: (3.5, n - 3.5)}
src, dst = np.float32([at[0], at[1], at[2], (n, n)]), [centres[f] for f in (0, 1, 2)]
def misfit(b):
g = cv2.getPerspectiveTransform(src, np.float32([*dst, b]))
d = np.array([math.log(np.linalg.norm(jacobian(g, u, v)[:, a])) - m for u, v, a, m in want])
return g, d - d.mean()
b, step = np.array(to_image(h, n, n), float), 0.05 * square
try:
want = [(*at[f], a, math.log(finder_width(r) * np.linalg.norm(jacobian(h, *at[f])[:, a])))
for f, a, r in fits if r["ok"] and f in centres]
for _ in range(10):
_, r = misfit(b)
jac = np.stack([(misfit(b + (step, 0))[1] - r) / step, (misfit(b + (0, step))[1] - r) / step], 1)
delta = np.linalg.lstsq(jac, -r, rcond=None)[0]
b = b + delta
if not np.hypot(*delta) >= 0.002 * square: # converged (or not finite: caught below)
break
g, r = misfit(b)
corners = np.array(to_image(g, np.array([0.0, n, n, 0]), np.array([0.0, 0, n, n]))).T
except (ValueError, ZeroDivisionError, cv2.error, np.linalg.LinAlgError):
return None
if not (np.isfinite(r).all() and np.isfinite(g).all()) or valid_quad(corners, shape) is None:
return None
return g, float(np.sqrt(np.mean(r ** 2))), float(np.hypot(*(b - to_image(h, n, n)))) / square
# ---- framing ------------------------------------------------------------------------------------------------------
def framing(q, n: int | None, shape: tuple[int, int]) -> dict:
"""The code's width (square root of its area) and its framing in the picture, in frame pixels: share of the long
side, share of the area, whether it comes within a square of the picture's edge, whether it is framed tight."""
hgt, wid = shape
a = area(q)
width = math.sqrt(a)
near = min((q[:, 0] + 0.5).min(), (q[:, 1] + 0.5).min(), wid - 0.5 - q[:, 0].max(), hgt - 0.5 - q[:, 1].max())
share = width / max(hgt, wid)
sides = np.linalg.norm(np.roll(q, -1, 0) - q, axis=1)
return {"width": width, "share": share, "area": a / (hgt * wid), "edge": bool(near < width / (n or 21)),
"tight": bool(share >= TIGHT_SHARE), "keystone": float(sides.max() / sides.min())}
def side_names(h, n: int) -> list[str]:
"""Each side of the code (top, right, bottom, left as drawn) named as the picture shows it (y down)."""
names, angles = ("top", "right", "bottom", "left"), np.radians([-90, 0, 90, 180])
cx, cy = to_image(h, n / 2, n / 2)
mx, my = to_image(h, np.array([n / 2, n, n / 2, 0]), np.array([0, n / 2, n, n / 2]))
ang = np.arctan2(my - cy, mx - cx)
best = None
for order in (1, -1):
for r in range(4):
idx = [(r + order * k) % 4 for k in range(4)]
cost = float(np.sum(np.angle(np.exp(1j * (ang - angles[idx]))) ** 2))
if best is None or cost < best[0]:
best = (cost, idx)
return [names[i] for i in best[1]]
# ---- the module count, when no scanner gave it --------------------------------------------------------------------
def _pattern(n: int):
"""Module points of the timing patterns and the three finder patterns with their separators, and their colours
(-1 dark, +1 light)."""
k = np.arange(8, n - 8)
timing = np.where(k % 2 == 0, -1.0, 1.0)
i, j = np.mgrid[0:8, 0:8]
ring = np.maximum(abs(i - 3), abs(j - 3))
fp = np.where((ring == 2) | (ring == 4), 1.0, -1.0).ravel()
pts = [(k, np.full_like(k, 6), timing), (np.full_like(k, 6), k, timing),
(j.ravel(), i.ravel(), fp), (n - 1 - j.ravel(), i.ravel(), fp), (j.ravel(), n - 1 - i.ravel(), fp)]
u = np.concatenate([p[0] for p in pts]) + 0.5
v = np.concatenate([p[1] for p in pts]) + 0.5
return u, v, np.concatenate([p[2] for p in pts])
def estimate_modules(img, quad) -> int | None:
"""Squares per side from the timing and finder patterns: the version whose expected pattern the code's pixels
match best. None if no version matches clearly, or the squares would be under 1.2 pixels."""
width = math.sqrt(area(quad))
scores = []
for version in range(1, 41):
n = 17 + 4 * version
if width / n < 1.2:
break
u, v, want = _pattern(n)
got = sample(img, *to_image(homography(quad, n), u, v))
keep = np.isfinite(got)
if keep.sum() < 0.9 * len(got) or got[keep].std() == 0:
scores.append((0.0, n))
continue
scores.append((abs(float(np.corrcoef(got[keep], want[keep])[0, 1])), n))
if not scores:
return None
scores.sort(reverse=True)
best, second = scores[0][0], scores[1][0] if len(scores) > 1 else 0.0
return scores[0][1] if best >= 0.5 and best - second >= 0.1 else None