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.

DEFISHEYE


Corrects for fisheye distortion in an image.

Download Script

last modified: January 17, 2022



USAGE: defisheye [-i ifov] [-o ofov] [-t type] [-f format] [-c xc,yc] [-r radius] [-a angle] infile outfile
USAGE: defisheye -d [-c xc,yc] [-r radius] [-s strokecolor] infile outfile
USAGE: defisheye [-h or -help]

-i .... ifov ......... input (fisheye) image field of view in degrees;
...................... float; 0<ifov<=180; default=180
-o .... ofov ......... output (perspective) image field of view in degrees;
...................... float; 0<ifov<180; default=120
-t .... type ......... type of fisheye lens; linear, equalarea,
...................... orthographic, stereographic; default=linear
-f .... format ....... format of fisheye lens image; circular or fullframe;
...................... default=circular
-c .... xc,yc ........ coordinates of the center of the fisheye image area,
...................... which will also become the center of the perspective
...................... view; float; default=center of fisheye image
-r .... radius ....... radius of fisheye area in the input image; float;
...................... radius>0; default=min(width,height)/2
-a .... angle ........ angle of rotation (clockwise) for the perspective image;
...................... float; 0<=angle<360; default=0
-d ................... draw circle on the input fisheye image of specified radius,
...................... center and color=scolor, which will then become the output
-s .... scolor ....... scolor is the stroke color for a circle that will be
...................... drawn on the input fisheye image; default=white

PURPOSE: To correct for fisheye distortion in an image.

DESCRIPTION: DEFISHEYE is designed to transform a fisheye image into a normal perspective view looking towards the center of the fisheye image.

ARGUMENTS:

-i ifov ... IFOV is the input fisheye image field of view in degrees. A value of 180 will correspond to a hemispherical fisheye image within the circular area. Values are floats in the range 0<ifov<=180. The default is 180 degrees for a full hemisphere.

-o ofov ... OFOV is the output perspective image field of view in degrees. Values are floats in the range 0<ofov<180. The default is to use 120 degrees both vertically and horizontally for a circular fisheye and diagonally for a full frame fisheye. The value for ofov relative to the ifov determines the proportional amount of the fisheye area that will be transformed. Note that in comparison, a value of 48.8 degrees corresponds to a diagonal field of view from a 35 mm camera (film size 36mm x 24mm) with a 50mm focal length lens, i.e. a "normal" view. Similarly, when the image diagonal is equal to the focal length of the camera, the field of view is about 53.1 degrees. Although the default value is perhaps not appropriate to a normal perspective image, this will produce an image that maximizes the area covered, but without too much distortion. If the original fisheye image was viewed obliquely, i.e. the camera was tilted between horizontal and vertical, then the resulting perspective view will have perspective distortion. That is vertical edges will be tilted outward or inward. Post processing with my 3Drotate or rotate3D script will then correct for this perspective distortion. Perspective distortion will be more pronounced with larger values for ofov.

-t type ... TYPE is the type of fisheye lens. The choices are: linear (equidistant), equalarea (equisolid), orthographic and stereographic. The default is linear.

-f format ... FORMAT is the format of the fisheye lens image. The choices are: circular (image fills a circle that spans the minimum of the width or height) or fullframe (image spans a circle that spans the diagonal dimension). The default is circular.

-c xc,yc ... XC,YC are the pixel coordinates in the input fisheye image that correspond to the (circular fisheye area) center. The pixel at this coordinate will then become the center of the perspective image. The default values are the center of the input fisheye image. Values are non-negative floats. You can use the -d option to validate your choice of center and radius for the fisheye image. See more below.

-r radius ... RADIUS is the radius of the fisheye circular area in the input image. Values are floats greater than zero. The default is half the minimum value between the input image width and height.

-a angle ... ANGLE is the clockwise positive rotation angle for the output perspective image relative to the orientation of the input fisheye image. Values are non-negative floats in range 0<=angle<360. The default is 0.

-d ... Use of this argument produces an ouput image that is simply the input image with a circle drawn on it to show where the expected fisheye image area is located. You can specify a radius and center point if you want to adjust the transformation to use the precise center and radius that matches the area delimited by the circle. Radius and center default as described above.

-s scolor ... SCOLOR is the stroke color to use to draw the circle when the -d argument is used. The default is white.

See the following references for definitions and mathematical details of each type of fisheye lens:
http://en.wikipedia.org/wiki/Fisheye_lens
http://www.bobatkins.com/photography/technical/field_of_view.html

NOTE: This script uses -fx and therefore will be rather slow.

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


Mandril (Square) Image - Artificially Created Fisheye Types / Circular
(Created With FISHEYE Script: Perspective FOV=120; Fisheye FOV=180)

Fisheye Distorted Images

Linear

Equal Area

Orthographic

Stereographic


original

Corrected Images

Linear
Arguments:
-o 120 -i 180 -t linear
-f circular

Equal Area
Arguments:
-o 120 -i 180 -t equalarea
-f circular

Orthographic
Arguments:
-o 120 -i 180 -t orthographic
-f circular

Stereographic
Arguments:
-o 120 -i 180 -t stereographic
-f circular


original


Woman (Non-Square Image) - Artificially Created Lineaer Fisheye - Circular vs. Fullframe
(Created With FISHEYE Script: Perspective FOV=120; Fisheye FOV=180)

Fisheye Distorted Images

Linear Circular

Linear Full Frame


original

Corrected Images

Linear Circular
Arguments:
-o 120 -i 180 -t linear
-f circular

Linear Full Frame
Arguments:
-o 120 -i 180 -t linear
-f fullframe


original


Computer Generated Linear Circular Fisheye Image - Correct vs Incorrect Type
http://www.path.unimelb.edu.au/~bernardk/tutorials/360/background/projections.html
http://wiki.panotools.org/Fisheye_Projection
http://wiki.panotools.org/Projections

Original

Linear
Arguments:
-o 120 -i 180 -t linear
-f circular

Equal Area
Arguments:
-o 120 -i 180 -t equalarea
-f circular

Orthographic
Arguments:
-o 120 -i 180 -t orthographic
-f circular

Stereographic
Arguments:
-o 120 -i 180 -t stereographic
-f circular



Computer Generated Linear Circular Fisheye Image (Full Size)
http://www.path.unimelb.edu.au/~bernardk/tutorials/360/background/projections.html
http://wiki.panotools.org/Fisheye_Projection
http://wiki.panotools.org/Projections

Original

Linear
Arguments:
-o 120 -i 180 -t linear -f circular



Linear Full Frame Fisheye Image
http://www.all-in-one.ee/~dersch/perspective/Wide_Angle_Perspective.html

Original

Corrected
Arguments:
-o 120 -i 180 -t linear -f circular

Trimmed



Equisolid Full Frame Fisheye Image
http://en.wikipedia.org/wiki/Fisheye_lens

Original

Corrected
Arguments:
-o 120 -i 170 -t linear -f circular

Perspective Corrected
and Trimmed
3Drotate tilt=30 auto=out



Linear Circular Fisheye Image - Adjustments
http://www.worldserver.com/turk/quicktimevr/defish/defish.html

Original

Original With
Default Circle
Arguments:
-d [-r 193 -c 256,192.5]

Original With
Adjusted Circle
Arguments:
-d -r 190 -c 260,192.5

Under Corrected
Outward Bowing
Arguments:
-o 120 -i 180
-t linear -f circular
-r 190 -c 260,192.5

Over Corrected
Inward Bowing
Arguments:
-o 120 -i 190
-t linear -f circular
-r 190 -c 260,192.5

Good Correction
Straight Edges
Arguments:
-o 120 -i 188
-t linear -f circular
-r 190 -c 260,192.5



What the script does is as follows:

  • For a linear circular fisheye distortion, it applies the following equations:
  • perspective: r=f*tan(phi); f=(N/2)/tan((fov/2)*(pi/180))
  • fisheye: r=f*phi; f=(N/2)/((fov/2)*(pi/180)) where N=smaller dimension

This is equivalent to the following IM commands for the case of a
linear circular fisheye image of ${dim}x${dim} to perspective image:

  • compute image dimensions and center coordinates, etc
  • xd="xd=i-$xc;"
  • yd="yd=j-$yc;"
  • rd="rd=hypot(xd,yd);"
  • phi="phi=atan($ofocinv*rd);"
  • ifoc=`convert xc: -format "%[fx:($dim*180)/($ifov*pi)]" info:`
  • rr="rr=$ifoc*phi;"
  • xs="xs=(rd?rr/rd:0)*xd+$xc;"
  • ys="ys=(rd?rr/rd:0)*yd+$yc;"
  • convert $infile -virtual-pixel black -fx \
    "$xd $yd $rd $phi $rr $xs $ys u.p{xs,ys}" \
    $outfile