.help rotate Dec98 images.imgeom
.ih
NAME
rotate -- rotate and shift a list of images
.ih
USAGE
rotate input output rotation
.ih
PARAMETERS
.ls input
List of images to be rotated.
.le
.ls output
List of output images.
.le
.ls rotation
Angle of rotation of the image in degrees. Positive angles will rotate
the image counter-clockwise from the x axis.
.le
.ls xin = INDEF, yin = INDEF
The origin of the rotation in pixels. Xin and yin default to the center of
the input image.
.le
.ls xout = INDEF, yout = INDEF
The origin of the output image. Xout and yout default to the center of the
output image.
.le
.ls ncols = INDEF, nlines = INDEF
The number of columns and rows in the output image. The default is to
keep the dimensions the same as the input image. If ncols and nrows is
less then or equal to zero the program will compute the number of columns
and rows needed to include the whole image, excluding the effects of
any origin shifts.
.le
.ls interpolant = "linear"
The interpolant. The options are the following:
.ls nearest
Nearest neighbor.
.le
.ls linear
Bilinear interpolation in x and y.
.le
.ls poly3
Third order polynomial in x and y.
.le
.ls poly5
Fifth order polynomial in x and y.
.le
.ls spline3
Bicubic spline.
.le
.ls sinc
2D sinc interpolation. Users can specify the sinc interpolant width by
appending a width value to the interpolant string, e.g. sinc51 specifies
a 51 by 51 pixel wide sinc interpolant. The sinc width will be rounded up to
the nearest odd number.  The default sinc width is 31 by 31.
.le
.ls lsinc
Look-up table sinc interpolation. Users can specify the look-up table sinc
interpolant width by appending a width value to the interpolant string, e.g.
lsinc51 specifies a 51 by 51 pixel wide look-up table sinc interpolant. The user
supplied sinc width will be rounded up to the nearest odd number. The default
sinc width is 31 by 31 pixels. Users can specify the resolution of the lookup
table sinc by appending the look-up table size in square brackets to the
interpolant string, e.g. lsinc51[20] specifies a 20 by 20 element sinc
look-up table interpolant with a pixel resolution of 0.05 pixels in x and y.
The default look-up table size and resolution are 20 by 20 and 0.05 pixels
in x and y respectively.
.le
.ls drizzle
2D drizzle resampling. Users can specify the drizzle pixel fraction in x and y
by appending a value between 0.0 and 1.0 in square brackets to the
interpolant string, e.g. drizzle[0.5]. The default value is 1.0.
The value 0.0 is increased internally to 0.001. Drizzle resampling
with a pixel fraction of 1.0 in x and y is equivalent to fractional pixel
rotated block summing (fluxconserve = yes) or averaging (flux_conserve = no)  if
xmag and ymag are > 1.0.
.le
.le
.ls boundary = "nearest"
The choices are:
.ls nearest
Use the value of the nearest boundary pixel.
.le
.ls constant
Use a constant value.
.le
.ls reflect
Generate a value by reflecting around the boundary.
.le
.ls wrap
Generate a value by wrapping around to the opposite side of the image.
.le
.le
.ls constant = 0.
The value of the constant for constant boundary extension.
.le
.ls nxblock = 512, nyblock = 512
If the dimensions of the output image are less than nxblock and nyblock
then the entire image is rotated at once. Otherwise nxblock by nyblock
segments of the image are rotated.
.le
.ih
DESCRIPTION

ROTATE rotates the list of images in input by rotation degrees and writes
the output to the images specified by output. The origins of the input and
output images may be specified by setting xin, yin, xout and yout. The
transformation is described below.

.nf
    xt = (x - xin) * cos (rotation) - (y - yin) * sin (rotation) + xout
    yt = (x - xin) * sin (rotation) + (y - yin) * cos (rotation) + yout

.fi

The output image gray levels are determined by interpolating in the input
image at the positions of the transformed output pixels. ROTATE uses the
routines in the 2-D interpolation package.

.ih
EXAMPLES

.nf
1. Rotate an image 45 degrees around its center.

   cl> rotate m51 m51r45 45.0

2. Rotate an image by 45 degrees around (100., 100.) and
   shift the origin to (150., 150.0) using bicubic interpolation.

   cl> rotate m92 m92r45 45.0 xin=100. yin=100. xout=150. yout=150.\
   >>> interp=poly3

3. Rotate an image 90 degrees counter-clockwise and clockwise around its
   center. Note the use of imtranspose and image section notation.

   cl> imtranspose m92[*,-*] m92d90

   cl> imtranspose m92[-*,*] m92d270

4. Rotate an image 180 degrees counter-clockwise. Note the use of imcopy
   and image section notation.

   cl> imcopy m92[-*,-*] m92d180
.fi

.ih
TIMINGS
It requires approximately 70 and 290 cpu seconds to rotate a 512 by 512
real image using bilinear and biquintic interpolation respectively
(Vax 11/750 fpa).
.ih
BUGS
The interpolation operation is done in real arithmetic. However the output
type of the pixels is set equal to the input type. This can lead to truncation
problems for integer images.

Simple 90, 180, 270 etc degree rotations are best performed using the
imtranspose task and/or image section notation.
.ih
SEE ALSO
imtranspose, imshift, magnify, lintran, geotran, geomap
.endhelp
