path: root/upstream/opensuse-tumbleweed/man1/pnmnorm.1

\
.\" 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 "Pnmnorm User Manual" 0 "19 December 2014" "netpbm documentation"

.SH NAME

pnmnorm - normalize the contrast in a Netpbm image

.UN synopsis
.SH SYNOPSIS

\fBpnmnorm\fP

[\fB-bpercent=\fP\fIpercent\fP | \fB-bvalue=\fP\fIN\fP | \fB-bsingle\fP]

[\fB-wpercent=\fP\fIpercent\fP | \fB-wvalue=\fP\fIN\fP | \fB-wsingle\fP]

[\fB-midvalue=\fP\fIN\fP]

[\fB-middle=N\fP]

[\fB-maxexpand=\fP\fIpercent\fP]

[\fB-keephues\fP]

[\fB-luminosity\fP | \fB-colorvalue\fP | \fB-saturation\fP]

[\fIppmfile\fP]
.PP
All options can be abbreviated to their shortest unique prefix.
You may use two hyphens instead of one to designate an option.  You
may use either white space or an equals sign between an option name
and its value.

.UN description
.SH DESCRIPTION
.PP
This program is part of
.BR "Netpbm" (1)\c
\&.
.PP
\fBpnmnorm\fP reads a PNM image (PBM, PGM, or PPM).  It normalizes the
contrast by forcing the brightest pixels to white, the darkest pixels to
black, and spreading out the ones in between.  It produces the same kind of
file as output.  This is pretty useless for a PBM image.
.PP
The program offers two ways of spreading out the pixels in between the
darkest and brightest: linear and quadratic.  In the quadratic case, you
specify some in between brightness and specify what brightness that should
become in the output.  With those three constraints: the brightness that
becomes black, the brightness that becomes white, and the brightness that
becomes that middle value, \fBpnmnorm\fP computes a quadratic equation that
maps all the other brightnesses from input values to output values.
.PP
The program first determines a mapping of old brightness to new
brightness.  For each possible brightness of a pixel, the program
determines a corresponding brightness for the output image.
.PP
Then for each pixel in the image, the program computes a color which has
the desired output brightness and puts that in the output.  With a color
image, it is not always possible to compute such a color and retain any
semblance of the original hue, so the brightest and dimmest pixels may only
approximate the desired brightness.
.PP
For a PPM image, you have a choice of three ways to define brightness:

.IP \(bu
luminosity
.IP \(bu
color value
.IP \(bu
saturation


In the case of saturation, "brightness" is pretty much a
misnomer, but you can use the brightness analogy to see what it does.
In the analogy, bright means saturated and dark means unsaturated.
.PP
Note that all of these are different from separately normalizing
the individual color components.
.PP
An alternative way to spread out the brightnesses in an image is
\fBpnmhisteq\fP.  \fBpnmhisteq\fP stretches the brightest pixels to
white and the darkest pixels to black, but rather than linearly
adjusting the ones in between, it adjusts them so that there are an
equal number of pixels of each brightness throughout the range.  This
gives you more contrast than \fBpnmnorm\fP does, but can considerably
change the picture in exchange.


.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
\&), \fBpnmnorm\fP recognizes the following
command line options:
.PP
By default, the darkest 2 percent of all pixels are mapped to
black, and the brightest 1 percent are mapped to white.  You can
override this behavior and specify either a different percentage, or
specific brightness values to map to black and to white, or just have
the single greatest brightness map to white and the least brightness map
to black.


.TP
\fB-bpercent\fP
.TP
\fB-wpercent\fP
.TP
\fB-bvalue\fP
.TP
\fB-wvalue\fP
.sp
To specify a percentage, use the \fB-bpercent\fP and
\fB-wpercent\fP options, or you can specify the exact pixel values to
be mapped by using the \fB-bvalue\fP and \fB-wvalue\fP options.
You can get appropriate numbers for the options from
\fBppmhist\fP.  If you just want to enhance the contrast, then
choose values at elbows in the histogram; e.g. if value 29 represents
3% of the image but value 30 represents 20%, choose 30 for
\fIbvalue\fP.  If you want to brighten the image, then set
\fIbvalue\fP to 0 and just fiddle with \fIwvalue\fP; similarly, to
darken the image, set \fIwvalue\fP to maxval and play with
\fIbvalue\fP.
.sp
If you specify both \fB-bvalue\fP and \fB-bpercent\fP, \fBpnmnorm\fP
uses the one that produces the least change.  The same goes for
\fB-wvalue\fP and \fB-wpercent\fP.  (In Netpbm 10.26 (January 2005),
the \fB-bvalue\fP/\fB-wvalue\fP takes precedence, and before that,
it's a syntax error to specify both).
.sp
If you want to maximize the change instead of minimizing it, just
cascade two runs of \fBpnmnorm\fP, specifying values for the first
and percentages for the second.
.sp
\fB-bpercent\fP and \fB-wpercent\fP values are floating point
decimal.  Zero is valid and is the same as \fB-bvalue=0\fP or
\fB-wvalue=\fP\fImaxval\fP, respectively.
.sp
Because there are whole numbers of pixels at each brightness,
\fBpnmnorm\fP obviously can't guarantee the exact percentage, so it
arranges that \fIat least\fP the percentage of pixels you specify
get remapped as promised.
.sp
It is possible for your \fB-bpercent\fP or \fB-wpercent\fP
to overlap your \fB-wvalue\fP or \fB-bvalue\fP, respectively.  For
example, you say \fB-bpercent=20\fP and \fB-wvalue=100\fP for an
image in which only 10 percent of the pixels are darker than 100.
In that case, \fBpnmnorm\fP adjusts the percentile value as
required.  In the example, it uses 99 as the black value (like
\fB-bvalue=99\fP).
.sp
It is also possible for your \fB-bpercent\fP and \fB-wpercent\fP
options to select the same brightness value for the stretch-to-white
and stretch-to-black value because of the fact that \fBpnmnorm\fP
can't subdivide a histogram cell.  E.g. if an image is all brightness
100, then no matter what \fB-bpercent\fP and \fB-wpercent\fP
values you choose, it's the same as saying \fB-bvalue=100 -wvalue=100\fP.
In that case, \fBpnmnorm\fP changes one of the values by 1 to make it
legal.  In the example, \fBpnmnorm\fP would either make the black
value 99 or the white value 101.
.sp
Before Netpbm 10.43 (June 2008), \fBpnmnorm\fP fails if the
\fB-wpercent\fP and/or \fB-bpercent\fP values specify an overlap.
.sp
The stretch points are further constrained by the \fB-maxexpand\fP
option.  Sometimes, too much contrast is a bad thing.  If your
intensities are all concentrated in the middle, \fB-bpercent=2\fP and
\fB-wpercent=1\fP might mean that an intensity of 60 gets stretched
up to 100 and intensity of 20 gets stretched down to zero, for a
range expansion of 150% (from a range of 40 to a range of 100).  That
much stretching means two adjacent pixels that used to differ in
intensity by 4 units now differ by 10, and that might be unsightly.

.TP
\fB-bsingle\fP
.sp
To specify that the single least brightness in the image should stretch to
black in the output, specify \fB-bsingle\fP.  To specify that the single
greatest brightness in the image should stretch to white in the output,
specify \fB-wsingle\fP.  \fB-bsingle\fP and \fB-wsingle\fP were new in
Netpbm 10.69 (December 2014).

.TP
\fB-maxexpand\fP
.sp
So that you can put a limit on the amount of expansion without
having to examine the image first, there is the \fB-maxexpand\fP
option.  It specifies the maximum expansion you will tolerate, as an
additional percentage.  In the example above, you could say
\fB-maxexpand=50\fP to say you want the range to expand by at most
50%, regardless of your other options.  \fBpnmnorm\fP figures out
what intensity to stretch to full intensity and what intensity to
stretch to zero intensity as described above, and then raises the
former and lowers the latter as needed to limit the expansion to the
amount you specified.
.sp
When \fBpnmnorm\fP limits the expansion because of \fB-maxexpand\fP,
it tells you about it with a message like this:
.nf

    limiting expansion of 150% to 50%


.fi
.sp
In any case, \fBpnmnorm\fP tells you exactly what expansion it's
doing, like this:

.nf

    remapping 25..75 to 0..100


.fi
.sp
Before Netpbm 10.26 (December 2004), it was not valid to specify both
\fB-bvalue\fP and \fB-bpercent\fP or \fB-wvalue\fP and \fB-wpercent\fP.
.sp
\fB-maxexpand\fP was new in Netpbm 10.32 (February 2006).

.TP
\fB-keephues\fP
.sp
This option says to keep each pixel the same hue as
it is in the input; just adjust its brightness.  You normally want this;
the only reason it is not the default behavior is backward compatibility
with a design mistake.
.sp
By default, \fBpnmnorm\fP normalizes contrast in each component
independently (except that the meaning of the \fB-wpercent\fP and
\fB-bpercent\fP options are based on the overall brightnesses of the
colors, not each component taken separately).  So if you have a color
which is intensely red but dimly green, \fBpnmnorm\fP would make the
red more intense and the green less intense, so you end up with a
different hue than you started with.

.TP
\fB-midvalue=\fP\fIN\fP
.TP
\fB-middle=\fP\fIN\fP
.sp
When you specify \fB-midvalue=\fP\fIN\fP, \fBpnmnorm\fP uses a quadratic
function to map old brightnesses to new ones, making sure that an old
brightness of \fIN\fP becomes 50% bright in the output.  You can override
that 50% default with \fB-middle\fP.  The value of \fB-middle\fP is a
floating point number in the range 0 through 1 with 0 being full darkness and
1 full brightness.  If your \fB-midvalue\fP and \fB-middle\fP indicate an
ambiguous or impossible quadratic function (e.g. \fB-midvalue\fP is the same
as \fB-bvalue\fP, so an infinite number of quadratic functions
fit), \fBpnmnorm\fP just ignores your \fB-midvalue\fP and maps linearly.

\fB-midvalue\fP and \fB-middle\fP were new in Netpbm 10.57 (December 2011).
.sp
If you specify \fB-keephues\fP, \fBpnmnorm\fP would likely leave
this pixel alone, since its overall brightness is medium.
.sp
\fB-keephues\fP can cause clipping, because a certain color may be
below a target intensity while one of its components is saturated.
Where that's the case, \fBpnmnorm\fP uses the maximum representable
intensity for the saturated component and the pixel ends up with less
overall intensity, and a different hue, than it is supposed to have.
.sp
This option is meaningless on grayscale images.
.sp
When you \fIdon't\fP specify \fB-keephues\fP, the
\fB-luminosity\fP, \fB-colorvalue\fP, and \fB-saturation\fP options
affect the transfer function (which is the same for all three RGB
components), but are meaningless when it comes to applying the
transfer function (since it is applied to each individual RGB
component).
.sp
Before Netpbm 9.25 (March 2002), there was no \fB-keephues\fP option.

.TP
\fB-luminosity\fP
.TP
\fB-colorvalue\fP
.TP
\fB-saturation\fP
.sp
\fB-luminosity\fP, \fB-colorvalue\fP, and \fB-saturation\fP determine
what property of the pixels \fBpnmnorm\fP normalizes.  I.e., what kind of
brightness.  You cannot specify more than one of these.
.sp
The \fB-luminosity\fP option says to use the luminosity (i.e. the
"Y" in the YUV or YCbCr color space) as the pixel's brightness.  The
luminosity is a measure of how bright a human eye would find the color,
taking into account the fact that the human eye is more sensitive to some
RGB components than others.
.sp
This option is default.
.sp
This option is meaningless on grayscale images.
.sp
Before Netpbm 10.28 (August 2005), there was no \fB-luminosity\fP option,
but its meaning was still the default.
.sp
Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option.
.sp
The \fB-colorvalue\fP option says to use the color value (i.e. the
"V" in the HSV color space) as the pixel's brightness.  The
color value is the gamma-adjusted intensity of the most intense RGB
component.
.sp
This option is meaningless on grayscale images.
.sp
Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option.
.sp
The \fB-saturation\fP option says to use the saturation (i.e. the
"S" in the HSV color space) as the pixel's brightness.  The
saturation is the ratio of the intensity of the most intense RGB
component to the difference between the intensities of the most and least
intense RGB component (all intensities gamma-adjusted).
.sp
In this case, "brightness" is more of a metaphor than anything.
"bright" means saturated and "dark" means unsaturated.
.sp
This option is meaningless on grayscale images.
.sp
Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option.



.UN seealso
.SH SEE ALSO
.BR "pnmhisteq" (1)\c
\&,
.BR "pamlevels" (1)\c
\&,
.BR "ppmhist" (1)\c
\&,
.BR "pgmhist" (1)\c
\&,
.BR "pambrighten" (1)\c
\&,
.BR "ppmdim" (1)\c
\&,
.BR "pnmgamma" (1)\c
\&,
.BR "pnm" (5)\c
\&
.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/pnmnorm.html
.PP