qreader 1.3.2

Robust and Straight-Forward solution for reading difficult and tricky QR codes within images in Python.

QReader

QReader is a Robust and Straight-Forward solution for reading difficult and tricky QR codes within images in Python.

Behind the scenes, this detector is based on several other Detectors & Decoders, such as Pyzbar, OpenCV and YoloV3, as well as different image preprocessing techniques. QReader will transparently combine all these techniques to maximize the detection rate on difficult images (e.g. QR code too small).

Installation

To install QReader, simply run:

pip install qreader

If you're not using Windows, you may need to install some additional pyzbar dependencies:

On Linux:

sudo apt-get install libzbar0

On Mac OS X:

brew install zbar

Usage

QReader is a very simple and straight-forward library. For most use cases, you'll only need to call detect_and_decode:

from qreader import QReader
import cv2


# Create a QReader instance
qreader = QReader()

# Get the image that contains the QR code (QReader expects an uint8 numpy array)
image = cv2.imread("path/to/image.png")

# Use the detect_and_decode function to get the decoded QR data
decoded_text = qreader.detect_and_decode(image=image)

The detect_and_decode function will automatically apply several QR detection (OpenCV, YoloV3, sub-region search...) and decoding methods (sharpening, binarization, blurring, rescaling...) until finding one able to retrieve the decoded QR information within that image.

API Reference

QReader.detect_and_decode(image, deep_search = True)

This method will decode the QR code in the given image and return the result. If the QR code is not detected, it will return None.

• image: np.ndarray. NumPy Array containing the image to decode. The image must is expected to be in uint8 format [HxWxC].

• deep_search: boolean. If True, it will make a deep search if the QR can't be detected at the first attempt. This deep search will inspect subregions of the image to locate difficult and small QR codes. It can be slightly slower but severally increases the detection rate. Default: True.

• Returns: str. The decoded text of the QR code. If the QR code is not detected, it will return None.

QReader.detect(image)

This method detects the QR in the image and returns the bounding box surrounding it in the format (x1, y1, x2, y2).

This method will always assume that there is only one QR code in the image.

• image: np.ndarray. NumPy Array containing the image to decode. The image must is expected to be in uint8 format [HxWxC].

• Returns: Tuple of Integers or None. The bounding box of the QR code in the format (x1, y1, x2, y2). If the QR code is not detected, it will return None.

QReader.decode(image, bbox = None)

This method decodes the QR code of the given image, if a bbox is given it will only look within that delimited region.

Internally, this method will run the pyzbar decoder, but sequentially using some image preprocessing techniques (sharpening, binarization, blurring...) to increase the detection rate.

• image: np.ndarray. NumPy Array containing the image to decode. The image must is expected to be in uint8 format [HxWxC].

• bbox: Tuple of Integers or None. The bounding box of the QR code in the format (x1, y1, x2, y2). If None, it will look for the QR code in the whole image. Default: None.

• Returns: str. The decoded text of the QR code. If the QR code is not detected, it will return None.

Usage Tests

Two sample images. At left, an image taken with a mobile phone. At right, a 64x64 QR pasted over a drawing.

The following code will try to decode these images containing QRs with QReader, pyzbar and OpenCV.

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

# Initialize the three tested readers (QRReader, OpenCV and pyzbar)
qreader_reader, cv2_reader, pyzbar_reader = QReader(), QRCodeDetector(), decode

for img_path in ('test_mobile.jpeg', 'test_draw_64x64.jpeg'):
    # Read the image
    img = imread(img_path)

    # Try to decode the QR code with the three readers
    qreader_out = qreader_reader.detect_and_decode(image=img)
    cv2_out = cv2_reader.detectAndDecode(img=img)[0]
    pyzbar_out = pyzbar_reader(image=img)
    # Read the content of the pyzbar output
    pyzbar_out = pyzbar_out[0].data.decode('utf-8') if len(pyzbar_out) > 0 else ""

    # Print the results
    print(f"Image: {img_path} -> QReader: {qreader_out}. OpenCV: {cv2_out}. pyzbar: {pyzbar_out}.")

The output of the previous code is:

Image: test_mobile.jpeg -> QReader: https://github.com/Eric-Canas/QReader. OpenCV: . pyzbar: .
Image: test_draw_64x64.jpeg -> QReader: https://github.com/Eric-Canas/QReader. OpenCV: . pyzbar: .

Note that QReader internally uses pyzbar as decoder and a combination of OpenCV and YoloV3 for the detector. The improved detection-decoding rate that QReader achieves doesn't come from the usage of more powerful readers, but from the combination of the different image pre-processing and QR search methods it applies.

Acknowledgements

This library is based on the following projects:

• Pretrained model weights of QR-code-locatiazation-YOLOv3 by Gabriel Bellport.
• Pyzbar QR Decoder.
• OpenCV methods for image filtering and QR Detection.