last modified by "Ramme, F. L. P."  : June 30, 2015
last modified by "Fred Weinhaus" : August 27, 2013

USAGE: perspective.sh pan,tilt,roll[,pef] infile outfile
USAGE: perspective.sh

pan ................. rotation about image vertical centerline: -180 to +180 (deg)
tilt ................ rotation about image horizontal centerline: -180 to +180 (deg)
roll ................ rotation about the image center: -180 to +180 (deg)
pef ................. perspective exaggeration factor: 0 to 3.19
function name only .. get help

PURPOSE: To apply a perspective distortion to an image by providing three rotation angles and an optional perspective exaggeration.

DESCRIPTION: ROTATE3D applies a perspective distortion to an image by providing three optional rotation angle: pan, tilt and roll with an option to control the perspective exaggeration.

PAN is a rotation of the image about its vertical centerline -180 to +180 degrees. Positive rotations turn the right side of the image away from the viewer and the left side towards the viewer. Zero is no rotation. A PAN of +/- 180 deg achieves the same results as -flip.

TILT is a rotation of the image about its horizontal centerline -180 to +180 degrees. Positive rotations turn the top of the image away from the viewer and the bottom towards the viewer. Zero is no rotation. A TILT of +/- 180 deg achieves the same results as -flop.

ROLL (like image rotation) is a rotation in the plane of the the image -180 to +180 degrees. Positive values are clockwise and negative values are counter-clockwise. Zero is no rotation. A ROLL of any angle achieves the same results as -rotate.

PAN, TILT and ROLL are order dependent. If all three are provided, then they will be done in that order.

PEF is the perspective exaggeration factor. It ranges from 0 to 3.19. A normal perspective is achieved with the default of 1. As PEF is increased from one the perspective effect moves towards that of a wide angle lens (more distortion). If PEF is decreased from one the perspective effect moves towards a telephoto lens (less distortion). PEF of 0.5 achieves an effect close to no perspective distortion. PEF values too large may cause part of the image appear above the 'horizon' in the 'sky'.