wx-paper-parser 1.1.30__tar.gz

wx_paper_parser-1.1.30/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: wx_paper_parser
+Version: 1.1.30
+Summary: Answer sheet ID recognition
+Author: asan
+License: GPL-3.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: opencv-python>=4.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: onnxruntime>=1.16
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: zxing-cpp>=2.0
+Requires-Dist: shapely>=2.0
+
+# wx_paper_parser
+
+> Answer-sheet student-ID recognition library — barcode / QR + handwritten bubble filling, with CNN OCR fallback.
+
+答题卡学号识别库。从扫描或拍摄的答题卡图像中识别考号（条码 / 二维码 + 手写填涂）。
+
+## 识别流程
+
+入口 `EnhanceIdExtractor` 按速度优先依次 fallback：
+
+```
+条码 / 二维码 → CNN 检测 + OCR → 遗留识别器
+```
+
+- **条码 / 二维码**：最快，命中即返回
+- **CNN 检测 + 手写 OCR**：定位学号区域并逐位识别
+- **遗留识别器**：兼容旧版填涂式布局
+
+## 安装
+
+```bash
+pip install wx_paper_parser
+```
+
+## 依赖
+
+安装时自动拉取：`opencv-python`、`numpy`、`onnxruntime`、`pyyaml`、`zxing-cpp`、`shapely`。
+
+要求 Python ≥ 3.10。
+
+## 用法
+
+```python
+import cv2
+from wx_paper_parser import EnhanceIdExtractor
+
+extractor = EnhanceIdExtractor()                     # 默认使用包内模型，懒加载
+img = cv2.imread("answer_sheet.jpg")
+
+angle, corrected = extractor.correct_direction(img)  # 校正纸张方向
+student_id = extractor.read_code(corrected)          # 识别学号
+print(student_id)
+```
+
+## 主要模块
+
+| 名称 | 说明 |
+| --- | --- |
+| `EnhanceIdExtractor` | 识别入口，按速度优先 fallback |
+| `read_barcode` | 条码 / 二维码读取 |
+| `CNNIdRecognizer` | CNN 检测 + OCR 管线 |
+| `CompositionIdRecognizer` | 遗留识别器 |
+
+完整导出见 `wx_paper_parser/__init__.py`。
+
+## License
+
+GPL-3.0

wx_paper_parser-1.1.30/README.md

@@ -0,0 +1,58 @@
+# wx_paper_parser
+
+> Answer-sheet student-ID recognition library — barcode / QR + handwritten bubble filling, with CNN OCR fallback.
+
+答题卡学号识别库。从扫描或拍摄的答题卡图像中识别考号（条码 / 二维码 + 手写填涂）。
+
+## 识别流程
+
+入口 `EnhanceIdExtractor` 按速度优先依次 fallback：
+
+```
+条码 / 二维码 → CNN 检测 + OCR → 遗留识别器
+```
+
+- **条码 / 二维码**：最快，命中即返回
+- **CNN 检测 + 手写 OCR**：定位学号区域并逐位识别
+- **遗留识别器**：兼容旧版填涂式布局
+
+## 安装
+
+```bash
+pip install wx_paper_parser
+```
+
+## 依赖
+
+安装时自动拉取：`opencv-python`、`numpy`、`onnxruntime`、`pyyaml`、`zxing-cpp`、`shapely`。
+
+要求 Python ≥ 3.10。
+
+## 用法
+
+```python
+import cv2
+from wx_paper_parser import EnhanceIdExtractor
+
+extractor = EnhanceIdExtractor()                     # 默认使用包内模型，懒加载
+img = cv2.imread("answer_sheet.jpg")
+
+angle, corrected = extractor.correct_direction(img)  # 校正纸张方向
+student_id = extractor.read_code(corrected)          # 识别学号
+print(student_id)
+```
+
+## 主要模块
+
+| 名称 | 说明 |
+| --- | --- |
+| `EnhanceIdExtractor` | 识别入口，按速度优先 fallback |
+| `read_barcode` | 条码 / 二维码读取 |
+| `CNNIdRecognizer` | CNN 检测 + OCR 管线 |
+| `CompositionIdRecognizer` | 遗留识别器 |
+
+完整导出见 `wx_paper_parser/__init__.py`。
+
+## License
+
+GPL-3.0

wx_paper_parser-1.1.30/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wx_paper_parser"
+version = "1.1.30"
+description = "Answer sheet ID recognition"
+readme = "README.md"
+authors = [{name = "asan"}]
+license = {text = "GPL-3.0"}
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "opencv-python>=4.0",
+    "numpy>=1.24",
+    "onnxruntime>=1.16",
+    "pyyaml>=6.0",
+    "zxing-cpp>=2.0",
+    "shapely>=2.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["wx_paper_parser*"]
+
+[tool.setuptools.package-data]
+wx_paper_parser = ["mdl_config.yml", "mdl/**/*"]

wx_paper_parser-1.1.30/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wx_paper_parser-1.1.30/wx_paper_parser/__init__.py

@@ -0,0 +1,27 @@
+from .composition_id_recognizer import CompositionIdRecognizer, PaperType, StatusCode, RecognitionResult, b64_to_mat, mat_to_b64, mat_to_md5
+from .composition_id_recognizer_cnn import CNNIdRecognizer
+from .enhance_id_extractor import EnhanceIdExtractor
+from .digit_ocr import DigitOCR
+from .detector import SNDetector
+from .paper_orientation_checker import query_doc_orientation, get_detector
+from .text_det import TextDet
+from .barcode_reader import read_barcode
+
+
+__all__ = [
+    'CompositionIdRecognizer',
+    'CNNIdRecognizer',
+    'EnhanceIdExtractor',
+    'DigitOCR',
+    'SNDetector',
+    'query_doc_orientation',
+    'TextDet',
+    'get_detector',
+    'read_barcode',
+    'RecognitionResult',
+    'StatusCode',
+    'PaperType',
+    'b64_to_mat',
+    'mat_to_b64',
+    'mat_to_md5'
+]

wx_paper_parser-1.1.30/wx_paper_parser/_default_config.py

@@ -0,0 +1,25 @@
+"""包内默认模型路径解析工具"""
+
+from pathlib import Path
+import yaml
+
+
+def get_default_model_path(key: str) -> str:
+    """从包内 mdl_config.yml 读取指定 key 对应的模型路径（绝对路径）。
+
+    Args:
+        key: mdl_config.yml 中的配置 key，如 'id_det_mdl_path'
+
+    Returns:
+        解析后的绝对路径字符串，找不到则返回空字符串
+    """
+    config_path = Path(__file__).parent / "mdl_config.yml"
+    print(f"配置地址: {config_path}")
+    if not config_path.exists():
+        return ""
+    with open(config_path) as f:
+        cfg = yaml.safe_load(f) or {}
+    relative = cfg.get(key, "")
+    if not relative:
+        return ""
+    return str(config_path.parent / relative)

wx_paper_parser-1.1.30/wx_paper_parser/barcode_reader.py

@@ -0,0 +1,217 @@
+"""
+通用条码/二维码读取工具
+
+按速度优先的策略依次尝试（多二值化器 × 多缩放），命中即返回。
+默认检测 Code128、Code39、Code93 条码 + QRCode 二维码。
+
+使用方式:
+    from utils.barcode_reader import read_barcode
+
+    result = read_barcode(image)
+    if result:
+        content, points, code_type = result
+        # content: 识别到的文本
+        # points: 四角坐标 [[x,y], ...]
+        # code_type: 0=条形码, 1=二维码
+"""
+
+import logging
+from typing import List, Optional, Tuple
+import json
+import cv2
+from cv2.typing import MatLike
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+# 缩放因子（从小到大，兼顾速度与覆盖率）
+_SCALE_FACTORS = [1.0, 1.5, 2.0, 2.5, 3.0, 5.0]
+
+
+def _extract_points(position) -> List[List[int]]:
+    """从 zxingcpp Position 提取四角坐标"""
+    points = []
+    for attr in ('top_left', 'top_right', 'bottom_right', 'bottom_left'):
+        pt = getattr(position, attr, None)
+        if pt is not None:
+            points.append([int(pt.x), int(pt.y)])
+    return points
+
+
+def _max_channel_gray(image: MatLike) -> MatLike:
+    """取 BGR 三通道最大值作为灰度图，消除彩色背景对条形码识别的干扰。
+
+    标准 BGR2GRAY 使用加权平均 (0.299R+0.587G+0.114B)，纯红背景变成
+    gray=76，纯蓝变成 gray=29，在 zxingcpp FixedThreshold(127) 下与
+    黑色条码一起被二值化为黑色，对比度消失。
+    取三通道最大值后，任何饱和色都变成 255（白色），黑色条码保持 0，
+    恢复完整对比度。对标准灰度/白色背景图像无影响（B=G=R 时结果一致）。
+    """
+    if len(image.shape) == 2:
+        return image.copy()
+    return np.max(image, axis=2).astype(np.uint8)
+
+
+def _is_json_structured(txt: str) -> bool:
+    try:
+        result = json.loads(txt)
+        return isinstance(result, (dict, list))
+    except (ValueError, TypeError):
+        return False
+
+
+def read_barcode(
+    image: MatLike,
+    crop_top_ratio: Optional[float] = None,
+    digit_only: bool = False,
+    include_qr: bool = True,
+    keys: Optional[List[str]] = None, 
+) -> List[Tuple[str, List[List[int]], int]]:
+    """
+    读取条形码或二维码，命中即返回。
+
+    默认检测 Code128、Code39、Code93 条码 + QRCode 二维码。
+    策略顺序（尽早返回）：
+      每个 scale 级别依次尝试三种 zxingcpp 内置二值化器：
+      FixedThreshold → LocalAverage → GlobalHistogram
+
+    Args:
+        image: BGR 图像
+        crop_top_ratio: 只检测顶部指定比例区域 (0~1), None 为整图
+        digit_only: 仅接受纯数字内容
+        include_qr: 是否同时检测二维码，默认 True
+        keys: 指定要检测的二维码内容关键词列表，None 表示不进行关键词过滤
+    Returns:
+        [(内容, [[x,y], ...], code_type)]
+        code_type: 0=条形码, 1=二维码
+    """
+    try:
+        import zxingcpp
+    except ImportError:
+        logger.warning("[BarcodeReader] zxingcpp 未安装")
+        return []
+
+    # 检测格式：可靠的一维码 + 可选二维码
+    linear_formats = [zxingcpp.BarcodeFormat.Code128, zxingcpp.BarcodeFormat.Code39, zxingcpp.BarcodeFormat.Code93]
+    target_formats = linear_formats.copy()
+    if include_qr:
+        target_formats.append(zxingcpp.BarcodeFormat.QRCode)
+
+    h, w = image.shape[:2]
+
+    # 裁剪检测区域
+    if crop_top_ratio is not None and 0 < crop_top_ratio < 1:
+        roi = image[:int(h * crop_top_ratio), :]
+    else:
+        roi = image
+
+    roi_h, roi_w = roi.shape[:2]
+    is_color = len(roi.shape) == 3
+    gray = cv2.cvtColor(roi, cv2.COLOR_BGR2GRAY) if is_color else roi.copy()
+
+    # 三通道最大值灰度图：消除彩色边框/底色干扰
+    max_channel = _max_channel_gray(roi) if is_color else gray.copy()
+
+    # 预计算 CLAHE 对比度增强图（用于 fallback）
+    clahe = cv2.createCLAHE(clipLimit=3.0, tileGridSize=(8, 8))
+    enhanced = clahe.apply(gray)
+
+    # 二值化器列表（按覆盖率排序：FixedThreshold 覆盖最广且最快）
+    binarizers = [
+        ("Fixed", zxingcpp.Binarizer.FixedThreshold),
+        ("Local", zxingcpp.Binarizer.LocalAverage),
+        ("Global", zxingcpp.Binarizer.GlobalHistogram),
+    ]
+
+    def _scan_image(scaled_img, scale_val):
+        """在指定缩放的图像上扫描条码，返回匹配结果列表"""
+        scan_results = []
+        for bin_label, binarizer in binarizers:
+            codes = zxingcpp.read_barcodes(image=scaled_img, formats=target_formats, binarizer=binarizer)
+
+            for code in codes:
+                text = code.text
+                print(f"[BAR CODE] 读取条码: {text}, {code.format}")
+                if not text:
+                    continue
+                if code.format != zxingcpp.BarcodeFormat.QRCode and digit_only and not text.isdigit():
+                    continue
+
+                # 坐标映射回原始图像
+                points = _extract_points(code.position)
+                if scale_val != 1.0:
+                    points = [[int(p[0] / scale_val), int(p[1] / scale_val)] for p in points]
+
+                code_type = 1 if code.format == zxingcpp.BarcodeFormat.QRCode else 0
+                if code_type == 1:
+                    qr_info = {}
+                    is_json = _is_json_structured(text)
+                    if is_json:
+                        try:
+                            qr_info = json.loads(text)
+                        except Exception:
+                            pass
+                    if is_json:
+                        student_number = qr_info.get("studentNumber", "")
+                        # 说明是维学专属答题卡二维码，且要求学号必须为纯数字
+                        if not student_number or student_number.isdigit() == False:
+                            print(f"[BarcodeReader] 二维码内容不符合学号要求: {text}")
+                            continue
+                    elif not is_json and digit_only and not text.isdigit():
+                        continue
+
+                fmt_str = str(code.format)
+
+                print(f"[BarcodeReader] {bin_label} {scale_val}x: {text!r} ({fmt_str})")
+                scan_results.append((text, points, code_type))
+
+            if len(scan_results) > 0:
+                return scan_results
+        return scan_results
+
+    def _has_barcode(res):
+        return any(r[2] == 0 for r in res)
+
+    results = []
+    for scale in _SCALE_FACTORS:
+        new_w, new_h = int(roi_w * scale), int(roi_h * scale)
+        if scale == 1.0:
+            scaled = gray
+            scaled_enhanced = enhanced
+            scaled_maxch = max_channel
+        else:
+            scaled = cv2.resize(gray, (new_w, new_h), interpolation=cv2.INTER_CUBIC)
+            scaled_enhanced = cv2.resize(enhanced, (new_w, new_h), interpolation=cv2.INTER_CUBIC)
+            scaled_maxch = cv2.resize(max_channel, (new_w, new_h), interpolation=cv2.INTER_CUBIC)
+
+        # 原始图像扫描
+        results = _scan_image(scaled, scale)
+        has_barcode = _has_barcode(results)
+
+        # 同一 scale 内 CLAHE fallback（仅当尚未找到条形码时）
+        if not has_barcode:
+            clahe_results = _scan_image(scaled_enhanced, scale)
+            if clahe_results:
+                results.extend(clahe_results)
+                has_barcode = _has_barcode(results)
+
+        # 三通道最大值 fallback：消除彩色边框/底色干扰
+        # 即使已找到 QR 码，仍需检查是否存在被彩色遮挡的条形码
+        if not has_barcode:
+            maxch_results = _scan_image(scaled_maxch, scale)
+            if maxch_results:
+                results.extend(maxch_results)
+                has_barcode = _has_barcode(results)
+
+        # 已找到条形码（非 QR）即可返回
+        if has_barcode and len(results) > 0:
+            print(f"[BARCODE]1 识别结果: {results}")
+            return results
+
+        # 仅找到 QR 码时也返回（无条形码时不再继续尝试更大缩放）
+        if len(results) > 0:
+            print(f"[BARCODE]1 识别结果: {results}")
+            return results
+
+    print(f"[BARCODE]2 识别结果: {results}")
+    return results

wx_paper_parser-1.1.30/wx_paper_parser/bubble_classifier.py

@@ -0,0 +1,94 @@
+import cv2
+import numpy as np
+import onnxruntime as ort
+from PIL import Image
+if __package__:
+    from ._default_config import get_default_model_path
+else:
+    from _default_config import get_default_model_path
+
+
+class BubbleClassifier:
+    """填涂项二分类器，基于ONNX Runtime推理。
+
+    用法:
+        clf = BubbleClassifier("bubble_classifier.onnx")
+        result = clf.predict("image.jpg")
+        print(result)  # {'label': 'filled', 'probability': 0.98, 'filled': True}
+    """
+
+    def __init__(self, model_path: str | None = None, threshold=0.5, img_size=64):
+        model_path = model_path or get_default_model_path("bubble_cls_mdl_path")
+        self.session = ort.InferenceSession(model_path)
+        self.input_name = self.session.get_inputs()[0].name
+        self.threshold = threshold
+        self.img_size = img_size
+
+    def _preprocess(self, image):
+        if isinstance(image, str):
+            img = Image.open(image).convert("RGB")
+            img = img.resize((self.img_size, self.img_size), Image.BILINEAR)
+            arr = np.array(img, dtype=np.float32) / 255.0  # (H, W, 3)
+        else:
+            # OpenCV MatLike (BGR or Gray)
+            if image.ndim == 2:
+                arr = cv2.cvtColor(image, cv2.COLOR_GRAY2RGB).astype(np.float32) / 255.0
+            else:
+                arr = cv2.cvtColor(image, cv2.COLOR_BGR2RGB).astype(np.float32) / 255.0
+            arr = cv2.resize(arr, (self.img_size, self.img_size), interpolation=cv2.INTER_LINEAR)
+        arr = (arr - 0.8) / 0.2
+        arr = arr.transpose(2, 0, 1)  # (3, H, W)
+        arr = arr[np.newaxis, :, :, :]  # (1, 3, H, W)
+        return arr.astype(np.float32)
+
+    def predict(self, image):
+        """预测单张图片是否为填涂项。
+
+        Args:
+            image: 图片路径(str) 或 OpenCV MatLike (BGR/Gray numpy数组)
+
+        Returns:
+            dict: {'label': 'filled'/'unfilled', 'probability': float, 'filled': bool}
+        """
+        blob = self._preprocess(image)
+        logit = self.session.run(None, {self.input_name: blob})[0]
+        prob = 1.0 / (1.0 + np.exp(-logit[0]))  # sigmoid
+        filled = bool(prob >= self.threshold)
+        return {
+            "label": "filled" if filled else "unfilled",
+            "probability": float(prob),
+            "filled": filled,
+        }
+
+    def predict_group(self, images):
+        """对一组选项进行预测，通过组内相对比较判断哪个被填涂。
+
+        适用于同一道题的多个选项（如A/B/C/D），组内只选概率最高的作为filled。
+        如果组内所有选项概率都很低（低于绝对阈值），则判定为未作答。
+
+        Args:
+            images: 图片列表，每个元素为文件路径(str)或OpenCV MatLike
+
+        Returns:
+            list[dict]: 每个选项的预测结果，额外包含 'group_filled' 字段表示
+                        该选项是否为组内被选中的那个
+        """
+        results = [self.predict(img) for img in images]
+
+        max_idx = max(range(len(results)), key=lambda i: results[i]["probability"])
+        max_prob = results[max_idx]["probability"]
+
+        for i, r in enumerate(results):
+            r["group_filled"] = (i == max_idx and max_prob >= self.threshold)
+
+        return results
+
+
+_classifier: BubbleClassifier | None = None
+
+
+def get_classifier(model_path: str | None = None, threshold=0.5, img_size=64) -> BubbleClassifier:
+    global _classifier
+    if _classifier is None:
+        _classifier = BubbleClassifier(model_path, threshold, img_size)
+    return _classifier