Debian Codegraph @

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