PAMLEVELS(1)

💖 pamlevels — the glow-up your colors asked for 💖

okay bestie, welcome to pamlevels(1) from the Pamlevels User Manual, part of the Netpbm crew. she does one job and she does it beautifully: a 'levels' transformation. think of it like a filter, except it's math and it's precise and it's gonna eat. let's get into it 🦋

---

✨ SYNOPSIS ✨

pamlevels -from1 from1 -to1 to1 -from2 from2 -to2 to2 [-from3 from3 -to3
to3] [-linear] [-fitbrightness] [pamfile]

---

🌸 DESCRIPTION 🌸

so this program is part of Netpbm(1). it reads a Netpbm image from pamfile — or from standard input if you're feeling mysterious — applies a 'levels' transformation, and sends the result straight to standard output. iconic behavior, honestly. 💅

here's the tea: it finds a unique transformation that maps color from1 to to1, color from2 to to2, and — if you supply -from3 and -to3 — color from3 to to3. transformations based on two mappings are linear in light intensity and those based on three mappings are quadratic. and because she's generous, the color-mapping options may be shortened to -f1…-f3 and -t1…-t3. slay.

color values have this format: color[:scale], where color is a Netpbm color specification and scale is an optional coefficient that gets applied to the intensity (i.e. not gamma-adjusted) of each RGB component of color. iykyk.

and here's a moment of pure math romance 🌈: when the transformation is linear (i.e. uses two mappings) and preserves zero (i.e. maps black to black), it corresponds to multiplication of light intensity by a constant and preserves color integrity(1). periodt.

---

🎀 EXAMPLES 🎀

in the examples below, \ denotes a line continuation. noted, bestie, don't forget it.

to brighten an image by setting a darker white point —

pamlevels -f1 black -t1 black \
  -f2 white:0.9 -t2 white in.ppm > out.ppm

to adjust the white point —

pamlevels -f1 black -t1 black \
  -f2 rgbi:0.9/0.83/0.80 -t2 white in.ppm > out.ppm

to set a lighter black point —

pamlevels -f1 white:0.06 -t1 black \
  -f2 white -t2 white in.ppm > out.ppm

to increase brightness by compression —

pamlevels \
  -f1 black -t1 black -f2 white -t2 white \
  -f3 white:0.5 -t3 white:0.6 in.ppm > out.ppm

that last transformation is similar to gamma-correction, fyi. lowkey obsessed with it. 💜

---

💅 OPTIONS 💅

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

• -from1
• -to1
• -from2
• -to2
• -from3
• -to3 — these options define the mappings of input colors to output colors that anchor the transformation function. see DESCRIPTION. you must specify at least two of these pairs. no skipping, bestie, that's the whole point.
• -linear — this option tells pamlevels to work with the intensity-linear variation on PPM where the samples are proportional to light intensity, rather than brightness (gamma-adjusted) as in true PPM. the input must be of this form and pamlevels makes the output of this form.

note that the numbers in a color specification like rgbi:0.9/0.83/0.80 are brightness levels (gamma-adjusted) regardless of the input and output format.

you cannot use this with -fitbrightness because that function is not implemented. 🚫

• -fitbrightness — this option selects a transformation which is not very useful — it is linear or quadratic in brightness rather than light intensity of the pixels. there is no physical basis for doing it this way and the result is normally undesirable. (not me choosing violence against my own pixels 😭)

note that many tools other than Netpbm do the transformation this way. one use for this option is simply to demonstrate the poor result of this method. 💀

one advantage of this transformation is that it is faster, because the input and output image formats use brightness values. the result is approximately correct.

you cannot use this with -linear because that function is not implemented. 🚫

---

👑 SEE ALSO 👑

pnmnorm(1), pamrecolor(1), pnmgamma(1), pnm(1)

---

🫶 AUTHOR 🫶

this program was first submitted by Anton Shepelev (anton.txt@gmail.com). give them their flowers. 🌸

---

🧚 HISTORY 🧚

pamlevels was new in Netpbm 10.83 (June 2018). a whole era. ✨

---

📖 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/pamlevels.html

---

and that's the whole page, bestie — netpbm documentation, dated 13 June 2018, from the Pamlevels User Manual. go forth and adjust those levels. 🌈💖 mwah, no cap.