Debian Codegraph @

upstream/debian-trixie/man1/pamflip.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Pamflip User Manual" 1 "20 January 2008" "netpbm documentation"
7
8 .SH NAME
9
10 pamflip - flip or rotate a PAM or PNM image
11
12 .UN synopsis
13 .SH SYNOPSIS
14
15 \fBpamflip\fP
16 {
17 \fB-leftright\fP | \fB-lr\fP |
18 \fB-topbottom\fP | \fB-tb\fP |
19 \fB-transpose\fP | \fB-xy\fP |
20 \fB-rotate90\fP | \fB-r90\fP | \fB-cw\fP |
21 \fB-rotate270\fP | \fB-r270\fP | \fB-ccw\fP |
22 \fB-rotate180\fP | \fB-r180\fP
23 \fB-null\fP |
24 \fB-xform=\fP\fIxform1\fP\fB,\fP\fIxform2\fP...
25 }
26 [\fB-memsize=\fP\fImebibytes\fP]
27 [\fB-pagesize=\fP\fIbytes\fP]
28 [\fIpamfile\fP]
29 .PP
30 All options can be abbreviated to their shortest unique prefix. You
31 may use two hyphens instead of one to designate an option. You may
32 use either white space or an equals sign between an option name and
33 its value.
34
35
36 .UN description
37 .SH DESCRIPTION
38 .PP
39 This program is part of
40 .BR "Netpbm" (1)\c
41 \&.
42 .PP
43 \fBpamflip\fP flips a PAM or PNM image top for bottom or left for right,
44 or transposes it horizontal for vertical, or rotates it 1, 2, or 3 quarter
45 turns.
46 .PP
47 To rotate at other angles, use \fBpnmrotate\fP. It is much slower,
48 though.
49 .PP
50 The input image is \fIpamfile\fP, or Standard Input if \fIpamfile\fP
51 is not specified.
52 .PP
53 To flip/rotate a JFIF (JPEG) image losslessly, use \fBjpegtran\fP.
54 \fBjpegtran\fP is part of the Independent Jpeg Group's compression
55 library package, not part of Netpbm. The normal Netpbm way to flip a
56 JFIF file would be to convert it to PNM, use \fBpamflip\fP, and convert
57 back to JFIF. But since JPEG compression is lossy, the resulting image
58 would have less quality than the original. \fBjpegtran\fP, on the other
59 hand, can do this particular transformation directly on the compressed
60 data without loss.
61
62
63 .UN options
64 .SH OPTIONS
65 .PP
66 In addition to the options common to all programs based on libnetpbm
67 (most notably \fB-quiet\fP, see
68 .UR index.html#commonoptions
69 Common Options
70 .UE
71 \&), \fBpamflip\fP recognizes the following
72 command line options:
73
74 .UN transformation
75 .SS Specifying the Transformation
76 .PP
77 You must supply exactly one of the following options:
78 .PP
79 \fBpamflip\fP's predecessor (before Netpbm 10.7 - August 2002)
80 \fBpnmflip\fP did not have the \fB-xform\fP option and instead
81 allowed you to specify any number of the other options, including
82 zero. It applied all the indicated transformations, in the order
83 given, just like with \fBpamflip\fP's \fB-xform\fP option. (Reason
84 for the change: this kind of interpretation of options is inconsistent
85 with the rest of Netpbm and most of the Unix world, and thus hard to
86 understand and to implement).
87
88
89 .TP
90 \fB-leftright\fP
91 .TP
92 \fB-lr\fP
93 Flip left for right.
94
95 .TP
96 \fB-topbottom\fP
97 .TP
98 \fB-tb\fP
99 Flip top for bottom.
100
101 .TP
102 \fB-transpose\fP
103 .TP
104 \fB-xy\fP
105 Transpose horizontal for vertical. I.e. make the pixel at (x,y) be
106 at (y,x).
107
108 .TP
109 \fB-rotate90\fP
110 .TP
111 \fB-r90\fP
112 .TP
113 \fB-ccw\fP
114 Rotate counterclockwise 90 degrees.
115
116 .TP
117 \fB-rotate180\fP
118 .TP
119 \fB-r180\fP
120 Rotate 180 degrees.
121
122 .TP
123 \fB-rotate270\fP
124 .TP
125 \fB-r270\fP
126 .TP
127 \fB-cw\fP
128 Rotate counterclockwise 270 degrees (clockwise 90 degrees)
129
130 .TP
131 \fB-null\fP
132 No change. (The purpose of this option is the
133 convenience of programs that invoke \fBpamflip\fP after computing the
134 kind of transformation desired, including none at all).
135 .sp
136 This option was new in Netpbm 10.13 (December 2002).
137
138 .TP
139 \fB-xform=\fP\fIxform1\fP\fB,\fP\fIxform2\fP...
140 Apply all the transforms listed, in order. The valid values for
141 the transforms are as follows and have the same meanings as the
142 identically named options above.
143
144 .IP \(bu
145 leftright
146 .IP \(bu
147 topbottom
148 .IP \(bu
149 transpose
150
151 .sp
152 This option was new in Netpbm 10.13 (December 2002).
153
154
155
156 .UN memory
157 .SS Memory Management
158 .PP
159 The following options help \fBpamflip\fP use memory efficiently.
160 Some flipping operations on very large images can cause \fBpamflip\fP
161 to have a very large working set, which means if you don't have enough
162 real memory, the program can page thrash, which means it takes a
163 ridiculous amount time to run. If your entire image fits in real
164 memory, you don't have a problem. If you're just flipping top for
165 bottom or left for right, you don't have a problem. Otherwise, pay
166 attention. If you're interested in the details of the thrashing
167 problem and how \fBpamflip\fP approaches it, you're invited to read
168 a complete explanation in comments in the source code.
169
170
171 .TP
172 \fB-memsize=\fP\fImebibytes\fP
173 \fImebibytes\fP is the size in mebibytes (aka megabytes) of
174 memory available for \fBpamflip\fP. It is the lesser of the amount
175 of real or virtual memory available.
176
177 \fBpamflip\fP does nothing special to allocate real memory or control
178 its allocation -- it gets whatever it gets just by referencing
179 virtual memory normally. The real memory figure in question is the
180 maximum amount that \fBpamflip\fP can be expected to end up with by
181 doing that. This is just about impossible for you to know, of course,
182 but you can estimate. The total real memory in your system should be
183 a major factor in your estimate.
184 .sp
185 If \fBpamflip\fP cannot fit the entire image in the amount of
186 memory you specify, it does the transformation in chunks, using temporary
187 files for intermediate results.
188 .sp
189 In strict horizontal transformations (left for right) or the null
190 transformation, \fBpamflip\fP never keeps more than one row in memory, so the
191 memory size is irrelevant and \fBpamflip\fP doesn't use temporary files.
192 .sp
193 In strict vertical transformations (top for bottom), even when you
194 allow \fBpamflip\fP enough memory to keep the entire image in virtual memory,
195 it accesses it in a single pass, which does not cause any thrashing; the
196 chunks in temporary files thus don't help.
197 .sp
198 The real memory is important when you do a column for row type of
199 transformation (e.g. \fB-rotate90\fP). In that case, even if
200 \fBpamflip\fP can fit the entire image in virtual memory at once, if
201 it does not also fit in real memory, the program will thrash like
202 crazy because of the order in which \fBpamflip\fP accesses the
203 pixels, and that means it will take a ridiculously long time to run.
204 A proper \fB-memsize\fP drastically reduces the paging.
205 .sp
206 If you specify \fB-memsize\fP too large, \fBpamflip\fP may
207 attempt to get more virtual memory than the system allows it and fail.
208 If it can get the virtual memory, but \fB-memsize\fP is larger than
209 the amount of real memory the system allows it and the transformation
210 is row for column, it will page thrash and run very slowly. A value
211 even slightly too high is the same as infinity.
212 .sp
213 If you specify \fB-memsize\fP too small, the program will run
214 slightly more slowly because of extra overhead in manipulating temporary
215 files. Also, if your environment isn't set up to make temporary files
216 possible, \fBpamflip\fP will fail.
217 .sp
218 Doing the entire transformation "in memory" doesn't speed
219 things up as much as you might think, because even with the temporary
220 files, the data is just as likely to be in memory. Virtual memory
221 gets paged to disk and disk files get cached in memory. In fact, the
222 pixels fit much more compactly into memory when stored in a temporary
223 file than when stored "in memory" because \fBpamflip\fP
224 uses a more efficient format. So you're likely to have \fIless\fP
225 disk I/O when you allow \fBpamflip\fP less memory.
226 .sp
227 If you do not specify \fB-memsize\fP, \fBpamflip\fP assumes
228 infinity.
229 .sp
230 This option did not exist before Netpbm 10.7 (August 2002).
231 .sp
232 Before Netpbm 10.42 (March 2008), this option applied only to real
233 memory. \fBpamflip\fP would always keep the entire image in virtual
234 memory and if it could not get enough virtual memory, it failed.
235 \fBpamflip\fP accessed the pixels in an order designed to keep real
236 memory use within the specified amount.
237
238 .TP
239 \fB-pagesize=\fP\fIbytes\fP
240 \fIbytes\fP is the size in bytes of a paging unit -- the amount of
241 memory that gets paged in or out as an indivisible unit -- in your system.
242 The default is 4KiB.
243 .sp
244 This option has no effect.
245 .sp
246 Before Netpbm 10.42 (March 2008), \fBpamflip\fP used it to control its
247 use of real memory.
248 .sp
249 This option did not exist before Netpbm 10.7 (August 2002).
250
251
252
253 .UN misc
254 .SS Miscellaneous
255
256
257 .TP
258 \fB-verbose\fP
259 This option causes \fBpamflip\fP to issue messages to Standard Error
260 about its progress.
261
262
263 .UN seealso
264 .SH SEE ALSO
265 .BR "pnmrotate" (1)\c
266 \&,
267 .BR "pnm" (1)\c
268 \&,
269 .BR "pam" (1)\c
270 \&,
271 \fBjpegtran\fP manual
272
273 .UN history
274 .SH HISTORY
275 .PP
276 \fBpamflip\fP replaced \fBpnmflip\fP in Netpbm 10.13 (December 2002).
277 \fBpamflip\fP is backward compatible, but also works on PAM images.
278
279
280 .UN author
281 .SH AUTHOR
282
283 Copyright (C) 1989 by Jef Poskanzer.
284 .SH DOCUMENT SOURCE
285 This manual page was generated by the Netpbm tool 'makeman' from HTML
286 source. The master documentation is at
287 .IP
288 .B http://netpbm.sourceforge.net/doc/pamflip.html
289 .PP