Manual: pamlevels

Pamlevels User Manual(1)			   General Commands Manual			    Pamlevels User Manual(1)

NAME
       pamlevels - effect a 'levels' transformation

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

DESCRIPTION
       This program is part of Netpbm(1).

       pamlevels  reads	 a Netpbm image from pamfile or standard input, applies a 'levels' transformation, and sends the re‐
       sult to standard output. It finds a unique transformation that maps color from1 to to1, color from2  to	to2,  and-if
       -from3  and -to3 are supplied-color from3 to to3. Transformations based on two mappings are linear in light intensity
       and those based on three mappings quadratic.  The color-mapping options may be shortened to -f1...-f3 and -t1...-t3.

       Color values have the following format: color[:scale], where color is a	Netpbm color specification  and scale an op‐
       tional coefficient that is applied to the intensity (i.e. not gamma-adjusted) of each RGB component of color.

       When the transformation is linear (i.e. uses two mappings) and preserves zero (i.e. maps black to black),  it  corre‐
       sponds to multiplication of light intensity by a constant and preserves color integrity(1).

EXAMPLES
       In the examples below, \ denotes a line continuation:

       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

       The latter transformation is similar to gamma-correction.

OPTIONS
       In  addition  to	 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.

       -linear
	      This  option  tells pamlevels to work with the intensity-linear variation on PPM where the samples are propor‐
	      tional to light intensity, rather than brightness (gamma-adjusted) as in true PPM.  The input must be of	this
	      form and the 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	nor‐
	      mally undesirable.

	      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).

HISTORY
       pamlevels was new in Netpbm 10.83 (June 2018).

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

netpbm documentation					13 June 2018				    Pamlevels User Manual(1)