Provided by: netpbm_11.01.00-2build1_amd64 
NAME
pnmgamma - perform gamma adjustment on a PNM image
SYNOPSIS
pnmgamma {
-bt709tolinear |
-lineartobt709 |
-bt709tosrgb |
-srgbtobt709 } [-gamma=float] [-rgamma=float] [-ggamma=float] [-bgamma=float]
[pnmfile]
pnmgamma [
-bt709ramp |
-srgbramp ] [-ungamma] [{gamma | redgamma greengamma bluegamma} [pnmfile]]
DESCRIPTION
This program is part of Netpbm(1).
Pnmgamma performs gamma adjustment on pseudo-PNM images.
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.
However, people sometimes work with approximations of PPM and PGM where the sample values
represent intensity in different ways:
In one common variation, the sample value is directly proportional to radiance (often
called "linear intensity").
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.
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.
pnmgamma allows you to manipulate the gamma transfer function, thus working with and/or
creating pseudo-PPM files that are useful for various things.
For example, if you feed a true PPM to pnmgamma -bt709tolinear , 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 pnmgamma -linearto709, you get back a true PPM.
The situation for PGM images is analogous. And pnmgamma treats PBM images as PGM images.
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 pnmgamma 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 pnmgamma 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.
PARAMETERS
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.
You use the old syntax if you specify -bt709ramp (or its synonym -cieramp) or -srgramp or
if you don't specify any transfer function at all (and thus default to a simple
exponential). Otherwise, you use the new syntax.
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 -gamma, -rgamma, -ggamma, and -bgamma options described below.
OPTIONS
In addition to the options common to all programs based on libnetpbm (most notably -quiet,
see
Common Options ⟨index.html#commonoptions⟩ ), pnmgamma recognizes the following command
line options:
-bt709tolinear
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.
This option was new in Netpbm 10.32 (February 2006).
-lineartobt709
Convert the image from radiance to BT.709 luminance. I.e. convert to true PPM or
PGM from a radiance-linear variation.
You get true BT.709 (ergo true PPM or PGM) only if you use the default gamma value
(i.e. don't specify -gamma, etc.).
This option was new in Netpbm 10.32 (February 2006).
-bt709tosrgb
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.
You get true SRGB only if you use the default gamma value (i.e. don't specify
-gamma, etc.).
This option was new in Netpbm 10.32 (February 2006).
-srgbtobt709
Convert the image from SRGB luminance to BT.709 luminance. I.e. convert to true
PPM or PGM from an SRGB-based variation.
This option was new in Netpbm 10.32 (February 2006).
-bt709ramp
Same as -lineartobt709, but using the old syntax.
This option was renamed in Netpbm 10.32 (February 2006). Before that, its name is
-cieramp.
-cieramp
This is an obsolete synonym for -bt709ramp.
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.
-srgbramp
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).
This is an old syntax option. There is no equivalent in the new syntax because it
really shouldn't be a function of pnmgamma 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 -lineartobt709 followed by a
-bt709tosrgb. It's exactly analogous to the way you have to convert from PNG to
TIFF by doing a pngtopam followed by a pnmtotiff. The -srgbramp option actually
dates to before there was a standard definition of what the sample values of a
Netpbm image measure, and pnmgamma considered radiance-linear to be the proper
intermediate format.
-ungamma
Apply the inverse of the specified transfer function (i.e. go from gamma-adjusted
luminance to radiance).
This is valid only with -bt709ramp (aka -cieramp), -srgbramp, and the default
exponential transfer function.
-gamma=float
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.
The standards specify a particular gamma value. If you use anything else, you are
varying from the standard.
The default is the standard value. For the simple exponential transfer function
(which is not a standard), the default is 2.2.
In the -bt709tosrgb and -srgbtobt709 conversions there are two exponents. -gamma
affects the "to" function; the "from" function always uses the standard gamma
value.
If you specify one of the component-specific options (-rgamma, etc.), that
overrides the -gamma value.
With the -bt709ramp (aka -cieramp), -srgbramp, or the default exponential transfer
function, you can't actually use this option, but you specify the same thing with
parameters. ⟨#parameters⟩
This option was new in Netpbm 10.32 (February 2006).
-rgamma=float
-ggamma=float
-bgamma=float
These options are just like -gamma, except they specify the value for a particular
one of the color components.
If you don't specify this option for a particular color component, the default is
the -gamma value (or -gamma's default if you didn't specify that either).
With the -bt709ramp (aka -cieramp), -srgbramp, or the default exponential transfer
function, you can't actually use this option, but you specify the same thing with
parameters. ⟨#parameters⟩
This option was new in Netpbm 10.32 (February 2006).
-maxval=maxval
This is the maxval of the output image. By default, the maxval of the output is
the same as that of the input.
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 -ungamma -bt709ramp 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.
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 pamdepth.
WHAT IS GAMMA?
A good explanation of gamma is in Charles Poynton's Gamma FAQ at
http://www.poynton.com/GammaFAQ.html" (1) and Color FAQ at
http://www.poynton.com/ColorFAQ.html" (1).
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.
The gamma-adjusted value, proportional to subjective brightness, are known as the
luminance of the pixel.
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.
Virtually all image formats, either specified or de facto, use gamma-adjusted values for
their sample values.
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!
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.
SEE ALSO
pnm(1)
AUTHOR
Copyright (C) 1991 by Bill Davidson and Jef Poskanzer.
DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML source. The master
documentation is at
http://netpbm.sourceforge.net/doc/pnmgamma.html