\
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
.\" the corresponding HTML page on the Netpbm website, generate a patch
.\" against that, and send it to the Netpbm maintainer.
.TH "Pnmrotate User Manual" 0 "30 August 2002" "netpbm documentation"

.SH NAME
pnmrotate - rotate a PNM image by some angle

.UN synopsis
.SH SYNOPSIS

\fBpnmrotate\fP
[\fB-noantialias\fP] [\fB-background=\fP\fIcolor\fP] \fIangle\fP
[\fIpnmfile\fP]

.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.

\fBpnmrotate\fP reads a PNM image as input.  It rotates it by the
specified angle and produces the same kind of PNM image as output.
.PP
The input is the file named by \fIpnmfile\fP or Standard Input if you
don't specify \fIpnmfile\fP.  The output goes to Standard Output.
.PP
The resulting image is a rectangle that contains the (rectangular)
input image within it, rotated with respect to its bottom edge.  The
containing rectangle is as small as possible to contain the rotated
image.  The background of the containing image is a single color that
\fBpnmrotate\fP determines to be the background color of the original
image, or that you specify explicitly.
.PP
\fIangle\fP is in decimal degrees (floating point), measured
counter-clockwise.  It can be negative, but it should be between -90
and 90.
.PP
You should use \fBpamflip\fP instead for rotations that are a
multiple of a quarter turn.  It is faster and more accurate.
.PP
For rotations greater than 45 degrees you may get better results if
you first use \fIpamflip\fP to do a 90 degree rotation and then
\fIpnmrotate\fP less than 45 degrees back the other direction.
.PP
The rotation algorithm is Alan Paeth's three-shear method.  Each
shear is implemented by looping over the source pixels and
distributing fractions to each of the destination pixels.  This has an
"anti-aliasing" effect - it avoids jagged edges and similar
artifacts.  However, it also means that the original colors or gray
levels in the image are modified.  If you need to keep precisely the
same set of colors, you can use the \fB-noantialias\fP option.
.PP
The program runs faster and uses less real memory with the
\fB-noantialias\fP option.  It uses a large amount of virtual memory
either way, as it keeps a copy of the input image and a copy of the
output image in memory, using 12 bytes per pixel for each.  But with
\fB-noantialias\fP, it accesses this memory sequentially in half a
dozen passes, with only a few pages of memory at a time required in
real memory.
.PP
In contrast, without \fB-noantialias\fP, the program's real memory
working set size is one page per input image row plus one page per output
image row.  Before Netpbm 10.16 (June 2003), \fB-noantialias\fP had the
same memory requirement.

.UN options
.SH OPTIONS
.PP
All options can be abbreviated to their shortest unique prefix.  You
may use two hyphens instead of one to designate an option.  You may
use either white space or equals signs between an option name and its
value.


.TP
\fB-background=\fP\fIcolor\fP
This determines the color of the background on which the rotated image
sits.
.sp
Specify the color (\fIcolor\fP) as described for the 
.UR libppm.html#colorname
argument of the \fBppm_parsecolor()\fP library routine
.UE
\&.
.sp
By default, if you don't specify this option, \fBpnmrotate\fP selects
what appears to it to be the background color of the original image.  It 
determines this color rather simplistically, by taking an average of the colors
of the two top corners of the image.
.sp
This option was new in Netpbm 10.15.  Before that, \fBpnmrotate\fP
always behaved as is the default now.

.TP
\fB-noantialias\fP
This option forces \fBpnmrotate\fP to simply move pixels around instead 
of synthesizing output pixels from multiple input pixels.  The latter could
cause the output to contain colors that are not in the input, which may not
be desirable.  It also probably makes the output contain a large number of
colors.  If you need a small number of colors, but it doesn't matter if they
are the exact ones from the input, consider using \fBpnmquant\fP on the 
output instead of using \fB-noantialias\fP.
.sp
Note that to ensure the output does not contain colors that are not
in the input, you also must consider the background color.  See the
\fB-background\fP option.



.UN references
.SH REFERENCES

"A Fast Algorithm for General Raster Rotation" by Alan Paeth,
Graphics Interface '86, pp. 77-81.

.UN seealso
.SH SEE ALSO
.BR "pnmshear" (1)\c
\&,
.BR "pamflip" (1)\c
\&,
.BR "pnmquant" (1)\c
\&,
.BR "pnm" (5)\c
\&

.UN author
.SH AUTHOR

Copyright (C) 1989, 1991 by Jef Poskanzer.
.SH DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source.  The master documentation is at
.IP
.B http://netpbm.sourceforge.net/doc/pnmrotate.html
.PP