1Pnmcrop User Manual(0)                                  Pnmcrop User Manual(0)
2
3
4

NAME

6       pnmcrop - crop a Netpbm image
7
8

SYNOPSIS

10       pnmcrop
11
12       [-white      |-black     |-sides     |-bg-color=color     |-bg-corner={
13       topleft|topright|bottomleft|bottomright} ]
14
15       [-left]
16
17       [-right]
18
19       [-top]
20
21       [-bottom]
22
23       [-margin=pixels]
24
25       [-closeness=closeness_percent]
26
27       [-borderfile=filename]
28
29       [-blank-image={abort|pass|minimize|maxcrop}]
30
31       {[-reportfull]|[-reportsize]}
32
33       [-verbose]
34
35       [pnmfile]
36
37       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
42

DESCRIPTION

44       This program is part of Netpbm(1).
45
46       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
50       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
57       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
62       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
72
73       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
78       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
85       If you want to chop a specific amount off the side  of  an  image,  use
86       pamcut.
87
88       If  you want to add different borders after removing the existing ones,
89       use pnmcat or pamcomp.
90
91
92

OPTIONS

94       -white Take white to be the background color.  pnmcrop removes  borders
95              which are white.
96
97              You  may  specify  at  most  one of -black, -white, -sides, -bg-
98              color, and -bg-corner.
99
100
101       -black Take black to be the background color.  pnmcrop  removes borders
102              which are black.
103
104              You  may  specify  at  most  one of -black, -white, -sides, -bg-
105              color, and -bg-corner.
106
107
108       -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
114              You  may  specify  at  most  one of -black, -white, -sides, -bg-
115              color, and -bg-corner.
116
117              This option was new in Netpbm 10.86 (March 2019).
118
119
120       -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
124              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
131              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
135              You  may  specify  at  most  one of -black, -white, -sides, -bg-
136              color, and -bg-corner.
137
138
139       -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
144              You may specify at most one  of  -black,  -white,  -sides,  -bg-
145              color, and -bg-corner.
146
147              This option was new in Netpbm 10.86 (March 2019).
148
149
150       -left  Remove any left border.
151
152
153       -right Remove any right border.
154
155
156       -top   Remove any top border.
157
158
159       -bottom
160              Remove any bottom border.
161
162
163       -margin=pixels
164              Leave  pixels  pixels of border.  Expand the border to this size
165              if necessary.
166
167              This option was new in Netpbm 10.29 (August 2005).
168
169
170       -closeness=closeness_percent
171
172              Any color in the image that is at least this close to the opera‐
173              tive background color is considered to be background.
174
175              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
185              To  implement more complex rules for identifying background, use
186              -borderfile.
187
188              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
192              This option was new in Netpbm 10.78 (March  2017).   With  older
193              Netpbm, colors must match exactly.
194
195
196       -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
201              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
210              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
223              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
227              This option was new in Netpbm 10.29 (August 2005).
228
229              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
234
235       -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
240
241
242       abort
243
244              program fails, with explanatory message (default)
245
246
247       pass
248
249              no modification to image
250
251
252       minimize
253
254              output is a single pixel (of the background color)
255
256
257       maxcrop
258
259              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
282                    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
297
298
299              -margin is always ignored when the image is all background.
300
301              This option was new in Netpbm 10.86 (March 2019).
302
303
304       -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
310
311                   0 +7 -20 -10 200 300 rgb-255:10/0/255 0.0
312
313
314              The line is composed of the following blank-delimited tokens:
315
316
317
318       ·      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
323
324       ·      same, but for the right side.
325
326
327       ·      same, but for the top.
328
329
330       ·      same, but for the bottom.
331
332
333       ·      the resulting image width in pixels, in decimal.
334
335
336       ·      the resulting image height in pixels, in decimal.
337
338
339       ·      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
346
347       ·      The closeness value (see -closeness option) pnmcrop
348                 used, in floating point decimal.
349
350
351              You cannot use -borderfile together with this option.
352
353              This option was new in Netpbm 10.86 (March 2019).
354
355
356       -reportsize
357              This is like -reportfull, but reports only the left, right, top,
358              bottom, width, and height.
359
360              You cannot use -borderfile together with this option.
361
362              This option was new in Netpbm 10.86 (March 2019).
363
364
365       -verbose
366              Print  on  Standard  Error  information  about  the  processing,
367              including exactly how much is being cropped off of which sides.
368
369
370
371

SEE ALSO

373       pamcut(1), pamfile(1), pnm(1)
374
375

AUTHOR

377       Copyright (C) 1989 by Jef Poskanzer.
378

DOCUMENT SOURCE

380       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
381       source.  The master documentation is at
382
383              http://netpbm.sourceforge.net/doc/pnmcrop.html
384
385netpbm documentation            04 October 2019         Pnmcrop User Manual(0)
Impressum