\
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
.\" the corresponding HTML page on the Netpbm website, generate a patch
.\" against that, and send it to the Netpbm maintainer.
.TH "Pamlevels User Manual" 1 "13 June 2018" "netpbm documentation"

.SH NAME
pamlevels - effect a 'levels' transformation

.UN synopsis
.SH SYNOPSIS

\fBpamlevels\fP
\fB-from1\fP \fIfrom1\fP
\fB-to1\fP \fIto1\fP
\fB-from2\fP \fIfrom2\fP
\fB-to2\fP \fIto2\fP
[\fB-from3\fP \fIfrom3\fP
\fB-to3\fP \fIto3\fP]
[\fB-linear\fP]
[\fB-fitbrightness\fP]
[\fIpamfile\fP]

.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBpamlevels\fP reads a Netpbm image from \fIpamfile\fP or standard
input, applies a 'levels' transformation, and sends the result to
standard output. It finds a unique transformation that maps color
\fIfrom1\fP to \fIto1\fP, color \fIfrom2\fP to \fIto2\fP,
and-if \fB-from3\fP and \fB-to3\fP are supplied-color
\fIfrom3\fP to \fIto3\fP. 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 \fB-f1\fP...\fB-f3\fP and
\fB-t1\fP...\fB-t3\fP.  
.PP
Color values have the following format:
\fIcolor\fP[:\fIscale\fP], where \fIcolor\fP is a
.UR libppm.html#colorname
 Netpbm color specification
.UE
\& and
\fIscale\fP an optional coefficient that is applied to the intensity
(i.e. \fInot\fP gamma-adjusted) of each RGB component of \fIcolor\fP.
.PP
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
.BR "color integrity" (1)\c
\&.


.UN examples
.SH EXAMPLES
In the examples below, \f(CW\e\fP denotes a line continuation:
.PP
To brighten an image by setting a darker white point-
.nf
    pamlevels -f1 black -t1 black \e
      -f2 white:0.9 -t2 white in.ppm > out.ppm

.fi
.PP
To adjust the white point-
.nf
    pamlevels -f1 black -t1 black \e
      -f2 rgbi:0.9/0.83/0.80 -t2 white in.ppm > out.ppm

.fi
.PP
To set a lighter black point-
.nf
    pamlevels -f1 white:0.06 -t1 black \e
      -f2 white -t2 white in.ppm > out.ppm

.fi
.PP
To increase brightness by compression-
.nf
    pamlevels \e
      -f1 black -t1 black -f2 white -t2 white \e
      -f3 white:0.5 -t3 white:0.6 in.ppm > out.ppm

.fi
The latter transformation is similar to gamma-correction.


.UN options
.SH OPTIONS
.PP
In addition to the options common to all programs based on libnetpbm
(most notably \fB-quiet\fP, see 
.UR index.html#commonoptions
 Common Options
.UE
\&), \fBpamlevels\fP recognizes the following
command line options:


.TP
\fB-from1\fP
.TP
\fB-to1\fP
.TP
\fB-from2\fP
.TP
\fB-to2\fP
.TP
\fB-from3\fP
.TP
\fB-to3\fP
These options define the mappings of input colors to output colors that anchor
the transformation function.  See 
.UR #description
DESCRIPTION
.UE
\&.
.sp
You must specify at least two of these pairs.

.TP
\fB-linear\fP
This option tells \fBpamlevels\fP 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 \fBpamlevels\fP makes the output of this form.
.sp
Note that the numbers in a color specification like
\fBrgbi:0.9/0.83/0.80\fP are brightness levels (gamma-adjusted) regardless of
the input and output format.
.sp
You cannot use this with \fB-fitbrightness\fP because that function is
not implemented.
  
.TP
\fB-fitbrightness\fP
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.
.sp
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.
.sp
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.
.sp
You cannot use this with \fB-linear\fP because that function is not
implemented.
  


.UN seealso
.SH SEE ALSO
.BR "pnmnorm" (1)\c
\&,
.BR "pamrecolor" (1)\c
\&,
.BR "pnmgamma" (1)\c
\&,
.BR "pnm" (1)\c
\&

.UN author
.SH AUTHOR
.PP
This program was first submitted by Anton Shepelev
(\fIanton.txt@gmail.com\fP).

.UN history
.SH HISTORY
.PP
\fBpamlevels\fP was new in Netpbm 10.83 (June 2018).
.SH DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source.  The master documentation is at
.IP
.B http://netpbm.sourceforge.net/doc/pamlevels.html
.PP