.TL
Pnmnorm User Manual
.SH 1
pnmnorm
.LP
Updated: 6 January 2006
.br
Table Of Contents
.SH 2
NAME
.LP
pnmnorm - normalize the contrast in a Netbpm image
.SH 2
SYNOPSIS
.LP
\fBpnmnorm\fR
[\fB-bpercent=\fR\fIN\fR | \fB-bvalue=\fR\fIN\fR]
[\fB-wpercent=\fR\fIN\fR | \fB-wvalue=\fR\fIN\fR]
[\fB-maxexpand\fR
[\fB-keephues\fR]
[\fB-luminosity\fR | \fB-colorvalue\fR | \fB-saturation\fR]
[\fIppmfile\fR]
.LP
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.
.SH 2
DESCRIPTION
.LP
.LP
This program is part of Netpbm.
.LP
\fBpnmnorm\fR 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 linearly rescaling the ones in between; and
produces the same kind of file as output.  This is pretty useless for
a PBM image.
.LP
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.
.LP
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.
.LP
For a PPM image, you have a choice of three different ways to
define brightness:
.IP 1
luminosity
.IP 2
color value
.IP 3
saturation
.LP
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.
.LP
Note that all of these are different from separately normalizing
the individual color components.
.LP
An alternative way to spread out the brightnesses in an image is
\fBpnmhisteq\fR.  \fBpnmhisteq\fR 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\fR does, but can considerably
change the picture in exchange.
.SH 2
OPTIONS
.LP
.LP
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 these percentages by using the \fB-bpercent\fR and
\fB-wpercent\fR options, or you can specify the exact pixel values to
be mapped by using the \fB-bvalue\fR and \fB-wvalue\fR options.
You can get appropriate numbers for the options from
\fBppmhist\fR.  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\fR.  If you want to brighten the image, then set
\fIbvalue\fR to 0 and just fiddle with \fIwvalue\fR; similarly, to
darken the image, set \fIwvalue\fR to maxval and play with
\fIbvalue\fR.
.LP
If you specify both \fB-bvalue\fR and \fB-bpercent\fR, \fBpnmnorm\fR
uses the one that produces the least change.  The same goes for
\fB-wvalue\fR and \fB-wpercent\fR.
.LP
If you want to maximize the change instead of minimizing it, just
cascade two runs of \fBpnmnorm\fR, specifying values for the first
and percentages for the second.
.LP
This is further constrained by the \fB-maxexpand\fR option.
Sometimes, too much contrast is a bad thing.  If your intensities are
all concentrated in the middle, \fB-bpercent=2\fR and
\fB-wpercent=1\fR might mean that an intensity of 60 gets stretched
up to 100 and and intensity of 40 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.
.LP
So that you can put a limit on the amount of expansion without
having to examine the image first, there is the \fB-maxexpand\fR
option.  It specifies the maximum expansion you will tolerate, as an
additional per centage.  In the example above, you could say
\fB-maxexpand=50\fR to say you want the range to expand by at most
50%, regardless of your other options.  \fBpnmnorm\fR 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.
.LP
When \fBpnmnorm\fR limits the expansion due to \fB-maxexpand\fR,
it tells you about it with a message like this:
.DS L
\f(CW    limiting expansion of 150% to 50%
\fR.DE
.LP
In any case, \fBpnmnorm\fR tells you exactly what expansion it's
doing, like this:
.DS L
\f(CW    remapping 25..75 to 0..100
\fR.DE
.LP
Before Netpbm 10.26 (December 2004), it was not valid to specify both
\fB-bvalue\fR and \fB-bpercent\fR or \fB-wvalue\fR and \fB-wpercent\fR.
.LP
\fB-maxexpand\fR was new in Netpbm 10.32 (February 2006).
.LP
The \fB-keephues\fR 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.
.LP
By default, \fBpnmnorm\fR normalizes contrast in each component
independently (except that the meaning of the \fB-wpercent\fR and
\fB-bpercent\fR 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\fR would make the
red more intense and the green less intense, so you end up with a
different hue than you started with.
.LP
If you specify \fB-keephues\fR, \fBpnmnorm\fR would likely leave
this pixel alone, since its overall brightness is medium.
.LP
\fB-keephues\fR 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\fR 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.
.LP
This option is meaningless on grayscale images.
.LP
When you don't specify \fB-keephues\fR, the
\fB-luminosity\fR, \fB-colorvalue\fR, and \fB-saturation\fR 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).
.LP
Before Netpbm 9.25 (March 2002), there was no \fB-keephues\fR option.
.LP
\fB-luminosity\fR, \fB-colorvalue\fR, and \fB-saturation\fR determine
what property of the pixels \fBpnmnorm\fR normalizes.  I.e., what kind of
brightness.  You cannot specify more than one of these.
.LP
The \fB-luminosity\fR 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.
.LP
This option is default.
.LP
This option is meaningless on grayscale images.
.LP
Before Netpbm 10.28 (August 2005), there was no \fB-luminosity\fR option,
but its meaning was still the default.
.LP
Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fR option.
.LP
The \fB-colorvalue\fR 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.
.LP
This option is meaningless on grayscale images.
.LP
Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fR option.
.LP
The \fB-saturation\fR 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).
.LP
In this case, "brightness" is more of a metaphor than anything.
"bright" means saturated and "dark" means unsaturated.
.LP
This option is meaningless on grayscale images.
.LP
Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fR option.
.SH 2
SEE ALSO
.LP
\fBpnmhisteq\fR,
\fBppmhist\fR,
\fBpgmhist\fR,
\fBpnmgamma\fR,
\fBppmbrighten\fR,
\fBppmdim\fR,
\fBpnm\fR
.br
\l'5i'
.SH 2
Table Of Contents
.LP
.IP \(bu
SYNOPSIS
.IP \(bu
DESCRIPTION
.IP \(bu
OPTIONS
.IP \(bu
SEE ALSO
.LP