Debian Codegraph @

userguide/pnmcrop.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.3//EN">
2 <html><head><title>Pnmcrop User Manual</title></head>
3 <body>
4 <h1>pnmcrop</h1>
5 Updated: 16 August 2020
6 <br>
7 <a href="#index">Table Of Contents</a>
8
9 <h2>NAME</h2>
10 pnmcrop - crop a Netpbm image
11
12 <h2 id="synopsis">SYNOPSIS</h2>
13
14 <b>pnmcrop</b>
15
16 [<b>-white</b>
17 |<b>-black</b>
18 |<b>-sides</b>
19 |<b>-bg-color=</b><i>color</i>
20 |<b>-bg-corner=</b>{
21 <b>topleft</b>|<b>topright</b>|<b>bottomleft</b>|<b>bottomright</b>}
22 ]
23
24 [<b>-left</b>]
25
26 [<b>-right</b>]
27
28 [<b>-top</b>]
29
30 [<b>-bottom</b>]
31
32 [<b>-margin=</b><i>pixels</i>]
33
34 [<b>-closeness=</b><i>closeness_percent</i>]
35
36 [<b>-borderfile=</b><i>filename</i>]
37
38 [<b>-blank-image=</b>{<b>abort</b>|<b>pass</b>|<b>minimize</b>|<b>maxcrop</b>}]
39
40 {[<b>-reportfull</b>]|[<b>-reportsize</b>]}
41
42 [<b>-verbose</b>]
43
44 [<i>pnmfile</i>]
45
46 <p>Minimum unique abbreviation of option is acceptable. You may use
47 double hyphens instead of single hyphen to denote options. You may use
48 white space in place of the equals sign to separate an option name
49 from its value.
50
51 <h2 id="description">DESCRIPTION</h2>
52
53 <p>This program is part of <a href="index.html">Netpbm</a>.
54
55 <p><b>pnmcrop</b> reads a PBM, PGM, or PPM image as input, removes
56 borders that are the background color, and produces the same type of
57 image as output.
58
59 <p>If you don't specify otherwise, <b>pnmcrop</b> assumes the
60 background color is whatever color the top left and right corners of
61 the image are and if they are different colors, something midway
62 between them. You can specify that the background is white or black
63 with the <b>-white</b> and <b>-black</b> options or make
64 <b>pnmcrop</b> base its guess on all four corners instead of just two
65 with <b>-sides</b>.
66
67 <p>By default, <b>pnmcrop</b> chops off any stripe of background color
68 it finds, on all four sides. You can tell <b>pnmcrop</b> to remove
69 only specific borders with the <b>-left</b>, <b>-right</b>,
70 <b>-top</b>, and <b>-bottom</b> options.
71
72 <p>But note that <b>pnmcrop</b>'s determination of the background color is
73 independent of which edges you crop, which may not be intuitive. For example,
74 imagine an image with a blue border at the top and a black border at the
75 bottom and you say to crop the bottom (<b>-bottom</b>). You may have expected
76 to crop the black border, but you actually won't crop anything,
77 because <b>pnmcrop</b> considers the background color to be whatever color the
78 top two corners are, which is blue, and there is no blue at the bottom of the
79 image. If you do want <b>pnmcrop</b> to take the background color from the
80 edges being cropped, use <b>-bg-corner</b>.
81
82 <p>If you want to leave some border, use the <b>-margin</b> option. It
83 will not only spare some of the border from cropping, but will fill in
84 (with what <b>pnmcrop</b> considers the background color) if necessary
85 to get up to that size.
86
87 <p>If the input is a multi-image stream, <b>pnmcrop</b> processes each
88 one independently and produces a multi-image stream as output. It chooses
89 where to crop independently for each image. So if you start with a stream
90 of images of the same dimensions, you may end up with images of differing
91 dimensions. Before Netpbm 10.37 (December 2006), <b>pnmcrop</b> ignored
92 all input images but the first.
93
94 <p>If you want to chop a specific amount off the side of an image, use
95 <b>pamcut</b>.
96
97 <p>If you want to add different borders after removing the existing ones,
98 use <b>pamcat</b> or <b>pamcomp</b>.
99
100
101 <h2 id="options">OPTIONS</h2>
102
103 <p>In addition to the options common to all programs based on libnetpbm
104 (most notably <b>-quiet</b>, see <a href="index.html#commonoptions">
105 Common Options</a>), <b>pnmcrop</b> recognizes the following
106 command line options:
107
108 <dl compact>
109 <dt><b>-white</b>
110
111 <dd>Take white to be the background color. <b>pnmcrop</b> removes
112 borders which are white.
113
114 <p>You may specify at most one of <b>-black</b>, <b>-white</b>, <b>-sides</b>,
115 <b>-bg-color</b>, and <b>-bg-corner</b>.
116
117 <dt><b>-black</b>
118
119 <dd>Take black to be the background color. <b>pnmcrop </b> removes
120 borders which are black.
121
122 <p>You may specify at most one of <b>-black</b>, <b>-white</b>, <b>-sides</b>,
123 <b>-bg-color</b>, and <b>-bg-corner</b>.
124
125 <dt><b>-bg-color=</b><i>color</i>
126
127 <dd>This tells <b>pnmcrop</b> what color is the background - it will crop
128 areas of this color. <i>color</i> is a value that would be used as the
129 <a href="libnetpbm_image.html#colorname">argument of the
130 <b>pnm_parsecolor()</b> library routine</a>.
131
132 <p>You may specify at most one of <b>-black</b>, <b>-white</b>, <b>-sides</b>,
133 <b>-bg-color</b>, and <b>-bg-corner</b>.
134
135 <p>This option was new in Netpbm 10.86 (March 2019).
136
137 <dt><b>-sides</b>
138
139 <dd>Determine the background color from the colors of the four corners
140 of the input image. <b>pnmcrop</b> removes borders which are of the
141 background color.
142
143 <p>If at least three of the four corners are the same color,
144 <b>pnmcrop </b> takes that as the background color. If not,
145 <b>pnmcrop</b> looks for two corners of the same color in the
146 following order, taking the first found as the background color: top,
147 left, right, bottom. If all four corners are different colors,
148 <b>pnmcrop</b> assumes an average of the four colors as the background
149 color.
150
151 <p>The <b>-sides</b> option slows <b>pnmcrop</b> down, as it reads the
152 entire image to determine the background color in addition to the up
153 to three times that it would read it without <b>-sides</b>.
154
155 <p>You may specify at most one of <b>-black</b>, <b>-white</b>, <b>-sides</b>,
156 <b>-bg-color</b>, and <b>-bg-corner</b>.
157
158 <dt><b>-bg-corner=</b>{<b>topleft</b>|<b>topright</b>|<b>bottomleft</b>|<b>bottomright</b>
159
160 <dd>This option indicates a corner which is background. <b>pnmcrop</b> will
161 use the color of this corner as the background color and crop edges of that
162 color.
163
164 <p>You may specify at most one of <b>-black</b>, <b>-white</b>, <b>-sides</b>,
165 <b>-bg-color</b>, and <b>-bg-corner</b>.
166
167 <p>This option was new in Netpbm 10.86 (March 2019).
168
169 <dt><b>-left</b>
170
171 <dd>Remove any left border.
172
173 <dt><b>-right</b>
174
175 <dd>Remove any right border.
176
177 <dt><b>-top</b>
178
179 <dd>Remove any top border.
180
181 <dt><b>-bottom</b>
182
183 <dd>Remove any bottom border.
184
185 <dt><b>-margin=</b><i>pixels</i>
186
187 <dd>Leave <i>pixels</i> pixels of border. Expand the border to this size
188 if necessary.
189
190 <p>This option was new in Netpbm 10.29 (August 2005).
191
192 <dt><b>-closeness=</b><i>closeness_percent</i>
193
194 <dd>Any color in the image that is at least this close to the operative
195 background color is considered to be background.
196
197 <p>You can use this if the image has borders that vary slightly in color, such
198 as would be the case in a photograph. Consider a photograph against a white
199 screen. The color of the screen varies slightly with shading and dirt and
200 such, but is still quite distinct in color from the subject of the
201 photograph. <b>pnmcrop</b> will choose some particular shade as the
202 background color and if you specify an appropriate <b>-closeness</b> value, it
203 will correctly identify all of the screen as background and crop it off.
204
205 <p>To implement more complex rules for identifying background, use
206 <b>-borderfile</b>.
207
208 <p>The default is zero, which means a pixel's color must exactly match the
209 background color for the pixel to be considered part of a background border.
210
211 <p>This option was new in Netpbm 10.78 (March 2017). With older Netpbm,
212 colors must match exactly.
213
214 <dt><b>-borderfile=</b><i>filename</i>
215
216 <dd>Use the image in the file named <i>filename</i> instead of the input
217 image to determine where the borders of the input image are and the
218 background color.
219
220 <p>Without this option, <b>pnmcrop</b> examines the input image and figures
221 out what part of the image is border and what part is foreground (not border),
222 as well as the background color. With this option, <b>pnmcrop</b> finds the
223 borders in one image, then uses the those four border sizes (left, right, top,
224 bottom) in cropping a different image. Furthermore, if you use
225 <b>-margin</b> to add borders, the color of those borders is the background
226 color <b>pnmcrop</b> detects in the border file.
227
228 <p>The point of this is that you may want to help <b>pnmcrop</b> to come to a
229 different conclusion as to where the borders are and what the background color
230 is by preprocessing the input image. For example, consider an image that has
231 speckles of noise in its borders. <b>pnmcrop</b> isn't smart enough to
232 recognize these as noise; it sees them as foreground image. So <b>pnmcrop</b>
233 considers most of your borders to be foreground and does not crop them off as
234 you want. To fix this, run the image through a despeckler such as
235 <b>pbmclean</b> and tell <b>pnmcrop</b> to use the despeckled version of the
236 image as the <b>-borderfile</b> image, but the original speckled version as
237 the input image. That way, you crop the borders, but retain the true
238 foreground image, speckles and all.
239
240 <p>The border file must have the same number of images in it as the input
241 file; the background color determination for image N of the input is based on
242 the image N of the border file.
243
244 <p>This option was new in Netpbm 10.29 (August 2005).
245
246 <p>Before Netpbm 10.46 (March 2009), the original image and not the
247 border file determines the background color. <b>pnmcrop</b>
248 fails if there is no apparent background color in the original image
249 (i.e. the corners of the image don't have a common color).
250
251 <dt><b>-blank-image=</b>{<b>abort</b>|<b>pass</b>|<b>minimize</b>|<b>maxcrop</b>}
252
253 <dd>This determines how <b>pnmcrop</b> handles an image which is entirely
254 background (blank), a case where cropping doesn't make much sense.
255
256 <dl>
257 <dt>abort
258 <dd>program fails, with explanatory message (default)
259
260 <dt>pass
261 <dd>Output image is the same as the input image.
262 <b>-margin</b> has no effect.
263
264 <dt>minimize
265 <dd>output is a single row, column, or pixel (of the background color).
266 If you crop both vertically and horizontally (the default), it is a
267 single pixel. If you crop only vertically, a single row, of the
268 original width. If you crop only horizontally, it is a single column,
269 of the original height.
270
271 <p>This is a somewhat incongruous result; the mathematically consistent
272 result of cropping the background from an image that is entirely
273 background would be an image with no pixels at all. But such a thing
274 does not exist in the Netpbm formats (and you probably wouldn't want
275 it anyway, because whoever processes this output may not tolerate
276 that).
277
278 <p>The background can be more than one color when you specify
279 <b>-closeness</b>, so it matters which row, column, or pixel remains.
280 If you crop on the top and not bottom, it is the last row that remains.
281 If you crop on both the top and bottom, it is the middle row that
282 remains. The other cases follow similarly.
283
284 <p>If you specify a margin (<b>-margin</b>), the output image consists
285 entirely of the margins; there is no single row, column, or pixel
286 between the margins. So with <b>-margin</b>, the incongruity
287 mentioned above does not exist. But before Netpbm 10.92 (September
288 2020), <b>-margin</b> was ignored with <b>-blank-image=minimize</b>.
289
290 <dt>maxcrop
291 <dd>This odd function selects a hypothetical cropping which is not even
292 possible, and therefore is valid only with <b>-reportfull</b> or
293 <b>-reportsize</b>. The cropping that this selects is a crop of the
294 entire image on every side on which you request cropping. So if you
295 request cropping only on the left, of a 600 pixel wide image, this
296 selects a cropping of 600 pixels from the left and none from the other
297 three sides. Note that were this cropping actually applied, this would
298 produce an image with no pixels, which is not a valid Netpbm image. But
299 it gets stranger still if you request cropping on both the right and the
300 left. In that case, the cropping selected is a cropping of 600 pixels
301 from both the right and left sides, which would leave a negative-width
302 image.
303 <p>
304 This is actually useful if you are trying to find a single set of
305 cropping parameters to crop a stream of images. To do this, you could
306 do a pass with <b>-reportsize</b> and <b>-blank-image=maxcrop</b> to
307 compute the maximum crop for each edge, and then use those numbers in
308 <b>-crop<i>xxx</i></b> options on a <b>pamcut</b> pass to do the crop.
309 In this scenario, any all-background (blank) images would have no effect
310 on the cropping parameters you compute. If you do this, you must give
311 special consideration to a stream with nothing but blank images.
312
313 </dl>
314
315 <p><b>-margin</b> is always ignored when the image is all background.
316
317 <p>This option was new in Netpbm 10.86 (March 2019).
318
319 <dt><b>-reportfull</b>
320
321 <dd>
322 With this option, <b>pnmcrop</b> does not actually crop anything. Instead, it
323 just prints to Standard Output parameters of the cropping it would have done.
324 The output is a single line per image, like in this example:
325
326 <pre>
327 <span style="font-family: monospace;">
328 0 +7 -20 -10 200 300 rgb-255:10/0/255 0.0
329 </span>
330 </pre>
331
332 <p>The line is composed of the following blank-delimited tokens:
333
334 <ol>
335 <li>how many pixels would be cropped or padded on the left. This is
336 a signed decimal number, where + means pad and - means crop. If there
337 would be no change, this is unsigned zero.
338
339 <li>same, but for the right side.
340
341 <li>same, but for the top.
342
343 <li>same, but for the bottom.
344
345 <li>the resulting image width in pixels, in decimal.
346
347 <li>the resulting image height in pixels, in decimal.
348
349 <li>The color <b>pnmcrop</b> took to be the background color, like
350 &quot;rgb-255:10/0/255&quot; (This is a format recognized by
351 the <a href="libnetpbm_image.html#colorname"><b>pnm_parsecolor()</b></a>
352 library routine). The maxval in the color specification is the maxval of
353 the image.
354
355 <li>The closeness value (see <b>-closeness</b> option) <b>pnmcrop</b>
356 used, in floating point decimal.
357 </ol>
358
359 <p>You cannot use <b>-borderfile</b> together with this option.
360
361 <p>This option was new in Netpbm 10.86 (March 2019).
362
363 <dt><b>-reportsize</b>
364 <dd>
365 This is like <b>-reportfull</b>, but reports only the left, right, top,
366 bottom, width, and height.
367
368 <p>You cannot use <b>-borderfile</b> together with this option.
369
370 <p>This option was new in Netpbm 10.86 (March 2019).
371
372 <dt><b>-verbose</b>
373
374 <dd>Print on Standard Error information about the processing,
375 including exactly how much is being cropped off of which sides.
376
377 </dl>
378
379 <h2 id="seealso">SEE ALSO</h2>
380
381 <b><a href="pamcut.html">pamcut</a></b>,
382
383 <b><a href="pamfile.html">pamfile</a></b>,
384
385 <b><a href="pnm.html">pnm</a></b>
386
387 <h2 id="author">AUTHOR</h2>
388
389 Copyright (C) 1989 by Jef Poskanzer.
390
391
392 <hr>
393 <h2 id="index">Table Of Contents</h2>
394 <ul>
395 <li><a href="#synopsis">SYNOPSIS</a>
396 <li><a href="#description">DESCRIPTION</a>
397 <li><a href="#options">OPTIONS</a>
398 <li><a href="#seealso">SEE ALSO</a>
399 <li><a href="#author">AUTHOR</a>
400 </ul>
401 </body>
402 </html>