path: root/upstream/debian-unstable/man1/pnmgamma.1

\
.\" 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" 1 "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