USAGE: fisheye2rect [widthxheight] [-i ifov] [-o ofov] [-t type] [-f format] [-m mode] [-c xc,yc] [-l xl,yl] [-r radius] [-v vpmethod] [-b bgcolor] infile outfile
USAGE: fisheye2rect -d [-c xc,yc] [-r radius] [-s strokecolor] infile outfile
USAGE: fisheye2rect [-h or -help]

widthxheight ......... size (width and height) of desired output image;
...................... default is size of input image
-i .... ifov ......... input (fisheye) image field of view in degrees;
...................... float; 0<ifov<360; default=180
-o .... ofov ......... output (perspective) image diagnonal field of view in degrees;
...................... float; 0<ofov<180; default=90
-t .... type ......... type of fisheye lens; linear, equalarea,
...................... orthographic, stereographic; default=linear
-f .... format ....... format of fisheye lens image; circular or fullframe;
...................... default=circular
-m .... mode ......... nadir (n) or zenith (z) in center of fisheye image;
...................... default=nadir (n)
-c .... xc,yc ........ coordinates of the center of the fisheye image area;
...................... float; default=center of fisheye image
-l .... xl,yl ........ coordinates of the look point in the fisheye image area,
...................... which will also become the center in the perspective
...................... view; float; default is 3/4 towards the right side
...................... and 1/2 down from the top.
-r .... radius ....... radius of fisheye area in the input image; float;
...................... radius>0; default=min(width,height)/2
-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
-v .... vpmethod ..... virtual-pixel method to use to fill area of output image
...................... that are outside the input image; default=black
-b .... bgcolor ...... background color for virtual-pixel=background
...................... any valid IM color is allowed. The default=black

PURPOSE: To generate a perspective (rectilinear) image from a region of a vertically viewed fisheye image.

DESCRIPTION: FISHEYE2RECT generates a perspective (rectilinear) image from a region of a vertically viewed fisheye image. The region is identified by a point on the fisheye image and the specified output field of view. The perspective image will in general be tilted (not a view along the horizontal), except for example, when viewing from the center to the radius of a 180 degree fisheye image or from the center to the horizon radius in hyperwide fisheye images.

ARGUMENTS:

widthxheight ... WIDTHxHEIGHT are the desired dimensions for the output perspective image. If not specified, then the size of the perspective image will be identical to the size of the fisheye image.

-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<360. The default is 180 degrees for a full hemisphere. Note that ifov is not limited to 180 degrees to permit the use of hyperwide field of view fisheye systems that may view from below the horizon to above the horizon. These are typical of the one-shot mirrored 360 degree panoramic systems.

-o ofov ... OFOV is the diagonal output perspective image field of view in degrees. Values are floats in the range 0<ofov<180. The default is 90. The amount of input image in the output perspective image will depend upon the ofov parameter. 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.

-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.

-m mode ... MODE is either nadir (n) or zenith (z) at the center of the fisheye image. The default is nadir (n). If zenith is selected, the perspective image will undergo a 180 degree rotation.

-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.

-l xl,yl ... XL,YL are the pixel coordinates in the input fisheye image that determine the direction towards which the output perspective view is looking. That is the pixel at this coordinate will then be transormed to the center of the perspective image. The view will always be from the center of the input fisheye image. The default is at xl=0.75*width and yl=0.5*height, i.e. half way down and 3/4 towards the right edge. Note that as xl,yl get closer to the center of the fisheye, a horizontal stripe artifact will show at the nadir when it is within the field of view. Recommended locations are at least half way towards the edges (i.e. greater than about 1/2 the radius of the image from center).

-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.

-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.

-v vpmethod ... VPMETHOD is the virtual-pixel method. Any valid IM virtual-pixel setting is allowed. The default is black.

-b bgcolor ... BGCOLOR is the background color to use with vpmethod=background. Any valid IM color may be used. 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.