Debian Codegraph @

upstream/debian-unstable/man1/pnmnorm.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Pnmnorm User Manual" 1 "19 December 2014" "netpbm documentation"
7
8 .SH NAME
9
10 pnmnorm - normalize the contrast in a Netpbm image
11
12 .UN synopsis
13 .SH SYNOPSIS
14
15 \fBpnmnorm\fP
16
17 [\fB-bpercent=\fP\fIpercent\fP | \fB-bvalue=\fP\fIN\fP | \fB-bsingle\fP]
18
19 [\fB-wpercent=\fP\fIpercent\fP | \fB-wvalue=\fP\fIN\fP | \fB-wsingle\fP]
20
21 [\fB-midvalue=\fP\fIN\fP]
22
23 [\fB-middle=N\fP]
24
25 [\fB-maxexpand=\fP\fIpercent\fP]
26
27 [\fB-keephues\fP]
28
29 [\fB-luminosity\fP | \fB-colorvalue\fP | \fB-saturation\fP]
30
31 [\fIppmfile\fP]
32 .PP
33 All options can be abbreviated to their shortest unique prefix.
34 You may use two hyphens instead of one to designate an option. You
35 may use either white space or an equals sign between an option name
36 and its value.
37
38 .UN description
39 .SH DESCRIPTION
40 .PP
41 This program is part of
42 .BR "Netpbm" (1)\c
43 \&.
44 .PP
45 \fBpnmnorm\fP reads a PNM image (PBM, PGM, or PPM). It normalizes the
46 contrast by forcing the brightest pixels to white, the darkest pixels to
47 black, and spreading out the ones in between. It produces the same kind of
48 file as output. This is pretty useless for a PBM image.
49 .PP
50 The program offers two ways of spreading out the pixels in between the
51 darkest and brightest: linear and quadratic. In the quadratic case, you
52 specify some in between brightness and specify what brightness that should
53 become in the output. With those three constraints: the brightness that
54 becomes black, the brightness that becomes white, and the brightness that
55 becomes that middle value, \fBpnmnorm\fP computes a quadratic equation that
56 maps all the other brightnesses from input values to output values.
57 .PP
58 The program first determines a mapping of old brightness to new
59 brightness. For each possible brightness of a pixel, the program
60 determines a corresponding brightness for the output image.
61 .PP
62 Then for each pixel in the image, the program computes a color which has
63 the desired output brightness and puts that in the output. With a color
64 image, it is not always possible to compute such a color and retain any
65 semblance of the original hue, so the brightest and dimmest pixels may only
66 approximate the desired brightness.
67 .PP
68 For a PPM image, you have a choice of three ways to define brightness:
69
70 .IP \(bu
71 luminosity
72 .IP \(bu
73 color value
74 .IP \(bu
75 saturation
76
77
78 In the case of saturation, "brightness" is pretty much a
79 misnomer, but you can use the brightness analogy to see what it does.
80 In the analogy, bright means saturated and dark means unsaturated.
81 .PP
82 Note that all of these are different from separately normalizing
83 the individual color components.
84 .PP
85 An alternative way to spread out the brightnesses in an image is
86 \fBpnmhisteq\fP. \fBpnmhisteq\fP stretches the brightest pixels to
87 white and the darkest pixels to black, but rather than linearly
88 adjusting the ones in between, it adjusts them so that there are an
89 equal number of pixels of each brightness throughout the range. This
90 gives you more contrast than \fBpnmnorm\fP does, but can considerably
91 change the picture in exchange.
92
93
94 .UN options
95 .SH OPTIONS
96 .PP
97 In addition to the options common to all programs based on libnetpbm
98 (most notably \fB-quiet\fP, see
99 .UR index.html#commonoptions
100 Common Options
101 .UE
102 \&), \fBpnmnorm\fP recognizes the following
103 command line options:
104 .PP
105 By default, the darkest 2 percent of all pixels are mapped to
106 black, and the brightest 1 percent are mapped to white. You can
107 override this behavior and specify either a different percentage, or
108 specific brightness values to map to black and to white, or just have
109 the single greatest brightness map to white and the least brightness map
110 to black.
111
112
113 .TP
114 \fB-bpercent\fP
115 .TP
116 \fB-wpercent\fP
117 .TP
118 \fB-bvalue\fP
119 .TP
120 \fB-wvalue\fP
121 .sp
122 To specify a percentage, use the \fB-bpercent\fP and
123 \fB-wpercent\fP options, or you can specify the exact pixel values to
124 be mapped by using the \fB-bvalue\fP and \fB-wvalue\fP options.
125 You can get appropriate numbers for the options from
126 \fBppmhist\fP. If you just want to enhance the contrast, then
127 choose values at elbows in the histogram; e.g. if value 29 represents
128 3% of the image but value 30 represents 20%, choose 30 for
129 \fIbvalue\fP. If you want to brighten the image, then set
130 \fIbvalue\fP to 0 and just fiddle with \fIwvalue\fP; similarly, to
131 darken the image, set \fIwvalue\fP to maxval and play with
132 \fIbvalue\fP.
133 .sp
134 If you specify both \fB-bvalue\fP and \fB-bpercent\fP, \fBpnmnorm\fP
135 uses the one that produces the least change. The same goes for
136 \fB-wvalue\fP and \fB-wpercent\fP. (In Netpbm 10.26 (January 2005),
137 the \fB-bvalue\fP/\fB-wvalue\fP takes precedence, and before that,
138 it's a syntax error to specify both).
139 .sp
140 If you want to maximize the change instead of minimizing it, just
141 cascade two runs of \fBpnmnorm\fP, specifying values for the first
142 and percentages for the second.
143 .sp
144 \fB-bpercent\fP and \fB-wpercent\fP values are floating point
145 decimal. Zero is valid and is the same as \fB-bvalue=0\fP or
146 \fB-wvalue=\fP\fImaxval\fP, respectively.
147 .sp
148 Because there are whole numbers of pixels at each brightness,
149 \fBpnmnorm\fP obviously can't guarantee the exact percentage, so it
150 arranges that \fIat least\fP the percentage of pixels you specify
151 get remapped as promised.
152 .sp
153 It is possible for your \fB-bpercent\fP or \fB-wpercent\fP
154 to overlap your \fB-wvalue\fP or \fB-bvalue\fP, respectively. For
155 example, you say \fB-bpercent=20\fP and \fB-wvalue=100\fP for an
156 image in which only 10 percent of the pixels are darker than 100.
157 In that case, \fBpnmnorm\fP adjusts the percentile value as
158 required. In the example, it uses 99 as the black value (like
159 \fB-bvalue=99\fP).
160 .sp
161 It is also possible for your \fB-bpercent\fP and \fB-wpercent\fP
162 options to select the same brightness value for the stretch-to-white
163 and stretch-to-black value because of the fact that \fBpnmnorm\fP
164 can't subdivide a histogram cell. E.g. if an image is all brightness
165 100, then no matter what \fB-bpercent\fP and \fB-wpercent\fP
166 values you choose, it's the same as saying \fB-bvalue=100 -wvalue=100\fP.
167 In that case, \fBpnmnorm\fP changes one of the values by 1 to make it
168 legal. In the example, \fBpnmnorm\fP would either make the black
169 value 99 or the white value 101.
170 .sp
171 Before Netpbm 10.43 (June 2008), \fBpnmnorm\fP fails if the
172 \fB-wpercent\fP and/or \fB-bpercent\fP values specify an overlap.
173 .sp
174 The stretch points are further constrained by the \fB-maxexpand\fP
175 option. Sometimes, too much contrast is a bad thing. If your
176 intensities are all concentrated in the middle, \fB-bpercent=2\fP and
177 \fB-wpercent=1\fP might mean that an intensity of 60 gets stretched
178 up to 100 and intensity of 20 gets stretched down to zero, for a
179 range expansion of 150% (from a range of 40 to a range of 100). That
180 much stretching means two adjacent pixels that used to differ in
181 intensity by 4 units now differ by 10, and that might be unsightly.
182
183 .TP
184 \fB-bsingle\fP
185 .sp
186 To specify that the single least brightness in the image should stretch to
187 black in the output, specify \fB-bsingle\fP. To specify that the single
188 greatest brightness in the image should stretch to white in the output,
189 specify \fB-wsingle\fP. \fB-bsingle\fP and \fB-wsingle\fP were new in
190 Netpbm 10.69 (December 2014).
191
192 .TP
193 \fB-maxexpand\fP
194 .sp
195 So that you can put a limit on the amount of expansion without
196 having to examine the image first, there is the \fB-maxexpand\fP
197 option. It specifies the maximum expansion you will tolerate, as an
198 additional percentage. In the example above, you could say
199 \fB-maxexpand=50\fP to say you want the range to expand by at most
200 50%, regardless of your other options. \fBpnmnorm\fP figures out
201 what intensity to stretch to full intensity and what intensity to
202 stretch to zero intensity as described above, and then raises the
203 former and lowers the latter as needed to limit the expansion to the
204 amount you specified.
205 .sp
206 When \fBpnmnorm\fP limits the expansion because of \fB-maxexpand\fP,
207 it tells you about it with a message like this:
208 .nf
209
210 limiting expansion of 150% to 50%
211
212
213 .fi
214 .sp
215 In any case, \fBpnmnorm\fP tells you exactly what expansion it's
216 doing, like this:
217
218 .nf
219
220 remapping 25..75 to 0..100
221
222
223 .fi
224 .sp
225 Before Netpbm 10.26 (December 2004), it was not valid to specify both
226 \fB-bvalue\fP and \fB-bpercent\fP or \fB-wvalue\fP and \fB-wpercent\fP.
227 .sp
228 \fB-maxexpand\fP was new in Netpbm 10.32 (February 2006).
229
230 .TP
231 \fB-keephues\fP
232 .sp
233 This option says to keep each pixel the same hue as
234 it is in the input; just adjust its brightness. You normally want this;
235 the only reason it is not the default behavior is backward compatibility
236 with a design mistake.
237 .sp
238 By default, \fBpnmnorm\fP normalizes contrast in each component
239 independently (except that the meaning of the \fB-wpercent\fP and
240 \fB-bpercent\fP options are based on the overall brightnesses of the
241 colors, not each component taken separately). So if you have a color
242 which is intensely red but dimly green, \fBpnmnorm\fP would make the
243 red more intense and the green less intense, so you end up with a
244 different hue than you started with.
245
246 .TP
247 \fB-midvalue=\fP\fIN\fP
248 .TP
249 \fB-middle=\fP\fIN\fP
250 .sp
251 When you specify \fB-midvalue=\fP\fIN\fP, \fBpnmnorm\fP uses a quadratic
252 function to map old brightnesses to new ones, making sure that an old
253 brightness of \fIN\fP becomes 50% bright in the output. You can override
254 that 50% default with \fB-middle\fP. The value of \fB-middle\fP is a
255 floating point number in the range 0 through 1 with 0 being full darkness and
256 1 full brightness. If your \fB-midvalue\fP and \fB-middle\fP indicate an
257 ambiguous or impossible quadratic function (e.g. \fB-midvalue\fP is the same
258 as \fB-bvalue\fP, so an infinite number of quadratic functions
259 fit), \fBpnmnorm\fP just ignores your \fB-midvalue\fP and maps linearly.
260
261 \fB-midvalue\fP and \fB-middle\fP were new in Netpbm 10.57 (December 2011).
262 .sp
263 If you specify \fB-keephues\fP, \fBpnmnorm\fP would likely leave
264 this pixel alone, since its overall brightness is medium.
265 .sp
266 \fB-keephues\fP can cause clipping, because a certain color may be
267 below a target intensity while one of its components is saturated.
268 Where that's the case, \fBpnmnorm\fP uses the maximum representable
269 intensity for the saturated component and the pixel ends up with less
270 overall intensity, and a different hue, than it is supposed to have.
271 .sp
272 This option is meaningless on grayscale images.
273 .sp
274 When you \fIdon't\fP specify \fB-keephues\fP, the
275 \fB-luminosity\fP, \fB-colorvalue\fP, and \fB-saturation\fP options
276 affect the transfer function (which is the same for all three RGB
277 components), but are meaningless when it comes to applying the
278 transfer function (since it is applied to each individual RGB
279 component).
280 .sp
281 Before Netpbm 9.25 (March 2002), there was no \fB-keephues\fP option.
282
283 .TP
284 \fB-luminosity\fP
285 .TP
286 \fB-colorvalue\fP
287 .TP
288 \fB-saturation\fP
289 .sp
290 \fB-luminosity\fP, \fB-colorvalue\fP, and \fB-saturation\fP determine
291 what property of the pixels \fBpnmnorm\fP normalizes. I.e., what kind of
292 brightness. You cannot specify more than one of these.
293 .sp
294 The \fB-luminosity\fP option says to use the luminosity (i.e. the
295 "Y" in the YUV or YCbCr color space) as the pixel's brightness. The
296 luminosity is a measure of how bright a human eye would find the color,
297 taking into account the fact that the human eye is more sensitive to some
298 RGB components than others.
299 .sp
300 This option is default.
301 .sp
302 This option is meaningless on grayscale images.
303 .sp
304 Before Netpbm 10.28 (August 2005), there was no \fB-luminosity\fP option,
305 but its meaning was still the default.
306 .sp
307 Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option.
308 .sp
309 The \fB-colorvalue\fP option says to use the color value (i.e. the
310 "V" in the HSV color space) as the pixel's brightness. The
311 color value is the gamma-adjusted intensity of the most intense RGB
312 component.
313 .sp
314 This option is meaningless on grayscale images.
315 .sp
316 Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option.
317 .sp
318 The \fB-saturation\fP option says to use the saturation (i.e. the
319 "S" in the HSV color space) as the pixel's brightness. The
320 saturation is the ratio of the intensity of the most intense RGB
321 component to the difference between the intensities of the most and least
322 intense RGB component (all intensities gamma-adjusted).
323 .sp
324 In this case, "brightness" is more of a metaphor than anything.
325 "bright" means saturated and "dark" means unsaturated.
326 .sp
327 This option is meaningless on grayscale images.
328 .sp
329 Before Netpbm 10.28 (August 2005), there was no \fB-colorvalue\fP option.
330
331
332
333 .UN seealso
334 .SH SEE ALSO
335 .BR "pnmhisteq" (1)\c
336 \&,
337 .BR "pamlevels" (1)\c
338 \&,
339 .BR "ppmhist" (1)\c
340 \&,
341 .BR "pgmhist" (1)\c
342 \&,
343 .BR "pambrighten" (1)\c
344 \&,
345 .BR "ppmdim" (1)\c
346 \&,
347 .BR "pnmgamma" (1)\c
348 \&,
349 .BR "pnm" (1)\c
350 \&
351 .SH DOCUMENT SOURCE
352 This manual page was generated by the Netpbm tool 'makeman' from HTML
353 source. The master documentation is at
354 .IP
355 .B http://netpbm.sourceforge.net/doc/pnmnorm.html
356 .PP