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 result 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 optional 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 corresponds 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 proportional 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 normally 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)