Fred's ImageMagick Scripts



    Licensing:

    Copyright © Fred Weinhaus

    My scripts are available free of charge for non-commercial 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

FISHEYE2RECT


Generates a perspective (rectilinear) image from a region of a vertically viewed fisheye image.

Download Script

last modified: September 26, 2017



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.


EXAMPLES


Linear Circular Fisheye Image
Panoramic Vertical View Range: -90 deg to 0 deg = 90 deg
Fisheye Field Of View: 2*90 = 180 deg
Nadir At Center
http://local.wasp.uwa.edu.au/~pbourke/projection/fish2/

Original Scaled To Half Size For Display

Diagram Of Look Directions For Perspectives

Example 1:
Arguments:
-o 90 -i 180 -l 500,500 400x300

Example 2:
Arguments:
-o 90 -i 180 -l 220,575 400x300



Linear Circular Fisheye Image
Panoramic Vertical View Range: -90 deg to 0 deg = 90 deg
Fisheye Field Of View: 2(0 - (-90)) = 180 deg
Nadir At Center
Virtual Tour Of Schloss Marburg (Marburg Castle)

Original

Diagram Of Look Direction For Perspective

Arguments:
-o 100 -i 180 -l 180,360 600x300



Hyperwide (Panoramic) Fisheye Image
Panoramic Vertical View Range: -62.5 deg to 52.5 deg = 115 deg
Fisheye Field Of View: 2*(52.5 - (-90)) = 285 deg
Nadir At Center
http://www.0-360.com/index.asp

Original Scaled To 1/4 Size For Display

Diagram Of Look Direction For Perspective

Arguments:
-o 90 -i 285 -l 600,1260 400x300



Hyperwide (Panoramic) Fisheye Image
Panoramic Vertical View Range: -20 deg to 90 deg = 110 deg
Fisheye Field Of View: 2*(90 - (-20)) = 220 deg
Zenith At Center
Caesar's Palace, Las Vegas

Original

Diagram Of Look Directions For Perspectives

Example 1:
Arguments:
-o 90 -i 220 -l 50,100 400x300 -m zenith

Example 2:
Arguments:
-o 100 -i 220 -l 220,130 500x400 -m zenith



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 180 deg fisheye image of ${sdim}x${sdim} with a look point at
${xl}x${yl} to a 400x300 pixel perspective:

  • compute image dimensions and center coordinates, etc
  • xd="xd=i-$xc;"
  • yd="yd=j-$yc;"
  • ddim=`convert xc: -format "%[fx:sqrt(400^2+300^2)]" info:`
  • ofoc=`convert xc: -format "%[fx:$ddim/(2*tan($ofov*pi/360))]" info:`
  • thetal=`convert xc: -format "%[fx:atan2($yl-$ycs,$xl-$xcs)]" info:`
  • radl=`convert xc: -format "%[fx:sqrt(($yl-$ycs)^2+($xl-$xcs)^2)]" info:`
  • theta="theta=atan(xd/$ofoc)+$thetal;"
  • phi="phi=atan(yd/$ofoc);"
  • ifoc=`convert xc: -format "%[fx:($sdim*180)/($ifov*pi)]" info:`
  • phil=`convert xc: -format "%[fx:$radl/$ifoc]" info:`
  • rr="rr=$ifoc*(phi+$phil);"
  • xs="xs=rr*cos(theta)+$xcs;"
  • ys="ys=rr*sin(theta)+$ycs;"
  • convert \( -size 400x300 xc: \) $infile \
    -virtual-pixel $vpmethod -background $bgcolor -monitor \
    -fx "$xd $yd $theta $phi $rr $xs $ys v.p{xs,ys}" \
    $outfile