Debian Codegraph @

upstream/debian-trixie/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 This option was new in Netpbm 10.70 (March 2015).
150
151 .TP
152 \fB-rmap\fP \fImapfile\fP
153 Process the image using the luminosity map specified by the PGM
154 file \fImapfile\fP.
155
156 The PGM image, usually created by an earlier run of \fBpnmhisteq\fP
157 with the \fB-wmap\fP option, contains a single row with number of
158 columns equal to the maxval (greatest intensity value) of the image
159 plus one. Each pixel in the image is transformed by looking up its
160 luminosity in the corresponding column in the map file (column number
161 = luminosity) and changing it to the value given by that column.
162
163 .TP
164 \fB-wmap\fP \fImapfile\fP
165 Creates a PGM file \fImapfile\fP, containing the luminosity map
166 computed from the histogram of the input image. This map file can be
167 read on subsequent runs of \fBpnmhisteq\fP with the \fB-rmap\fP
168 option, allowing a group of images to be processed with an identical
169 map.
170
171 .TP
172 \fB-verbose\fP
173 Prints the histogram and luminosity map on Standard Error.
174
175
176
177 .UN limitations
178 .SH LIMITATIONS
179 .PP
180 Histogram equalization is effective for increasing the visible
181 detail in scientific imagery and in some continuous-tone pictures. It
182 is often too drastic, however, for scanned halftone images, where it
183 does an excellent job of making halftone artifacts apparent. You
184 might want to experiment with \fBpnmnorm\fP and \fBpnmgamma\fP for
185 more subtle contrast enhancement.
186 .PP
187 The luminosity map file supplied by the \fB-rmap\fP option must
188 have the same maxval as the input image. This is always the case when
189 the map file was created by the \fB-wmap\fP option of
190 \fBpnmhisteq\fP. If this restriction causes a problem, simply adjust
191 the maxval of the map with \fBpamdepth\fP to agree with the input
192 image.
193 .PP
194 If the input is a PBM file (on which histogram equalization is an
195 identity operation), the only effect of passing the file through
196 \fBpnmhisteq\fP will be the passage of time.
197
198 .UN seealso
199 .SH SEE ALSO
200 .BR "pnmnorm" (1)\c
201 \&,
202 .BR "pamcat" (1)\c
203 \&,
204 .BR "pamdepth" (1)\c
205 \&,
206 .BR "pnmgamma" (1)\c
207 \&,
208 .BR "pnm" (1)\c
209 \&,
210
211
212 .TP
213 [1]
214 Russ, John C. The Image Processing Handbook. Boca Raton: CRC
215 Press, 1992. Pages 105-110.
216 .SH DOCUMENT SOURCE
217 This manual page was generated by the Netpbm tool 'makeman' from HTML
218 source. The master documentation is at
219 .IP
220 .B http://netpbm.sourceforge.net/doc/pnmhisteq.html
221 .PP