pgmtoppm

Map all greyscale values of the input image to all colors between the two specified colors

$ pgmtoppm [[-b|-black]] [red] [[-w|-white]] [blue] [path/to/input.pgm] > [path/to/output.ppm]

$ pgmtoppm [[-m|-map]] [path/to/colormap.ppm] [path/to/input.pgm] > [path/to/output.ppm]

pgmtoppm [-white | -black] [-color=colorname | #rgb] [-red=value] [-green=value] [-blue=value] [pgmfile]

-white
    Maps the maximum intensity (white) pixels of the PGM image to the specified color. Intermediate grayscale values will be scaled between this color and black.

-black
    Maps the zero intensity (black) pixels of the PGM image to the specified color. Intermediate grayscale values will be scaled between black and this color.

-color=colorname | #rgb
    Specifies the target color to be used with either -white or -black. It can be a color name (from rgb.txt, e.g., "red") or a hexadecimal RGB value (e.g., "#FF0000").

-red=value
    Sets the red component of the target color. The value is an integer between 0 and 255 (or 0 and the image's maxval).

-green=value
    Sets the green component of the target color. The value is an integer between 0 and 255 (or 0 and the image's maxval).

-blue=value
    Sets the blue component of the target color. The value is an integer between 0 and 255 (or 0 and the image's maxval).

pgmfile
    The path to the input PGM image file. If this argument is omitted, pgmtoppm reads the image data from standard input.

pgmtoppm is a utility within the Netpbm package designed to convert images from the Portable Graymap (PGM) format to the Portable Pixmap (PPM) format. While both are part of the Netpbm family, PGM represents grayscale images, and PPM represents color images.

This command doesn't truly "color" an image in the artistic sense; instead, it maps grayscale intensity values to color values. You can specify a target color for either the black (zero intensity) or white (maximum intensity) pixels of the PGM image. Intermediate grayscale values are then linearly interpolated to create a gradient between the specified color and black (or vice versa).

It is commonly used in pipelines for image processing, allowing grayscale images to be integrated into workflows that require color formats or to apply a simple color tint. If no color options are specified, it effectively converts a PGM to a PPM where all color components (Red, Green, Blue) are set to the original PGM intensity, resulting in a grayscale PPM image.

You cannot specify both -white and -black options simultaneously; only one mapping extreme (black or white) can be controlled. The unmapped extreme (white if -black is used, or black if -white is used) will always map to black in the output PPM image.

If no options are specified (i.e., no -white, -black, or color arguments), pgmtoppm will convert the PGM image to a PPM image where all three color components (Red, Green, Blue) are set to the original PGM pixel intensity. This results in a grayscale PPM output image, effectively making no visual change but changing the format header.

pgmtoppm always writes the resulting PPM image data to standard output. To save the output to a file, you must redirect standard output, for example: pgmtoppm image.pgm > image.ppm.

When using -color, the color can be specified as a name (e.g., "blue") which is looked up in the system's rgb.txt file, or as a hexadecimal RGB triplet (e.g., "#0000FF"). The individual -red, -green, and -blue options allow for more granular control over the color components, overriding any color name or hex value provided.

pgmtoppm is part of the Netpbm project, a suite of graphics conversion tools that originated from Jef Poskanzer's PBMplus toolkit in the late 1980s. Netpbm maintains a philosophy of small, specialized tools that can be chained together via pipes to perform complex image manipulations. pgmtoppm exemplifies this by handling a specific, fundamental conversion within the Netpbm image format ecosystem.

ppmtopgm(1), pnmgamma(1), pnm(5), pgm(5), ppm(5), netpbm(1)