NAME

       pgmtoppm - colorize a PGM (grayscale) image into a PPM (color) image

SYNOPSIS

       pgmtoppm [-black=colorspec1] [-white=colorspec2]
        [pgmfile]   pgmtoppm   -map=filename  [pgmfile]  pgmtoppm  colorspec  [pgmfile]  pgmtoppm
       colorspec1-colorspec2 [pgmfile]

       Minimum unique abbreviation of option is 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).

       If all you want to do is convert PGM to PPM, keeping the same gray pixels,
         you may not need to.  All Netpbm programs that expect PPM input also
         recognize PGM.  And if you must have a PPM file, use ppmtoppm
         instead.  It is more efficient and easier to use.

       pgmtoppm reads a PGM as input and produces a PPM file as  output  with  a  specific  color
       assigned to each gray value in the input.

       You can specify the color in the output to which black in the input maps,
         and the color to which white maps.  All the gray values in between map
         linearly (across a three dimensional space) to colors between the black and
         white colors you specify.

       Use the -black and -white options for this.  For historical
         reasons, you can alternatively use a non-option argument to specify the
         colors.  If you do that, pgmtoppm interprets the color argument
         like this: if the argument takes the form black-white,
         it has the effect of -black=black -white=white
         If instead there is no hyphen in the color argument, it has the effect of
         -white=color_argument.

       Because of the historical syntax, it is not possible to let both
         -black and -white default (but you shouldn't want to --
         see below for advice on making such a null conversion).

       You can alternatively specify an entire colormap with the -map option.

       A  more  direct way to specify a particular color to replace each particular gray level is
       to use pamlookup.  You make an index file that explicitly associates  a  color  with  each
       possible gray level.

OPTIONS

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

       -black=colorspec
              The  program  maps  black  pixels  in  the  input to this color in the output.  The
              default is black.

              Specify the color (color) as described for the  argument  of  the  pnm_parsecolor()
              library routine ⟨libnetpbm_image.html#colorname⟩ .

              You cannot specify this together with -map.

              This option was new in Netpbm 10.97 (December 2021).  Before that,
                use the color argument.

       -white=colorspec
              The  program  maps  white  pixels  in  the  input to this color in the output.  The
              default is white.

              Specify the color (color) as described for the  argument  of  the  pnm_parsecolor()
              library routine ⟨libnetpbm_image.html#colorname⟩ .

              You cannot specify this together with -map.

              This option was new in Netpbm 10.97 (December 2021).  Before that,
                use the color argument.

       -map=filename
              This option specifies a complete mapping of gray values in the input to
                  color values in the output.  The map file (named filename) is just
                  a ppm file; it can be any shape, all that matters is the colors in
                  it and their order.  In this case, black gets mapped into the first color
                  in the map file, and white gets mapped to the last and gray values in
                  between are mapped linearly onto the sequence of colors in between.  The
                  maxval of the output image is the maxval of the map image.

NOTE - MAXVAL

       When  you  don't use -map, the "maxval," or depth, of the output image is the same as that
       of the input image.  The maxval affects the color resolution, which may cause quantization
       errors  you  don't  anticipate  in  your output.  For example, you have a simple black and
       white image as a PGM with maxval 1.  Run this image through pgmtoppm 0f/00/00  to  try  to
       make  the  image  black  and faint red.  Because the output image will also have maxval 1,
       there is no such thing as faint red.  It has to be either full-on red or black.   pgmtoppm
       rounds  the  color 0f/00/00 down to black, and you get an output image that is nothing but
       black.

       The fix is easy: Pass the input through pamdepth on the way into pgmtoppm to increase  its
       depth  to something that would give you the resolution you need to get your desired color.
       In this case, pamdepth 16 would do it.  Or spare yourself  the  unnecessary  thinking  and
       just say pamdepth 255.

       PBM input is a special case.  While you might think this would be equivalent to a PGM with
       maxval 1 since only two gray levels are necessary to represent a PBM image, pgmtoppm, like
       all Netpbm programs, in fact treats it as a maxval of 255.

SEE ALSO

       ppmtoppm(1), pamdepth(1), rgb3toppm(1), ppmtopgm(1), ppmtorgb3(1), ppm(1), pgm(1)

AUTHOR

       Copyright (C) 1991 by Jef Poskanzer.

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/pgmtoppm.html