NAME

       pambackground - create a mask of the background area of an image

SYNOPSIS

       pambackground

       [netpbmfile]

       [-verbose]

       Minimum  unique  abbreviations  of  options  are  acceptable.   You may use double 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.

DESCRIPTION

       This program is part of Netpbm(1).

       pambackground  reads a PNM or PAM image as input.  It generates as output a PAM image that
       identifies the background area of the image (a mask).

       To identify the background, pambackground assumes the image is a foreground image, smaller
       than  the  total  image  size,  placed  over  a  single-color background.  It assumes that
       foreground image is solid -- it does not have holes through which the  background  can  be
       seen.  So in specific, pambackground first identifies the background color, then finds all
       contiguous pixels of that color in regions touching any edge of the image.  Think of it as
       starting  at each of the four edges and moving inward and spreading out as far as possible
       until it hits pixels of another color (the foreground image).

       pambackground identifies the background color as follows: If any 3 corners  of  the  image
       are  the  same  color,  that's  the  background color.  If not, but 2 corners are the same
       color, the background color is the color of a pair of identically colored corners in  this
       priority  order:  top,  right,  left,  bottom.  If no two corners have the same color, the
       background color is the color of the upper left corner.

       In a typical photograph, the area that you would consider the background is many shades of
       a color, so to pambackground it is multiple colors and pambackground will not meaningfully
       identify the background of your image.  To use pambackground in this case, you  might  use
       ppmchange  to  change  all  similar  colors  to  a  single one first.  For example, if the
       photograph is a building against a blue sky, where nothing remotely  sky-blue  appears  in
       the  building,  you  could  use  ppmchange to change all pixels within 20% of "SkyBlue" to
       SkyBlue, then run pambackground on it.

       You might even extract the argument for  ppmchange  from  the  image  in  question,  using
       pamgetcolor.   In the foregoing example, we knew the background was approximately SkyBlue,
       but if we didn't we could just get the color of the top left pixel, in a form suitable for
       the color arguments of ppmchange like this:

           $ color=$(pamgetcolor 0,0 -infile=/tmp/bodyskl|cut --fields=2 -delim=' ')

       A  more  convenient  means  of dealing with a multi-shade background is to use pnmquant to
       produce a version of the image with a very small number of colors.  The  background  would
       likely then be all one color.

       If  the  pnmquant  and  ppmchange  methods  above do not adequately distinguish foreground
       colors from background colors, you can try a more elaborate method using pnmremap.  If you
       can  manually  create  a  palette  with  one  color to which all the background pixels are
       similar, and other colors to which the foreground pixels are similar, you can  use  it  as
       input  to  pnmremap  to  create  a  smarter  version  of what you get with the pnmquant or
       ppmchange methods, so that pambackground  is  more  likely  to  separate  background  from
       foreground as your eye does.

       The  PAM  that  pambackground  creates has a single plane, with a maxval of 1.  The sample
       value 1 means background; 0 means  foreground.   There  is  no  tuple  type.   Some  older
       programs  (but none that are part of Netpbm) don't know what a PAM is and expect a mask to
       be in the form of a PGM or PBM image.  To  convert  pambackground's  output  to  PBM,  use
       pamtopnm -assume.  To convert to PGM, use pgmtopgm.

       netpbmfile  is  the file specification of the input file, or - to indicate Standard Input.
       The default is Standard Input.

       A common use for a background  mask  is  with  pamcomp.   You  could  replace  the  entire
       background (or foreground) of your image with something else.

       Another  common  use  is  to  make an image with the background transparent (in some image
       format that has a concept of transparency) so that image  can  be  overlaid  onto  another
       image  later.   Netpbm's converters to image formats that have transparency (e.g. PNG) let
       you use the mask that pambackground generates to identify the transparent  areas  for  the
       output.  You can create a PAM image with transparency with pamstack.

       To  simply  make  a  mask of all the areas of a specified color, use ppmcolormask.  If you
       have a unique background color (one that doesn't occur in the foreground) and know what it
       is,  this can create a background mask in cases that pambackground cannot: where there are
       see-through holes in the foreground image.

OPTIONS

       In addition to the options common to all programs based on libnetpbm (most notably -quiet,
       see
        Common  Options  ⟨index.html#commonoptions⟩  ),  pambackground  recognizes  the following
       command line option:

       -verbose
              Tell interesting facts about the process.

EXAMPLES

           $ pambackground test.ppm | pnminvert >/tmp/bgmask.pgm
           $ pamcomp -alpha=bgmask.pgm test.ppm wallpaper.ppm >output.ppm

           $ pnmquant 5 test.pgm | pambackground test.ppm >/tmp/bgmask.pam

SEE ALSO

       ppmcolormask(1),  pamcomp(1),   ppmchange(1),   pnmquant(1),   pnmremap(1),   pamtopnm(1),
       pgmtopgm(1), pamstack(1), pamgetcolor(1), pbmmaskd(1), pnm(1), pam(1),

HISTORY

       pambackground was new in Netpbm 10.37 (December 2006).

DOCUMENT SOURCE

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

              http://netpbm.sourceforge.net/doc/pambackground.html