Discorpy’s documentation

Discorpy is an open-source Python package implementing methods for calibrating and correcting distortion in lens-based imaging systems [C1] [C2]. Unlike existing approaches that require multiple calibration images or iterative optimization, Discorpy and its algorithms can independently characterize both radial and perspective distortion with high accuracy across a wide range of distortion strengths - using only a single calibration image and direct computation. This makes the software a practical tool for a wide range of imaging applications.

To support different experimental conditions and enable fully automated workflows, Discorpy offers flexibility in calibration patterns, including dot-pattern, line-pattern, and chessboard images. It also provides robust preprocessing methods for extracting reference points, handling image artifacts, and grouping points into lines. Discorpy has been successfully applied to calibrate detectors in X-ray tomography systems, where sub-pixel accuracy is critical, as well as to correct fisheye distortion in large-field-of-view cameras.

Showcases: https://discorpy.readthedocs.io/en/latest/usage.html#demonstrations

Source code: https://github.com/DiamondLightSource/discorpy

Examples: https://github.com/DiamondLightSource/discorpy/tree/master/examples

Author: Nghia T. Vo - NSLS-II, Brookhaven National Laboratory, US; Diamond Light Source, UK.

Keywords: Camera calibration, radial lens distortion, perspective distortion, distortion correction, fisheye distortion, distortion center determination, tomography.

Contents

• 1. Installation
  • 1.1. Using conda
  • 1.2. Using pip
  • 1.3. Installing from source
  • 1.4. Using Google Colab
• 2. Tutorials
  • 2.1. Causes of distortion
  • 2.2. Methods for correcting distortions
    • 2.2.1. Introduction
    • 2.2.2. Extracting reference-points from a calibration image
    • 2.2.3. Grouping reference-points into horizontal lines and vertical lines
    • 2.2.4. Calculating the optical center of radial distortion
    • 2.2.5. Correcting perspective effect
    • 2.2.6. Calculating coefficients of a correction model for perspective distortion
    • 2.2.7. Calculating coefficients of a polynomial model for radial-distortion correction
    • 2.2.8. Correcting a distorted image
    • 2.2.9. Summary
• 3. Usage
  • 3.1. Resources
  • 3.2. Notes related to Python programming
  • 3.3. Demonstrations
    • 3.3.1. Process a high-quality calibration image
    • 3.3.2. Process an X-ray target image having perspective effect
    • 3.3.3. Process a challenging X-ray target image
    • 3.3.4. Process a line-pattern image
    • 3.3.5. Correct both radial distortion and perspective distortion
    • 3.3.6. Calibrate a camera using a chessboard image
    • 3.3.7. Correct perspective distortion
    • 3.3.8. Correct radial distortion of an image without using a calibration target
    • 3.3.9. Useful tips
• 4. Technical notes
  • 4.1. Distortion calibration and correction for fisheye cameras
    • 4.1.1. Introduction
    • 4.1.2. Acquiring calibration image
    • 4.1.3. Preprocessing steps
    • 4.1.4. Processing steps
    • 4.1.5. Correction results
    • 4.1.6. Using other types of calibration images
  • 4.2. Distortion correction for X-ray Tomography
• 5. API reference
  • 5.1. Input-output
    • 5.1.1. discorpy.losa.loadersaver
  • 5.2. Pre-processing
    • 5.2.1. discorpy.prep.preprocessing
    • 5.2.2. discorpy.prep.linepattern
  • 5.3. Processing
    • 5.3.1. discorpy.proc.processing
  • 5.4. Post-processing
    • 5.4.1. discorpy.post.postprocessing
  • 5.5. Utility methods
    • 5.5.1. discorpy.util.utility
• 6. Update notes
• 7. Credit