1Pnmnorm User Manual(0) Pnmnorm User Manual(0)
2
3
4
6 pnmnorm - normalize the contrast in a Netpbm image
7
8
10 pnmnorm
11
12 [-bpercent=percent | -bvalue=N | -bsingle]
13
14 [-wpercent=percent | -wvalue=N | -wsingle]
15
16 [-midvalue=N]
17
18 [-middle=N]
19
20 [-maxexpand=percent]
21
22 [-keephues]
23
24 [-luminosity | -colorvalue | -saturation]
25
26 [ppmfile]
27
28 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
33
35 This program is part of Netpbm(1).
36
37 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
42 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
51 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
55 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
61 For a PPM image, you have a choice of three ways to define brightness:
62
63
64 · luminosity
65
66 · color value
67
68 · saturation
69
70
71 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
76 Note that all of these are different from separately normalizing the
77 individual color components.
78
79 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
86
87
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
94 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
100
101
102 -bpercent
103
104 -wpercent
105
106 -bvalue
107
108 -wvalue
109
110 To specify a percentage, use the -bpercent and -wpercent
111 options, or you can specify the exact pixel values to be mapped
112 by using the -bvalue and -wvalue options. You can get appropri‐
113 ate numbers for the options from ppmhist. If you just want to
114 enhance 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
121 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
127 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
131 -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
135 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
140 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
147 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
154 legal. In the example, pnmnorm would either make the black
155 value 99 or the white value 101.
156
157 Before Netpbm 10.43 (June 2008), pnmnorm fails if the -wpercent
158 and/or -bpercent values specify an overlap.
159
160 The stretch points are further constrained by the -maxexpand
161 option. Sometimes, too much contrast is a bad thing. If your
162 intensities 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
170
171 -bsingle
172
173 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
179
180 -maxexpand
181
182 So that you can put a limit on the amount of expansion without
183 having to examine the image first, there is the -maxexpand
184 option. It specifies the maximum expansion you will tolerate,
185 as an additional percentage. In the example above, you could
186 say -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
193 When pnmnorm limits the expansion because of -maxexpand, it
194 tells you about it with a message like this:
195 <span style="font-family: monospace">
196 limiting expansion of 150% to 50%
197 </span>
198
199 In any case, pnmnorm tells you exactly what expansion it's
200 doing, like this:
201
202 <span style="font-family: monospace">
203 remapping 25..75 to 0..100
204 </span>
205
206 Before Netpbm 10.26 (December 2004), it was not valid to specify
207 both -bvalue and -bpercent or -wvalue and -wpercent.
208
209 -maxexpand was new in Netpbm 10.32 (February 2006).
210
211
212 -keephues
213
214 This option says to keep each pixel the same hue as it is in the
215 input; just adjust its brightness. You normally want this; the
216 only reason it is not the default behavior is backward compati‐
217 bility with a design mistake.
218
219 By default, pnmnorm normalizes contrast in each component inde‐
220 pendently (except that the meaning of the -wpercent and -bper‐
221 cent options are based on the overall brightnesses of the col‐
222 ors, not each component taken separately). So if you have a
223 color which is intensely red but dimly green, pnmnorm would make
224 the red more intense and the green less intense, so you end up
225 with a different hue than you started with.
226
227
228 -midvalue=N
229
230 -middle=N
231
232 When you specify -midvalue=N, pnmnorm uses a quadratic function
233 to map old brightnesses to new ones, making sure that an old
234 brightness of N becomes 50% bright in the output. You can over‐
235 ride that 50% default with -middle. The value of -middle is a
236 floating point number in the range 0 through 1 with 0 being full
237 darkness and 1 full brightness. If your -midvalue and -middle
238 indicate an ambiguous or impossible quadratic function (e.g.
239 -midvalue is the same as -bvalue, so an infinite number of qua‐
240 dratic functions fit), pnmnorm just ignores your -midvalue and
241 maps linearly.
242
243 -midvalue and -middle were new in Netpbm 10.57 (December 2011).
244
245 If you specify -keephues, pnmnorm would likely leave this pixel
246 alone, since its overall brightness is medium.
247
248 -keephues can cause clipping, because a certain color may be
249 below a target intensity while one of its components is satu‐
250 rated. Where that's the case, pnmnorm uses the maximum repre‐
251 sentable intensity for the saturated component and the pixel
252 ends up with less overall intensity, and a different hue, than
253 it is supposed to have.
254
255 This option is meaningless on grayscale images.
256
257 When you don't specify -keephues, the -luminosity, -colorvalue,
258 and -saturation options affect the transfer function (which is
259 the same for all three RGB components), but are meaningless when
260 it comes to applying the transfer function (since it is applied
261 to each individual RGB component).
262
263 Before Netpbm 9.25 (March 2002), there was no -keephues option.
264
265
266 -luminosity
267
268 -colorvalue
269
270 -saturation
271
272 -luminosity, -colorvalue, and -saturation determine what prop‐
273 erty of the pixels pnmnorm normalizes. I.e., what kind of
274 brightness. You cannot specify more than one of these.
275
276 The -luminosity option says to use the luminosity (i.e. the "Y"
277 in the YUV or YCbCr color space) as the pixel's brightness. The
278 luminosity is a measure of how bright a human eye would find the
279 color, taking into account the fact that the human eye is more
280 sensitive to some RGB components than others.
281
282 This option is default.
283
284 This option is meaningless on grayscale images.
285
286 Before Netpbm 10.28 (August 2005), there was no -luminosity
287 option, but its meaning was still the default.
288
289 Before Netpbm 10.28 (August 2005), there was no -colorvalue
290 option.
291
292 The -colorvalue option says to use the color value (i.e. the "V"
293 in the HSV color space) as the pixel's brightness. The color
294 value is the gamma-adjusted intensity of the most intense RGB
295 component.
296
297 This option is meaningless on grayscale images.
298
299 Before Netpbm 10.28 (August 2005), there was no -colorvalue
300 option.
301
302 The -saturation option says to use the saturation (i.e. the "S"
303 in the HSV color space) as the pixel's brightness. The satura‐
304 tion is the ratio of the intensity of the most intense RGB com‐
305 ponent to the difference between the intensities of the most and
306 least intense RGB component (all intensities gamma-adjusted).
307
308 In this case, "brightness" is more of a metaphor than anything.
309 "bright" means saturated and "dark" means unsaturated.
310
311 This option is meaningless on grayscale images.
312
313 Before Netpbm 10.28 (August 2005), there was no -colorvalue
314 option.
315
316
317
318
320 pnmhisteq(1), pamlevels(1), ppmhist(1), pgmhist(1), pambrighten(1),
321 ppmdim(1), pnmgamma(1), pnm(1)
322
324 This manual page was generated by the Netpbm tool 'makeman' from HTML
325 source. The master documentation is at
326
327 http://netpbm.sourceforge.net/doc/pnmnorm.html
328
329netpbm documentation 19 December 2014 Pnmnorm User Manual(0)