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  ⟨libppm.html#colorname⟩   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 tranformation is similar to gamma-correction.

OPTIONS

       In addition to the options common to all programs based on libnetpbm (most notably -quiet,
       see
        Common  Options  ⟨index.html#commonoptions⟩ ), 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 ⟨#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