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.

FISHEYE2PANO


Generates a strip panoramic image from a linear type fisheye image with optional vertical perspective correction.

Download Script

last modified: January 17, 2022



USAGE: fisheye2pano [-w width] [-e extend] [-h hcen,hran] [-f format] [-p pfov] [-c xc,yc] [-v vcen,vrad] [-r radius] [-vp vpmethod] [-b bgcolor] infile outfile
USAGE: fisheye2pano -d [-c xc,yc] [-r radius] [-s strokecolor] infile outfile
USAGE: fisheye2pano [-help]

-w .... width ........... width of output; default is same as input
-e .... extend .......... percentage to extend height of output from
......................... natural size. Only allowed for perspective formats.
-h .... hcen,hran ....... horizontal angular center of output and horizontal
......................... angular range between left and right side of output;
......................... default=0,360; where hcen increases clockwise
......................... from the top center of the input as seen from
......................... its center and must be between 0 and 360.
-f .... format .......... output vertical format; angle (A), tilt (T) (perspective),
......................... or level (L) (perspective); default=angle
-p .... pfov ............ perspective image vertical field of view in degrees;
......................... float; 0<pfov<180; default=vrange=(vrad-vcen)
-c .... xc,yc ........... pixel coordinates of the center of the fisheye image area;
......................... float; default=center of fisheye image
-v .... vcen,vrad ....... vertical viewing angles corresponding to the
......................... fisheye circular area center and the circular
......................... area radius; default=-90,0 (90 degree vertical
......................... range of view, i.e. nadir to horizontal)
-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
-vp ... 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 strip panoramic image from a linear type fisheye image with optional vertical perspective correction.

DESCRIPTION: FISHEYE2PANO generates a strip panoramic image from a linear type fisheye image. The output formats are either angle, tilt perspective or level perspective. These describe the vertical format for the image, where the latter two are perspectively corrected. The tilt perspective will be a tilted view with the mid radius at the center of the perspective. The level perspective will be looking horizontally. The horizontal format will always be angle.

ARGUMENTS:

-w width ... WIDTH is the desired width for the output image. If not specified, then the width of the output will be identical to that of the input or to 2*radius of circular area of the input if provided. If the width is adjusted then the height will be adjusted in proportion.

-e extend ... EXTEND is the percentage to increase the height of the output from its natural size. A value of 100 results in the natural height. The natural height is (ifov/360)*width, where ifov is the input fisheye image vertical field of view and is given by 2*abs(vcen-vrad). This is only allowed for the two perspective output formats. It will not change the scale of the image in the vertical dimension. It only allows more data to be viewed.

-h hcen,aran ... HCEN,HRAN are the angular direction for the horizontal center of the output image and the horizontal angular range between left and right side of the output; default=0,360; where hcen increases clockwise from the top center of the input as seen from its center and must be between 0 and 360.

-f format ... FORMAT is the output image vertical format. The choices are: angle (A), tilt (T) perspective and level (L) perspective. (Note: the output image horizontal format is always angle.) The default is angle. If tilt (T) is chosen, then the output image will have perspective correction applied in the vertical direction and the image will be centered about the mid-angle of the fisheye image. In other words a tilted vertical perspective will be produced. If level (L) is chosen, then the output image will also have perspective correction applied in the vertical direction. But the view will be one that is not tilted, but looking horizontally. The horizon line will be at or near the top of the outpt image for a fisheye image whose center is the nadir and will be at or near the bottom of the output image for a fisheye image whose center is the zenith. The exact placement depends upon the ratio of vrad to vrange=abs(vcen-vrad). The level format is generally only useful for the latter case and especially with hyperwide fisheye images whose field of view across the circular area diameter is greater than 180 degrees.

-p pfov ... PFOV is the vertical output perspective image field of view in degrees. Values are floats in the range 0<pfov<180. The default is to use the vertical viewing range of the fisheye image, which is vrange = (vrad-vcen) = ifov/2 (half of the field of view across the circular diameter). The amount of input image in the output perspective image will depend upon the pfov parameter. Note that in comparison, a value of 27 degrees corresponds to a vertical field of view from a 35 mm camera (film size 36mm x 24mm) with a 50mm focal length lens, i.e. a "normal" view.

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

-v vcen,vrad ... VCEN,VRAD are the vertical viewing angles in the input fisheye image corresponding to the center of the circular area and to its radius (perimeter). The default is -90,0 which corresponds to a 90 degree vertical range of view, i.e. nadir to horizontal and thus 2*90=180 full fisheye diameter field of view). Note: vcen will generally be either -90 or +90, even if the specs says the min value is greater than -90 or the max value is less than +90. You can tell this by the dark circlular area at the center which extends from the center out to whatever is the relevant min or max value specified by the camera system.

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

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

Diagram Of Look
Directions For Panoramas

Example 1:
Format: Angle
Horizontal Center = 0 Deg
Arguments:
-v -90,0 -h 0 -f angle

Diagram Rotate So That Center Direction
Is At Top For Easier Comparison

Example 2:
Format: Angle
Horizontal Center = 90 Deg
Arguments:
-v -90,0 -h 90 -f angle

Diagram Rotate So That Center Direction
Is At Top For Easier Comparison

Example 3:
Format: Angle
Horizontal Center = 180 Deg
Arguments:
-v -90,0 -h 180 -f angle

Diagram Rotate So That Center Direction
Is At Top For Easier Comparison

Example 4:
Format: Angle
Horizontal Center = 270 Deg
Arguments:
-v -90,0 -h 270 -f angle

Diagram Rotate So That Center Direction
Is At Top For Easier Comparison

Example 5:
Format: Tilt (Perspective)
Horizontal Center = 0 Deg
Arguments:
-v -90,0 -h 0 -f tilt

Diagram Rotate So That Center Direction
Is At Top For Easier Comparison

Example 6:
Format: Angle
Horizontal Center = 0 Deg
Width = 500
Arguments:
-v -90,0 -h 0 -f angle -w 500

Example 7:
Format: Tilt (Perspective)
Horizontal Center = 0 Deg
Width = 500
Arguments:
-v -90,0 -h 0 -f tilt -w 500



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

Diagram Of Look
Direction For Panorama

Example 1:
Format: Angle
Horizontal Center = 211.5 Deg
Arguments:
-v -90,52.5 -h 211.5 -f angle

Diagram Rotate So That Center Direction
Is At Top For Easier Comparison

Example 2:
Format: Tilt
Horizontal Center = 211.5 Deg
Persp. FOV = ifov/2 = 142.5 Deg
Arguments:
-v -90,52.5 -h 211.5 -f tilt

Diagram Rotate So That Center Direction
Is At Top For Easier Comparison



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:
Format: Angle
Horizontal Center = 0 Deg
Arguments:
-v 90,-20 -h 0 -f angle

Diagram Rotate So That Center Direction
Is At Bottom For Easier Comparison

Example 2:
Format: Angle
Horizontal Center = 90 Deg
Arguments:
-v 90,-20 -h 90 -f angle

Diagram Rotate So That Center Direction
Is At Bottom For Easier Comparison

Example 3:
Format: Angle
Horizontal Center = 180 Deg
Arguments:
-v 90,-20 -h 180 -f angle

Diagram Rotate So That Center Direction
Is At Bottom For Easier Comparison

Example 4:
Format: Angle
Horizontal Center = 0 Deg
Arguments:
-v 90,-20 -h 270 -f angle

Diagram Rotate So That Center Direction
Is At Bottom For Easier Comparison

Example 5:
Format: Tilt (Perspective)
Horizontal Center = 180 Deg
Persp. FOV = ifov/2 = 110 Deg
Arguments:
-v 90,-20 -h 180 -f tilt -p 110

Diagram Rotate So That Center Direction
Is At Bottom For Easier Comparison

Example 6:
Format: Level (Perspective)
Horizontal Center = 180 Deg
Persp. FOV = ifov/2 = 110 Deg
Arguments:
-v 90,-20 -h 180 -f level -p 110

Diagram Rotate So That Center Direction
Is At Bottom For Easier Comparison

Example 7:
Format: Level (Perspective)
Horizontal Center = 180 Deg
Persp. FOV = ifov/2 = 110 Deg
Output Extended 150% Vertically
Arguments:
-v 90,-20 -h 180 -f level -p 110 -e 150

Diagram Rotate So That Center Direction
Is At Bottom For Easier Comparison

Example 8:
Format: Angle
Horizontal Center = 180 Deg
Persp. FOV = ifov/2 = 110 Deg
Arguments:
-v 90,-20 -h 180 -f angle -w 500

Diagram Rotate So That Center Direction
Is At Bottom For Easier Comparison

Example 9:
Format: Tilt (Perspective)
Horizontal Center = 180 Deg
Persp. FOV = ifov/2 = 110 Deg
Arguments:
-v 90,-20 -h 180 -f tilt -w 500

Diagram Rotate So That Center Direction
Is At Bottom For Easier Comparison



Similar Results Using Multiple IM "Convert" Steps
Including The New IM -distort depolar

Note: all the steps below could be put into one command line
which would prevent excess resampling/blurring

Note: the roll step can be avoided as it can be folded into the
-distort depolar by providing the correct parameters

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

Diagram Of Look
Direction For Panorama

Step 1:
Convert Fisheye To Panorama

Arguments:
-depolar 0

Step 2:
Roll to put look direction 211.5 deg at center and
Flip (as nadir is at center of fisheye)

rollx=width*(211.5-180)/360=37.185

Arguments:
-roll +37.185+0 -flip

Step 3:
Resize for desired width of 600 and to correct angular aspect ratio

aspect=vrange/180=142.5/360=0.395833
wfactor=100*desiredwidth/imagewidth=100*600/425=141.176
hfactor=aspect*wfactor=0.385833*141.176=55.8821

Arguments:
-resize 141.176x55.8821%

Step 4:
Correct to proper tilted planar perspective

compute inverse of perspective focal length from vrange

vrange=(vrad-vcen)=(52.5 - (-90)) = 142.5 deg
pfinv=(2*tan(vrange*pi/360))/height=0.02486

Arguments:
convert testimage2_depolar0_flip_roll_resize.jpg \
-monitor -fx "yd=j-h/2; ys=(180*h/(pi*$vrange))*atan($pfinv*yd)+h/2; u.p{i,ys}" \
testimage2_depolar0_flip_roll_resize_persp.jpg



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 size 362x362 extending from nadir
at the center to horizontal at its radius=181 and a tilt perspective fov = 90
(ifov/2) looking such that the top of the fisheye (0 deg) will be in the
center of the output.

  • dim=362"
  • yc=181"
  • yd="yd=j-$yc;"
  • pfov=90
  • pfoc=`convert xc: -format "%[fx:$dim/(2*tan($pfov*pi/360))]" info:`
  • phicenter=-90
  • phiradius=0
  • ifov=`convert xc: -format "%[fx:2*abs($phiradius-$phicenter)]" info:`
  • aspect=`convert xc: -format "%[fx:360/$ifov/]" info:`
  • height=`convert xc: -format "%[fx:$aspect*$dim]" info:`
  • phioffset=`convert xc: -format "%[fx:(pi/180)*abs(($phiradius-$phicenter))/2]" info:`
  • phi="phi=atan2(yd,$pfoc)+$phioffset;"
  • rr="rr=$aspect*$ifoc*phi;"
  • theta0=`convert xc: -format "%[fx:($thetacenter-($thetarange/2)-90)*pi/180]" info:`
  • theta1=`convert xc: -format "%[fx:($thetarange)*pi/180]" info:`
  • theta="theta=$theta1*(i/(w-1))+$theta0;"
  • xs="xs=rr*cos(theta)+$xc;"
  • ys="ys=rr*sin(theta)+$yc;"
  • convert \( -size ${dim}x${height} xc: \) $infile \
    -virtual-pixel $vpmethod -background $bgcolor -monitor \
    -fx "$yd $phi $rr $theta $xs $ys v.p{xs,ys}" \
    $outfile