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.

FISHEYE


Applies a fisheye distortion to an image.

Download Script

last modified: January 17, 2022



USAGE: fisheye [-i ifov] [-o ofov] [-t type] [-f format] [-c xc,yc] [-r radius] [-a angle] [-m vpmethod] [-v vpcolor] [-b bgcolor] infile outfile
USAGE: fisheye [-h or -help]

-i .... ifov ......... input (perspective) image field of view in degrees;
...................... float; 0<ifov<180; default=120
-o .... ofov ......... output (fisheye) image field of view in degrees;
...................... float; 0<ifov<=180; default=180
-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 in the perspective image to make the
...................... center of the fisheye view; float;
...................... default=center of perspective image
-r .... radius ....... radius of fisheye area in output image; float;
...................... radius>0; default=min(width,height)/2
-a .... angle ........ angle of rotation (clockwise) for the fisheye image;
...................... float; 0<=angle<360; default=0
-m .... vpmethod ..... vp is the virtual-pixel method; default=black
-v .... vpcolor ...... vpcolor is the color for the case when
...................... -virtual-pixel=background; this is where parts
...................... of the fisheye circle map outside image;
...................... use none for transparent; default=black
-b .... bgcolor ...... bgcolor is the color for the area outside the
...................... circle of the fisheye area;
...................... use none for transparent; default=black

PURPOSE: To apply a fisheye distortion to an image.

DESCRIPTION: FISHEYE is designed to transform a normal perspective image into a fisheye view.

ARGUMENTS:

-i ifov ... IFOV is the input perspective image field of view in degrees. Values are floats in the range 0<ifov<180. The default is to use 120 degrees both vertically and horizontally. The value for ifov relative to the ofov determines the proportional amount of the fisheye area that will be filled. 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 enlarge the amount of area filled in the fisheye result and thereby produce a significant fisheye distortion.

-o ofov ... OFOV is the output fisheye image field of view in degrees. A value of 180 will produce a hemispherical fisheye image within the circular area. A smaller value will produce less curvature of the circular area corresponding to less distortion. Values are floats in the range 0<ifov<=180. The default is 180 degrees for a full hemisphere.

-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 perspective image that are desired to be the center of the fisheye image. The default values are the center of the input perspective image. Values are non-negative floats.

-r radius ... RADIUS is the radius of the fisheye circular area in the output image. Values are floats greater than zero. The default is half the minimum value between the input image width and height. This parameter controls the scaling of the fisheye result. The default produces -f circular. If radius is set equal to half the diagonal dimension of the image, the result will be the same as specifying -f fullframe. A value for radius that is smaller than half the minimum of the width and height will produce a smaller circular area.

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

-m vpmethod ... VPMETHOD is the virtual-pixel method to use. Any valid IM virtual-pixel may be used. The default is black.

-v vpcolor ... VPCOLOR is the virtual-pixel color to use when vp=background. This color is used to fill the fisheye circle where no image shows. Use "none" for transparent. The default is black.

-b bgcolor ... BGCOLOR is the color to use to fill the area around the fisheye circular area. Use "none" for transparent. The default is black.

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 - Fisheye Types / Circular
OFOV=180 and IFOV=120

Original Image

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

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

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

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



Mandril (Square) Image - Fisheye Types / Circular
OFOV=180 and IFOV=90

Original Image

Linear
Arguments:
-o 180 -i 90 -t linear
-f circular -m gray

Equal Area
Arguments:
-o 180 -i 90 -t equalarea
-f circular -m gray

Orthographic
Arguments:
-o 180 -i 90 -t orthographic
-f circular -m gray

Stereographic
Arguments:
-o 180 -i 90 -t stereographic
-f circular -m gray



Mandril (Square) Image - Fisheye Types / Full Frame
OFOV=180 and IFOV=120

Original Image

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

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

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

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



Mandril (Square) Image - Fisheye Types / Circular
Variations In Parameters

Original Image

Change Radius
Arguments:
-o 180 -i 120 -t linear
-f circular -r 48 -m gray

Change Angle
Arguments:
-o 180 -i 120 -t linear
-f circular -a 90 -m gray

Change Center
Arguments:
-o 180 -i 120 -t linear
-f circular -c 48,64.5 -m gray

Transparent Overlaid On Checkerboard
Arguments:
-o 180 -i 120 -t linear
-f circular -m backround -v none -b none
(post-processed to composite
onto checkerboard background)



Mandril (Square) Image - Fisheye Types / Circular
Change In Distortion

Original Image

Arguments:
-o 60 -i 60 -t linear
-f circular -m gray

Arguments:
-o 90 -i 90 -t linear
-f circular -m gray

Arguments:
-o 120 -i 120 -t linear
-f circular -m gray

Arguments:
-o 150 -i 150 -t linear
-f circular -m gray



Woman (Non-Square Image) - Linear - Circular vs. Fullframe

Original Image

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

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



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
perspective image of ${dim}x${dim} to a linear circular fisheye image:

  • compute image dimensions and center coordinates, etc
  • xd="xd=i-$xc;"
  • yd="yd=j-$yc;"
  • rd="rd=hypot(xd,yd);"
  • ofocinv=`convert xc: -format "%[fx:($ofov*pi)/($dim*180)]" info:`
  • phi="phi=$ofocinv*rd;"
  • rr="rr=$ifoc*tan(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 (rd>$dim/2)?black:u.p{xs,ys}" \
    $outfile