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 re‐
58 tain 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 un‐
74 saturated.
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 pn‐
80 mhisteq. 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 In addition to the options common to all programs based on libnetpbm
90 (most notably -quiet, see
91 Common Options ⟨index.html#commonoptions⟩ ), pnmnorm recognizes the
92 following command line options:
93 By default, the darkest 2 percent of all pixels are mapped to black,
95 and the brightest 1 percent are mapped to white. You can override this
96 behavior and specify either a different percentage, or specific bright‐
97 ness values to map to black and to white, or just have the single
98 greatest brightness map to white and the least brightness map to black.
99 -bpercent
103 -wpercent
105 -bvalue
107 -wvalue
109 To specify a percentage, use the -bpercent and -wpercent op‐
111 tions, or you can specify the exact pixel values to be mapped by
112 using the -bvalue and -wvalue options. You can get appropriate
113 numbers for the options from ppmhist. If you just want to en‐
114 hance the contrast, then choose values at elbows in the his‐
115 togram; e.g. if value 29 represents 3% of the image but value 30
116 represents 20%, choose 30 for bvalue. If you want to brighten
117 the image, then set bvalue to 0 and just fiddle with wvalue;
118 similarly, to darken the image, set wvalue to maxval and play
119 with bvalue.
120 If you specify both -bvalue and -bpercent, pnmnorm uses the one
122 that produces the least change. The same goes for -wvalue and
123 -wpercent. (In Netpbm 10.26 (January 2005), the -bvalue/-wvalue
124 takes precedence, and before that, it's a syntax error to spec‐
125 ify both).
126 If you want to maximize the change instead of minimizing it,
128 just cascade two runs of pnmnorm, specifying values for the
129 first and percentages for the second.
130 -bpercent and -wpercent values are floating point decimal. Zero
132 is valid and is the same as -bvalue=0 or -wvalue=maxval, respec‐
133 tively.
134 Because there are whole numbers of pixels at each brightness,
136 pnmnorm obviously can't guarantee the exact percentage, so it
137 arranges that at least the percentage of pixels you specify get
138 remapped as promised.
139 It is possible for your -bpercent or -wpercent to overlap your
141 -wvalue or -bvalue, respectively. For example, you say -bper‐
142 cent=20 and -wvalue=100 for an image in which only 10 percent of
143 the pixels are darker than 100. In that case, pnmnorm adjusts
144 the percentile value as required. In the example, it uses 99 as
145 the black value (like -bvalue=99).
146 It is also possible for your -bpercent and -wpercent options to
148 select the same brightness value for the stretch-to-white and
149 stretch-to-black value because of the fact that pnmnorm can't
150 subdivide a histogram cell. E.g. if an image is all brightness
151 100, then no matter what -bpercent and -wpercent values you
152 choose, it's the same as saying -bvalue=100 -wvalue=100. In
153 that case, pnmnorm changes one of the values by 1 to make it le‐
154 gal. In the example, pnmnorm would either make the black value
155 99 or the white value 101.
156 Before Netpbm 10.43 (June 2008), pnmnorm fails if the -wpercent
158 and/or -bpercent values specify an overlap.
159 The stretch points are further constrained by the -maxexpand op‐
161 tion. Sometimes, too much contrast is a bad thing. If your in‐
162 tensities are all concentrated in the middle, -bpercent=2 and
163 -wpercent=1 might mean that an intensity of 60 gets stretched up
164 to 100 and intensity of 20 gets stretched down to zero, for a
165 range expansion of 150% (from a range of 40 to a range of 100).
166 That much stretching means two adjacent pixels that used to dif‐
167 fer in intensity by 4 units now differ by 10, and that might be
168 unsightly.
169 -bsingle
172 To specify that the single least brightness in the image should
174 stretch to black in the output, specify -bsingle. To specify
175 that the single greatest brightness in the image should stretch
176 to white in the output, specify -wsingle. -bsingle and -wsingle
177 were new in Netpbm 10.69 (December 2014).
178 -maxexpand
181 So that you can put a limit on the amount of expansion without
183 having to examine the image first, there is the -maxexpand op‐
184 tion. It specifies the maximum expansion you will tolerate, as
185 an additional percentage. In the example above, you could say
186 -maxexpand=50 to say you want the range to expand by at most
187 50%, regardless of your other options. pnmnorm figures out what
188 intensity to stretch to full intensity and what intensity to
189 stretch to zero intensity as described above, and then raises
190 the former and lowers the latter as needed to limit the expan‐
191 sion to the amount you specified.
192 When pnmnorm limits the expansion because of -maxexpand, it
194 tells you about it with a message like this:
195 limiting expansion of 150% to 50%
197 In any case, pnmnorm tells you exactly what expansion it's do‐
201 ing, like this:
202 remapping 25..75 to 0..100
205 Before Netpbm 10.26 (December 2004), it was not valid to specify
209 both -bvalue and -bpercent or -wvalue and -wpercent.
210 -maxexpand was new in Netpbm 10.32 (February 2006).
212 -keephues
215 This option says to keep each pixel the same hue as it is in the
217 input; just adjust its brightness. You normally want this; the
218 only reason it is not the default behavior is backward compati‐
219 bility with a design mistake.
220 By default, pnmnorm normalizes contrast in each component inde‐
222 pendently (except that the meaning of the -wpercent and -bper‐
223 cent options are based on the overall brightnesses of the col‐
224 ors, not each component taken separately). So if you have a
225 color which is intensely red but dimly green, pnmnorm would make
226 the red more intense and the green less intense, so you end up
227 with a different hue than you started with.
228 -midvalue=N
231 -middle=N
233 When you specify -midvalue=N, pnmnorm uses a quadratic function
235 to map old brightnesses to new ones, making sure that an old
236 brightness of N becomes 50% bright in the output. You can over‐
237 ride that 50% default with -middle. The value of -middle is a
238 floating point number in the range 0 through 1 with 0 being full
239 darkness and 1 full brightness. If your -midvalue and -middle
240 indicate an ambiguous or impossible quadratic function (e.g.
241 -midvalue is the same as -bvalue, so an infinite number of qua‐
242 dratic functions fit), pnmnorm just ignores your -midvalue and
243 maps linearly.
244 -midvalue and -middle were new in Netpbm 10.57 (December 2011).
246 If you specify -keephues, pnmnorm would likely leave this pixel
248 alone, since its overall brightness is medium.
249 -keephues can cause clipping, because a certain color may be be‐
251 low a target intensity while one of its components is saturated.
252 Where that's the case, pnmnorm uses the maximum representable
253 intensity for the saturated component and the pixel ends up with
254 less overall intensity, and a different hue, than it is supposed
255 to have.
256 This option is meaningless on grayscale images.
258 When you don't specify -keephues, the -luminosity, -colorvalue,
260 and -saturation options affect the transfer function (which is
261 the same for all three RGB components), but are meaningless when
262 it comes to applying the transfer function (since it is applied
263 to each individual RGB component).
264 Before Netpbm 9.25 (March 2002), there was no -keephues option.
266 -luminosity
269 -colorvalue
271 -saturation
273 -luminosity, -colorvalue, and -saturation determine what prop‐
275 erty of the pixels pnmnorm normalizes. I.e., what kind of
276 brightness. You cannot specify more than one of these.
277 The -luminosity option says to use the luminosity (i.e. the "Y"
279 in the YUV or YCbCr color space) as the pixel's brightness. The
280 luminosity is a measure of how bright a human eye would find the
281 color, taking into account the fact that the human eye is more
282 sensitive to some RGB components than others.
283 This option is default.
285 This option is meaningless on grayscale images.
287 Before Netpbm 10.28 (August 2005), there was no -luminosity op‐
289 tion, but its meaning was still the default.
290 Before Netpbm 10.28 (August 2005), there was no -colorvalue op‐
292 tion.
293 The -colorvalue option says to use the color value (i.e. the "V"
295 in the HSV color space) as the pixel's brightness. The color
296 value is the gamma-adjusted intensity of the most intense RGB
297 component.
298 This option is meaningless on grayscale images.
300 Before Netpbm 10.28 (August 2005), there was no -colorvalue op‐
302 tion.
303 The -saturation option says to use the saturation (i.e. the "S"
305 in the HSV color space) as the pixel's brightness. The satura‐
306 tion is the ratio of the intensity of the most intense RGB com‐
307 ponent to the difference between the intensities of the most and
308 least intense RGB component (all intensities gamma-adjusted).
309 In this case, "brightness" is more of a metaphor than anything.
311 "bright" means saturated and "dark" means unsaturated.
312 This option is meaningless on grayscale images.
314 Before Netpbm 10.28 (August 2005), there was no -colorvalue op‐
316 tion.
317
322 pnmhisteq(1), pamlevels(1), ppmhist(1), pgmhist(1), pambrighten(1), pp‐
323 mdim(1), pnmgamma(1), pnm(1)
324
326 This manual page was generated by the Netpbm tool 'makeman' from HTML
327 source. The master documentation is at
328 http://netpbm.sourceforge.net/doc/pnmnorm.html
330netpbm documentation 19 December 2014 Pnmnorm User Manual(0)