优化定二维码识别逻辑

2026-07-28 17:33:22 +08:00
parent c9f62563d6
commit 33b3686c25
3 changed files with 358 additions and 54 deletions
@@ -1,4 +1,8 @@
-"""二维码检测与裁剪工具。"""
+"""二维码检测与裁剪工具。
+
+识别引擎优先用 zxing-cpp（对反色、旋转、小尺寸、艺术化二维码的容错明显更好），
+拿不到时退回 OpenCV 自带检测器，保证不装 zxing-cpp 也能跑。
+"""

 from __future__ import annotations

@@ -8,6 +12,34 @@ from pathlib import Path
 import cv2
 import numpy as np

+from app.core.logger import log
+
+try:  # zxing-cpp 是可选依赖，缺失时自动退化为纯 OpenCV
+    import zxingcpp
+
+    _HAS_ZXING = True
+except ImportError:  # pragma: no cover - 取决于部署环境
+    zxingcpp = None
+    _HAS_ZXING = False
+    log.warning("未安装 zxing-cpp，二维码识别将退化为 OpenCV 检测器，识别率会明显下降")
+
+
+# 要识别的二维码类型：标准 QR + 微型 QR + 矩形 QR
+_QR_FORMATS = (
+    [
+        zxingcpp.BarcodeFormat.QRCode,
+        zxingcpp.BarcodeFormat.MicroQRCode,
+        zxingcpp.BarcodeFormat.RMQRCode,
+    ]
+    if _HAS_ZXING
+    else []
+)
+
+# 放大重试的尺寸上限，避免长图被放大到内存爆掉
+_MAX_UPSCALE_SIDE = 2600
+# 裁剪区域重试时补的静默区宽度（像素）
+_QUIET_ZONE = 16
+

@dataclass
 class QrRegion:
@@ -15,6 +47,7 @@ class QrRegion:

    points: tuple[tuple[int, int], ...]
    crop: np.ndarray | None = None
+    text: str = ""


@dataclass
@@ -105,34 +138,159 @@ def _normalize_points(points: np.ndarray | None) -> list[tuple[tuple[int, int],
    return result


-def _detect_points(img: np.ndarray) -> list[tuple[tuple[int, int], ...]]:
-    detector = cv2.QRCodeDetector()
+def _clip_points(
+    quad: tuple[tuple[int, int], ...], shape: tuple[int, ...]
+) -> tuple[tuple[int, int], ...]:
+    """把角点裁进图像范围内，避免透视变换取到界外。"""
+    height, width = shape[:2]
+    return tuple(
+        (min(max(x, 0), width - 1), min(max(y, 0), height - 1)) for x, y in quad
+    )

-    if hasattr(detector, "detectMulti"):
-        ok, points = detector.detectMulti(img)
-        if ok:
-            normalized_points = _normalize_points(points)
-            if normalized_points:
-                return normalized_points

-    ok, points = detector.detect(img)
-    if ok:
-        normalized_points = _normalize_points(points)
-        if normalized_points:
-            return normalized_points
+def zxing_read(
+    img: np.ndarray,
+    *,
+    binarizer: object | None = None,
+    try_downscale: bool = True,
+) -> list:
+    """用 zxing-cpp 识别图中所有二维码，失败返回空列表。

+    zxing-cpp 默认已开启 try_invert（反色）和 try_rotate（旋转），
+    这是它比 OpenCV 检测器兼容性好的主要原因。
+    """
+    if not _HAS_ZXING:
+        return []
+
+    kwargs = {
+        "formats": _QR_FORMATS,
+        "try_rotate": True,
+        "try_invert": True,
+        "try_downscale": try_downscale,
+    }
+    if binarizer is not None:
+        kwargs["binarizer"] = binarizer
+
+    try:
+        return list(zxingcpp.read_barcodes(img, **kwargs))
+    except Exception as exc:  # zxing 内部异常不应该打断整个流程
+        log.debug(f"zxing-cpp 识别异常: {exc}")
+        return []
+
+
+def zxing_variants(img: np.ndarray) -> list[tuple[str, np.ndarray]]:
+    """构造 zxing 的重试图像变体：原图之外再补一版放大图。
+
+    放大主要救「长图里的小二维码」和「低分辨率二维码」两类。
+    """
+    variants: list[tuple[str, np.ndarray]] = [("原图", img)]
+
+    longest = max(img.shape[:2])
+    if longest and longest * 2 <= _MAX_UPSCALE_SIDE:
+        variants.append(
+            ("放大2倍", cv2.resize(img, None, fx=2, fy=2, interpolation=cv2.INTER_CUBIC))
+        )
+    return variants
+
+
+def pad_quiet_zone(img: np.ndarray, border: int = _QUIET_ZONE) -> np.ndarray:
+    """给裁剪出来的二维码补静默区。
+
+    有些海报把二维码贴边放，裁出来没有留白，补一圈能提高解码成功率。
+    边框颜色取图像四角的中位数，反色码补深色、正常码补浅色，避免破坏极性。
+    """
+    corners = np.array(
+        [img[0, 0], img[0, -1], img[-1, 0], img[-1, -1]], dtype=np.float32
+    )
+    color = np.median(corners, axis=0)
+    value = tuple(int(round(c)) for c in np.atleast_1d(color))
+    if len(value) == 1:
+        value = value * 3
+    return cv2.copyMakeBorder(
+        img, border, border, border, border, cv2.BORDER_CONSTANT, value=value
+    )
+
+
+def _points_from_zxing(barcode: object) -> tuple[tuple[int, int], ...] | None:
+    """把 zxing 的 position 转成四角点。"""
+    position = getattr(barcode, "position", None)
+    if position is None:
+        return None
+
+    quad: list[tuple[int, int]] = []
+    for name in ("top_left", "top_right", "bottom_right", "bottom_left"):
+        point = getattr(position, name, None)
+        if point is None:
+            return None
+        quad.append((int(round(point.x)), int(round(point.y))))
+    return tuple(quad)
+
+
+def _detect_by_opencv(img: np.ndarray) -> list[tuple[tuple[int, int], ...]]:
+    """OpenCV 检测器兜底，额外补一次反色重试。"""
+    for candidate in (img, cv2.bitwise_not(img)):
+        for detector in (cv2.QRCodeDetector(), cv2.QRCodeDetectorAruco()):
+            try:
+                if hasattr(detector, "detectMulti"):
+                    ok, points = detector.detectMulti(candidate)
+                    if ok:
+                        normalized = _normalize_points(points)
+                        if normalized:
+                            return normalized
+
+                ok, points = detector.detect(candidate)
+                if ok:
+                    normalized = _normalize_points(points)
+                    if normalized:
+                        return normalized
+            except cv2.error:
+                continue
    return []


+def _detect_regions(img: np.ndarray) -> list[QrRegion]:
+    """检测二维码区域：zxing 优先（顺带拿到内容），OpenCV 兜底。"""
+    for name, variant in zxing_variants(img):
+        barcodes = zxing_read(variant)
+        if not barcodes:
+            continue
+
+        scale = variant.shape[1] / img.shape[1] if img.shape[1] else 1
+        regions: list[QrRegion] = []
+        for barcode in barcodes:
+            quad = _points_from_zxing(barcode)
+            if quad is None:
+                continue
+            if scale != 1:
+                quad = tuple(
+                    (int(round(x / scale)), int(round(y / scale))) for x, y in quad
+                )
+            quad = _clip_points(quad, img.shape)
+            regions.append(
+                QrRegion(
+                    points=quad,
+                    crop=_warp_qr_image(img, np.array(quad, dtype=np.float32)),
+                    text=getattr(barcode, "text", "") or "",
+                )
+            )
+        if regions:
+            if name != "原图":
+                log.debug(f"二维码检测命中变体: {name}")
+            return regions
+
+    return [
+        QrRegion(
+            points=quad,
+            crop=_warp_qr_image(img, np.array(quad, dtype=np.float32)),
+        )
+        for quad in _detect_by_opencv(img)
+    ]
+
+
 def scan_qr(image: bytes | np.ndarray | str | Path) -> QrDetectResult:
    """扫描图片中是否存在二维码，并返回二维码区域。"""
    img = _load_image(image)
-    points_list = _detect_points(img)
-
-    items = [
-        QrRegion(points=points, crop=_warp_qr_image(img, np.array(points, dtype=np.float32)))
-        for points in points_list
-    ]
+    items = _detect_regions(img)
    return QrDetectResult(has_qr=bool(items), items=items)