diff options
Diffstat (limited to 'upstream/fedora-40/man1/pnmgamma.1')
| -rw-r--r-- | upstream/fedora-40/man1/pnmgamma.1 | 339 |
1 files changed, 339 insertions, 0 deletions
diff --git a/upstream/fedora-40/man1/pnmgamma.1 b/upstream/fedora-40/man1/pnmgamma.1 new file mode 100644 index 00000000..152dc7ad --- /dev/null +++ b/upstream/fedora-40/man1/pnmgamma.1 @@ -0,0 +1,339 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Pnmgamma User Manual" 0 "30 June 2007" "netpbm documentation" + +.SH NAME +pnmgamma - perform gamma adjustment on a PNM image + +.UN synopsis +.SH SYNOPSIS +.PP +\fBpnmgamma\fP +{ + \fB-bt709tolinear\fP | + \fB-lineartobt709\fP | + \fB-bt709tosrgb\fP | + \fB-srgbtobt709\fP +} +[\fB-gamma=\fP\fIfloat\fP] +[\fB-rgamma=\fP\fIfloat\fP] +[\fB-ggamma=\fP\fIfloat\fP] +[\fB-bgamma=\fP\fIfloat\fP] + +[\fIpnmfile\fP] +.PP +\fBpnmgamma \fP +[ + \fB-bt709ramp\fP | + \fB-srgbramp\fP +] +[\fB-ungamma\fP] +[{\fIgamma\fP | \fIredgamma\fP \fIgreengamma\fP \fIbluegamma\fP} +[\fIpnmfile\fP]] + + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBPnmgamma\fP performs gamma adjustment on pseudo-PNM images. +.PP +The PPM format specification specifies that certain sample values +in a file represent certain light intensities in an image. In +particular, they specify that the sample values are directly +proportional to luminance as defined by ITU-R Recommendation BT.709. +BT.709 luminance as a function of radiance is a power function +modified with a linear ramp near black. +.PP +However, people sometimes work with approximations of PPM and PGM +where the sample values represent intensity in different ways: +.PP +In one common variation, the sample value is directly proportional +to radiance (often called "linear intensity"). +.PP +Another popular variation is to make the samples proportional to +luminance as defined by the International Electrotechnical Commission +(IEC) SRGB standard. The SRGB gamma transfer function is like the +BT.709 one except with different constants in it. +.PP +Note that SRGB is often spelled "sRGB". In this +document, we use standard English typography, though, which doesn't +allow for that kind of capitalization. +.PP +\fBpnmgamma\fP allows you to manipulate the gamma transfer +function, thus working with and/or creating pseudo-PPM files that are +useful for various things. +.PP +For example, if you feed a true PPM to \f(CWpnmgamma -bt709tolinear +\fP, you get as output a file which is PPM in every respect except +that the sample values are radiances. If you feed such a file to +\f(CWpnmgamma -linearto709\fP, you get back a true PPM. +.PP +The situation for PGM images is analogous. And \fBpnmgamma\fP +treats PBM images as PGM images. +.PP +When you feed a radiance-proportional pseudo-PPM image to a display +program that expects a true PPM, the display appears darker than it +should, so \fBpnmgamma\fP has the effect of lightening the image. +When you feed a true PPM to a display program that expects +radiance-proportional sample values, and therefore does a gamma +adjustment of its own on them, the display appears lighter than it +should, so \fBpnmgamma\fP with a gamma value less than one (the +multiplicative inverse of whatever gamma value the display program +uses) has the effect of darkening the image. + +.UN parameters +.SH PARAMETERS +.PP +The form of the parameters depends on whether you're using the old +syntax or the new syntax. With the old syntax, the parameters are +a mixture of gamma values and the input file name. With the new +syntax, the only parameter is the input file name and you specify gamma +values with option. +.PP +You use the old syntax if you specify \fB-bt709ramp\fP (or +its synonym \fB-cieramp\fP) or \fB-srgramp\fP or if you don't specify +any transfer function at all (and thus default to a simple exponential). +Otherwise, you use the new syntax. +.PP +With the old syntax, you may specify a single gamma value or 3 +separate gamma values (red, green, and blue) or no gamma values. In +any case, the meanings of those parameters is the same as the more +modern \fB-gamma\fP, \fB-rgamma\fP, \fB-ggamma\fP, and +\fB-bgamma\fP options described below. + + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBpnmgamma\fP recognizes the following +command line options: + + + +.TP +\fB-bt709tolinear\fP +Convert the image from BT.709 luminance to radiance. I.e. convert +from true PPM or PGM to a radiance-linear variation that can be used +with certain tools that need it. +.sp +This option was new in Netpbm 10.32 (February 2006). + +.TP +\fB-lineartobt709\fP +Convert the image from radiance to BT.709 luminance. I.e. convert +to true PPM or PGM from a radiance-linear variation. +.sp +You get true BT.709 (ergo true PPM or PGM) only if you use the +default gamma value (i.e. don't specify \fB-gamma\fP, etc.). +.sp +This option was new in Netpbm 10.32 (February 2006). + +.TP +\fB-bt709tosrgb\fP +Convert the image from BT.709 luminance to SRGB luminance. +I.e. convert from true PPM or PGM to an SRGB-based variation that is +required by certain tools and display devices. +.sp +You get true SRGB only if you use the default gamma value +(i.e. don't specify \fB-gamma\fP, etc.). +.sp +This option was new in Netpbm 10.32 (February 2006). + +.TP +\fB-srgbtobt709\fP +Convert the image from SRGB luminance to BT.709 luminance. +I.e. convert to true PPM or PGM from an SRGB-based variation. +.sp +This option was new in Netpbm 10.32 (February 2006). + +.TP +\fB-bt709ramp\fP +Same as \fB-lineartobt709\fP, but using the old syntax. +.sp +This option was renamed in Netpbm 10.32 (February 2006). Before that, +its name is \fB-cieramp\fP. + +.TP +\fB-cieramp\fP +This is an obsolete synonym for \fB-bt709ramp\fP. +.sp +The name of this option comes from a former belief that this was a +standard of CIE (International Commission On Illumination), but it now +(August 2005) looks like it never was. + +.TP +\fB-srgbramp \fP +Convert the image from radiance to SRGB luminance. Note that it is +true SRGB only if you use the default gamma value (i.e. don't specify +any gamma parameters). +.sp +This is an old syntax option. There is no equivalent in the new +syntax because it really shouldn't be a function of \fBpnmgamma\fP at +all. It exists solely for backward compatibility. The reason it +shouldn't exist is that the way to do this conversion consistent with +the Netpbm philosophy is do a \fB-lineartobt709\fP followed by a +\fB-bt709tosrgb\fP. It's exactly analogous to the way you have to +convert from PNG to TIFF by doing a \fBpngtopam\fP followed by a +\fBpnmtotiff\fP. The \fB-srgbramp\fP option actually dates to +before there was a standard definition of what the sample values of a +Netpbm image measure, and \fBpnmgamma\fP considered radiance-linear +to be the proper intermediate format. + +.TP +\fB-ungamma\fP +Apply the inverse of the specified transfer function (i.e. go from +gamma-adjusted luminance to radiance). +.sp +This is valid only with \fB-bt709ramp\fP (aka \fB-cieramp\fP), +\fB-srgbramp\fP, and the default exponential transfer function. + +.TP +\fB-gamma=\fP\fIfloat\fP +This specifies the gamma value to use in the transfer function. All +of the transfer functions involve an exponent, and the gamma value is that +exponent. +.sp +The standards specify a particular gamma value. If you use anything +else, you are varying from the standard. +.sp +The default is the standard value. For the simple exponential transfer +function (which is not a standard), the default is 2.2. +.sp +In the \fB-bt709tosrgb\fP and \fB-srgbtobt709\fP conversions +there are \fItwo\fP exponents. \fB-gamma\fP affects the +"to" function; the "from" function always uses the +standard gamma value. +.sp +If you specify one of the component-specific options (\fB-rgamma\fP, +etc.), that overrides the \fB-gamma\fP value. +.sp +With the \fB-bt709ramp\fP (aka \fB-cieramp\fP), \fB-srgbramp\fP, +or the default exponential transfer function, you can't actually use +this option, but you specify the same thing with +.UR #parameters +parameters. +.UE +\& +.sp +This option was new in Netpbm 10.32 (February 2006). + +.TP +\fB-rgamma=\fP\fIfloat\fP +.TP +\fB-ggamma=\fP\fIfloat\fP +.TP +\fB-bgamma=\fP\fIfloat\fP +These options are just like \fB-gamma\fP, except they specify the +value for a particular one of the color components. +.sp +If you don't specify this option for a particular color component, +the default is the \fB-gamma\fP value (or \fB-gamma\fP's default if +you didn't specify that either). +.sp +With the \fB-bt709ramp\fP (aka \fB-cieramp\fP), \fB-srgbramp\fP, +or the default exponential transfer function, you can't actually use +this option, but you specify the same thing with +.UR #parameters +parameters. +.UE +\& +.sp +This option was new in Netpbm 10.32 (February 2006). + +.TP +\fB-maxval=\fP\fImaxval\fP +This is the maxval of the output image. By default, the maxval of +the output is the same as that of the input. +.sp +Because the transformation is not linear, you need a greater maxval +in the output in order not to lose any information from the input. +For example, if you convert to radiance-linear sample values with +\f(CW-ungamma -bt709ramp\fP and default gamma value, and your maxval is +255 on both input and output, 3 different input sample values all +generate output sample value 254. In order to have a different output +sample value for each input sample value, you would need an output +maxval at least 3 times the input maxval. +.sp +This option was new in Netpbm 10.32 (February 2006). Before that, +you can achieve the same result by increasing the maxval of the input +or decreasing the maxval of the output using \fBpamdepth\fP. + + + +.UN gamma +.SH WHAT IS GAMMA? +.PP +A good explanation of gamma is in Charles Poynton's Gamma FAQ at +.BR " +http://www.poynton.com/GammaFAQ.html" (1)\c +\& and Color FAQ at +.BR " +http://www.poynton.com/ColorFAQ.html" (1)\c +\&. +.PP +In brief: The simplest way to code an image is by using sample +values that are directly proportional to the radiance of the color +components. Radiance is a physical quantification based on the amount +of power in the light; it is easily measurable in a laboratory, but +does not take into account what the light looks like to a person. It +wastes the sample space because the human eye can't discern +differences between low-radiance colors as well as it can between +high-radiance colors. So instead, we pass the radiance values +through a transfer function that makes it so that changing a sample +value by 1 causes the same level of perceived color change anywhere in +the sample range. We store those resulting values in the image file. +That transfer function is called the gamma transfer function and the +transformation is called gamma adjusting. +.PP +The gamma-adjusted value, proportional to subjective brightness, +are known as the luminance of the pixel. +.PP +There is no precise objective way to measure luminance, since it's +psychological. Also, perception of brightness varies according to a +variety of factors, including the surrounding in which an image is +viewed. Therefore, there is not just one gamma transfer function. +.PP +Virtually all image formats, either specified or de facto, use +gamma-adjusted values for their sample values. +.PP +What's really nice about gamma is that by coincidence, the inverse +function that you have to do to convert the gamma-adjusted values +back to radiance is done automatically by CRTs. You just apply a +voltage to the CRT's electron gun that is proportional to the +gamma-adjusted sample value, and the radiance of the light that comes +out of the screen is close to the radiance value you had before you +applied the gamma transfer function! +.PP +And when you consider that computer video devices usually want you +to store in video memory a value proportional to the signal voltage +you want to go to the monitor, which the monitor turns into a +proportional drive voltage on the electron gun, it is really +convenient to work with gamma-adjusted sample values. + +.UN seealso +.SH SEE ALSO +.BR "pnm" (1)\c +\& + +.UN author +.SH AUTHOR + +Copyright (C) 1991 by Bill Davidson and Jef Poskanzer. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/pnmgamma.html +.PP
\ No newline at end of file |