1Pnmnorm User Manual(0) Pnmnorm User Manual(0)
2
6 pnmnorm - normalize the contrast in a Netpbm image
7
10 pnmnorm
11 [-bpercent=percent | -bvalue=N | -bsingle]
13 [-wpercent=percent | -wvalue=N | -wsingle]
15 [-midvalue=N]
17 [-middle=N]
19 [-maxexpand=percent]
21 [-keephues]
23 [-luminosity | -colorvalue | -saturation]
25 [ppmfile]
27 All options can be abbreviated to their shortest unique prefix. You
29 may use two hyphens instead of one to designate an option. You may use
30 either white space or an equals sign between an option name and its
31 value.
32
35 This program is part of Netpbm(1).
36 pnmnorm reads a PNM image (PBM, PGM, or PPM). It normalizes the con‐
38 trast by forcing the brightest pixels to white, the darkest pixels to
39 black, and spreading out the ones in between. It produces the same
40 kind of file as output. This is pretty useless for a PBM image.
41 The program offers two ways of spreading out the pixels in between the
43 darkest and brightest: linear and quadratic. In the quadratic case,
44 you specify some in between brightness and specify what brightness that
45 should become in the output. With those three constraints: the bright‐
46 ness that becomes black, the brightness that becomes white, and the
47 brightness that becomes that middle value, pnmnorm computes a quadratic
48 equation that maps all the other brightnesses from input values to out‐
49 put values.
50 The program first determines a mapping of old brightness to new bright‐
52 ness. For each possible brightness of a pixel, the program determines
53 a corresponding brightness for the output image.
54 Then for each pixel in the image, the program computes a color which
56 has the desired output brightness and puts that in the output. With a
57 color image, it is not always possible to compute such a color and
58 retain any semblance of the original hue, so the brightest and dimmest
59 pixels may only approximate the desired brightness.
60 For a PPM image, you have a choice of three ways to define brightness:
62 · luminosity
65 · color value
67 · saturation
69 In the case of saturation, "brightness" is pretty much a mis‐
72 nomer, but you can use the brightness analogy to see what it
73 does. In the analogy, bright means saturated and dark means
74 unsaturated.
75 Note that all of these are different from separately normalizing the
77 individual color components.
78 An alternative way to spread out the brightnesses in an image is
80 pnmhisteq. pnmhisteq stretches the brightest pixels to white and the
81 darkest pixels to black, but rather than linearly adjusting the ones in
82 between, it adjusts them so that there are an equal number of pixels of
83 each brightness throughout the range. This gives you more contrast
84 than pnmnorm does, but can considerably change the picture in exchange.
85
89 By default, the darkest 2 percent of all pixels are mapped to black,
90 and the brightest 1 percent are mapped to white. You can override this
91 behavior and specify either a different percentage, or specific bright‐
92 ness values to map to black and to white, or just have the single
93 greatest brightness map to white and the least brightness map to black.
94 To specify a percentage, use the -bpercent and -wpercent options, or
96 you can specify the exact pixel values to be mapped by using the
97 -bvalue and -wvalue options. You can get appropriate numbers for the
98 options from ppmhist. If you just want to enhance the contrast, then
99 choose values at elbows in the histogram; e.g. if value 29 represents
100 3% of the image but value 30 represents 20%, choose 30 for bvalue. If
101 you want to brighten the image, then set bvalue to 0 and just fiddle
102 with wvalue; similarly, to darken the image, set wvalue to maxval and
103 play with bvalue.
104 If you specify both -bvalue and -bpercent, pnmnorm uses the one that
106 produces the least change. The same goes for -wvalue and -wpercent.
107 (In Netpbm 10.26 (January 2005), the -bvalue/-wvalue takes precedence,
108 and before that, it's a syntax error to specify both).
109 If you want to maximize the change instead of minimizing it, just cas‐
111 cade two runs of pnmnorm, specifying values for the first and percent‐
112 ages for the second.
113 -bpercent and -wpercent values are floating point decimal. Zero is
115 valid and is the same as -bvalue=0 or -wvalue=maxval, respectively.
116 Because there are whole numbers of pixels at each brightness, pnmnorm
118 obviously can't guarantee the exact percentage, so it arranges that at
119 least the percentage of pixels you specify get remapped as promised.
120 It is possible for your -bpercent or -wpercent to overlap your -wvalue
122 or -bvalue, respectively. For example, you say -bpercent=20 and
123 -wvalue=100 for an image in which only 10 percent of the pixels are
124 darker than 100. In that case, pnmnorm adjusts the percentile value as
125 required. In the example, it uses 99 as the black value (like
126 -bvalue=99).
127 It is also possible for your -bpercent and -wpercent options to select
129 the same brightness value for the stretch-to-white and stretch-to-black
130 value because of the fact that pnmnorm can't subdivide a histogram
131 cell. E.g. if an image is all brightness 100, then no matter what
132 -bpercent and -wpercent values you choose, it's the same as saying
133 -bvalue=100 -wvalue=100. In that case, pnmnorm changes one of the val‐
134 ues by 1 to make it legal. In the example, pnmnorm would either make
135 the black value 99 or the white value 101.
136 Before Netpbm 10.43 (June 2008), pnmnorm fails if the -wpercent and/or
138 -bpercent values specify an overlap.
139 The stretch points are further constrained by the -maxexpand option.
141 Sometimes, too much contrast is a bad thing. If your intensities are
142 all concentrated in the middle, -bpercent=2 and -wpercent=1 might mean
143 that an intensity of 60 gets stretched up to 100 and intensity of 20
144 gets stretched down to zero, for a range expansion of 150% (from a
145 range of 40 to a range of 100). That much stretching means two adja‐
146 cent pixels that used to differ in intensity by 4 units now differ by
147 10, and that might be unsightly.
148 To specify that the single least brightness in the image should stretch
150 to black in the output, specify -bsingle. To specify that the single
151 greatest brightness in the image should stretch to white in the output,
152 specify -wsingle. -bsingle and -wsingle were new in Netpbm 10.69
153 (December 2014).
154 So that you can put a limit on the amount of expansion without having
156 to examine the image first, there is the -maxexpand option. It speci‐
157 fies the maximum expansion you will tolerate, as an additional percent‐
158 age. In the example above, you could say -maxexpand=50 to say you want
159 the range to expand by at most 50%, regardless of your other options.
160 pnmnorm figures out what intensity to stretch to full intensity and
161 what intensity to stretch to zero intensity as described above, and
162 then raises the former and lowers the latter as needed to limit the
163 expansion to the amount you specified.
164 When pnmnorm limits the expansion because of -maxexpand, it tells you
166 about it with a message like this:
167 limiting expansion of 150% to 50%
168 In any case, pnmnorm tells you exactly what expansion it's doing, like
170 this:
171 remapping 25..75 to 0..100
173 Before Netpbm 10.26 (December 2004), it was not valid to specify both
175 -bvalue and -bpercent or -wvalue and -wpercent.
176 -maxexpand was new in Netpbm 10.32 (February 2006).
178 The -keephues option says to keep each pixel the same hue as it is in
180 the input; just adjust its brightness. You normally want this; the
181 only reason it is not the default behavior is backward compatibility
182 with a design mistake.
183 By default, pnmnorm normalizes contrast in each component independently
185 (except that the meaning of the -wpercent and -bpercent options are
186 based on the overall brightnesses of the colors, not each component
187 taken separately). So if you have a color which is intensely red but
188 dimly green, pnmnorm would make the red more intense and the green less
189 intense, so you end up with a different hue than you started with.
190 When you specify -midvalue=N, pnmnorm uses a quadratic function to map
192 old brightnesses to new ones, making sure that an old brightness of N
193 becomes 50% bright in the output. You can override that 50% default
194 with -middle. The value of -middle is a floating point number in the
195 range 0 through 1 with 0 being full darkness and 1 full brightness. If
196 your -midvalue and -middle indicate an ambiguous or impossible quadrat‐
197 ic function (e.g. -midvalue is the same as -bvalue, so an infinite num‐
198 ber of quadratic functions fit), pnmnorm just ignores your -midvalue
199 and maps linearly.
200 -midvalue and -middle were new in Netpbm 10.57 (December 2011).
202 If you specify -keephues, pnmnorm would likely leave this pixel alone,
204 since its overall brightness is medium.
205 -keephues can cause clipping, because a certain color may be below a
207 target intensity while one of its components is saturated. Where
208 that's the case, pnmnorm uses the maximum representable intensity for
209 the saturated component and the pixel ends up with less overall inten‐
210 sity, and a different hue, than it is supposed to have.
211 This option is meaningless on grayscale images.
213 When you don't specify -keephues, the -luminosity, -colorvalue, and
215 -saturation options affect the transfer function (which is the same for
216 all three RGB components), but are meaningless when it comes to apply‐
217 ing the transfer function (since it is applied to each individual RGB
218 component).
219 Before Netpbm 9.25 (March 2002), there was no -keephues option.
221 -luminosity, -colorvalue, and -saturation determine what property of
223 the pixels pnmnorm normalizes. I.e., what kind of brightness. You
224 cannot specify more than one of these.
225 The -luminosity option says to use the luminosity (i.e. the "Y" in the
227 YUV or YCbCr color space) as the pixel's brightness. The luminosity is
228 a measure of how bright a human eye would find the color, taking into
229 account the fact that the human eye is more sensitive to some RGB com‐
230 ponents than others.
231 This option is default.
233 This option is meaningless on grayscale images.
235 Before Netpbm 10.28 (August 2005), there was no -luminosity option, but
237 its meaning was still the default.
238 Before Netpbm 10.28 (August 2005), there was no -colorvalue option.
240 The -colorvalue option says to use the color value (i.e. the "V" in the
242 HSV color space) as the pixel's brightness. The color value is the
243 gamma-adjusted intensity of the most intense RGB component.
244 This option is meaningless on grayscale images.
246 Before Netpbm 10.28 (August 2005), there was no -colorvalue option.
248 The -saturation option says to use the saturation (i.e. the "S" in the
250 HSV color space) as the pixel's brightness. The saturation is the
251 ratio of the intensity of the most intense RGB component to the differ‐
252 ence between the intensities of the most and least intense RGB compo‐
253 nent (all intensities gamma-adjusted).
254 In this case, "brightness" is more of a metaphor than anything.
256 "bright" means saturated and "dark" means unsaturated.
257 This option is meaningless on grayscale images.
259 Before Netpbm 10.28 (August 2005), there was no -colorvalue option.
261
266 pnmhisteq(1), pamlevels(1), ppmhist(1), pgmhist(1), pambrighten(1),
267 ppmdim(1), pnmgamma(1), pnm(1)
268
270 This manual page was generated by the Netpbm tool 'makeman' from HTML
271 source. The master documentation is at
272 http://netpbm.sourceforge.net/doc/pnmnorm.html
274netpbm documentation 19 December 2014 Pnmnorm User Manual(0)