QReader

<img alt="QReader" title="QReader" src="https://yellow-cdn.veclightyear.com/835a84d5/efdc1711-dac2-42be-9891-9c160ee4ce7e.png" width="20%" align="left"> QReader是一个健壮且直接的Python解决方案，用于读取图像中难以识别和棘手的QR码。它由<a href="https://github.com/Eric-Canas/qrdet" target="_blank">YOLOv8</a>模型驱动。

该库的核心由两个主要组成部分构成：一个经过训练用于检测和分割QR码的<a href="https://github.com/ultralytics/ultralytics" target="_blank">YOLOv8</a>QR检测器模型（也作为<a href="https://github.com/Eric-Canas/qrdet" target="_blank">独立项目</a>提供），以及<a href="https://github.com/NaturalHistoryMuseum/pyzbar" target="_blank">Pyzbar</a>QR解码器。利用从这个QR检测器中提取的信息，QReader在<a href="https://github.com/NaturalHistoryMuseum/pyzbar" target="_blank">Pyzbar</a>的基础上透明地应用了不同的图像预处理技术，最大化了难度较大图像的解码率。

安装

要安装QReader，只需运行：

pip install qreader

你可能需要安装一些额外的pyzbar依赖：

在Windows上：

极少数情况下，你可能会遇到与lizbar-64.dll相关的丑陋的ImportError。如果发生这种情况，请从_Visual C++ Redistributable Packages for Visual Studio 2013_安装vcredist_x64.exe

在Linux上：

sudo apt-get install libzbar0

在Mac OS X上：

brew install zbar

要在本地安装QReader包，运行pip

python -m pip install --editable .

注意：如果你在资源非常有限的服务器上运行QReader，你可能想在安装QReader之前安装PyTorch的CPU版本。要做到这一点，运行：pip install torch --no-cache-dir（感谢@cjwalther的建议）。

使用方法

<a href="https://colab.research.google.com/github/Eric-Canas/QReader/blob/main/example.ipynb" target="_blank"><img src="https://yellow-cdn.veclightyear.com/835a84d5/09a80407-4e70-4a4e-b2a8-4fc7ad442895.svg" alt="在Colab中打开" data-canonical-src="https://yellow-cdn.veclightyear.com/835a84d5/09a80407-4e70-4a4e-b2a8-4fc7ad442895.svg" style="max-width: 100%;"></a>

QReader是一个非常简单直接的库。对于大多数用例，你只需要调用detect_and_decode：

from qreader import QReader
import cv2

# 创建一个QReader实例
qreader = QReader()

# 获取包含QR码的图像
image = cv2.cvtColor(cv2.imread("path/to/image.png"), cv2.COLOR_BGR2RGB)

# 使用detect_and_decode函数获取解码后的QR数据
decoded_text = qreader.detect_and_decode(image=image)

detect_and_decode将返回一个tuple，包含图像中每个找到的QR的解码_字符串_。

注意：某些条目可能为None，这种情况发生在QR被检测到但无法解码时。

API参考

QReader(model_size = 's', min_confidence = 0.5, reencode_to = 'shift-jis', weights_folder = None)

这是库的主类。请尽量只实例化一次，以避免每次需要检测QR码时都加载模型。

• model_size：str。要使用的模型大小。可以是**'n'（nano）、's'（small）、'm'（medium）或'l'（large）。较大的模型可能更准确但速度较慢。推荐：'s'**（#37）。默认：'s'。
• min_confidence：float。QR检测被认为有效的最小置信度。接近0.0的值可能会得到更多_假阳性_，而接近1.0的值可能会丢失难以识别的QR。默认（并推荐）：0.5。
• reencode_to：str | None。用于重新编码utf-8解码后的QR字符串的编码。如果为None，则不会重新编码。如果发现某些字符解码不正确，可以尝试设置与你特定字符集匹配的代码页。已发现有用的建议：
  • 'shift-jis'用于日耳曼语系
  • 'cp65001'用于亚洲语言（感谢@nguyen-viet-hung的建议）
• weights_folder：str|None。检测模型将被下载的文件夹。如果为None，它将被下载到默认的qrdet包内部文件夹，确保在卸载时正确删除。在像AWS Lambda这样只有/tmp文件夹可写的环境中工作时，你可能需要更改它，如#21中所述。默认：None（<qrdet_package>/.model）。

QReader.detect_and_decode(image, return_detections = False)

此方法将解码给定图像中的QR码，并返回解码后的_字符串_（如果检测到但未解码，则返回_None_）。

• image：np.ndarray。要读取的图像。预期为_RGB_或_BGR_（uint8）格式（HxWx3）。

• return_detections：bool。如果为True，将返回完整的检测结果以及解码后的QR。如果为False，则只返回QR码的解码内容。

• is_bgr：boolean。如果为True，则接收的图像预期为_BGR_而不是_RGB_。

• 返回：tuple[str | None] | tuple[tuple[dict[str, np.ndarray | float | tuple[float | int, float | int]]], str | None]]：一个包含所有检测到的QR码解码结果的元组。如果return_detections为False，输出将如下所示：('解码QR 1', '解码QR 2', None, '解码QR 4', ...)。如果return_detections为True，则如下所示：(('解码QR 1', {'bbox_xyxy': (x1_1, y1_1, x2_1, y2_1), 'confidence': conf_1}), ('解码QR 2', {'bbox_xyxy': (x1_2, y1_2, x2_2, y2_2), 'confidence': conf_2, ...}), ...)。有关检测格式的更多信息，请参阅QReader.detect()。

<a name="QReader_detect"></a>

QReader.detect(image)

此方法检测图像中的QR码，并返回包含所有检测信息的_字典元组_。

• image：np.ndarray。要读取的图像。预期为_RGB_或_BGR_（uint8）格式（HxWx3）。

• is_bgr：boolean。如果为True，则接收的图像预期为_BGR_而不是_RGB_。 <a name="QReader_detect_table"></a>

• 返回：tuple[dict[str, np.ndarray|float|tuple[float|int, float|int]]]。包含每个检测的所有信息的字典元组。包含以下键。

键	值描述	值类型	值形式
confidence	检测置信度	float	conf.
bbox_xyxy	边界框	np.ndarray (4)	[x1, y1, x2, y2]
cxcy	边界框中心	tuple[float, float]	(x, y)
wh	边界框宽度和高度	tuple[float, float]	(w, h)
polygon_xy	精确分割_QR_的多边形	np.ndarray (N, 2)	[[x1, y1], [x2, y2], ...]
quad_xy	分割_QR_的四角多边形	np.ndarray (4, 2)	[[x1, y1], ..., [x4, y4]]
padded_quad_xy	填充以完全覆盖polygon_xy的quad_xy	np.ndarray (4, 2)	[[x1, y1], ..., [x4, y4]]
image_shape	输入图像的形状	tuple[int, int]	(h, w)

注意：

• 所有np.ndarray值的类型为np.float32
• 除confidence和image_shape外，所有键都有一个归一化（'n'）版本。例如，bbox_xyxy表示图像坐标系中的QR边界框[[0., im_w], [0., im_h]]，而bbox_xyxyn包含归一化坐标[0., 1.]中的相同边界框。
• bbox_xyxy[n]和polygon_xy[n]被裁剪到image_shape。你可以直接使用它们进行索引，无需进一步处理。

注意：这是你唯一需要的方法吗？看看<a href="https://github.com/Eric-Canas/qrdet" target="_blank">QRDet</a>。

QReader.decode(image, detection_result)

此方法根据给定的检测结果解码图像上的单个二维码。

内部实现上，该方法将运行 <a href="https://github.com/NaturalHistoryMuseum/pyzbar" target="_blank">pyzbar</a> 解码器，利用 detection_result 的信息，应用不同的图像预处理技术，大大提高解码成功率。

• image：np.ndarray。包含要解码的二维码的图像的 NumPy 数组。图像应为 uint8 格式 [HxWxC]，RGB。

• detection_result：dict[str, np.ndarray|float|tuple[float|int, float|int]]。detect 方法返回的检测字典之一。注意，QReader.detect() 返回这些字典的 tuple。此方法只需要其中一个。

• 返回值：str | None。二维码的解码内容，如果无法读取则返回 None。

使用测试

<div><img alt="test_on_mobile" title="test_on_mobile" src="https://yellow-cdn.veclightyear.com/835a84d5/b3475d94-bf40-44fb-b583-edb7a6c07d05.jpeg" width="60%"><img alt="" title="QReader" src="https://yellow-cdn.veclightyear.com/835a84d5/df77c41b-bc45-4bc4-85a9-4cdf80dde15f.jpeg" width="32%" align="right"></div> <div>两张样例图像。左图是用手机拍摄的图像。右图是贴在绘画上的 64x64 二维码。</div> <br>

以下代码将尝试使用 QReader、<a href="https://github.com/NaturalHistoryMuseum/pyzbar" target="_blank">pyzbar</a> 和 <a href="https://opencv.org/" target="_blank">OpenCV</a> 解码这些包含二维码的图像。

from qreader import QReader
from cv2 import QRCodeDetector, imread
from pyzbar.pyzbar import decode

# 初始化三个测试的读取器（QReader、OpenCV 和 pyzbar）
qreader_reader, cv2_reader, pyzbar_reader = QReader(), QRCodeDetector(), decode

for img_path in ('test_mobile.jpeg', 'test_draw_64x64.jpeg'):
    # 读取图像
    img = imread(img_path)

    # 尝试使用三个读取器解码二维码
    qreader_out = qreader_reader.detect_and_decode(image=img)
    cv2_out = cv2_reader.detectAndDecode(img=img)[0]
    pyzbar_out = pyzbar_reader(image=img)
    # 读取 pyzbar 输出的内容（双重解码可以避免很多错误解码的字符）
    pyzbar_out = tuple(out.data.data.decode('utf-8').encode('shift-jis').decode('utf-8') for out in pyzbar_out)

    # 打印结果
    print(f"图像：{img_path} -> QReader：{qreader_out}。OpenCV：{cv2_out}。pyzbar：{pyzbar_out}。")

上述代码的输出如下：

图像：test_mobile.jpeg -> QReader：('https://github.com/Eric-Canas/QReader')。OpenCV：。pyzbar：()。
图像：test_draw_64x64.jpeg -> QReader：('https://github.com/Eric-Canas/QReader')。OpenCV：。pyzbar：()。

请注意，QReader 内部使用 <a href="https://github.com/NaturalHistoryMuseum/pyzbar" target="_blank">pyzbar</a> 作为解码器。QReader 实现的更高检测-解码率来自于不同图像预处理技术的组合，以及基于 <a href="https://github.com/ultralytics/ultralytics" target="_blank">YOLOv8</a> 的 <a href="https://github.com/Eric-Canas/qrdet" target="_blank">二维码检测器</a>，它能够在比传统计算机视觉方法更困难的条件下检测二维码。

运行测试

可以通过 pytest 启动测试。确保安装了包的测试版本

python -m pip install --editable ".[test]"

然后，你可以运行测试

python -m pytest tests/

基准测试

旋转测试

<div> <img alt="旋转测试" title="旋转测试" src="https://yellow-cdn.veclightyear.com/835a84d5/9a4f4cd2-b7f4-4852-bf6a-8e0c118512af.gif" width="40%" align="left">

                             

<div align="center">

方法	最大旋转角度
Pyzbar	17º
OpenCV	46º
QReader	79º

</div> </div>