1Pnmnorm User Manual(0)                                  Pnmnorm User Manual(0)
2
3
4

NAME

6       pnmnorm - normalize the contrast in a Netpbm image
7
8

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

SEE ALSO

320       pnmhisteq(1),  pamlevels(1),  ppmhist(1),  pgmhist(1),  pambrighten(1),
321       ppmdim(1), pnmgamma(1), pnm(1)
322

DOCUMENT SOURCE

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)
Impressum