Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Pnmcrop	User Manual(0)					Pnmcrop	User Manual(0)

       pnmcrop - crop a	Netpbm image


       [-white	    |-black	|-sides	    |-bg-color=color	 |-bg-corner={
       topleft|topright|bottomleft|bottomright}	]












       Minimum unique abbreviation of option is	acceptable.  You may use  dou-
       ble  hyphens  instead  of single	hyphen to denote options.  You may use
       white space in place of the equals sign to separate an option name from
       its value.

       This program is part of Netpbm(1).

       pnmcrop	reads  a PBM, PGM, or PPM image	as input, removes borders that
       are the background color, and produces the same type of image  as  out-

       If you don't specify otherwise, pnmcrop assumes the background color is
       whatever	color the top left and right corners of	the image are  and  if
       they  are  different  colors,  something	 midway	between	them.  You can
       specify that the	background is white  or	 black	with  the  -white  and
       -black  options	or make	pnmcrop	base its guess on all four corners in-
       stead of	just two with -sides.

       By default, pnmcrop chops off any stripe	of background color it	finds,
       on  all	four sides.  You can tell pnmcrop to remove only specific bor-
       ders with the -left, -right,
	 -top, and -bottom options.

       But note	that pnmcrop's determination of	the background color is	 inde-
       pendent of which	edges you crop,	which may not be intuitive.  For exam-
       ple, imagine an image with a blue border	at the top and a black	border
       at  the	bottom and you say to crop the bottom (-bottom).  You may have
       expected	to crop	the black border, but you  actually  won't  crop  any-
       thing,  because	pnmcrop	 considers the background color	to be whatever
       color the top two corners are, which is blue, and there is no  blue  at
       the bottom of the image.	 If you	do want	pnmcrop	to take	the background
       color from the edges being cropped, use -bg-corner.

       If you want to leave some border, use the -margin option.  It will  not
       only  spare  some  of  the border from cropping,	but will fill in (with
       what pnmcrop considers the background color) if necessary to get	up  to
       that size.

       If  the input is	a multi-image stream, pnmcrop processes	each one inde-
       pendently and produces a	multi-image  stream  as	 output.   It  chooses
       where  to  crop	independently  for each	image.	So if you start	with a
       stream of images	of the same dimensions,	you may	end up with images  of
       differing dimensions.  Before Netpbm 10.37 (December 2006), pnmcrop ig-
       nored all input images but the first.

       If you want to chop a specific amount off the side  of  an  image,  use

       If  you want to add different borders after removing the	existing ones,
       use pnmcat or pamcomp.

       -white Take white to be the background color.  pnmcrop removes  borders
	      which are	white.

	      You  may	specify	 at  most  one of -black, -white, -sides, -bg-
	      color, and -bg-corner.

       -black Take black to be the background color.  pnmcrop  removes borders
	      which are	black.

	      You  may	specify	 at  most  one of -black, -white, -sides, -bg-
	      color, and -bg-corner.

	      This tells pnmcrop what color is the background -	it  will  crop
	      areas of this color.  color is a value that would	be used	as the
	      argument	  of	the    pnm_parsecolor()	   library     routine
	      <libnetpbm_image.html#colorname> .

	      You  may	specify	 at  most  one of -black, -white, -sides, -bg-
	      color, and -bg-corner.

	      This option was new in Netpbm 10.86 (March 2019).

       -sides Determine	the background color from the colors of	the four  cor-
	      ners  of	the input image.  pnmcrop removes borders which	are of
	      the background color.

	      If at least three	of the four corners are	the same  color,  pnm-
	      crop  takes that as the background color.	 If not, pnmcrop looks
	      for two corners of the same color	in the following order,	taking
	      the  first found as the background color:	top, left, right, bot-
	      tom.  If all four	corners	are different colors, pnmcrop  assumes
	      an average of the	four colors as the background color.

	      The -sides option	slows pnmcrop down, as it reads	the entire im-
	      age to determine the background color in addition	to the	up  to
	      three times that it would	read it	without	-sides.

	      You  may	specify	 at  most  one of -black, -white, -sides, -bg-
	      color, and -bg-corner.

	      This option indicates a corner  which  is	 background.   pnmcrop
	      will  use	 the  color of this corner as the background color and
	      crop edges of that color.

	      You may specify at most one  of  -black,	-white,	 -sides,  -bg-
	      color, and -bg-corner.

	      This option was new in Netpbm 10.86 (March 2019).

       -left  Remove any left border.

       -right Remove any right border.

       -top   Remove any top border.

	      Remove any bottom	border.

	      Leave  pixels  pixels of border.	Expand the border to this size
	      if necessary.

	      This option was new in Netpbm 10.29 (August 2005).


	      Any color	in the image that is at	least this close to the	opera-
	      tive background color is considered to be	background.

	      You  can use this	if the image has borders that vary slightly in
	      color, such as would be the case in a  photograph.   Consider  a
	      photograph  against  a  white  screen.   The color of the	screen
	      varies slightly with shading and dirt and	 such,	but  is	 still
	      quite distinct in	color from the subject of the photograph.  pn-
	      mcrop will choose	some particular	shade as the background	 color
	      and if you specify an appropriate	-closeness value, it will cor-
	      rectly identify all of the screen	as background and crop it off.

	      To implement more	complex	rules for identifying background,  use

	      The  default  is	zero, which means a pixel's color must exactly
	      match the	background color for the pixel to be  considered  part
	      of a background border.

	      This  option  was	 new in	Netpbm 10.78 (March 2017).  With older
	      Netpbm, colors must match	exactly.

	      Use the image in the file	named filename instead	of  the	 input
	      image  to	determine where	the borders of the input image are and
	      the background color.

	      Without this option, pnmcrop examines the	input image  and  fig-
	      ures out what part of the	image is border	and what part is fore-
	      ground (not border), as well as the background color.  With this
	      option,  pnmcrop	finds  the borders in one image, then uses the
	      those four border	sizes (left, right, top, bottom) in cropping a
	      different	 image.	  Furthermore,	if you use -margin to add bor-
	      ders, the	color of those borders is the background color pnmcrop
	      detects in the border file.

	      The  point  of this is that you may want to help pnmcrop to come
	      to a different conclusion	as to where the	borders	are  and  what
	      the  background  color is	by preprocessing the input image.  For
	      example, consider	an image that has speckles  of	noise  in  its
	      borders.	 pnmcrop  isn't	 smart	enough	to  recognize these as
	      noise; it	sees them as foreground	image.	So  pnmcrop  considers
	      most of your borders to be foreground and	does not crop them off
	      as you want.  To fix this, run the image	through	 a  despeckler
	      such  as pbmclean	and tell pnmcrop to use	the despeckled version
	      of the image as the -borderfile image, but the original speckled
	      version as the input image.  That	way, you crop the borders, but
	      retain the true foreground image,	speckles and all.

	      The border file must have	the same number	of images in it	as the
	      input  file;  the	 background color determination	for image N of
	      the input	is based on the	image N	of the border file.

	      This option was new in Netpbm 10.29 (August 2005).

	      Before Netpbm 10.46 (March 2009),	the original image and not the
	      border  file  determines the background color.  pnmcrop fails if
	      there is no apparent background  color  in  the  original	 image
	      (i.e. the	corners	of the image don't have	a common color).

	      This determines how pnmcrop handles an image which is entirely
		background  (blank),  a	 case where cropping doesn't make much


	      program fails, with explanatory message (default)


	      no modification to image


	      output is	a single pixel (of the background color)


	      This odd function	selects	a hypothetical cropping	which  is  not
		    possible, and therefore is valid only with -reportfull or
		    -reportsize.   The cropping	that this selects is a crop of
		    entire image on every side on which	you request  cropping.
	      So if you
		    request cropping only on the left, of a 600	pixel wide im-
	      age, this
		    selects a cropping of 600 pixels from the  left  and  none
	      from the other
		    three  sides.   Note  that were this cropping actually ap-
	      plied, this would
		    produce an image with no pixels,  which  is	 not  a	 valid
	      Netpbm image.  But
		    it gets stranger still if you request cropping on both the
	      right and	the
		    left.  In that case, the cropping selected is  a  cropping
	      of 600 pixels
		    from  both	the  right and left sides, which would leave a

		    This is actually useful if you are trying to find a	single
	      set of
		    cropping  parameters  to  crop  a stream of	images.	 To do
	      this, you	could
		    do a pass with -reportsize and -blank-image=maxcrop	to
		    compute the	maximum	crop for each edge, and	then use those
	      numbers in
		    -cropxxx options on	a pamcut pass to do the	crop.
		    In	this scenario, any all-background (blank) images would
	      have no effect
		    on the cropping parameters you compute.  If	you  do	 this,
	      you must give
		    special  consideration  to a stream	with nothing but blank

	      -margin is always	ignored	when the image is all background.

	      This option was new in Netpbm 10.86 (March 2019).

	      With this	option,	pnmcrop	does not actually crop anything.   In-
	      stead, it	just prints to Standard	Output parameters of the crop-
	      ping it would have done.	The output is a	single line per	image,
	      like in this example:

		   0 +7	-20 -10	200 300	rgb-255:10/0/255 0.0

	      The line is composed of the following blank-delimited tokens:

       o      how many pixels would be cropped or padded on the	left.  This is
		  a signed decimal number, where + means pad and - means crop.
	      If there
		  would	be no change, this is unsigned zero.

       o      same, but	for the	right side.

       o      same, but	for the	top.

       o      same, but	for the	bottom.

       o      the resulting image width	in pixels, in decimal.

       o      the resulting image height in pixels, in decimal.

       o      The color	pnmcrop	took to	be the background color, like
		 'rgb-255:10/0/255' (This is a format recognized by
		 the pnm_parsecolor() <libnetpbm_image.html#colorname>
		 library routine).  The	maxval in the color  specification  is
	      the maxval of
		 the image.

       o      The closeness value (see -closeness option) pnmcrop
		 used, in floating point decimal.

	      You cannot use -borderfile together with this option.

	      This option was new in Netpbm 10.86 (March 2019).

	      This is like -reportfull,	but reports only the left, right, top,
	      bottom, width, and height.

	      You cannot use -borderfile together with this option.

	      This option was new in Netpbm 10.86 (March 2019).

	      Print on Standard	Error information about	 the  processing,  in-
	      cluding exactly how much is being	cropped	off of which sides.

       pamcut(1), pamfile(1), pnm(5)

       Copyright (C) 1989 by Jef Poskanzer.

       This  manual  page was generated	by the Netpbm tool 'makeman' from HTML
       source.	The master documentation is at

netpbm documentation		04 October 2019		Pnmcrop	User Manual(0)


Want to link to this manual page? Use this URL:

home | help