nghia-vo / vounwarp

Distortion correction with high-accuracy for lens-based detector systems

Vounwarp

Distortion calibration and correction software for lens-based detector systems

Vounwarp is an open-source Python package for radial distortion correction with sub-pixel accuracy as required by tomography detector systems. It calculates parameters of a polynomial model of radial lens distortion, which are the center of distortion and the polynomial coefficients, using a grid pattern image. The package implements methods published, Nghia T. Vo et al. "Radial lens distortion correction with sub-pixel accuracy for X-ray micro- tomography" Optics Express 23, 32859-32868 (2015), https://doi.org/10.1364/OE.23.032859.

Important notice

Vounwarp was changed to Discorpy and maintained at: https://github.com/DiamondLightSource/discorpy The latest version, Discorpy 1.4, includes methods for correcting perspective distortion and methods for processing line-pattern images and chessboard images.

Documentation: https://discorpy.readthedocs.io/en/latest/

To install from conda-forge channel:

$ conda install -c conda-forge discorpy

Features

• Pre-processing methods for finding coordinates of dot-centroids, grouping them into lines, removing non-dot objects or misplaced dots.
• Procesing methods for calculating distortion parameters; which are the center of distortion and polynomial coefficients; of a backward model, a forward model, and a backward-from-forward model.
• Post-processing methods for: unwarping lines of points, images, or slices of a 3D dataset; evaluating the accuracy of correction results.
• Some methods may be useful for other applications:
  • Correct non-uniform background using a FFT-based filter and a median filter.
  • Select binary objects in a certain range of values.
  • Unwarp slices of a 3D dataset.

Install

• vounwarp is available on the conda-forge channel. To install:
  • Install Miniconda (just to run conda) or Anaconda (conda + loads of python packages).
  • Open a command prompt/terminal and run the following command:

    $ conda install -c conda-forge vounwarp
    

• To install from the source codes:
  • Download the source codes from this github page (click-> Code -> Download ZIP). Unzip to a local folder.
  • Install Miniconda.
  • Open command prompt, navigate to the source folder, run the following commands:

    $ conda create -n vounwarp
    $ conda activate vounwarp
    $ conda install python
    $ python setup.py install
    

  • Set the python interpreter-path (of your IDE) to ../Anaconda3/envs/vounwarp

How to use

• A document explaining step-by-step how to calculate distortion coefficients from a dot pattern image is in the "/doc" folder or can be downloaded from: https://zenodo.org/record/1322720
• Examples of how to use the package are in the "/examples" folder.
• Coefficients determined by the package can be used by other tomographic software such as Tomopy or Savu for correction.

Demonstrations

• Apply to a visible dot-target collected at Beamline I12, Diamond Light Source, UK:

• Apply to an X-ray dot-target collected at Beamline I13, Diamond Light Source, UK:

• Apply to a hazard camera of the Mars Perseverance Rover. Details of how to estimate distortion coefficients of that camera without using a calibration target are shown here