# QRDet
**QRDet** is a robust **QR Detector** based on <a href="https://github.com/ultralytics/ultralytics" target="_blank">YOLOv8</a>.
**QRDet** will detect & segment **QR** codes even in **difficult** positions or **tricky** images. If you are looking for a complete **QR Detection** + **Decoding** pipeline, take a look at <a href="https://github.com/Eric-Canas/qreader" target="_blank">QReader</a>.
## Installation
To install **QRDet**, simply run:
```bash
pip install qrdet
```
## Usage
There is only one function you'll need to call to use **QRDet**, ``detect``:
```python
from qrdet import QRDetector
import cv2
detector = QRDetector(model_size='s')
image = cv2.imread(filename='resources/qreader_test_image.jpeg')
detections = detector.detect(image=image, is_bgr=True)
# Draw the detections
for detection in detections:
x1, y1, x2, y2 = detection['bbox_xyxy']
confidence = detection['confidence']
segmenation_xy = detection['quadrilateral_xy']
cv2.rectangle(image, (x1, y1), (x2, y2), color=(0, 255, 0), thickness=2)
cv2.putText(image, f'{confidence:.2f}', (x1, y1 - 10), fontFace=cv2.FONT_HERSHEY_SIMPLEX,
fontScale=1, color=(0, 255, 0), thickness=2)
# Save the results
cv2.imwrite(filename='resources/qreader_test_image_detections.jpeg', img=image)
```
<img alt="detections_output" title="detections_output" src="https://raw.githubusercontent.com/Eric-Canas/qrdet/main/resources/qreader_test_image_detections.jpeg" width="100%">
## API Reference
### QRDetector(model_size = 's', conf_th = 0.5, nms_iou = 0.3, weights_folder = '<qrdet_package>/.model')
- ``model_size``: **"n"|"s"|"m"|"l"**. Size of the model to load. Smaller models will be faster, while larger models will be more capable for difficult situations. Default: `'s'`.
- ``conf_th``: **float**. Confidence threshold to consider that a detection is valid. Incresing this value will reduce _false positives_ while decreasing will reduce _false_negatives_. Default: `0.5`.
- ``nms_iou``: **float**. _Intersection over Union_ (IoU) threshold for _Non-Maximum Suppression_ (NMS). NMS is a technique used to eliminate redundant bounding boxes for the same object. Increase this number if you find problems with duplicated detections. Default: `0.3`
- ``weights_folder``: **str**. Folder where detection model will be downloaded. By default, it points out to an internal folder within the package, making sure that it gets correctly removed when uninstalling. You could need to change it when working in environments like [AWS Lambda](https://aws.amazon.com/es/pm/lambda/) where only [/tmp folder is writable](https://docs.aws.amazon.com/lambda/latest/api/API_EphemeralStorage.html), as issued in [#11](https://github.com/Eric-Canas/qrdet/issues/11). Default: `'<qrdet_package>/.model'`.
### QRDetector.detect(image, is_bgr = False, **kwargs)
- ``image``: **np.ndarray|'PIL.Image'|'torch.Tensor'|str**. `np.ndarray` of shape **(H, W, 3)**, `PIL.Image`, `Tensor` of shape **(1, 3, H, W)**, or `path`/`url` to the image to predict. `'screen'` for grabbing a screenshot.
- ``is_bgr``: **bool**. If `True` the image is expected to be in **BGR**. Otherwise, it will be expected to be **RGB**. Only used when image is `np.ndarray` or `torch.tensor`. Default: `False`
- ``legacy``: **bool**. If sent as **kwarg**, will parse the output to make it identical to 1.x versions. Not Recommended. Default: False.
- **Returns**: **tuple[dict[str, np.ndarray|float|tuple[float|int, float|int]]]**. A tuple of dictionaries containing all the information of every detection. Contains the following keys.
| Key | Value Desc. | Value Type | Value Form |
|------------------|---------------------------------------------|----------------------------|-----------------------------|
| `confidence` | Detection confidence | `float` | `conf.` |
| `bbox_xyxy` | Bounding box | np.ndarray (**4**) | `[x1, y1, x2, y2]` |
| `cxcy` | Center of bounding box | tuple[`float`, `float`] | `(x, y)` |
| `wh` | Bounding box width and height | tuple[`float`, `float`] | `(w, h)` |
| `polygon_xy` | Precise polygon that segments the _QR_ | np.ndarray (**N**, **2**) | `[[x1, y1], [x2, y2], ...]` |
| `quad_xy` | Four corners polygon that segments the _QR_ | np.ndarray (**4**, **2**) | `[[x1, y1], ..., [x4, y4]]` |
| `padded_quad_xy` |`quad_xy` padded to fully cover `polygon_xy` | np.ndarray (**4**, **2**) | `[[x1, y1], ..., [x4, y4]]` |
| `image_shape` | Shape of the input image | tuple[`float`, `float`] | `(h, w)` |
> **NOTE:**
> - All `np.ndarray` values are of type `np.float32`
> - All keys (except `confidence` and `image_shape`) have a normalized ('n') version. For example,`bbox_xyxy` represents the bbox of the QR in image coordinates [[0., im_w], [0., im_h]], while `bbox_xyxyn` contains the same bounding box in normalized coordinates [0., 1.].
> - `bbox_xyxy[n]` and `polygon_xy[n]` are clipped to `image_shape`. You can use them for indexing without further management
## Acknowledgements
This library is based on the following projects:
- <a href="https://github.com/ultralytics/ultralytics" target="_blank">YoloV8</a> model for **Object Segmentation**.
- <a href="https://github.com/Eric-Canas/quadrilateral-fitter" target="_blank">QuadrilateralFitter</a> for fitting 4 corners polygons from noisy **segmentation outputs**.
Raw data
{
"_id": null,
"home_page": "https://github.com/Eric-Canas/qrdet",
"name": "qrdet",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Eric Canas",
"author_email": "eric@ericcanas.com",
"download_url": "https://files.pythonhosted.org/packages/73/b9/fe08068b0d8c308e6d92c6e7205b6ed3f37a59fed75b8463aaaa196e2479/qrdet-2.5.tar.gz",
"platform": null,
"description": "# QRDet\n**QRDet** is a robust **QR Detector** based on <a href=\"https://github.com/ultralytics/ultralytics\" target=\"_blank\">YOLOv8</a>.\n\n**QRDet** will detect & segment **QR** codes even in **difficult** positions or **tricky** images. If you are looking for a complete **QR Detection** + **Decoding** pipeline, take a look at <a href=\"https://github.com/Eric-Canas/qreader\" target=\"_blank\">QReader</a>. \n\n## Installation\n\nTo install **QRDet**, simply run:\n\n```bash\npip install qrdet\n```\n\n## Usage\n\nThere is only one function you'll need to call to use **QRDet**, ``detect``:\n\n```python\n\nfrom qrdet import QRDetector\nimport cv2\n\ndetector = QRDetector(model_size='s')\nimage = cv2.imread(filename='resources/qreader_test_image.jpeg')\ndetections = detector.detect(image=image, is_bgr=True)\n\n# Draw the detections\nfor detection in detections:\n x1, y1, x2, y2 = detection['bbox_xyxy']\n confidence = detection['confidence']\n segmenation_xy = detection['quadrilateral_xy']\n cv2.rectangle(image, (x1, y1), (x2, y2), color=(0, 255, 0), thickness=2)\n cv2.putText(image, f'{confidence:.2f}', (x1, y1 - 10), fontFace=cv2.FONT_HERSHEY_SIMPLEX,\n fontScale=1, color=(0, 255, 0), thickness=2)\n# Save the results\ncv2.imwrite(filename='resources/qreader_test_image_detections.jpeg', img=image)\n```\n\n<img alt=\"detections_output\" title=\"detections_output\" src=\"https://raw.githubusercontent.com/Eric-Canas/qrdet/main/resources/qreader_test_image_detections.jpeg\" width=\"100%\">\n\n## API Reference\n\n### QRDetector(model_size = 's', conf_th = 0.5, nms_iou = 0.3, weights_folder = '<qrdet_package>/.model')\n\n- ``model_size``: **\"n\"|\"s\"|\"m\"|\"l\"**. Size of the model to load. Smaller models will be faster, while larger models will be more capable for difficult situations. Default: `'s'`.\n- ``conf_th``: **float**. Confidence threshold to consider that a detection is valid. Incresing this value will reduce _false positives_ while decreasing will reduce _false_negatives_. Default: `0.5`.\n- ``nms_iou``: **float**. _Intersection over Union_ (IoU) threshold for _Non-Maximum Suppression_ (NMS). NMS is a technique used to eliminate redundant bounding boxes for the same object. Increase this number if you find problems with duplicated detections. Default: `0.3`\n- ``weights_folder``: **str**. Folder where detection model will be downloaded. By default, it points out to an internal folder within the package, making sure that it gets correctly removed when uninstalling. You could need to change it when working in environments like [AWS Lambda](https://aws.amazon.com/es/pm/lambda/) where only [/tmp folder is writable](https://docs.aws.amazon.com/lambda/latest/api/API_EphemeralStorage.html), as issued in [#11](https://github.com/Eric-Canas/qrdet/issues/11). Default: `'<qrdet_package>/.model'`.\n\n### QRDetector.detect(image, is_bgr = False, **kwargs)\n\n- ``image``: **np.ndarray|'PIL.Image'|'torch.Tensor'|str**. `np.ndarray` of shape **(H, W, 3)**, `PIL.Image`, `Tensor` of shape **(1, 3, H, W)**, or `path`/`url` to the image to predict. `'screen'` for grabbing a screenshot.\n- ``is_bgr``: **bool**. If `True` the image is expected to be in **BGR**. Otherwise, it will be expected to be **RGB**. Only used when image is `np.ndarray` or `torch.tensor`. Default: `False`\n- ``legacy``: **bool**. If sent as **kwarg**, will parse the output to make it identical to 1.x versions. Not Recommended. Default: False.\n\n- **Returns**: **tuple[dict[str, np.ndarray|float|tuple[float|int, float|int]]]**. A tuple of dictionaries containing all the information of every detection. Contains the following keys.\n\n| Key | Value Desc. | Value Type | Value Form |\n|------------------|---------------------------------------------|----------------------------|-----------------------------|\n| `confidence` | Detection confidence | `float` | `conf.` |\n| `bbox_xyxy` | Bounding box | np.ndarray (**4**) | `[x1, y1, x2, y2]` |\n| `cxcy` | Center of bounding box | tuple[`float`, `float`] | `(x, y)` |\n| `wh` | Bounding box width and height | tuple[`float`, `float`] | `(w, h)` |\n| `polygon_xy` | Precise polygon that segments the _QR_ | np.ndarray (**N**, **2**) | `[[x1, y1], [x2, y2], ...]` |\n| `quad_xy` | Four corners polygon that segments the _QR_ | np.ndarray (**4**, **2**) | `[[x1, y1], ..., [x4, y4]]` |\n| `padded_quad_xy` |`quad_xy` padded to fully cover `polygon_xy` | np.ndarray (**4**, **2**) | `[[x1, y1], ..., [x4, y4]]` |\n| `image_shape` | Shape of the input image | tuple[`float`, `float`] | `(h, w)` | \n\n> **NOTE:**\n> - All `np.ndarray` values are of type `np.float32` \n> - All keys (except `confidence` and `image_shape`) have a normalized ('n') version. For example,`bbox_xyxy` represents the bbox of the QR in image coordinates [[0., im_w], [0., im_h]], while `bbox_xyxyn` contains the same bounding box in normalized coordinates [0., 1.].\n> - `bbox_xyxy[n]` and `polygon_xy[n]` are clipped to `image_shape`. You can use them for indexing without further management\n\n## Acknowledgements\n\nThis library is based on the following projects:\n\n- <a href=\"https://github.com/ultralytics/ultralytics\" target=\"_blank\">YoloV8</a> model for **Object Segmentation**.\n- <a href=\"https://github.com/Eric-Canas/quadrilateral-fitter\" target=\"_blank\">QuadrilateralFitter</a> for fitting 4 corners polygons from noisy **segmentation outputs**.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Robust QR Detector based on YOLOv8",
"version": "2.5",
"project_urls": {
"Homepage": "https://github.com/Eric-Canas/qrdet"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bb799498c59fea1b3881cbdb87f333de33d0d7998ee2d0e0407db22621c46be2",
"md5": "4ea16b2945e1a2995130facd85257bd8",
"sha256": "35ab9f056e2709814c46795417c897275cb21ffc113a375e2f4c5a9b25931f57"
},
"downloads": -1,
"filename": "qrdet-2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4ea16b2945e1a2995130facd85257bd8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 22829,
"upload_time": "2024-06-15T07:21:18",
"upload_time_iso_8601": "2024-06-15T07:21:18.245428Z",
"url": "https://files.pythonhosted.org/packages/bb/79/9498c59fea1b3881cbdb87f333de33d0d7998ee2d0e0407db22621c46be2/qrdet-2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "73b9fe08068b0d8c308e6d92c6e7205b6ed3f37a59fed75b8463aaaa196e2479",
"md5": "6e76c6d176069a583395381f6310646c",
"sha256": "ed1742dac3f4abb50a5b75490776e7fa35dcb098d9b6be8a3dc08351e9bfdc80"
},
"downloads": -1,
"filename": "qrdet-2.5.tar.gz",
"has_sig": false,
"md5_digest": "6e76c6d176069a583395381f6310646c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14317,
"upload_time": "2024-06-15T07:21:20",
"upload_time_iso_8601": "2024-06-15T07:21:20.168368Z",
"url": "https://files.pythonhosted.org/packages/73/b9/fe08068b0d8c308e6d92c6e7205b6ed3f37a59fed75b8463aaaa196e2479/qrdet-2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-15 07:21:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Eric-Canas",
"github_project": "qrdet",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "ultralytics",
"specs": []
},
{
"name": "quadrilateral-fitter",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "tqdm",
"specs": []
}
],
"lcname": "qrdet"
}
JSON
