\
.\" 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 "Pamflip User Manual" 1 "20 January 2008" "netpbm documentation"

.SH NAME

pamflip - flip or rotate a PAM or PNM image

.UN synopsis
.SH SYNOPSIS

\fBpamflip\fP
{
\fB-leftright\fP | \fB-lr\fP |
\fB-topbottom\fP | \fB-tb\fP |
\fB-transpose\fP | \fB-xy\fP |
\fB-rotate90\fP | \fB-r90\fP | \fB-cw\fP |
\fB-rotate270\fP | \fB-r270\fP | \fB-ccw\fP |
\fB-rotate180\fP | \fB-r180\fP
\fB-null\fP |
\fB-xform=\fP\fIxform1\fP\fB,\fP\fIxform2\fP...
}
[\fB-memsize=\fP\fImebibytes\fP]
[\fB-pagesize=\fP\fIbytes\fP]
[\fIpamfile\fP]
.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 an equals sign between an option name and
its value.


.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBpamflip\fP flips a PAM or PNM image top for bottom or left for right,
or transposes it horizontal for vertical, or rotates it 1, 2, or 3 quarter
turns.
.PP
To rotate at other angles, use \fBpnmrotate\fP.  It is much slower,
though.
.PP
The input image is \fIpamfile\fP, or Standard Input if \fIpamfile\fP
is not specified.
.PP
To flip/rotate a JFIF (JPEG) image losslessly, use \fBjpegtran\fP.
\fBjpegtran\fP is part of the Independent Jpeg Group's compression
library package, not part of Netpbm.  The normal Netpbm way to flip a
JFIF file would be to convert it to PNM, use \fBpamflip\fP, and convert
back to JFIF.  But since JPEG compression is lossy, the resulting image
would have less quality than the original.  \fBjpegtran\fP, on the other
hand, can do this particular transformation directly on the compressed
data without loss.


.UN options
.SH OPTIONS
.PP
In addition to the options common to all programs based on libnetpbm
(most notably \fB-quiet\fP, see 
.UR index.html#commonoptions
 Common Options
.UE
\&), \fBpamflip\fP recognizes the following
command line options:

.UN transformation
.SS Specifying the Transformation
.PP
You must supply exactly one of the following options:
.PP
\fBpamflip\fP's predecessor (before Netpbm 10.7 - August 2002)
\fBpnmflip\fP did not have the \fB-xform\fP option and instead
allowed you to specify any number of the other options, including
zero.  It applied all the indicated transformations, in the order
given, just like with \fBpamflip\fP's \fB-xform\fP option.  (Reason
for the change: this kind of interpretation of options is inconsistent
with the rest of Netpbm and most of the Unix world, and thus hard to
understand and to implement).


.TP
\fB-leftright\fP
.TP
\fB-lr\fP
Flip left for right.

.TP
\fB-topbottom\fP
.TP
\fB-tb\fP
Flip top for bottom.

.TP
\fB-transpose\fP
.TP
\fB-xy\fP
Transpose horizontal for vertical.  I.e. make the pixel at (x,y) be
at (y,x).

.TP
\fB-rotate90\fP
.TP
\fB-r90\fP
.TP
\fB-ccw\fP
Rotate counterclockwise 90 degrees.

.TP
\fB-rotate180\fP
.TP
\fB-r180\fP
Rotate 180 degrees.

.TP
\fB-rotate270\fP
.TP
\fB-r270\fP
.TP
\fB-cw\fP
Rotate counterclockwise 270 degrees (clockwise 90 degrees)

.TP
\fB-null\fP 
No change.  (The purpose of this option is the
convenience of programs that invoke \fBpamflip\fP after computing the
kind of transformation desired, including none at all).
.sp
This option was new in Netpbm 10.13 (December 2002).
     
.TP
\fB-xform=\fP\fIxform1\fP\fB,\fP\fIxform2\fP...
Apply all the transforms listed, in order.  The valid values for
the transforms are as follows and have the same meanings as the
identically named options above.

.IP \(bu
leftright
.IP \(bu
topbottom
.IP \(bu
transpose

.sp
This option was new in Netpbm 10.13 (December 2002).



.UN memory
.SS Memory Management
.PP
The following options help \fBpamflip\fP use memory efficiently.
Some flipping operations on very large images can cause \fBpamflip\fP
to have a very large working set, which means if you don't have enough
real memory, the program can page thrash, which means it takes a
ridiculous amount time to run.  If your entire image fits in real
memory, you don't have a problem.  If you're just flipping top for
bottom or left for right, you don't have a problem.  Otherwise, pay
attention.  If you're interested in the details of the thrashing
problem and how \fBpamflip\fP approaches it, you're invited to read
a complete explanation in comments in the source code.


.TP
\fB-memsize=\fP\fImebibytes\fP
\fImebibytes\fP is the size in mebibytes (aka megabytes) of
memory available for \fBpamflip\fP.  It is the lesser of the amount
of real or virtual memory available.

\fBpamflip\fP does nothing special to allocate real memory or control
its allocation -- it gets whatever it gets just by referencing
virtual memory normally.  The real memory figure in question is the
maximum amount that \fBpamflip\fP can be expected to end up with by
doing that.  This is just about impossible for you to know, of course,
but you can estimate.  The total real memory in your system should be
a major factor in your estimate.
.sp
If \fBpamflip\fP cannot fit the entire image in the amount of
memory you specify, it does the transformation in chunks, using temporary
files for intermediate results.
.sp
In strict horizontal transformations (left for right) or the null
transformation, \fBpamflip\fP never keeps more than one row in memory, so the
memory size is irrelevant and \fBpamflip\fP doesn't use temporary files.
.sp
In strict vertical transformations (top for bottom), even when you
allow \fBpamflip\fP enough memory to keep the entire image in virtual memory,
it accesses it in a single pass, which does not cause any thrashing; the
chunks in temporary files thus don't help.
.sp
The real memory is important when you do a column for row type of
transformation (e.g. \fB-rotate90\fP).  In that case, even if
\fBpamflip\fP can fit the entire image in virtual memory at once, if
it does not also fit in real memory, the program will thrash like
crazy because of the order in which \fBpamflip\fP accesses the
pixels, and that means it will take a ridiculously long time to run.
A proper \fB-memsize\fP drastically reduces the paging.
.sp
If you specify \fB-memsize\fP too large, \fBpamflip\fP may
attempt to get more virtual memory than the system allows it and fail.
If it can get the virtual memory, but \fB-memsize\fP is larger than
the amount of real memory the system allows it and the transformation
is row for column, it will page thrash and run very slowly.  A value
even slightly too high is the same as infinity.
.sp
If you specify \fB-memsize\fP too small, the program will run
slightly more slowly because of extra overhead in manipulating temporary
files.  Also, if your environment isn't set up to make temporary files
possible, \fBpamflip\fP will fail.
.sp
Doing the entire transformation "in memory" doesn't speed
things up as much as you might think, because even with the temporary
files, the data is just as likely to be in memory.  Virtual memory
gets paged to disk and disk files get cached in memory.  In fact, the
pixels fit much more compactly into memory when stored in a temporary
file than when stored "in memory" because \fBpamflip\fP
uses a more efficient format.  So you're likely to have \fIless\fP
disk I/O when you allow \fBpamflip\fP less memory.
.sp
If you do not specify \fB-memsize\fP, \fBpamflip\fP assumes
infinity.
.sp
This option did not exist before Netpbm 10.7 (August 2002).
.sp
Before Netpbm 10.42 (March 2008), this option applied only to real
memory.  \fBpamflip\fP would always keep the entire image in virtual
memory and if it could not get enough virtual memory, it failed.
\fBpamflip\fP accessed the pixels in an order designed to keep real
memory use within the specified amount.
     
.TP
\fB-pagesize=\fP\fIbytes\fP
\fIbytes\fP is the size in bytes of a paging unit -- the amount of
memory that gets paged in or out as an indivisible unit -- in your system.
The default is 4KiB.
.sp
This option has no effect.
.sp
Before Netpbm 10.42 (March 2008), \fBpamflip\fP used it to control its
use of real memory.
.sp
This option did not exist before Netpbm 10.7 (August 2002).



.UN misc
.SS Miscellaneous


.TP
\fB-verbose\fP
This option causes \fBpamflip\fP to issue messages to Standard Error
about its progress.


.UN seealso
.SH SEE ALSO
.BR "pnmrotate" (1)\c
\&, 
.BR "pnm" (1)\c
\&,
.BR "pam" (1)\c
\&,
\fBjpegtran\fP manual

.UN history
.SH HISTORY
.PP
\fBpamflip\fP replaced \fBpnmflip\fP in Netpbm 10.13 (December 2002).
\fBpamflip\fP is backward compatible, but also works on PAM images.


.UN author
.SH AUTHOR

Copyright (C) 1989 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/pamflip.html
.PP