PPMCHANGE(1)

💅 NAME 💅

ppmchange — swap every single pixel of one color for another in a PPM image. That's the whole job. That's the moment. ✨

It's a member of the Netpbm family, bestie, so it plays nice with the rest of the clan.

---

🌸 SYNOPSIS 🌸

ppmchange

[-closeness=closeness_percent] [-remainder=remainder_color] [-closeok]
[oldcolor newcolor] ...  [ppmfile]

---

🎀 EXAMPLES 🎀

Okay so these are literally the moods:

ppmchange red blue redimage.ppm >blueimage.ppm

ppmchange red red -remainder=black myimage.ppm >redblack.ppm

ppmchange -closeness=10 white white black black

---

🦋 DESCRIPTION 🦋

So bestie, this program is part of Netpbm(1). 🌈

ppmchange reads a PPM image as input and changes all pixels of color oldcolor to color newcolor. Iconic behavior. No notes. 💖

You may specify up to 256 oldcolor/newcolor pairs on the command line. Yes, 256. That's your limit, and honestly that's plenty. ✨ ppmchange leaves all colors not mentioned unchanged, unless you specify the -remainder option, in which case they are all changed to the single specified color. She's thorough like that. 💅

You can specify that colors similar, but not identical, to the ones you specify get replaced by specifying a "closeness" factor. Lowkey powerful.

Specify the colors as described for the argument of the pnm_parsecolor() library routine. That's the vibe check for color syntax, iykyk.

If a pixel matches two different oldcolors, ppmchange replaces it with the newcolor of the leftmost specified one. Leftmost wins. Periodt. 👑

The maxval of the output image is the same as that of the input image. If a newcolor you specify cannot be exactly represented in that maxval, ppmchange assumes a color that is as close as possible to what you specified but can be represented with your maxval. Unless you specify the -closeok option, ppmchange issues a warning that it is using an approximation. She's telling you for your own good. 🫶

A common way that you can have this maxval problem, where the color you specify cannot be represented with your maxval, is that your input is a PBM (black and white) image that you are colorizing. The maxval in this case is 1, which severely limits the colors to which you can change. 😭 To avoid this problem, use pamdepth to make the maxval of your input something consistent with your colors. 255 is usually a good choice. Do it. Glow up your maxval first. ✨

Before Netpbm 10.22 (April 2004), ppmchange always behaved as if the user specified -closeok, and there was no -closeok option. Lore. 📜

---

✨ OPTIONS ✨

In addition to the options common to all programs based on libnetpbm (most notably -quiet, see Common Options), ppmchange recognizes the following command line options:

• -closeness closeness_percent — closeness is a percentage indicating how close to the color you specified a pixel must be to get replaced. By default, it is 0, which means the pixel must be the exact color you specified. No wiggle room, no crumbs left.

A pixel gets replaced if the distance in color between it and the color you specified is less than or equal to closeness per cent of the maxval.

The "distance" in color is defined as the Cartesian sum of the individual differences in red, green, and blue intensities between the two pixels, normalized so that the difference between black and white is 100%.

This is probably simpler than what you want most the time. You probably would like to change colors that have similar chrominance, regardless of their intensity. So if there's a red barn that is variously shadowed, you want the entire barn changed. But because the shadowing significantly changes the color according to ppmchange's distance formula, parts of the barn are probably about as distant in color from other parts of the barn as they are from green grass next to the barn. The barn said "one of us" and the algorithm said "ma'am you are grass now." 💀

Maybe ppmchange will be enhanced some day to do chrominance analysis. We're manifesting. 🙏✨

This option was new in Netpbm 9.8 (September 2000).

• -closeok — This option affects how ppmchange interprets a color you specify in the arguments. When you specify this option, ppmchange may use a color close to, but not the same as what you specify. See the description section for details.

This option was new in Netpbm 10.22 (April 2004). Before that, ppmchange always behaved as if you specified this option.

• -remainder color — ppmchange changes all pixels which are not of a color for which you specify an explicit replacement color on the command line to color color. Everything else? Handled. Everything left over? Gets the glow.

An example application of this is

ppmchange -remainder=black red red

to lift only the red portions from an image, or

ppmchange -remainder=black red white | ppmtopgm

to create a mask file for the red portions of the image. Mask serving, honestly. 🎭

---

👀 SEE ALSO 👀

pgmtoppm(1), ppmcolormask(1), ppm(1)

---

🫶 AUTHOR 🫶

Wilson H. Bent. Jr. (whb@usc.edu) with modifications by Alberto Accomazzi (alberto@cfa.harvard.edu). Legends. Thank you for your service. 💜

---

📚 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/ppmchange.html

---

That's the whole thing, bestie — go colorize something and make it iconic. 🌸🦋💖

netpbm documentation, December 2016 — Ppmchange User Manual(1), signing off. Mwah. 💅✨