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       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
95       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
105       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
110       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
114       -bpercent and -wpercent values are floating  point  decimal.   Zero  is
115       valid and is the same as -bvalue=0 or -wvalue=maxval, respectively.
116
117       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
121       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
128       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
137       Before  Netpbm 10.43 (June 2008), pnmnorm fails if the -wpercent and/or
138       -bpercent values specify an overlap.
139
140       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
149       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
155       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
165       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
169       In any case, pnmnorm tells you exactly what expansion it's doing,  like
170       this:
171
172           remapping 25..75 to 0..100
173
174       Before  Netpbm  10.26 (December 2004), it was not valid to specify both
175       -bvalue and -bpercent or -wvalue and -wpercent.
176
177       -maxexpand was new in Netpbm 10.32 (February 2006).
178
179       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
184       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
191       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
201       -midvalue and -middle were new in Netpbm 10.57 (December 2011).
202
203       If you specify -keephues, pnmnorm would likely leave this pixel  alone,
204       since its overall brightness is medium.
205
206       -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
212       This option is meaningless on grayscale images.
213
214       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
220       Before Netpbm 9.25 (March 2002), there was no -keephues option.
221
222       -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
226       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
232       This option is default.
233
234       This option is meaningless on grayscale images.
235
236       Before Netpbm 10.28 (August 2005), there was no -luminosity option, but
237       its meaning was still the default.
238
239       Before Netpbm 10.28 (August 2005), there was no -colorvalue option.
240
241       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
245       This option is meaningless on grayscale images.
246
247       Before Netpbm 10.28 (August 2005), there was no -colorvalue option.
248
249       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
255       In this case,  "brightness"  is  more  of  a  metaphor  than  anything.
256       "bright" means saturated and "dark" means unsaturated.
257
258       This option is meaningless on grayscale images.
259
260       Before Netpbm 10.28 (August 2005), there was no -colorvalue option.
261
262
263
264

SEE ALSO

266       pnmhisteq(1),   ppmhist(1),  pgmhist(1),  pnmgamma(1),  ppmbrighten(1),
267       ppmdim(1), pnm(1)
268

DOCUMENT SOURCE

270       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
271       source.  The master documentation is at
272
273              http://netpbm.sourceforge.net/doc/pnmnorm.html
274
275netpbm documentation           19 December 2014         Pnmnorm User Manual(0)
Impressum