pnmremap

Replace the colors in an image with those in the specified color palette

$ pnmremap [[-ma|-mapfile]] [path/to/palette_file.ppm] [path/to/input.pnm] > [path/to/output.pnm]

$ pnmremap [[-ma|-mapfile]] [path/to/palette_file.ppm] [[-fs|-floyd]] [path/to/input.pnm] > [path/to/output.pnm]

$ pnmremap [[-ma|-mapfile]] [path/to/palette_file.ppm] [[-fi|-firstisdefault]] [path/to/input.pnm] > [path/to/output.pnm]

$ pnmremap [[-ma|-mapfile]] [path/to/palette_file.ppm] [[-m|-missingcolor]] [color] [path/to/input.pnm] > [path/to/output.pnm]

pnmremap [-map=<mapfile>] [-optimize] [-nofind] [-quiet] [<pnmfile>]

-map=<mapfile>
    Specifies the PNM image file to be used as the color map. All colors in the input image will be remapped to the closest colors found in this map file. If this option is omitted, a default 12-color CGA palette is used.

-optimize
    Causes pnmremap to generate a color map based on the input image itself, rather than using a specified <mapfile>. The generated map will contain all the colors present in the input image, up to a maximal color depth of 8 bits (256 colors). This is useful for color quantization where you want to reduce colors but keep the most important ones from the original image.

-nofind
    Disables the 'find closest color' functionality. When this option is used, pnmremap will only remap colors if they exactly match a color in the map file. If any color in the input image does not have an exact match in the map, an error will be generated and the command will fail.

-quiet
    Suppresses any verbose output or informational messages that pnmremap might otherwise print to standard error.

pnmremap is a Netpbm command-line utility designed to remap the colors of a PNM (Portable Anymap) image. It takes an input image and transforms its colors to a predefined set of colors found in a 'map' image. For each color in the input image, pnmremap finds the closest matching color in the map image (typically using Euclidean distance in RGB color space) and replaces it. This process is useful for reducing the number of colors in an image, converting an image to a specific color palette (e.g., for older displays or file formats), or preparing an image for dithering. The input image must be in PPM format, and the map image is typically also a PPM. If no map file is specified, pnmremap defaults to a standard 12-color CGA palette.

pnmremap internally converts non-PPM input to PPM if necessary. The map file, if specified, is also expected to be in PNM format, though it can automatically convert GIF to PPM if a GIF is provided.

When using -optimize, pnmremap essentially performs a color quantization, limiting the output palette to 256 colors. Without -nofind, the 'closest' color matching is based on Euclidean distance in RGB color space, which may not always correspond to perceptual similarity.

pnmremap is part of the Netpbm project, a toolkit of graphic file format converters and image processing utilities. Netpbm has a long history, evolving from the original PBMPLUS package created by Jef Poskanzer in the late 1980s. The modular design of Netpbm tools, including pnmremap, allows them to be easily chained together using pipes for complex image manipulations. Its development reflects the ongoing need for robust, open-source image manipulation tools on Unix-like systems.

pnmquant(1), pnmgamma(1), ppmdith(1), ppmcie(1), pnmcolormap(1), netpbm(1)