Manual: pgmtoppm

Pgmtoppm User Manual(1)				   General Commands Manual			     Pgmtoppm User Manual(1)

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  ),
       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 .

	      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 .

	      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

netpbm documentation				       02 October 2021				     Pgmtoppm User Manual(1)