.TH "pfsdisplayfunction" 1
.SH NAME
pfsdisplayfunction \- Apply display function to color or gray-scale images
.SH SYNOPSIS
.B pfsdisplayfunction
[\fB--display-function\fR <\fIdf-spec\fR>] [--\fBto-pixels\fR | --\fBto-luminance\fR]
[--\fBhelp\fR] [--\fBverbose\fR]
.SH DESCRIPTION
Use this command to convert pixel values to luminance / radiance units
displayed on a monitor or to perform inverse conversion. This command
is useful in combination with the HDR-VDP to convert LDR images to
luminance maps representing images shown on a particular display. The
display function specification is identical to the specification used
in the \fIpfstmo_mantiuk08\fR tone mapping operator (from the pfstmo
package).
.PP
If neither --\fBto-luminance\fR nor --\fBto-pixels\fR option is
specified, the appropriate conversion direction will be deducted from
the LUMINANCE tag in the pfs stream.
.SH OPTIONS
.TP
--\fBto-luminance\fR, -\fBl\fR
Convert pixel values to absolute
luminance / radiance units. For RGB images the same display function
is applied in each color channel.
.TP
--\fBto-pixels\fR, -\fBp\fR
Convert absolute luminance / radiance units to pixel values. For RGB
images the same display function is applied in each color channel.
.TP
\fB--display-function\fR <\fIdf-spec\fR>, \fB-d\fR <\fIdf-spec\fR>
The
display function describes how output luminance of a display changes
with pixel values. If no parameter is given, the command assumes
\fB-df\ pd=lcd\fR (see \fIPre-defined display\fR below). There are
several ways to specify the display function:
.TP
\fIGamma-gain-black-ambient display model\fR
.IP
g=<float>:l=<float>:b=<float>:k=<float>:a=<float>[:n=<float>]
.IP
Gamma-gain-black-ambient model can approximate a range of displays and
is a compact way to specify a display function. It assumes that a display function
has the following form:
.IP 
L_d(I) = (l-b)*I^gamma + b + k/pi*a
.IP
The parameters are as follows:
.RS
.PD 0
.TP 5
\fBg\fR - 
gamma or exponent of a display function (default 2.2, usually from 1.8 to 2.8)
.TP 5
\fBl\fR -
peak luminance of a display in cd/m^2  (default 100, from 80 for CRTs to 500 or more for newer displays)
.TP 5
\fBb\fR -
black level, which is luminance of a black pixel when the display is on (default 1, usually from 0.3 to 1 cd/m^2)
.TP 5
\fBk\fR -
reflectivity of a screen (assuming that it is diffuse) (default 0.01, usually about 0.01 (1%) for LCD displays, more for CRTs)
.TP 5
\fBa\fR -
ambient illumination in lux. Typical values are:
.RS
.IP 50\ lux
Family living room (dim, \fBdefault\fR)
.IP 400\ lux
A brightly lit office
.IP 32000\ lux
Sunlight on an average day (min.)
.IP 100000\ lux
Sunlight on an average day (max.)
.RE
.RE
.PD
.TP
\fIPre-defined display\fR
.IP
\fBpd\fR=\fI<display_type>\fI
.IP
Use pre-defined display type. This options are for convenience only
and they do not mean to accurately model the response of a particular
display.  The following \fIdisplay type\fRs are recognized:
.RS
.TP
\fBlcd_office\fR (g=2.2, l=100, b=0.8, k=0.01, a=400 )
lcd set to "office" mode seen in bright environment
.PD 0
.TP
\fBlcd\fR        (g=2.2, l=200, b=0.8, k=0.01, a=60  )
typical lcd seen in dim environment (\fBdefault\fR)
.TP
\fBlcd_bright\fR (g=2.6, l=500, b=0.5, k=0.01, a=10  )
newer LCD TV seen in dark environment
.TP
\fBcrt\fR        (g=2.2, l=80,  b=1,   k=0.02, a=60  )
CRT monitor seen in dim environment
.PD
.RE
.IP
The parameters
in the parenthesis are the same as for the gamma-gain-black-ambient
model explained above.
.TP
\fILookup-table\fR
.IP
\fBlut\fR=\fI<file>\fI
.IP
This is the most accurate specification of the display response
function, but requires measuring it with a luminance meter. The lookup
table should account also for ambient light, so that it is recommended
to use the luminance meter that can measure screen luminance from a
distance, such as Minolta LS-100 (as opposed to those that use rubber
tube touching a display that eliminates the influence of ambient
light). The <file> must be a comma-separated text file in a format
(CSV) with two columns: first column represents pixel values (from 0.0
to 1.0) and the second physical luminance in cd/m^2. Both the pixel
value and the luminance should increase in each raw.
.SH EXAMPLES
.TP
pfsin barbara.jpg | pfsdisplayfunction -l -d pd:crt -v  | pfsout barbara_crt.hdr
.IP
Convert barbara.jpg image from pixel values to a luminance map of the
image shown on a CRT monitor and store the map as an HDR image.
.SH "SEE ALSO"
.BR pfsgamma (1)
.BR pfstmo_mantiuk08 (1)
.SH BUGS
Please report bugs and comments to the pfstools discussion group
(http://groups.google.com/group/pfstools).