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.

PANO2RECT


Applies vertical perspective correction to an angular panoramic image.

Download Script

last modified: November 29, 2023



USAGE: pano2rect [-v vtop,vbot] [-p pfov] [-f format] [-i iyc] [-o oyc] [-h height] [-vp vpmethod] [-b bgcolor] infile outfile
USAGE: pano2rect [-help]

-v .... vtop,vbot ....... vertical viewing angles corresponding to the
......................... top and bottom of the panoramic image;
......................... default=-0,-90 (90 degree vertical
......................... range of view, i.e. horizon to nadir)
-p .... pfov ............ perspective image vertical field of view in degrees;
......................... float; 0<pfov<180; default=vrange=(vtop-vbot)
-f .... format .......... output perspective format; tilt (T)
......................... or level (L) (perspective); default=tilt
-i .... iyc ............. pixel coordinates of the desired row in the input
......................... panoramic image that is to be the center of
......................... the perspective correction; float;
......................... default=center of panorama image
-o .... oyc ............. pixel coordinates of the desired row in the output
......................... perspective image that is to be the center of
......................... the perspective correction; float;
......................... default=center of perspective image for format=tilt;
......................... default=bottom of perspective image for format=level
-h .... height .......... desired height of output;
......................... Default=same as input
-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 apply vertical perspective correction to an angular panoramic image

DESCRIPTION: PANO2RECT applies vertical perspective correction to an angular panoramic image. The output formats are either tilt or leve. These describe only the vertical format for the output image. The horizontal format will not be changed. For tilt format, the output will be a tilted view with the look direction towards the mid row of the input panoramic image. For level format, the perspective will be looking horizontally.

ARGUMENTS:

-v vtop,vbot ... VTOP,VBOT are the vertical viewing angles at the top and bottom of the input panorama image. The default is 90,0 which corresponds to a 90 degree vertical range of view, i.e. zenith to horizon.

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

-f format ... FORMAT is the output image perspective format. The choices are: tilt (T) and level (L). The default is tilt. If tilt (T) is chosen, then the output image will have perspective correction applied in the vertical direction and the image will be centered by default about the mid-angle of the panorama image, i.e., vertical center of the panorama. 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 default to the bottom of the output image (assuming that the top row of the panorama image is looking above the horizon).

-i iyc ... IYC is the pixel coordinates in the input panorama image that will be the center of the perspective correction. The default is the center row of the panorama image. Values are non-negative floats.

-o oyc ... OYC is the pixel coordinates in the output perspective image that will be the center of the perspective correction. The default is the center row of the perspective image for format=tilt and the bottom row of the perspective image for format=level (assuming that the top row of the panorama image is looking above the horizon). Values are non-negative floats.

-h height ... HEIGHT is the desired height of the perspective image. The default is the same as the input. Values larger than the input may be useful in showing more of the image when a level perspective is used. Values other than the default will not change the scale of the perspective image in the vertical dimension. They will only allow more (or less) data to be viewed.

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

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


Panoramic Image From Hyperwide Fisheye Image
Panoramic Vertical View Range: -62.5 deg to 52.5 deg = 115 deg
Nadir At Center
http://www.0-360.com/index.asp

Original Fisheye With Direction For Center Of Panorama

Panorama Image Generated From Fisheye
center direction = 211.5 deg implies:
horizontal roll = 37.2 pixels
vertical-to-horizontal aspect ratio = (52.5 + 90)/360 = 39.6%
Arguments:
-distort depolar 0 -roll +37.2+0 -flip -resize 100x39.6%

Tilt Perspective Correction:
Arguments:
-v 52.5,-90 -f tilt



Panoramic Image From Hyperwide Fisheye Image
Panoramic Vertical View Range: -20 deg to 90 deg = 110 deg
Zenith At Center
Caesar's Palace, Las Vegas

Original Fisheye Image With Direction For Center Of Panorama

Panorama Image Generated From Fisheye
vertical-to-horizontal aspect ratio = (90 + 20)/360 = 30.6%
Arguments:
-distort depolar 0 -resize 200x61.1%

Tilt Perspective Correction:
Arguments:
-v 90,-20 -f tilt

Level Perspective Correction:
Arguments:
-v 90,-20 -f level

Level Perspective Correction With Extra Height:
Arguments:
-v 90,-20 -f level -h 242



What the script does is as follows:

  • Applies the following equations in the vertical direction only:
  • perspective: r=f*tan(phi); f=(N/2)/tan((fov/2)*(pi/180))

This is equivalent to the following IM commands for the case of a
panoramic strip image of verical range from 52.5 to -90 = 142.5 degrees
with a tilt perspective correction.

  • width=425"
  • height=168"
  • iyc=83.5"
  • oyc=83.5"
  • vrange=142.5
  • pfov=142.5
  • pfocinv=`convert xc: -format "%[fx:(2*tan($pfov*pi/360))/$height]" info:`
  • convert \( -size ${width}x${height} xc: \) $tmpA \
    -virtual-pixel $vpmethod -background $bgcolor -monitor \
    -fx "yd=j-$oyc; v.p{i,(180*($sheight-1)/(pi*$vrange))*atan($pfocinv*yd)+$iyc}" \
    $outfile