Fred's ImageMagick Scripts



    Licensing:

    Copyright © Fred Weinhaus

    My scripts are available free of charge for non-commercial (non-profit) use, ONLY.

    For use of my scripts in commercial (for-profit) environments or non-free applications, please contact me (Fred Weinhaus) for licensing arrangements. My email address is fmw at alink dot net.

    If you: 1) redistribute, 2) incorporate any of these scripts into other free applications or 3) reprogram them in another scripting language, then you must contact me for permission, especially if the result might be used in a commercial or for-profit environment.

    Usage, whether stated or not in the script, is restricted to the above licensing arrangements. It is also subject, in a subordinate manner, to the ImageMagick license, which can be found at: http://www.imagemagick.org/script/license.php

    Please read the Pointers For Use on my home page to properly install and customize my scripts.

PINBARREL


Corrects or applies pincushion and/or barrel lens distortion to an image.

Download Script

last modified: February 04, 2019



USAGE: pinbarrel "ax,bx,cx,dx,ex ay,by,cy,dy,ey" [-c coords] [-m mode] [-v vp] infile outfile
USAGE: pinbarrel [-h or -help]

ax,bx,cx,dx,ex ...... radial coefficients for x dimension;
..................... mode=normal r*(ax+bx*r+cx*r^2+dx*r^3+ex*r^4);
..................... mode=inverse r/(ax+bx*r+cx*r^2+dx*r^3+ex*r^4);
..................... ax=1,bx=0,c=0x,dx=0,ex=0 (means no change);
..................... ax,bx,cx,dx,ex are floating point values;
ay,by,cy,dy,ey ...... radial coefficients for y dimension;
..................... mode=normal r*(ay+by*r+cy*r^2+dy*r^3+ey*r^4);
..................... mode=inverse r/(ay+by*r+cy*r^2+dy*r^3+ey*r^4);
..................... ay=1,by=0,c=0y,dy=0,ey=0 (means no change);
..................... ay,by,cy,dy,ex are floating point values
-c .... coords ...... x,y center point coordinates;
..................... positive or negative floating point values;
..................... default is center of image
-m .... mode ........ normal or inverse; controls whether to use the
..................... normal polynomial coefficient term or its inverse;
..................... default=normal
-v .... vp .......... vp is the virtual-pixel method; default=black

Note: if only one set of values are provided, then they will be used for
both dimensions. Enclose the set of coefficients in double quotes and
separate the two sets with a space.

PURPOSE: To correct or apply pincushion or barrel lens distortion.

DESCRIPTION: PINBARREL is designed to correct or apply pincushion or barrel lens distortion. The script makes use of -fx and therefore will be rather slow.

ARGUMENTS:

ax,bx,cx,dx,ex ... These are the radial distortion/correction coefficients for the X dimension equation of: R=r*(a + b*r + c*r^2 + d*r^3 + e*r^4) for normal mode and R=r/(a + b*r + c*r^2 + d*r^3 + e*r^4) for inverse mode, where R is the radius from the center of the infile and r is the radius from the center of the outfile.

ay,by,cy,dy,ey ... These are the radial distortion/correction coefficients for the y dimension equation of: R=r*(a + b*r + c*r^2 + d*r^3 + e*r^4) for normal mode and R=r/(a + b*r + c*r^2 + d*r^3 + e*r^4) for inverse mode, where R is the radius from the center of the infile and r is the radius from the center of the outfile.

The coefficient a represents scaling and the radial terms control pincushion and barrel distortion. The higher order coefficients affect the pixels further from center. The whole expression has a scaling effect. Thus, to avoid overall scaling, keep a+b+c+d+e=1. For normal mode, pincushion correction and barrel distortion are achieved using b,c,d,e positive and barrel correction and pincushion distortion are achieved using b,c,d,e negative. For a+b+c+d+e>1, the image will be scaled smaller and for a+b+c+d+e<1, the image will be scaled larger. Typical values are: a near 1 and b,c,d,e near zero. For inverse mode, the situation above is reversed. Thus for inverse mode, pincushion correction and barrel distortion are achieved using b,c,d,e negative and barrel correction and pincushion distortion are achieved using b,c,d,e positive. For a+b+c+d+e<1, the image will be scaled smaller and for a+b+c+d+e>1, the image will be scaled larger. Values of a=1,b=0,c=0,d=0,e=0 makes no change in the image in the appropriate dimension. Coefficients a,b,c,d,e are floating point values.

-c ... COORDS are the x,y center point coordinates for computing the radial distances. These values may be positive or negative floating point values to allow the center point to be off the image if the image is a subsection.

-m ... MODE controls whether to use the normal polynomial coefficient term or its inverse form. The default is normal.

-v ... VP is the virtual-pixel method to use. Any valid IM virtual-pixel may be used. The default is black.

For more details, see Helmut Dersch's page at http://www.all-in-one.ee/~dersch/barrel/barrel.html and http://wiki.panotools.org/Lens_correction_model

Note that the meaning and order of a,b,c,d have been reversed in this script from that of Dresch's work to make parameter specification easier and keep the most significant parameters first in the list.

Also as some references suggest that a proper barrel or pincushion distortion is modeled by only the coefficients of the even exponents of r, a fifth term (ex*r^4 and ey*r^4) has been added so that one can specify at least three even term (a+c*r^2+e*r^4). See http://www.imatest.com/docs/distortion.html and http://www.fieldrobotics.org/~cgeyer/OMNIVIS05/final/Li.pdf

Other references suggest that the inverse form allows better fit with the same or fewer coefficients. See http://www.fieldrobotics.org/~cgeyer/OMNIVIS05/final/Li.pdf

WARNING: The input file must not start with a digit or the script will think it is another set of coefficients.

RECOMMENDATION: Use the IM function -distort barrel

CAVEAT: No guarantee that this script will work on all platforms, nor that trapping of inconsistent parameters is complete and foolproof. Use At Your Own Risk.


EXAMPLES


Barrel Distortion - White Square On Black Background

Original Image

Both Directions:
Arguments (a,b):
"0.5,0.5,0,0,0"

X Direction Only:
Arguments (a,b):
"0.5,0.5,0,0,0 1,0,0,0,0"

Y Direction Only:
Arguments (a,b):
"1,0,0,0,0 0.5,0.5,0,0,0"



Pincushion Distortion - White Square On Black Background

Original Image

Both Directions:
Arguments (a,b):
"1.5,-0.5,0,0,0"

X Direction Only:
Arguments (a,b):
"1.5,-0.5,0,0,0 1,0,0,0,0"

Y Direction Only:
Arguments (a,b):
"1,0,0,0,0 1.5,-0.5,0,0,0"



Mixed Barrel And Pincushion Distortion - White Square On Black Background

Original Image

Barrel in X and Pincusion in Y
Arguments (a,b):
"0.5,0.5,0,0,0 1.5,-0.5,0,0,0"

Pincusion in X and Barrel in Y
Arguments (a,b):
"1.5,-0.5,0,0,0 0.5,0.5,0,0,0"



Barrel Distortion With Scaling - White Square On Black Background

Original Image

Barrel Scaled Smaller
Arguments (a,b):
"1,0.5,0,0,0"

Barrel Scaled Larger
Arguments (a,b):
"0.25.5,0,0,0"



Pincushion Distortion With Scaling - White Square On Black Background

Original Image

Pincusion Scaled Smaller
Arguments (a,b):
"1.75,-0.5,0,0,0"

Pincusion Scaled Larger
Arguments (a,b):
"1.35,-0.5,0,0,0"



Off Center Barrel And Pincushion Distortions - White Square On Black Background

Original Image

Barrel
Arguments (a,b):
"0.5,0.5,0,0,0" -c 64,64

Pincusion
Arguments (a,b):
"1.5,-0.5,0,0,0" -c 64,64



Off Center Barrel And Pincushion Distortions - Girl Image (Fat Head vs Pin Head)

Original Image

Barrel
Arguments (a,b):
"0.5,0.5,0,0,0 1.5,-0.5,0,0,0" -c 92,82

Pincusion
Arguments (a,b):
"1.5,-0.5,0,0,0 0.5,0.5,0,0,0" -c 92,82



Barrel Distortion Animations

Original Image

Big Chin
a=0.5 e=0 and one of b,c,d=0.5

Evil Eye
a=0.5 e=0 and one of b,c,d=0.5 -c 64,48



Barrel Distortion Parameter Normalization Versus Image Size

Full Size Image

Image Center
Arguments
"0.5,0.5,0,0,0"

Eye Center
Arguments
"0.5,0.5,0,0,0" -c 128,96

Half Size Image

Image Center
Arguments
"0.5,0.5,0,0,0"

Eye Center
Arguments
"0.5,0.5,0,0,0" -c 64,48

Full Size Results Resized By 50%

Image Center
-resize 50%

Eye Center
-resize 50%



Barrel Distortion - Grid Image

Original Image

Arguments (a,b):
"0.8,0.2,0,0,0"

Arguments (a,b):
"0.5,0.5,0,0,0"

Arguments (a,b):
"0.2,0.8,0,0,0"

Animation



Pincushion Distortion - Grid Image

Original Image

Arguments (a,b):
"1.2,-0.2,0,0,0"

Arguments (a,b):
"1.5,-0.5,0,0,0"

Arguments (a,b):
"1.8,-0.8,0,0,0"

Animation



Barrel Distortion - Grid Image

Original Image

Arguments (a,b):
"0.8,0.2,0,0,0"

Arguments (a,c):
"0.8,0,0.2,0,0"

Arguments (a,d):
"0.8,0,0,0.2,0"

Animation



Pincushion Distortion - Grid Image

Original Image

Arguments (a,b):
"1.2,-0.2,0,0,0"

Arguments (a,c):
"1.2,0,-0.2,0,0"

Arguments (a,d):
"1.2,0,0,-0.2,0"

Animation



Barrel Distortion: Normal Versus Inverse Mode - Grid Image

Original Image

Normal Mode
Arguments (a,b):
"0.5,0.5,0,0,0"

Normal Mode
Arguments (a,c):
"0.5,0,0.5,0,0"

Normal Mode
Arguments (a,d):
"0.5,0,0,0.5,0"

Normal Mode
Arguments (a,e):
"0.5,0,0,0,0.5"

Animation

Original Image

Inverse Mode
Arguments (a,b):
"1.5,-0.5,0,0,0"

Normal Mode
Arguments (a,c):
"1.5,0,-0.5,0,0"

Normal Mode
Arguments (a,d):
"1.5,0,0,-0.5,0"

Normal Mode
Arguments (a,e):
"1.5,0,0,0,-0.5"

Animation



Barrel Distortion: Normal Versus Inverse Mode - Grid Image

Original Image

Normal Mode
Arguments (a,b):
"0.9,0.1,0,0,0"

Normal Mode
Arguments (a,b,c):
"0.8,0.1,0.1,0,0"

Normal Mode
Arguments (a,b,c,d):
"0.7,0.1,0.1,0.1,0"

Normal Mode
Arguments (a,b,c,d,e):
"0.6,0.1,0.1,0.1,0.1"

Animation

Original Image

Inverse Mode
Arguments (a,b):
"1.1,-0.1,0,0,0"

Inverse Mode
Arguments (a,b,c):
"1.2,-0.1,-0.1,0,0"

Inverse Mode
Arguments (a,b,c,d):
"1.3,-0.1,-0.1,-0.1,0"

Inverse Mode
Arguments (a,b,c,d,e):
"1.4,-0.1,-0.1,-0.1,-0.1"

Animation



Barrel Distortion Correction - Dersch Image

Original Image

Dersch Correction
a=0, b=0, c=-0.075, d=1.1


Arguments (a,b):
"1.1,-0.075,0,0,0"



What the script does is as follows:

  • Applies barrel and/or pincushion distortion according to
    formulae of Helmut Dersch
  • Uses -fx; therefore slow

This is equivalent to the following IM commands:

  • compute sf=minimum of the image width or height
  • convert -monitor $infile -fx \
    "ww=w/2; hh=h/2; xd=(i-ww); yd=(j-hh); rd=hypot(xd,yd)/$sf;
    rrd=rd*rd; rrrd=rrd*rd; fdx=($dx*rrrd + $cx*rrd + $bx*rd + $ax);
    fdy=($dy*rrrd + $cy*rrd + $by*rd + $ay); xs=fdx*xd+ww; ys=fdy*yd+hh; u.p{xs,ys}" \
    $outfile