Debian Codegraph @

upstream/debian-unstable/man1/pnmgamma.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 "Pnmgamma User Manual" 1 "30 June 2007" "netpbm documentation"
7
8 .SH NAME
9 pnmgamma - perform gamma adjustment on a PNM image
10
11 .UN synopsis
12 .SH SYNOPSIS
13 .PP
14 \fBpnmgamma\fP
15 {
16 \fB-bt709tolinear\fP |
17 \fB-lineartobt709\fP |
18 \fB-bt709tosrgb\fP |
19 \fB-srgbtobt709\fP
20 }
21 [\fB-gamma=\fP\fIfloat\fP]
22 [\fB-rgamma=\fP\fIfloat\fP]
23 [\fB-ggamma=\fP\fIfloat\fP]
24 [\fB-bgamma=\fP\fIfloat\fP]
25
26 [\fIpnmfile\fP]
27 .PP
28 \fBpnmgamma \fP
29 [
30 \fB-bt709ramp\fP |
31 \fB-srgbramp\fP
32 ]
33 [\fB-ungamma\fP]
34 [{\fIgamma\fP | \fIredgamma\fP \fIgreengamma\fP \fIbluegamma\fP}
35 [\fIpnmfile\fP]]
36
37
38 .UN description
39 .SH DESCRIPTION
40 .PP
41 This program is part of
42 .BR "Netpbm" (1)\c
43 \&.
44 .PP
45 \fBPnmgamma\fP performs gamma adjustment on pseudo-PNM images.
46 .PP
47 The PPM format specification specifies that certain sample values
48 in a file represent certain light intensities in an image. In
49 particular, they specify that the sample values are directly
50 proportional to luminance as defined by ITU-R Recommendation BT.709.
51 BT.709 luminance as a function of radiance is a power function
52 modified with a linear ramp near black.
53 .PP
54 However, people sometimes work with approximations of PPM and PGM
55 where the sample values represent intensity in different ways:
56 .PP
57 In one common variation, the sample value is directly proportional
58 to radiance (often called "linear intensity").
59 .PP
60 Another popular variation is to make the samples proportional to
61 luminance as defined by the International Electrotechnical Commission
62 (IEC) SRGB standard. The SRGB gamma transfer function is like the
63 BT.709 one except with different constants in it.
64 .PP
65 Note that SRGB is often spelled "sRGB". In this
66 document, we use standard English typography, though, which doesn't
67 allow for that kind of capitalization.
68 .PP
69 \fBpnmgamma\fP allows you to manipulate the gamma transfer
70 function, thus working with and/or creating pseudo-PPM files that are
71 useful for various things.
72 .PP
73 For example, if you feed a true PPM to \f(CWpnmgamma -bt709tolinear
74 \fP, you get as output a file which is PPM in every respect except
75 that the sample values are radiances. If you feed such a file to
76 \f(CWpnmgamma -linearto709\fP, you get back a true PPM.
77 .PP
78 The situation for PGM images is analogous. And \fBpnmgamma\fP
79 treats PBM images as PGM images.
80 .PP
81 When you feed a radiance-proportional pseudo-PPM image to a display
82 program that expects a true PPM, the display appears darker than it
83 should, so \fBpnmgamma\fP has the effect of lightening the image.
84 When you feed a true PPM to a display program that expects
85 radiance-proportional sample values, and therefore does a gamma
86 adjustment of its own on them, the display appears lighter than it
87 should, so \fBpnmgamma\fP with a gamma value less than one (the
88 multiplicative inverse of whatever gamma value the display program
89 uses) has the effect of darkening the image.
90
91 .UN parameters
92 .SH PARAMETERS
93 .PP
94 The form of the parameters depends on whether you're using the old
95 syntax or the new syntax. With the old syntax, the parameters are
96 a mixture of gamma values and the input file name. With the new
97 syntax, the only parameter is the input file name and you specify gamma
98 values with option.
99 .PP
100 You use the old syntax if you specify \fB-bt709ramp\fP (or
101 its synonym \fB-cieramp\fP) or \fB-srgramp\fP or if you don't specify
102 any transfer function at all (and thus default to a simple exponential).
103 Otherwise, you use the new syntax.
104 .PP
105 With the old syntax, you may specify a single gamma value or 3
106 separate gamma values (red, green, and blue) or no gamma values. In
107 any case, the meanings of those parameters is the same as the more
108 modern \fB-gamma\fP, \fB-rgamma\fP, \fB-ggamma\fP, and
109 \fB-bgamma\fP options described below.
110
111
112 .UN options
113 .SH OPTIONS
114 .PP
115 In addition to the options common to all programs based on libnetpbm
116 (most notably \fB-quiet\fP, see
117 .UR index.html#commonoptions
118 Common Options
119 .UE
120 \&), \fBpnmgamma\fP recognizes the following
121 command line options:
122
123
124
125 .TP
126 \fB-bt709tolinear\fP
127 Convert the image from BT.709 luminance to radiance. I.e. convert
128 from true PPM or PGM to a radiance-linear variation that can be used
129 with certain tools that need it.
130 .sp
131 This option was new in Netpbm 10.32 (February 2006).
132
133 .TP
134 \fB-lineartobt709\fP
135 Convert the image from radiance to BT.709 luminance. I.e. convert
136 to true PPM or PGM from a radiance-linear variation.
137 .sp
138 You get true BT.709 (ergo true PPM or PGM) only if you use the
139 default gamma value (i.e. don't specify \fB-gamma\fP, etc.).
140 .sp
141 This option was new in Netpbm 10.32 (February 2006).
142
143 .TP
144 \fB-bt709tosrgb\fP
145 Convert the image from BT.709 luminance to SRGB luminance.
146 I.e. convert from true PPM or PGM to an SRGB-based variation that is
147 required by certain tools and display devices.
148 .sp
149 You get true SRGB only if you use the default gamma value
150 (i.e. don't specify \fB-gamma\fP, etc.).
151 .sp
152 This option was new in Netpbm 10.32 (February 2006).
153
154 .TP
155 \fB-srgbtobt709\fP
156 Convert the image from SRGB luminance to BT.709 luminance.
157 I.e. convert to true PPM or PGM from an SRGB-based variation.
158 .sp
159 This option was new in Netpbm 10.32 (February 2006).
160
161 .TP
162 \fB-bt709ramp\fP
163 Same as \fB-lineartobt709\fP, but using the old syntax.
164 .sp
165 This option was renamed in Netpbm 10.32 (February 2006). Before that,
166 its name is \fB-cieramp\fP.
167
168 .TP
169 \fB-cieramp\fP
170 This is an obsolete synonym for \fB-bt709ramp\fP.
171 .sp
172 The name of this option comes from a former belief that this was a
173 standard of CIE (International Commission On Illumination), but it now
174 (August 2005) looks like it never was.
175
176 .TP
177 \fB-srgbramp \fP
178 Convert the image from radiance to SRGB luminance. Note that it is
179 true SRGB only if you use the default gamma value (i.e. don't specify
180 any gamma parameters).
181 .sp
182 This is an old syntax option. There is no equivalent in the new
183 syntax because it really shouldn't be a function of \fBpnmgamma\fP at
184 all. It exists solely for backward compatibility. The reason it
185 shouldn't exist is that the way to do this conversion consistent with
186 the Netpbm philosophy is do a \fB-lineartobt709\fP followed by a
187 \fB-bt709tosrgb\fP. It's exactly analogous to the way you have to
188 convert from PNG to TIFF by doing a \fBpngtopam\fP followed by a
189 \fBpnmtotiff\fP. The \fB-srgbramp\fP option actually dates to
190 before there was a standard definition of what the sample values of a
191 Netpbm image measure, and \fBpnmgamma\fP considered radiance-linear
192 to be the proper intermediate format.
193
194 .TP
195 \fB-ungamma\fP
196 Apply the inverse of the specified transfer function (i.e. go from
197 gamma-adjusted luminance to radiance).
198 .sp
199 This is valid only with \fB-bt709ramp\fP (aka \fB-cieramp\fP),
200 \fB-srgbramp\fP, and the default exponential transfer function.
201
202 .TP
203 \fB-gamma=\fP\fIfloat\fP
204 This specifies the gamma value to use in the transfer function. All
205 of the transfer functions involve an exponent, and the gamma value is that
206 exponent.
207 .sp
208 The standards specify a particular gamma value. If you use anything
209 else, you are varying from the standard.
210 .sp
211 The default is the standard value. For the simple exponential transfer
212 function (which is not a standard), the default is 2.2.
213 .sp
214 In the \fB-bt709tosrgb\fP and \fB-srgbtobt709\fP conversions
215 there are \fItwo\fP exponents. \fB-gamma\fP affects the
216 "to" function; the "from" function always uses the
217 standard gamma value.
218 .sp
219 If you specify one of the component-specific options (\fB-rgamma\fP,
220 etc.), that overrides the \fB-gamma\fP value.
221 .sp
222 With the \fB-bt709ramp\fP (aka \fB-cieramp\fP), \fB-srgbramp\fP,
223 or the default exponential transfer function, you can't actually use
224 this option, but you specify the same thing with
225 .UR #parameters
226 parameters.
227 .UE
228 \&
229 .sp
230 This option was new in Netpbm 10.32 (February 2006).
231
232 .TP
233 \fB-rgamma=\fP\fIfloat\fP
234 .TP
235 \fB-ggamma=\fP\fIfloat\fP
236 .TP
237 \fB-bgamma=\fP\fIfloat\fP
238 These options are just like \fB-gamma\fP, except they specify the
239 value for a particular one of the color components.
240 .sp
241 If you don't specify this option for a particular color component,
242 the default is the \fB-gamma\fP value (or \fB-gamma\fP's default if
243 you didn't specify that either).
244 .sp
245 With the \fB-bt709ramp\fP (aka \fB-cieramp\fP), \fB-srgbramp\fP,
246 or the default exponential transfer function, you can't actually use
247 this option, but you specify the same thing with
248 .UR #parameters
249 parameters.
250 .UE
251 \&
252 .sp
253 This option was new in Netpbm 10.32 (February 2006).
254
255 .TP
256 \fB-maxval=\fP\fImaxval\fP
257 This is the maxval of the output image. By default, the maxval of
258 the output is the same as that of the input.
259 .sp
260 Because the transformation is not linear, you need a greater maxval
261 in the output in order not to lose any information from the input.
262 For example, if you convert to radiance-linear sample values with
263 \f(CW-ungamma -bt709ramp\fP and default gamma value, and your maxval is
264 255 on both input and output, 3 different input sample values all
265 generate output sample value 254. In order to have a different output
266 sample value for each input sample value, you would need an output
267 maxval at least 3 times the input maxval.
268 .sp
269 This option was new in Netpbm 10.32 (February 2006). Before that,
270 you can achieve the same result by increasing the maxval of the input
271 or decreasing the maxval of the output using \fBpamdepth\fP.
272
273
274
275 .UN gamma
276 .SH WHAT IS GAMMA?
277 .PP
278 A good explanation of gamma is in Charles Poynton's Gamma FAQ at
279 .BR "
280 http://www.poynton.com/GammaFAQ.html" (1)\c
281 \& and Color FAQ at
282 .BR "
283 http://www.poynton.com/ColorFAQ.html" (1)\c
284 \&.
285 .PP
286 In brief: The simplest way to code an image is by using sample
287 values that are directly proportional to the radiance of the color
288 components. Radiance is a physical quantification based on the amount
289 of power in the light; it is easily measurable in a laboratory, but
290 does not take into account what the light looks like to a person. It
291 wastes the sample space because the human eye can't discern
292 differences between low-radiance colors as well as it can between
293 high-radiance colors. So instead, we pass the radiance values
294 through a transfer function that makes it so that changing a sample
295 value by 1 causes the same level of perceived color change anywhere in
296 the sample range. We store those resulting values in the image file.
297 That transfer function is called the gamma transfer function and the
298 transformation is called gamma adjusting.
299 .PP
300 The gamma-adjusted value, proportional to subjective brightness,
301 are known as the luminance of the pixel.
302 .PP
303 There is no precise objective way to measure luminance, since it's
304 psychological. Also, perception of brightness varies according to a
305 variety of factors, including the surrounding in which an image is
306 viewed. Therefore, there is not just one gamma transfer function.
307 .PP
308 Virtually all image formats, either specified or de facto, use
309 gamma-adjusted values for their sample values.
310 .PP
311 What's really nice about gamma is that by coincidence, the inverse
312 function that you have to do to convert the gamma-adjusted values
313 back to radiance is done automatically by CRTs. You just apply a
314 voltage to the CRT's electron gun that is proportional to the
315 gamma-adjusted sample value, and the radiance of the light that comes
316 out of the screen is close to the radiance value you had before you
317 applied the gamma transfer function!
318 .PP
319 And when you consider that computer video devices usually want you
320 to store in video memory a value proportional to the signal voltage
321 you want to go to the monitor, which the monitor turns into a
322 proportional drive voltage on the electron gun, it is really
323 convenient to work with gamma-adjusted sample values.
324
325 .UN seealso
326 .SH SEE ALSO
327 .BR "pnm" (1)\c
328 \&
329
330 .UN author
331 .SH AUTHOR
332
333 Copyright (C) 1991 by Bill Davidson and Jef Poskanzer.
334 .SH DOCUMENT SOURCE
335 This manual page was generated by the Netpbm tool 'makeman' from HTML
336 source. The master documentation is at
337 .IP
338 .B http://netpbm.sourceforge.net/doc/pnmgamma.html
339 .PP