Robust and Straight-Forward solution for reading difficult and tricky QR codes within images in Python.
Project description
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 theimage
to decode. The image must is expected to be inuint8
format [HxWxC]. -
deep_search
: boolean. IfTrue
, it will make a deep search if the QR can't be detected at the first attempt. This deep search will inspect subregions of theimage
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 theimage
to decode. The image must is expected to be inuint8
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 theimage
to decode. The image must is expected to be inuint8
format [HxWxC]. -
bbox
: Tuple of Integers or None. The bounding box of the QR code in the format (x1, y1, x2, y2). IfNone
, 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
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.