Debian Codegraph @

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