# Discorpy
(**Dis**)tortion (**Cor**)rection (**Py**)thon-package
*Camera calibration and distortion correction software for lens-based detector systems*
[](https://pepy.tech/project/discorpy)
[](https://anaconda.org/conda-forge/vounwarp)
[](https://anaconda.org/conda-forge/discorpy)
[](https://discorpy.readthedocs.io/en/latest/?badge=latest)
[](https://anaconda.org/conda-forge/discorpy)
[](https://anaconda.org/conda-forge/discorpy)
**Discorpy** is an open-source Python package designed for camera calibration and distortion
correction with sub-pixel accuracy. It calculates parameters of correction models
using a grid pattern image. Primarily, the package implements methods published in
[Optics Express](https://doi.org/10.1364/OE.23.032859) and offers a comprehensive
pipeline for data processing. Starting from version 1.4, the package also includes
perspective distortion correction capabilities.
**Author and maintainer:** Nghia Vo, *NSLS-II, Brookhaven National Laboratory, US; Diamond Light Source, UK.*
Features
========
- The [polynomial model](https://discorpy.readthedocs.io/en/latest/tutorials/methods.html#calculating-coefficients-of-a-polynomial-model-for-radial-distortion-correction)
used by the package is versatile enough to calibrate images with varying levels of
radial distortion. This practical feature eliminates the need for users to switch
between different models based on the degree of distortion in the images.
- Discorpy offers a unique feature where [radial distortion, the center of distortion, and perspective distortion](https://discorpy.readthedocs.io/en/latest/tutorials/methods.html)
can be independently determined and corrected using a single calibration image.
- The software provides a full pipeline of data processing including:
+ [Pre-processing methods](https://discorpy.readthedocs.io/en/latest/api.html#pre-processing)
for: extracting reference-points from a dot-pattern image, line-pattern image,
and chessboard (checkerboard) image; grouping these points line-by-line.
+ [Processing methods](https://discorpy.readthedocs.io/en/latest/api.html#processing) for calculating
the optical center, coefficients of polynomial models for correcting radial distortion, and parameters
of a model for correcting perspective distortion.
+ [Post-processing methods](https://discorpy.readthedocs.io/en/latest/api.html#post-processing) for:
unwarping lines of points, images, or slices of a 3D dataset; and evaluating the accuracy of the correction results.
+ Some methods may be useful for other applications:
* [Correct non-uniform background](https://discorpy.readthedocs.io/en/latest/api/discorpy.prep.preprocessing.html#discorpy.prep.preprocessing.normalization_fft) of an image.
* Select [binary objects](https://discorpy.readthedocs.io/en/latest/api/discorpy.prep.preprocessing.html#discorpy.prep.preprocessing.select_dots_based_distance) in a certain range of values.
* Unwarp slices of a [3D dataset](https://discorpy.readthedocs.io/en/latest/api/discorpy.post.postprocessing.html#discorpy.post.postprocessing.unwarp_slice_backward).
Installation
============
- https://discorpy.readthedocs.io/en/latest/install.html
Documentation
=============
- https://discorpy.readthedocs.io/en/latest/
Usage
=====
- To achieve high-accuracy results, the quality of the calibration image is crucial.
An ideal calibration image should contain [numerous reference points](https://discorpy.readthedocs.io/en/latest/tutorials/methods.html#extracting-reference-points-from-a-calibration-image)
extracted from [dot-patterns, line-patterns](https://github.com/DiamondLightSource/discorpy/tree/master/data),
or [checkerboard images](https://github.com/DiamondLightSource/discorpy/tree/master/data/laptop_camera), covering most of
the camera's field of view and minimizing perspective distortion.
- https://discorpy.readthedocs.io/en/latest/usage.html
Demonstrations
==============
- Detailed step-by-step demonstrations featuring codes and explanations of how to use Discorpy for various types of calibration images
are shown [here](https://discorpy.readthedocs.io/en/latest/usage.html#demonstrations).
- Apply to a visible dot-target collected at [Beamline I12](https://www.diamond.ac.uk/Instruments/Imaging-and-Microscopy/I12/Detectors-at-I12.html),
Diamond Light Source, UK:
- Apply to an X-ray dot-target collected at [Beamline I13](https://www.diamond.ac.uk/Instruments/Imaging-and-Microscopy/I13/Diamond-Manchester_Imaging_Branchline/Facilities_and_equipment_Imaging.html),
Diamond Light Source, UK:
- Improvement of tomographic reconstructed images after distortion correction:
+ For a detector with strong radial distortion:
+ For a detector with small radial distortion:
- Calibrate a commercial camera with capabilities of correcting [radial distortion and perspective distortion](https://discorpy.readthedocs.io/en/latest/usage/demo_05.html)
independently.
- Calibrate a laptop [webcam](https://discorpy.readthedocs.io/en/latest/usage/demo_06.html) using a checkboard image.
- Apply to a hazard camera of the [Mars Perseverance Rover](https://mars.nasa.gov/mars2020/multimedia/raw-images/).
Details of how to estimate distortion coefficients of that camera without using
a calibration target are shown [here](https://discorpy.readthedocs.io/en/latest/usage/demo_08.html).
- Correct [perspective distortion](https://discorpy.readthedocs.io/en/latest/usage/demo_07.html):
Raw data
{
"_id": null,
"home_page": "https://github.com/DiamondLightSource/discorpy",
"name": "discorpy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "Distortion correction,Tomography,Radial lens distortion,Camera calibration,Perspective distortion",
"author": "Nghia Vo",
"author_email": "nvo@bnl.gov",
"download_url": "https://files.pythonhosted.org/packages/d4/e7/f985b837efd1b9b728c1180a39ac12d539b3568746b2a590d00f9d741d5f/discorpy-1.6.0.tar.gz",
"platform": "Any",
"description": "# Discorpy\r\n(**Dis**)tortion (**Cor**)rection (**Py**)thon-package\r\n\r\n*Camera calibration and distortion correction software for lens-based detector systems*\r\n\r\n \r\n[](https://pepy.tech/project/discorpy) \r\n[](https://anaconda.org/conda-forge/vounwarp) \r\n[](https://anaconda.org/conda-forge/discorpy) \r\n[](https://discorpy.readthedocs.io/en/latest/?badge=latest) \r\n[](https://anaconda.org/conda-forge/discorpy) \r\n \r\n[](https://anaconda.org/conda-forge/discorpy)\r\n\r\n\r\n\r\n**Discorpy** is an open-source Python package designed for camera calibration and distortion \r\ncorrection with sub-pixel accuracy. It calculates parameters of correction models \r\nusing a grid pattern image. Primarily, the package implements methods published in \r\n[Optics Express](https://doi.org/10.1364/OE.23.032859) and offers a comprehensive \r\npipeline for data processing. Starting from version 1.4, the package also includes \r\nperspective distortion correction capabilities. \r\n\r\n**Author and maintainer:** Nghia Vo, *NSLS-II, Brookhaven National Laboratory, US; Diamond Light Source, UK.*\r\n\r\nFeatures\r\n========\r\n- The [polynomial model](https://discorpy.readthedocs.io/en/latest/tutorials/methods.html#calculating-coefficients-of-a-polynomial-model-for-radial-distortion-correction) \r\n used by the package is versatile enough to calibrate images with varying levels of \r\n radial distortion. This practical feature eliminates the need for users to switch \r\n between different models based on the degree of distortion in the images.\r\n- Discorpy offers a unique feature where [radial distortion, the center of distortion, and perspective distortion](https://discorpy.readthedocs.io/en/latest/tutorials/methods.html)\r\n can be independently determined and corrected using a single calibration image.\r\n- The software provides a full pipeline of data processing including:\r\n + [Pre-processing methods](https://discorpy.readthedocs.io/en/latest/api.html#pre-processing) \r\n for: extracting reference-points from a dot-pattern image, line-pattern image, \r\n and chessboard (checkerboard) image; grouping these points line-by-line.\r\n + [Processing methods](https://discorpy.readthedocs.io/en/latest/api.html#processing) for calculating \r\n the optical center, coefficients of polynomial models for correcting radial distortion, and parameters \r\n of a model for correcting perspective distortion.\r\n + [Post-processing methods](https://discorpy.readthedocs.io/en/latest/api.html#post-processing) for: \r\n unwarping lines of points, images, or slices of a 3D dataset; and evaluating the accuracy of the correction results.\r\n + Some methods may be useful for other applications:\r\n * [Correct non-uniform background](https://discorpy.readthedocs.io/en/latest/api/discorpy.prep.preprocessing.html#discorpy.prep.preprocessing.normalization_fft) of an image.\r\n * Select [binary objects](https://discorpy.readthedocs.io/en/latest/api/discorpy.prep.preprocessing.html#discorpy.prep.preprocessing.select_dots_based_distance) in a certain range of values.\r\n * Unwarp slices of a [3D dataset](https://discorpy.readthedocs.io/en/latest/api/discorpy.post.postprocessing.html#discorpy.post.postprocessing.unwarp_slice_backward).\r\n\r\nInstallation\r\n============\r\n\r\n- https://discorpy.readthedocs.io/en/latest/install.html\r\n\r\nDocumentation\r\n=============\r\n\r\n- https://discorpy.readthedocs.io/en/latest/\r\n\r\nUsage\r\n=====\r\n\r\n- To achieve high-accuracy results, the quality of the calibration image is crucial. \r\n An ideal calibration image should contain [numerous reference points](https://discorpy.readthedocs.io/en/latest/tutorials/methods.html#extracting-reference-points-from-a-calibration-image) \r\n extracted from [dot-patterns, line-patterns](https://github.com/DiamondLightSource/discorpy/tree/master/data), \r\n or [checkerboard images](https://github.com/DiamondLightSource/discorpy/tree/master/data/laptop_camera), covering most of \r\n the camera's field of view and minimizing perspective distortion.\r\n- https://discorpy.readthedocs.io/en/latest/usage.html\r\n\r\nDemonstrations\r\n==============\r\n\r\n- Detailed step-by-step demonstrations featuring codes and explanations of how to use Discorpy for various types of calibration images\r\n are shown [here](https://discorpy.readthedocs.io/en/latest/usage.html#demonstrations). \r\n\r\n- Apply to a visible dot-target collected at [Beamline I12](https://www.diamond.ac.uk/Instruments/Imaging-and-Microscopy/I12/Detectors-at-I12.html),\r\n Diamond Light Source, UK:\r\n\r\n \r\n\r\n \r\n\r\n- Apply to an X-ray dot-target collected at [Beamline I13](https://www.diamond.ac.uk/Instruments/Imaging-and-Microscopy/I13/Diamond-Manchester_Imaging_Branchline/Facilities_and_equipment_Imaging.html),\r\n Diamond Light Source, UK:\r\n\r\n \r\n\r\n \r\n\r\n- Improvement of tomographic reconstructed images after distortion correction:\r\n + For a detector with strong radial distortion:\r\n \r\n \r\n \r\n + For a detector with small radial distortion:\r\n \r\n \r\n\r\n- Calibrate a commercial camera with capabilities of correcting [radial distortion and perspective distortion](https://discorpy.readthedocs.io/en/latest/usage/demo_05.html)\r\n independently.\r\n\r\n \r\n\r\n- Calibrate a laptop [webcam](https://discorpy.readthedocs.io/en/latest/usage/demo_06.html) using a checkboard image.\r\n \r\n \r\n\r\n \r\n\r\n- Apply to a hazard camera of the [Mars Perseverance Rover](https://mars.nasa.gov/mars2020/multimedia/raw-images/).\r\n Details of how to estimate distortion coefficients of that camera without using\r\n a calibration target are shown [here](https://discorpy.readthedocs.io/en/latest/usage/demo_08.html). \r\n\r\n \r\n\r\n \r\n\r\n- Correct [perspective distortion](https://discorpy.readthedocs.io/en/latest/usage/demo_07.html):\r\n\r\n \r\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Correction for radial distortion and perspective distortion in Python",
"version": "1.6.0",
"project_urls": {
"Download": "https://github.com/DiamondLightSource/discorpy.git",
"Homepage": "https://github.com/DiamondLightSource/discorpy"
},
"split_keywords": [
"distortion correction",
"tomography",
"radial lens distortion",
"camera calibration",
"perspective distortion"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "88487ab58829a4fc9b6509c8380cb2a30f149b7ae84796368baaa8eea7c78317",
"md5": "b5fa68f381479078e4ffc3f27ea454a1",
"sha256": "9532b2f32c10e98821bc7a009997291a01f32dc2576ac9b1c3c19be7d019a12b"
},
"downloads": -1,
"filename": "discorpy-1.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b5fa68f381479078e4ffc3f27ea454a1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 39901,
"upload_time": "2023-11-21T03:15:45",
"upload_time_iso_8601": "2023-11-21T03:15:45.948550Z",
"url": "https://files.pythonhosted.org/packages/88/48/7ab58829a4fc9b6509c8380cb2a30f149b7ae84796368baaa8eea7c78317/discorpy-1.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d4e7f985b837efd1b9b728c1180a39ac12d539b3568746b2a590d00f9d741d5f",
"md5": "b7c8ca26b0db9611388cd72bad033c76",
"sha256": "0ee2b8e7f04efbdc214fd7954bc5aa36cd3b69cc9412473b8b66a5003f46a8e6"
},
"downloads": -1,
"filename": "discorpy-1.6.0.tar.gz",
"has_sig": false,
"md5_digest": "b7c8ca26b0db9611388cd72bad033c76",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 46042,
"upload_time": "2023-11-21T03:15:48",
"upload_time_iso_8601": "2023-11-21T03:15:48.218764Z",
"url": "https://files.pythonhosted.org/packages/d4/e7/f985b837efd1b9b728c1180a39ac12d539b3568746b2a590d00f9d741d5f/discorpy-1.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-21 03:15:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DiamondLightSource",
"github_project": "discorpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "discorpy"
}
JSON
