Debian Codegraph @

upstream/debian-unstable/man1/pnmhisteq.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Pnmhisteq User Manual" 1 "22 March 2015" "netpbm documentation"
7
8 .SH NAME
9
10 pnmhisteq - histogram equalize a PNM image
11
12 .UN synopsis
13 .SH SYNOPSIS
14
15 \fBpnmhisteq\fP
16
17 [\fB-gray\fP]
18
19 [\fB-noblack\fP]
20 [\fB-nowhite\fP]
21
22 [\fB-rmap\fP \fIpgmfile\fP]
23
24 [\fB-wmap\fP \fIpgmfile\fP]
25
26 [\fB-verbose\fP]
27
28 [\fIpnmfile\fP]
29
30
31 .UN description
32 .SH DESCRIPTION
33 .PP
34 This program is part of
35 .BR "Netpbm" (1)\c
36 \&.
37 .PP
38 \fBpnmhisteq\fP increases the contrast of a PGM or PPM image
39 through the technique of "histogram equalization."[1]
40 .PP
41 \fBpnmhisteq\fP computes a histogram of the luminosity of the
42 pixels in the image. It then calculates a mapping between each
43 luminosity and a new luminosity such that it spreads out intensity
44 levels around histogram peaks and compresses them at troughs. I.e.
45 it moves pixels around in the histogram so as to make it flat. It
46 applies that mapping to the input image to produce the output image.
47 The effect of this is that the image has equal numbers of pixels at each
48 possible intensity level, which means it uses the available levels of
49 intensity more efficiently and thereby has more visible detail.
50 .PP
51 Mathematically, the luminosity mapping is this: Assume the pixels
52 are sorted by luminosity into \fIB\fP buckets numbered from 0 (lowest
53 luminosity) to \fIB\fP-1. \fIN[i]\fP is the number of pixels in
54 bucket \fIi\fP. \fIT\fP is the total number of pixels (sum of
55 \fIN[i]\fP over all \fIi\fP). \fIW\fP is the luminosity of white.
56 .PP
57 \fBpnmhisteq\fP replaces an input pixel whose luminosity falls into
58 bucket \fIj\fP with one whose luminosity is:
59
60 .nf
61
62 j
63 ---
64 \e
65 > (N[i] / T) * W
66 /
67 ---
68 i=0
69
70 .fi
71 .PP
72 Considering a grayscale image for simplicity, this means that
73 pixels in the most luminous bucket become white. Pixels in the 10th
74 per centile of luminosity become 10% of white.
75 .PP
76 \fBpnmhisteq\fP maps a single luminosity in the input to a single
77 luminosity in the output. That means if pixels A and B both have luminosity
78 \&.2 in the input, and pixel A has luminosity .4 in the output, pixel B also has
79 luminosity .4 in the output. And since the luminosities in the input are not
80 continuous, the luminosities in the output aren't either and \fBpnmhisteq\fP
81 doesn't meet the ideal of having exactly the same number of pixels of each
82 luminosity in the output.
83 .PP
84 If you're processing a related set of images, for example frames of
85 an animation, it's generally best to apply the same luminosity mapping
86 to every frame, since otherwise you'll get distracting frame-to-frame
87 changes in the brightness of objects. \fBpnmhisteq\fP's \fB-wmap\fP
88 option allows you to save, as a PGM image, the luminosity map it
89 computes from an image. The \fB-rmap\fP option causes \fBpnmisteq\fP
90 to use such an image as its luminosity map.
91 .PP
92 So you can run \fBpnmhisteq\fP with \fB-wmap\fP on a composite you
93 created with \fBpamcat\fP of the images you intend to process. Then, you can
94 run \fBpnmisteq\fP with \fB-rmap\fP on each of the individual images, using
95 the luminosity map you generated from the composite.
96 .PP
97 Use \fBpnmhistmap\fP to see the result. Run a color image through
98 \fBppmtopgm\fP first so that you see a histogram of the luminosity instead of
99 histograms of the three color components. It should generally show a flat
100 histogram. But because of the quantization effects described above, you might
101 see high bars interleaved with low bars, with the local average being flat.
102 To see local averages, use the \fB-width\fP option of \fBpnmhistmap\fP.
103
104
105 .UN options
106 .SH OPTIONS
107 .PP
108 In addition to the options common to all programs based on libnetpbm
109 (most notably \fB-quiet\fP, see
110 .UR index.html#commonoptions
111 Common Options
112 .UE
113 \&), \fBpnmhisteq\fP recognizes the following
114 command line options:
115 .PP
116 You can abbreviate any option to its shortest unique prefix.
117
118
119 .TP
120 \fB-gray\fP
121 When processing a color image, only gray pixels (those with identical
122 red, green, and blue values) are included in the histogram and
123 modified in the output image. This is a special purpose option
124 intended for images where the actual data are gray scale, with color
125 annotations you don't want modified. Weather satellite images that
126 show continent outlines in color are best processed using this option.
127 The option has no effect when the input is a graymap.
128
129 .TP
130 \fB-noblack\fP
131 Do not include black pixels in the equalization. The black pixels in the
132 output are exactly the black pixels in the input and the number of black
133 pixels does not affect the color of any other pixels.
134 .sp
135 Sometimes, black isn't as much a color as a background or annotation for
136 the real colors, so you want to treat it specially this way. Think of a
137 picture of stars, which is nearly all black, but with lots of stars of
138 different brightness. You want to change the brightnesses of the stars to
139 maximize contrast between them, but if you considered the blackness to be
140 significant, all the stars would end up close to full white.
141 .sp
142 This option was new in Netpbm 10.70 (March 2015).
143
144 .TP
145 \fB-nowhite\fP
146 .sp
147 Same as \fB-noblack\fP, but for the white pixels.
148 .sp
149 You can use both \fB-noblack\fP and \fB-nowhite\fP if you like.
150 .sp
151 This option was new in Netpbm 10.70 (March 2015).
152
153 .TP
154 \fB-rmap\fP \fImapfile\fP
155 Process the image using the luminosity map specified by the PGM
156 file \fImapfile\fP.
157
158 The PGM image, usually created by an earlier run of \fBpnmhisteq\fP
159 with the \fB-wmap\fP option, contains a single row with number of
160 columns equal to the maxval (greatest intensity value) of the image
161 plus one. Each pixel in the image is transformed by looking up its
162 luminosity in the corresponding column in the map file (column number
163 = luminosity) and changing it to the value given by that column.
164
165 .TP
166 \fB-wmap\fP \fImapfile\fP
167 Creates a PGM file \fImapfile\fP, containing the luminosity map
168 computed from the histogram of the input image. This map file can be
169 read on subsequent runs of \fBpnmhisteq\fP with the \fB-rmap\fP
170 option, allowing a group of images to be processed with an identical
171 map.
172
173 .TP
174 \fB-verbose\fP
175 Prints the histogram and luminosity map on Standard Error.
176
177
178
179 .UN limitations
180 .SH LIMITATIONS
181 .PP
182 Histogram equalization is effective for increasing the visible
183 detail in scientific imagery and in some continuous-tone pictures. It
184 is often too drastic, however, for scanned halftone images, where it
185 does an excellent job of making halftone artifacts apparent. You
186 might want to experiment with \fBpnmnorm\fP and \fBpnmgamma\fP for
187 more subtle contrast enhancement.
188 .PP
189 The luminosity map file supplied by the \fB-rmap\fP option must
190 have the same maxval as the input image. This is always the case when
191 the map file was created by the \fB-wmap\fP option of
192 \fBpnmhisteq\fP. If this restriction causes a problem, simply adjust
193 the maxval of the map with \fBpamdepth\fP to agree with the input
194 image.
195 .PP
196 If the input is a PBM file (on which histogram equalization is an
197 identity operation), the only effect of passing the file through
198 \fBpnmhisteq\fP will be the passage of time.
199
200 .UN seealso
201 .SH SEE ALSO
202 .BR "pnmnorm" (1)\c
203 \&,
204 .BR "pamcat" (1)\c
205 \&,
206 .BR "pamdepth" (1)\c
207 \&,
208 .BR "pnmgamma" (1)\c
209 \&,
210 .BR "pnm" (1)\c
211 \&,
212
213
214 .TP
215 [1]
216 Russ, John C. The Image Processing Handbook. Boca Raton: CRC
217 Press, 1992. Pages 105-110.
218 .SH DOCUMENT SOURCE
219 This manual page was generated by the Netpbm tool 'makeman' from HTML
220 source. The master documentation is at
221 .IP
222 .B http://netpbm.sourceforge.net/doc/pnmhisteq.html
223 .PP