# PyCBD: Python Checkerboard Detection Toolbox
## About
Python checkerboard detection toolbox with Gaussian process based enhancement which can be used to expand detected
checkerboards beyond occlusions, predict corners to fill in occlusions, refine corner positions, and dewarp +
rectify the checkerboard images.
* [Source](https://github.com/InViLabUAntwerp/PyCBD)
## Requirements
* Microsoft Windows OS
* MS VCRUNTIME14_01 needs to be installed
* Python ~=3.8, ~=3.10 (3.10 recommended)
## Usage
Images should either be 2D grayscale (x, y) or 3D BGR (x, y, c) numpy arrays. It is recommended to use the `CBDPipeline`
class, which combines the detector and enhancer. While it is not necessary to provide the checkerboard dimensions (the
amount of inner corners), providing them will allow the detector to determine whether the checkerboard got detected in
its entirety or only partially, and whether the object space coordinates are "absolute" or only "relative" to what got
detected in the image. A simple checkerboard detection is performed as follows:
```
from PyCBD.pipelines import CBDPipeline
detector = CBDPipeline()
result, board_uv, board_xy = detection_pipeline.detect_checkerboard(image)
```
The enhancer that handles board expansion and prediction is not used by default and is activated by passing additional
arguments to the pipeline constructor. When using board expansion, it is recommended to provide the checkerboard
dimensions because it is used to stops/skip expansion when the entire board has been found. In order for the enhancer
to work properly, the detected corners must have the correct coordinates, otherwise all results achieved with the
enhancer will be wrong. The enhancer is activated as follows:
```
from PyCBD.pipelines import CBDPipeline
detector = CBDPipeline(expand=True, predict=True)
result, board_uv, board_xy = detection_pipeline.detect_checkerboard(image, (n_rows, n_cols))
```
It is also possible to use another detector in combination with the pipeline. The requirements are that this detector
is contained within a class that has a `detect_checkerboard` method that accepts the same inputs and provides the
same outputs as our `CheckerboardDetector` class. A class instance of the detector can then be passed to the
`CBDPipeline` constructor:
```
from PyCBD.pipelines import CBDPipeline
import YourCustomDetector
detector = CBDPipeline(YourCustomDetector())
result, board_uv, board_xy = detection_pipeline.detect_checkerboard(image)
```
Instead of using the pipeline users can also use the separate `CheckerboardDetector` for detection:
```
from PyCBD.checkerboard_detection.checkerboard_detector import CheckerboardDetector
from PyCBD.pipelines import prepare_image
prepared_image = prepare_image(image)
checkerboard_detector = CheckerboardDetector()
detected_board_uv, detected_board_xy, detected_corners_uv = checkerboard_detector.detect_checkerboard(prepared_image)
```
and the `CheckerboardEnhancer` for expanding the board and predicting corners:
```
from PyCBD.checkerboard_enhancement.checkerboard_enhancer import CheckerboardEnhancer
checkerboard_enhancer = CheckerboardEnhancer()
expanded_board_uv, expanded_board_xy = checkerboard_enhancer.fit_and_expand_board(image,
detected_board_uv,
detected_board_xy,
detected_corners_uv)
predicted_board_uv, predicted_board_xy = checkerboard_enhancer.fit_and_predict_board(image,
expanded_board_uv,
expanded_board_xy)
```
Finally, the enhancer can be used to remove warping and perspective error from the image after the checkerboard has been
detected. Both `CBDPipeline` and `CheckerboardEnhancer` have a `dewarp_image` method for this purpose:
```
dewarped = pipeline_or_enhancer.dewarp_image(image, board_uv, board_xy)
```
In case the detection fails, or you get a weird outcome, you can set certain flags on the different classes to show
intermediate results and diagnose the problem, and configure the package logger, so you get additional info prints
during execution. If there are problems at the enhancer level, it is possible they can be resolved by adjusting the
parameters. Please refer to the documentation for additional in-depth information.
## Citation
@Article{math11224568,
AUTHOR = {Hillen, Michaël and De Boi, Ivan and De Kerf, Thomas and Sels, Seppe and Cardenas De La Hoz, Edgar and Gladines, Jona and Steenackers, Gunther and Penne, Rudi and Vanlanduit, Steve},
TITLE = {Enhanced Checkerboard Detection Using Gaussian Processes},
JOURNAL = {Mathematics},
VOLUME = {11},
YEAR = {2023},
NUMBER = {22},
ARTICLE-NUMBER = {4568},
URL = {https://www.mdpi.com/2227-7390/11/22/4568},
ISSN = {2227-7390},
DOI = {10.3390/math11224568}
}
## License
Distributed under the GNU General Public License v3.0. Check the `LICENCE` files for more info.
## Contact
InViLab - [invilab@uantwerpen.be](mailto:invilab@uantwerpen.be) - [website](https://www.invilab.be/) -
[LinkedIn](https://www.linkedin.com/company/invilab-uantwerp)
## Acknowledgements
The checkerboard detector in this toolbox is a modified version of the C++ implementation of libcbdetect
[[1]](#ref1)[[2]](#ref2). For the Gaussian processes we use the GPy library [[3]](#ref3)
## References
<a id="ref1">[1]</a>
Geiger, A., Moosmann, F., Car, Ö., & Schuster, B. (2012, May). Automatic camera and range sensor calibration using a
single shot. In Robotics and Automation (ICRA), 2012 IEEE International Conference on (pp. 3936-3943). IEEE.
<a id="ref2">[2]</a>
ftdlyc (March 13 2020). Unofficial implemention of libcbdetect in C++. [https://github.com/ftdlyc/libcbdetect](https://github.com/ftdlyc/libcbdetect)
<a id="ref3">[3]</a>
GPy (since 2012). GPy: A Gaussian process framework in python. [http://github.com/SheffieldML/GPy](http://github.com/SheffieldML/GPy)
Raw data
{
"_id": null,
"home_page": "",
"name": "PyCBD",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.10,~=3.8",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "Micha\u00ebl Hillen <michael.hillen@uantwerpen.be>, Ivan De Boi <ivan.deboi@uantwerpen.be>, Edgar Cardenas <edgar.cardenas@uantwerpen.be>, Thomas De Kerf <thomas.dekerf@uantwerpen.be>, Seppe Sels <seppe.sels@uantwerpen.be>, Jona Gladines <jona.gladines@uantwerpen.be>, Rudi Penne <rudi.penne@uantwerpen.be>, Steve Vanlanduit <steve.vanlanduit@uantwerpen.be>, Gunther Steenackers <gunther.steenackers@uantwerpen.be>",
"download_url": "https://files.pythonhosted.org/packages/f3/80/cf10d297aeeba223f1ce9e48940263992412c9843b42079bb5bda9a6eb6f/PyCBD-1.2.3.tar.gz",
"platform": null,
"description": "# PyCBD: Python Checkerboard Detection Toolbox\r\n\r\n## About\r\n\r\nPython checkerboard detection toolbox with Gaussian process based enhancement which can be used to expand detected \r\ncheckerboards beyond occlusions, predict corners to fill in occlusions, refine corner positions, and dewarp + \r\nrectify the checkerboard images.\r\n\r\n* [Source](https://github.com/InViLabUAntwerp/PyCBD)\r\n\r\n## Requirements\r\n\r\n* Microsoft Windows OS\r\n* MS VCRUNTIME14_01 needs to be installed\r\n* Python ~=3.8, ~=3.10 (3.10 recommended)\r\n\r\n## Usage\r\n\r\nImages should either be 2D grayscale (x, y) or 3D BGR (x, y, c) numpy arrays. It is recommended to use the `CBDPipeline` \r\nclass, which combines the detector and enhancer. While it is not necessary to provide the checkerboard dimensions (the \r\namount of inner corners), providing them will allow the detector to determine whether the checkerboard got detected in \r\nits entirety or only partially, and whether the object space coordinates are \"absolute\" or only \"relative\" to what got \r\ndetected in the image. A simple checkerboard detection is performed as follows:\r\n\r\n```\r\nfrom PyCBD.pipelines import CBDPipeline\r\n\r\ndetector = CBDPipeline()\r\nresult, board_uv, board_xy = detection_pipeline.detect_checkerboard(image)\r\n```\r\n\r\nThe enhancer that handles board expansion and prediction is not used by default and is activated by passing additional\r\narguments to the pipeline constructor. When using board expansion, it is recommended to provide the checkerboard\r\ndimensions because it is used to stops/skip expansion when the entire board has been found. In order for the enhancer\r\nto work properly, the detected corners must have the correct coordinates, otherwise all results achieved with the\r\nenhancer will be wrong. The enhancer is activated as follows:\r\n\r\n```\r\nfrom PyCBD.pipelines import CBDPipeline\r\n\r\ndetector = CBDPipeline(expand=True, predict=True)\r\nresult, board_uv, board_xy = detection_pipeline.detect_checkerboard(image, (n_rows, n_cols))\r\n```\r\n\r\nIt is also possible to use another detector in combination with the pipeline. The requirements are that this detector \r\nis contained within a class that has a `detect_checkerboard` method that accepts the same inputs and provides the \r\nsame outputs as our `CheckerboardDetector` class. A class instance of the detector can then be passed to the \r\n`CBDPipeline` constructor:\r\n\r\n```\r\nfrom PyCBD.pipelines import CBDPipeline\r\nimport YourCustomDetector\r\n\r\ndetector = CBDPipeline(YourCustomDetector())\r\nresult, board_uv, board_xy = detection_pipeline.detect_checkerboard(image)\r\n```\r\n\r\nInstead of using the pipeline users can also use the separate `CheckerboardDetector` for detection:\r\n\r\n```\r\nfrom PyCBD.checkerboard_detection.checkerboard_detector import CheckerboardDetector\r\nfrom PyCBD.pipelines import prepare_image\r\n\r\n\r\nprepared_image = prepare_image(image)\r\ncheckerboard_detector = CheckerboardDetector()\r\ndetected_board_uv, detected_board_xy, detected_corners_uv = checkerboard_detector.detect_checkerboard(prepared_image)\r\n```\r\n\r\nand the `CheckerboardEnhancer` for expanding the board and predicting corners:\r\n\r\n```\r\nfrom PyCBD.checkerboard_enhancement.checkerboard_enhancer import CheckerboardEnhancer\r\n\r\ncheckerboard_enhancer = CheckerboardEnhancer()\r\nexpanded_board_uv, expanded_board_xy = checkerboard_enhancer.fit_and_expand_board(image,\r\n detected_board_uv,\r\n detected_board_xy,\r\n detected_corners_uv)\r\npredicted_board_uv, predicted_board_xy = checkerboard_enhancer.fit_and_predict_board(image, \r\n expanded_board_uv,\r\n expanded_board_xy)\r\n```\r\n\r\nFinally, the enhancer can be used to remove warping and perspective error from the image after the checkerboard has been\r\ndetected. Both `CBDPipeline` and `CheckerboardEnhancer` have a `dewarp_image` method for this purpose:\r\n\r\n```\r\ndewarped = pipeline_or_enhancer.dewarp_image(image, board_uv, board_xy)\r\n```\r\n\r\nIn case the detection fails, or you get a weird outcome, you can set certain flags on the different classes to show \r\nintermediate results and diagnose the problem, and configure the package logger, so you get additional info prints \r\nduring execution. If there are problems at the enhancer level, it is possible they can be resolved by adjusting the \r\nparameters. Please refer to the documentation for additional in-depth information.\r\n\r\n## Citation\r\n\r\n @Article{math11224568,\r\n AUTHOR = {Hillen, Micha\u00ebl and De Boi, Ivan and De Kerf, Thomas and Sels, Seppe and Cardenas De La Hoz, Edgar and Gladines, Jona and Steenackers, Gunther and Penne, Rudi and Vanlanduit, Steve},\r\n TITLE = {Enhanced Checkerboard Detection Using Gaussian Processes},\r\n JOURNAL = {Mathematics},\r\n VOLUME = {11},\r\n YEAR = {2023},\r\n NUMBER = {22},\r\n ARTICLE-NUMBER = {4568},\r\n URL = {https://www.mdpi.com/2227-7390/11/22/4568},\r\n ISSN = {2227-7390},\r\n DOI = {10.3390/math11224568}\r\n }\r\n\r\n## License\r\n\r\nDistributed under the GNU General Public License v3.0. Check the `LICENCE` files for more info.\r\n\r\n## Contact\r\n\r\nInViLab - [invilab@uantwerpen.be](mailto:invilab@uantwerpen.be) - [website](https://www.invilab.be/) - \r\n[LinkedIn](https://www.linkedin.com/company/invilab-uantwerp)\r\n\r\n## Acknowledgements\r\n\r\nThe checkerboard detector in this toolbox is a modified version of the C++ implementation of libcbdetect \r\n[[1]](#ref1)[[2]](#ref2). For the Gaussian processes we use the GPy library [[3]](#ref3)\r\n\r\n## References\r\n\r\n<a id=\"ref1\">[1]</a> \r\nGeiger, A., Moosmann, F., Car, \u00d6., & Schuster, B. (2012, May). Automatic camera and range sensor calibration using a \r\nsingle shot. In Robotics and Automation (ICRA), 2012 IEEE International Conference on (pp. 3936-3943). IEEE.\r\n\r\n<a id=\"ref2\">[2]</a> \r\nftdlyc (March 13 2020). Unofficial implemention of libcbdetect in C++. [https://github.com/ftdlyc/libcbdetect](https://github.com/ftdlyc/libcbdetect)\r\n\r\n<a id=\"ref3\">[3]</a> \r\nGPy (since 2012). GPy: A Gaussian process framework in python. [http://github.com/SheffieldML/GPy](http://github.com/SheffieldML/GPy)\r\n",
"bugtrack_url": null,
"license": "",
"summary": "PyCBD: Python checkerboard detection toolbox",
"version": "1.2.3",
"project_urls": {
"Source": "https://github.com/InViLabUAntwerp/PyCBD"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "be2372d715d26c96c0ea21889cd3ce3b97c5d9e0676b84cc35dacc443b4d9f95",
"md5": "abf087a392ad197d19c0f3480c697dca",
"sha256": "4c580b1d3641c765e04d262b2b2dc2dbf8aff23ba3ba4b73a13d5de42efcb1c9"
},
"downloads": -1,
"filename": "PyCBD-1.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "abf087a392ad197d19c0f3480c697dca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.10,~=3.8",
"size": 29309855,
"upload_time": "2024-01-17T01:39:03",
"upload_time_iso_8601": "2024-01-17T01:39:03.939394Z",
"url": "https://files.pythonhosted.org/packages/be/23/72d715d26c96c0ea21889cd3ce3b97c5d9e0676b84cc35dacc443b4d9f95/PyCBD-1.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f380cf10d297aeeba223f1ce9e48940263992412c9843b42079bb5bda9a6eb6f",
"md5": "816333ccb876a595cf70a67662c89aec",
"sha256": "400f5829b8d65a7fc5c1e2b59c779d5004fe3b3212e8c6526b8346c400b9b78a"
},
"downloads": -1,
"filename": "PyCBD-1.2.3.tar.gz",
"has_sig": false,
"md5_digest": "816333ccb876a595cf70a67662c89aec",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.10,~=3.8",
"size": 29180223,
"upload_time": "2024-01-17T01:39:28",
"upload_time_iso_8601": "2024-01-17T01:39:28.668975Z",
"url": "https://files.pythonhosted.org/packages/f3/80/cf10d297aeeba223f1ce9e48940263992412c9843b42079bb5bda9a6eb6f/PyCBD-1.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-17 01:39:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "InViLabUAntwerp",
"github_project": "PyCBD",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.20.0"
],
[
"<=",
"1.23.5"
]
]
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "scikit-learn",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "opencv-python",
"specs": []
},
{
"name": "gpy",
"specs": []
},
{
"name": "Pillow",
"specs": []
},
{
"name": "h5py",
"specs": []
},
{
"name": "albumentations",
"specs": []
},
{
"name": "opencv-python",
"specs": []
}
],
"lcname": "pycbd"
}
JSON
