.TL
Pnmhisteq User Manual
.SH 1
pnmhisteq
.LP
Updated: 10 September 2005
.br
Table Of Contents
.SH 2
NAME
.LP
pnmhisteq - histogram equalize a PNM image
.SH 2
SYNOPSIS
.LP
\fBpnmhisteq\fR
[\fB-gray\fR]
[\fB-rmap\fR \fIpgmfile\fR]
[\fB-wmap\fR \fIpgmfile\fR]
[\fB-verbose\fR]
[\fIpnmfile\fR]
.LP
You can abbreviate any option to its shortest unique prefix.
.SH 2
DESCRIPTION
.LP
.LP
This program is part of Netpbm.
.LP
\fBpnmhisteq\fR increases the contrast of a PGM or PPM image
through the technique of "histogram equalization."[1]
.LP
\fBpnmhisteq\fR computes a histogram of the luminosity of the
pixels in the image.  It then calculates a mapping between each
luminosity and a new luminosity such that it spreads out intensity
levels around histogram peaks and compresses them at troughs.  I.e.
it moves pixels around in the histogram so as to make it flat.  It
applies that mapping to the input image to produce the output image.
The effect of this is that the image has equal numbers of pixels at each
possible intensity level, which means it uses the available levels of
intensity more efficiently and thereby has more visible detail.
.LP
Mathematically, the luminosity mapping is this: Assume the pixels
are sorted by luminosity into \fIB\fR buckets numbered from 0 (lowest
luminosity) to \fIB\fR-1.  \fIN[i]\fR is the number of pixels in
bucket \fIi\fR.  \fIT\fR is the total number of pixels (sum of
\fIN[i]\fR over all \fIi\fR).  \fIW\fR is the luminosity of white.
.LP
\fBpnmhisteq\fR replaces an input pixel whose luminosity falls into
bucket \fIj\fR with one whose luminosity is:
.DS L
      j
     ---
     \
      > (N[i] / T) * W
     /
     ---
     i=0
.DE
.LP
Considering a grayscale image for simplicity, this means that
pixels in the most luminous bucket become white.  Pixels in the 10th
per centile of luminosity become 10% of white.
.LP
If you're processing a related set of images, for example frames of
an animation, it's generally best to apply the same luminosity mapping
to every frame, since otherwise you'll get distracting frame-to-frame
changes in the brightness of objects.  \fBpnmhisteq\fR's \fB-wmap\fR
option allows you to save, as a PGM image, the luminosity map it
computes from an image.  The \fB-rmap\fR option causes \fBpnmisteq\fR
to use such an image as its luminosity map.
.LP
So you can run \fBpnmhisteq\fR with \fB-wmap\fR on a composite
you created with \fBpnmcat\fR of the images you intend to process.
Then, you can run \fBpnmisteq\fR with \fB-rmap\fR on each of the
individual images, using the luminosity map you generated from the
composite.
.SH 2
OPTIONS
.LP
.RS
.IP "\fB-gray\fR"
When processing a pixmap, only gray pixels (those with identical
red, green, and blue values) are included in the histogram and
modified in the output image.  This is a special purpose option
intended for images where the actual data are gray scale, with color
annotations you don't want modified.  Weather satellite images that
show continent outlines in color are best processed using this option.
The option has no effect when the input is a graymap.
.IP "\fB-rmap\fR \fImapfile\fR"
Process the image using the luminosity map specified by the PGM
file \fImapfile\fR.
The PGM image, usually created by an earlier run of \fBpnmhisteq\fR
with the \fB-wmap\fR option, contains a single row with number of
columns equal to the maxval (greatest intensity value) of the image
plus one.  Each pixel in the image is transformed by looking up its
luminosity in the corresponding column in the map file (column number
= luminosity) and changing it to the value given by that column.
.IP "\fB-wmap\fR \fImapfile\fR"
Creates a PGM file \fImapfile\fR, containing the luminosity map
computed from the histogram of the input image.  This map file can be
read on subsequent runs of \fBpnmhisteq\fR with the \fB-rmap\fR
option, allowing a group of images to be processed with an identical
map.
.IP "\fB-verbose\fR"
Prints the histogram and luminosity map on Standard Error.
.RE
.SH 2
LIMITATIONS
.LP
.LP
Histogram equalization is effective for increasing the visible
detail in scientific imagery and in some continuous-tone pictures.  It
is often too drastic, however, for scanned halftone images, where it
does an excellent job of making halftone artifacts apparent.  You
might want to experiment with \fBpnmnorm\fR and \fBpnmgamma\fR for
more subtle contrast enhancement.
.LP
The luminosity map file supplied by the \fB-rmap\fR option must
have the same maxval as the input image.  This is always the case when
the map file was created by the \fB-wmap\fR option of
\fBpnmhisteq\fR.  If this restriction causes a problem, simply adjust
the maxval of the map with \fBpamdepth\fR to agree with the input
image.
.LP
If the input is a PBM file (on which histogram equalization is an
identity operation), the only effect of passing the file through
\fBpnmhisteq\fR will be the passage of time.
.SH 2
SEE ALSO
.LP
\fBpnmnorm\fR,
\fBpnmcat\fR,
\fBpamdepth\fR,
\fBpnmgamma\fR,
\fBpnm\fR,
.RS
.IP "[1]"
Russ, John C.  The Image Processing Handbook.  Boca Raton: CRC
Press, 1992.  Pages 105-110.
.RE
.SH 2
AUTHOR
.LP
.LP
Copyright (C) 1995 by John Walker (kelvin@fourmilab.ch).  WWW home
page: http://www.fourmilab.ch/
.LP
Permission to use, copy, modify, and distribute this software and
its documentation for any purpose and without fee is hereby granted,
without any conditions or restrictions.  This software is provided
"as is" without express or implied warranty.
.br
\l'5i'
.SH 2
Table Of Contents
.LP
.IP \(bu
NAME
.IP \(bu
SYNOPSIS
.IP \(bu
DESCRIPTION
.IP \(bu
OPTIONS
.IP \(bu
BUGS
.IP \(bu
SEE ALSO
.IP \(bu
AUTHOR
.LP