1Pnmhisteq User Manual(0)                              Pnmhisteq User Manual(0)
2
3
4

NAME

6       pnmhisteq - histogram equalize a PNM image
7
8

SYNOPSIS

10       pnmhisteq
11
12       [-gray]
13
14       [-noblack] [-nowhite]
15
16       [-rmap pgmfile]
17
18       [-wmap pgmfile]
19
20       [-verbose]
21
22       [pnmfile]
23
24
25

DESCRIPTION

27       This program is part of Netpbm(1).
28
29       pnmhisteq  increases  the  contrast  of  a PGM or PPM image through the
30       technique of "histogram equalization."[1]
31
32       pnmhisteq computes a histogram of the luminosity of the pixels  in  the
33       image.   It then calculates a mapping between each luminosity and a new
34       luminosity such that it spreads out intensity levels  around  histogram
35       peaks  and compresses them at troughs.  I.e.  it moves pixels around in
36       the histogram so as to make it flat.  It applies that  mapping  to  the
37       input  image  to  produce the output image.  The effect of this is that
38       the image has equal numbers of pixels at each possible intensity level,
39       which  means it uses the available levels of intensity more efficiently
40       and thereby has more visible detail.
41
42       Mathematically, the luminosity mapping is this: Assume the  pixels  are
43       sorted by luminosity into B buckets numbered from 0 (lowest luminosity)
44       to B-1.  N[i] is the number of pixels in bucket i.  T is the total num‐
45       ber of pixels (sum of N[i] over all i).  W is the luminosity of white.
46
47       pnmhisteq  replaces an input pixel whose luminosity falls into bucket j
48       with one whose luminosity is:
49
50
51             j
52            ---
53            \
54             > (N[i] / T) * W
55            /
56            ---
57            i=0
58
59       Considering a grayscale image for simplicity, this means that pixels in
60       the  most luminous bucket become white.  Pixels in the 10th per centile
61       of luminosity become 10% of white.
62
63       pnmhisteq maps a single luminosity in the input to a single  luminosity
64       in the output.  That means if pixels A and B both have luminosity .2 in
65       the input, and pixel A has luminosity .4 in the output,  pixel  B  also
66       has  luminosity  .4  in  the output.  And since the luminosities in the
67       input are not continuous, the luminosities in the output aren't  either
68       and  pnmhisteq doesn't meet the ideal of having exactly the same number
69       of pixels of each luminosity in the output.
70
71       If you're processing a related set of images, for example frames of  an
72       animation,  it's generally best to apply the same luminosity mapping to
73       every frame, since  otherwise  you'll  get  distracting  frame-to-frame
74       changes  in the brightness of objects.  pnmhisteq's -wmap option allows
75       you to save, as a PGM image, the luminosity map  it  computes  from  an
76       image.   The  -rmap  option causes pnmisteq to use such an image as its
77       luminosity map.
78
79       So you can run pnmhisteq with -wmap on a  composite  you  created  with
80       pnmcat of the images you intend to process.  Then, you can run pnmisteq
81       with -rmap on each of the individual images, using the  luminosity  map
82       you generated from the composite.
83
84       Use  pnmhistmap  to see the result.  Run a color image through ppmtopgm
85       first so that you see a histogram of the  luminosity  instead  of  his‐
86       tograms of the three color components.  It should generally show a flat
87       histogram.  But because of the quantization  effects  described  above,
88       you might see high bars interleaved with low bars, with the local aver‐
89       age being flat.  To see  local  averages,  use  the  -width  option  of
90       pnmhistmap.
91
92
93

OPTIONS

95       In  addition  to  the options common to all programs based on libnetpbm
96       (most notably -quiet, see
97        Common Options ⟨index.html#commonoptions⟩ ), pnmhisteq recognizes  the
98       following command line options:
99
100       You can abbreviate any option to its shortest unique prefix.
101
102
103
104       -gray  When  processing  a  color  image,  only gray pixels (those with
105              identical red, green, and blue values) are included in the  his‐
106              togram and modified in the output image.  This is a special pur‐
107              pose option intended for images where the actual data  are  gray
108              scale,  with color annotations you don't want modified.  Weather
109              satellite images that show continent outlines in color are  best
110              processed  using this option.  The option has no effect when the
111              input is a graymap.
112
113
114       -noblack
115              Do not include black pixels in the equalization.  The black pix‐
116              els  in the output are exactly the black pixels in the input and
117              the number of black pixels does not  affect  the  color  of  any
118              other pixels.
119
120              Sometimes,  black isn't as much a color as a background or anno‐
121              tation for the real colors, so you want to  treat  it  specially
122              this  way.   Think  of  a  picture of stars, which is nearly all
123              black, but with lots of stars of different brightness.  You want
124              to  change  the  brightnesses  of the stars to maximize contrast
125              between them, but if you considered the blackness to be signifi‐
126              cant, all the stars would end up close to full white.
127
128              This option was new in Netpbm 10.70 (March 2015).
129
130
131       -nowhite
132
133              Same as -noblack, but for the white pixels.
134
135              This option was new in Netpbm 10.70 (March 2015).
136
137
138       -rmap mapfile
139              Process  the image using the luminosity map specified by the PGM
140              file mapfile.
141
142              The PGM image, usually created by an earlier  run  of  pnmhisteq
143              with the -wmap option, contains a single row with number of col‐
144              umns equal to the maxval (greatest intensity value) of the image
145              plus  one.  Each pixel in the image is transformed by looking up
146              its luminosity in the corresponding column in the map file (col‐
147              umn  number  = luminosity) and changing it to the value given by
148              that column.
149
150
151       -wmap mapfile
152              Creates a PGM file mapfile, containing the luminosity  map  com‐
153              puted  from the histogram of the input image.  This map file can
154              be read on subsequent runs of pnmhisteq with the  -rmap  option,
155              allowing  a  group  of  images to be processed with an identical
156              map.
157
158
159       -verbose
160              Prints the histogram and luminosity map on Standard Error.
161
162
163
164

LIMITATIONS

166       Histogram equalization is effective for increasing the  visible  detail
167       in  scientific  imagery  and  in  some continuous-tone pictures.  It is
168       often too drastic, however, for scanned halftone images, where it  does
169       an excellent job of making halftone artifacts apparent.  You might want
170       to experiment with  pnmnorm  and  pnmgamma  for  more  subtle  contrast
171       enhancement.
172
173       The luminosity map file supplied by the -rmap option must have the same
174       maxval as the input image.  This is always the case when the  map  file
175       was  created  by  the  -wmap  option of pnmhisteq.  If this restriction
176       causes a problem, simply adjust the maxval of the map with pamdepth  to
177       agree with the input image.
178
179       If the input is a PBM file (on which histogram equalization is an iden‐
180       tity operation), the only effect of passing the file through  pnmhisteq
181       will be the passage of time.
182
183

SEE ALSO

185       pnmnorm(1), pnmcat(1), pamdepth(1), pnmgamma(1), pnm(1),
186
187
188
189       [1]    Russ,  John  C.  The Image Processing Handbook.  Boca Raton: CRC
190              Press, 1992.  Pages 105-110.
191

DOCUMENT SOURCE

193       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
194       source.  The master documentation is at
195
196              http://netpbm.sourceforge.net/doc/pnmhisteq.html
197
198netpbm documentation             22 March 2015        Pnmhisteq User Manual(0)
Impressum