ppmchange

Exchange the first color in each oldcolor - newcolor pair with the second color

$ ppmchange [oldcolor1 newcolor1 oldcolor2 newcolor2 ...] [path/to/input.ppm] > [path/to/output.ppm]

$ ppmchange -closeness [percentage] [oldcolor1 newcolor1 oldcolor2 newcolor2 ...] [path/to/input.ppm] > [path/to/output.ppm]

$ ppmchange [[-r|-remainder]] [color] [oldcolor1 newcolor1 oldcolor2 newcolor2 ...] [path/to/input.ppm] > [path/to/output.ppm]

ppmchange [-verbose] [-map mapfile] [oldcolor1 newcolor1 [oldcolor2 newcolor2 ...]] [netpbmfile]

-verbose
    Prints a progress report to standard error as the image is processed, showing the percentage completed.

-map mapfile
    Reads the color transformation pairs from the specified mapfile instead of the command line. Each non-comment line in the file should contain an oldcolor followed by a newcolor, separated by whitespace.

oldcolor
    The color to be found and replaced in the input image. This can be a standard X11 color name (e.g., 'red', 'blue') or a hexadecimal RGB value (e.g., '#FF0000', '#0000FF').

newcolor
    The color to which matching oldcolor pixels will be changed. Specified in the same format as oldcolor.

netpbmfile
    The path to the input PPM image file. If omitted, ppmchange reads image data from standard input.

ppmchange is a utility from the Netpbm suite designed for modifying the colors of pixels within a Portable Pixmap (PPM) image. It reads an input PPM image, either from a specified file or standard input, and applies a series of color replacement rules to its pixels. For each pixel in the image, ppmchange compares its color against a list of "old" colors. If a match is found, the pixel's color is changed to the corresponding "new" color.

This command is particularly useful for tasks such as remapping color palettes, selectively changing specific colors in an image, or performing basic color correction. The color changes can be specified directly on the command line as pairs of oldcolor and newcolor, or loaded from a separate map file for more complex or numerous transformations. The output is a new PPM image, typically written to standard output, allowing for easy piping with other Netpbm tools. It processes changes sequentially, meaning the order of color replacement pairs can affect the final image if colors overlap.

ppmchange primarily works with the PPM (Portable Pixmap) image format. While Netpbm can convert other formats to PPM, ppmchange itself expects PPM input.

Color matching is exact; there is no tolerance for near matches. Colors must be specified precisely according to their RGB values or defined color names.

The order of oldcolor newcolor pairs is significant. Changes are applied sequentially from left to right on the command line (or top to bottom in a map file). If the newcolor of one transformation matches the oldcolor of a subsequent transformation, the pixel will undergo multiple changes (e.g., changing 'red' to 'blue' and then 'blue' to 'green' will result in an original 'red' pixel becoming 'green').

Colors can be specified either by standard X11 color names (e.g., 'red', 'green', 'white', 'black', 'lightgray', etc.), which ppmchange looks up in a color name database, or by hexadecimal RGB values. Hexadecimal values are written as '#RRGGBB', where RR, GG, and BB are two-digit hexadecimal numbers representing the red, green, and blue components respectively (e.g., '#FF0000' for pure red, '#00FF00' for pure green, '#0000FF' for pure blue).

When multiple color replacement pairs are provided, ppmchange applies them in the exact order they are listed. This means that a pixel's color might be changed multiple times if it matches subsequent oldcolor values after an initial transformation. For instance, if you have rules 'red blue' and then 'blue green', an original red pixel would first become blue, and then immediately become green. This cascading effect must be considered when defining complex color transformations.

ppmchange is an integral part of the Netpbm package, a widely used suite of graphics utilities. It originated as part of the Pbmplus package, created by Jef Poskanzer, which formed the foundation of Netpbm. Since its inception, it has been maintained and expanded upon within the Netpbm project, serving as a fundamental tool for specific color manipulation tasks in PPM images. Its design reflects the Unix philosophy of small, specialized tools that can be chained together for complex image processing workflows.

netpbm(1), ppm(5), ppmmake(1), ppmquant(1), pnmarith(1)