1Pnmcrop User Manual(0) Pnmcrop User Manual(0)
2
6 pnmcrop - crop a Netpbm image
7
10 pnmcrop
11 [-white |-black |-sides |-bg-color=color |-bg-corner={
13 topleft|topright|bottomleft|bottomright} ]
14 [-left]
16 [-right]
18 [-top]
20 [-bottom]
22 [-margin=pixels]
24 [-closeness=closeness_percent]
26 [-borderfile=filename]
28 [-blank-image={abort|pass|minimize|maxcrop}]
30 {[-reportfull]|[-reportsize]}
32 [-verbose]
34 [pnmfile]
36 Minimum unique abbreviation of option is acceptable. You may use dou‐
38 ble hyphens instead of single hyphen to denote options. You may use
39 white space in place of the equals sign to separate an option name from
40 its value.
41
44 This program is part of Netpbm(1).
45 pnmcrop reads a PBM, PGM, or PPM image as input, removes borders that
47 are the background color, and produces the same type of image as out‐
48 put.
49 If you don't specify otherwise, pnmcrop assumes the background color is
51 whatever color the top left and right corners of the image are and if
52 they are different colors, something midway between them. You can
53 specify that the background is white or black with the -white and
54 -black options or make pnmcrop base its guess on all four corners
55 instead of just two with -sides.
56 By default, pnmcrop chops off any stripe of background color it finds,
58 on all four sides. You can tell pnmcrop to remove only specific bor‐
59 ders with the -left, -right,
60 -top, and -bottom options.
61 But note that pnmcrop's determination of the background color is inde‐
63 pendent of which edges you crop, which may not be intuitive. For exam‐
64 ple, imagine an image with a blue border at the top and a black border
65 at the bottom and you say to crop the bottom (-bottom). You may have
66 expected to crop the black border, but you actually won't crop any‐
67 thing, because pnmcrop considers the background color to be whatever
68 color the top two corners are, which is blue, and there is no blue at
69 the bottom of the image. If you do want pnmcrop to take the background
70 color from the edges being cropped, use -bg-corner.
71 If you want to leave some border, use the -margin option. It will not
74 only spare some of the border from cropping, but will fill in (with
75 what pnmcrop considers the background color) if necessary to get up to
76 that size.
77 If the input is a multi-image stream, pnmcrop processes each one inde‐
79 pendently and produces a multi-image stream as output. It chooses
80 where to crop independently for each image. So if you start with a
81 stream of images of the same dimensions, you may end up with images of
82 differing dimensions. Before Netpbm 10.37 (December 2006), pnmcrop
83 ignored all input images but the first.
84 If you want to chop a specific amount off the side of an image, use
86 pamcut.
87 If you want to add different borders after removing the existing ones,
89 use pnmcat or pamcomp.
90
94 -white Take white to be the background color. pnmcrop removes borders
95 which are white.
96 You may specify at most one of -black, -white, -sides, -bg-
98 color, and -bg-corner.
99 -black Take black to be the background color. pnmcrop removes borders
102 which are black.
103 You may specify at most one of -black, -white, -sides, -bg-
105 color, and -bg-corner.
106 -bg-color=color
109 This tells pnmcrop what color is the background - it will crop
110 areas of this color. color is a value that would be used as the
111 argument of the pnm_parsecolor() library routine
112 ⟨libnetpbm_image.html#colorname⟩ .
113 You may specify at most one of -black, -white, -sides, -bg-
115 color, and -bg-corner.
116 This option was new in Netpbm 10.86 (March 2019).
118 -sides Determine the background color from the colors of the four cor‐
121 ners of the input image. pnmcrop removes borders which are of
122 the background color.
123 If at least three of the four corners are the same color, pnm‐
125 crop takes that as the background color. If not, pnmcrop looks
126 for two corners of the same color in the following order, taking
127 the first found as the background color: top, left, right, bot‐
128 tom. If all four corners are different colors, pnmcrop assumes
129 an average of the four colors as the background color.
130 The -sides option slows pnmcrop down, as it reads the entire
132 image to determine the background color in addition to the up to
133 three times that it would read it without -sides.
134 You may specify at most one of -black, -white, -sides, -bg-
136 color, and -bg-corner.
137 -bg-corner={topleft|topright|bottomleft|bottomright
140 This option indicates a corner which is background. pnmcrop
141 will use the color of this corner as the background color and
142 crop edges of that color.
143 You may specify at most one of -black, -white, -sides, -bg-
145 color, and -bg-corner.
146 This option was new in Netpbm 10.86 (March 2019).
148 -left Remove any left border.
151 -right Remove any right border.
154 -top Remove any top border.
157 -bottom
160 Remove any bottom border.
161 -margin=pixels
164 Leave pixels pixels of border. Expand the border to this size
165 if necessary.
166 This option was new in Netpbm 10.29 (August 2005).
168 -closeness=closeness_percent
171 Any color in the image that is at least this close to the opera‐
173 tive background color is considered to be background.
174 You can use this if the image has borders that vary slightly in
176 color, such as would be the case in a photograph. Consider a
177 photograph against a white screen. The color of the screen
178 varies slightly with shading and dirt and such, but is still
179 quite distinct in color from the subject of the photograph.
180 pnmcrop will choose some particular shade as the background
181 color and if you specify an appropriate -closeness value, it
182 will correctly identify all of the screen as background and crop
183 it off.
184 To implement more complex rules for identifying background, use
186 -borderfile.
187 The default is zero, which means a pixel's color must exactly
189 match the background color for the pixel to be considered part
190 of a background border.
191 This option was new in Netpbm 10.78 (March 2017). With older
193 Netpbm, colors must match exactly.
194 -borderfile=filename
197 Use the image in the file named filename instead of the input
198 image to determine where the borders of the input image are and
199 the background color.
200 Without this option, pnmcrop examines the input image and fig‐
202 ures out what part of the image is border and what part is fore‐
203 ground (not border), as well as the background color. With this
204 option, pnmcrop finds the borders in one image, then uses the
205 those four border sizes (left, right, top, bottom) in cropping a
206 different image. Furthermore, if you use -margin to add bor‐
207 ders, the color of those borders is the background color pnmcrop
208 detects in the border file.
209 The point of this is that you may want to help pnmcrop to come
211 to a different conclusion as to where the borders are and what
212 the background color is by preprocessing the input image. For
213 example, consider an image that has speckles of noise in its
214 borders. pnmcrop isn't smart enough to recognize these as
215 noise; it sees them as foreground image. So pnmcrop considers
216 most of your borders to be foreground and does not crop them off
217 as you want. To fix this, run the image through a despeckler
218 such as pbmclean and tell pnmcrop to use the despeckled version
219 of the image as the -borderfile image, but the original speckled
220 version as the input image. That way, you crop the borders, but
221 retain the true foreground image, speckles and all.
222 The border file must have the same number of images in it as the
224 input file; the background color determination for image N of
225 the input is based on the image N of the border file.
226 This option was new in Netpbm 10.29 (August 2005).
228 Before Netpbm 10.46 (March 2009), the original image and not the
230 border file determines the background color. pnmcrop fails if
231 there is no apparent background color in the original image
232 (i.e. the corners of the image don't have a common color).
233 -blank-image={abort|pass|minimize|maxcrop}
236 This determines how pnmcrop handles an image which is entirely
237 background (blank), a case where cropping doesn't make much
238 sense.
239 abort
243 program fails, with explanatory message (default)
245 pass
248 no modification to image
250 minimize
253 output is a single pixel (of the background color)
255 maxcrop
258 This odd function selects a hypothetical cropping which is not
260 even
261 possible, and therefore is valid only with -reportfull or
262 -reportsize. The cropping that this selects is a crop of
263 the
264 entire image on every side on which you request cropping.
265 So if you
266 request cropping only on the left, of a 600 pixel wide
267 image, this
268 selects a cropping of 600 pixels from the left and none
269 from the other
270 three sides. Note that were this cropping actually
271 applied, this would
272 produce an image with no pixels, which is not a valid
273 Netpbm image. But
274 it gets stranger still if you request cropping on both the
275 right and the
276 left. In that case, the cropping selected is a cropping
277 of 600 pixels
278 from both the right and left sides, which would leave a
279 negative-width
280 image.
281 This is actually useful if you are trying to find a single
283 set of
284 cropping parameters to crop a stream of images. To do
285 this, you could
286 do a pass with -reportsize and -blank-image=maxcrop to
287 compute the maximum crop for each edge, and then use those
288 numbers in
289 -cropxxx options on a pamcut pass to do the crop.
290 In this scenario, any all-background (blank) images would
291 have no effect
292 on the cropping parameters you compute. If you do this,
293 you must give
294 special consideration to a stream with nothing but blank
295 images.
296 -margin is always ignored when the image is all background.
300 This option was new in Netpbm 10.86 (March 2019).
302 -reportfull
305 With this option, pnmcrop does not actually crop anything.
306 Instead, it just prints to Standard Output parameters of the
307 cropping it would have done. The output is a single line per
308 image, like in this example:
309 0 +7 -20 -10 200 300 rgb-255:10/0/255 0.0
312 The line is composed of the following blank-delimited tokens:
315 · how many pixels would be cropped or padded on the left. This is
319 a signed decimal number, where + means pad and - means crop.
320 If there
321 would be no change, this is unsigned zero.
322 · same, but for the right side.
325 · same, but for the top.
328 · same, but for the bottom.
331 · the resulting image width in pixels, in decimal.
334 · the resulting image height in pixels, in decimal.
337 · The color pnmcrop took to be the background color, like
340 'rgb-255:10/0/255' (This is a format recognized by
341 the pnm_parsecolor() ⟨libnetpbm_image.html#colorname⟩
342 library routine). The maxval in the color specification is
343 the maxval of
344 the image.
345 · The closeness value (see -closeness option) pnmcrop
348 used, in floating point decimal.
349 You cannot use -borderfile together with this option.
352 This option was new in Netpbm 10.86 (March 2019).
354 -reportsize
357 This is like -reportfull, but reports only the left, right, top,
358 bottom, width, and height.
359 You cannot use -borderfile together with this option.
361 This option was new in Netpbm 10.86 (March 2019).
363 -verbose
366 Print on Standard Error information about the processing,
367 including exactly how much is being cropped off of which sides.
368
373 pamcut(1), pamfile(1), pnm(1)
374
377 Copyright (C) 1989 by Jef Poskanzer.
378
380 This manual page was generated by the Netpbm tool 'makeman' from HTML
381 source. The master documentation is at
382 http://netpbm.sourceforge.net/doc/pnmcrop.html
384netpbm documentation 04 October 2019 Pnmcrop User Manual(0)