pfstmo_mantiuk08(1)					      General Commands Manual					       pfstmo_mantiuk08(1)

NAME

       pfstmo_mantiuk08 - Display adaptive tone mapping

SYNOPSIS

       pfstmo_mantiuk08  [--display-function <df-spec>] [--display-size=<size-spec>] [--color-saturation <float>] [--contrast-enhancement <float>]
       [--white-y=<float>] [--temporal=<pass>] [--output-tone-curve=<file name>] [--verbose] [--help]

DESCRIPTION

       This command applies the display adaptive tone mapping, which attempts to preserve contrast of an input (HDR) image as  close  as  possible
       given  the  characteristic  of  an  output  display.  Use  this tone mapping operator if you want to preserve original image appearance, or
       slightly enhance contrast (-e option) while maintaining the natural look of images. The operator can  also  compensate  for  ambient  light
       reflections on a screen, and for varying dynamic range and brightness of a display.

       More details can be found in:
	      Rafal Mantiuk, Scott Daly and Louis Kerofsky.
	      Display Adaptive Tone Mapping.
	      In: ACM Transactions on Graphics 27 (3), 2008.
	      http://www.mpi-inf.mpg.de/resources/hdr/datmo/

       If you find this TMO useful in your research project, please cite the paper above.

       This operator also employs color correction mechanism from:
	      Radoslaw Mantiuk, Rafal Mantiuk, Anna Tomaszewska, Wolfgang Heidrich.
	      Color Correction for Tone Mapping.
	      In: Computer Graphics Forum (Proc. of EUROGRAPHICS'09), 28(2), 2009.
	      http://zgk.wi.ps.pl/color_correction/

       The result of this TMO does not require gamma correction.

OPTIONS

       --display-function <df-spec>, -d <df-spec>
	      To  adapt  tone-mapping to different displays, this operator must be provided a display function. The display function describes how
	      output luminance of a display changes with pixel values. If no parameter is given, the command assumes -df pd=lcd  (see  Pre-defined
	      display below). There are several ways to specify the display function:

       Gamma-gain-black-ambient display model

	      g=<float>:l=<float>:b=<float>:k=<float>:a=<float>[:n=<float>]

	      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:

	      L_d(I) = (l-b)*I^gamma + b + k/pi*a

	      The parameters are as follows:
	      g -  gamma or exponent of a display function (default 2.2, usually from 1.8 to 2.8)
	      l -  peak luminance of a display in cd/m^2  (default 100, from 80 for CRTs to 500 or more for newer displays)
	      b -  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)
	      k -  reflectivity of a screen (assuming that it is diffuse) (default 0.01, usually about 0.01 (1%) for LCD displays, more for CRTs)
	      a -  ambient illumination in lux. Typical values are:
		   50 lux Family living room (dim, default)
		   400 lux
			  A brightly lit office
		   32000 lux
			  Sunlight on an average day (min.)
		   100000 lux
			  Sunlight on an average day (max.)

       Pre-defined display

	      pd=<display_type>

	      Use pre-defined display type. This options are for convenience only and they do not mean to accurately model the response of a  par-
	      ticular display.	The following display types are recognized:

	      lcd_office (g=2.2, l=100, b=0.8, k=0.01, a=400 )
		     lcd set to "office" mode seen in bright environment
	      lcd	 (g=2.2, l=200, b=0.8, k=0.01, a=60  )
		     typical lcd seen in dim environment (default)
	      lcd_bright (g=2.6, l=500, b=0.5, k=0.01, a=10  )
		     newer LCD TV seen in dark environment
	      crt	 (g=2.2, l=80,	b=1,   k=0.02, a=60  )
		     CRT monitor seen in dim environment

	      The parameters in the parenthesis are the same as for the gamma-gain-black-ambient model explained above.

       Lookup-table

	      lut=<file>

	      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  repre-
	      sents  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.

       --display-size=<size-spec>, -s=<size_spec>
	      Specifies how large the image appears to a viewer and what is the viewing distance.  If no parameter is given, -s ppd=30 is assumed.
	      Since  this  tone-mapper is global, display size has moderate effect on the resulting images and thus skipping this parameter should
	      not do much harm. There are two ways to specify image size:
	      vres=<lines>:vd=<screen_heights>[:d=<meters>]
		     vres   - screen's vertical resolution in lines, for example 1024.
		     vd     - viewing distance specified as multiplies of screen height. For example if the display is	seen  from  0.5m  and  the
			    height of its screen is 25cm, vd=2.
		     d	    -  (optional)  viewing distance in meters. This is to account for lower eye's sensitivity for larger viewing distances
			    (although the effect is negligible). By default -d=0.5 is assumed.
	      ppd=<pixels_per_visual_degree>[:d=<meters>]
		     ppd    - how many pixels spans one visual degree.
		     d	    - (optional) viewing distance in meters. This is to account for lower eye's sensitivity for larger	viewing  distances
			    (although the effect is negligible). By default -d=0.5 is assumed.

       --color-saturation <float>, -c <float>
	      Decrease	or  increase color saturation after tone mapping. Default value -c=1 attempts to preserve color appearance of the original
	      image. Use values >1 to increase and <1 to decrease color saturation.

       --contrast-enhancement <float>, -e <float>
	      By default this tone-mapper attempts to preserve contrast of an input image (-e=1). This parameter controls whether the contrast	of
	      an  input  image	should	be enhanced before tone-mapping. For example -e=1.15 boosts contrast by 15%. Note that if a target display
	      does not offer sufficient dynamic range, contrast may be enhanced only for selected tone-values (those that dominate in an image) or
	      not enhanced at all.

       --white-y=<float>, -y=<float>
	      Tells  the  tone-mapper  what  luminance	level in the input image should be mapped to the maximum luminance of a display. Since HDR
	      images contain only relative luminance information, tone-mapper does not know how bright should be the scene. This option  is  meant
	      to  fix  this  problem by providing tone-mapper with the information what luminance level in an input image should be perceived as a
	      diffuse white surface. Default is none, which means that no such mapping will be enforced and tone-mapper is free to find an optimal
	      brightness  for  a  given image. This is a recommended setting for HDR images. Setting --white-y could be necessary for dark scenes,
	      which could be made too bright by the tone-mapper. The value of this parameter can be also passed in pfsstream  as  a  tag  WHITE_Y.
	      pfstools	1.7  and newer sets set this tag automatically for LDR images. The command line option overrides the value of the pfstream
	      tag.

       --temporal=<pass>, -t=<pass>
	      Use temporal filtering of the tone-curve to tone-map video sequence. This option should be used for video sequences to avoid  flick-
	      ering. Since the temporal filter requires knowledge of at least 25 frames in advance, the filtering must be performed in two passes,
	      similar to MPEG video encoding. In the first pass (pass=1) tone-curves are calculated for each frame and stored in a temporary  file
	      (datmo_tone_curves.tmp  in the current directory). In the second pass (pass=2) the tone-curves are read from that file, filtered and
	      used to tone-map video sequence. The tone-mapper does not produce any output (frames) in the first pass. See below an example how to
	      use two-pass filtering. Note that the same set of tone mapping options must be provided for both passes.

       --output-tone-curve=<file name>, -o=<file name>
	      Write  tone-curves  to a text file. This option is mainly for debugging purposes, but can be used to visualize computed tone-curves.
	      The tone-curve data is stored in a comma separated text file (CSV), consisting of three columns: frame number, log10 of input  lumi-
	      nance factor, log10 of the resulting display luminance, and the pixel value (0-1).

       --verbose, -v
	      Print additional information during program execution.

       --quiet, -q
	      Do not display progress report.

       --help, -h
	      Print list of commandline options.

EXAMPLES

       pfsin memorial.hdr | pfstmo_mantiuk08 -d pd=crt | pfsout memorial.png

	      Tone map memorial image for a CRT display and store the result in the PNG format.

       pfsin memorial.hdr | pfstmo_mantiuk08 -d g=2.6:l=500:b=0.5:k=0.01:a=10 | pfsview

	      Tone  map  memorial  image  for a display that has a 2.2 gamma, the peak luminance of 500 cd/m^2, the black level of 0.5 cd/m^2, the
	      panel reflectivity of 1% (0.01) and is seen under the illumination of 10 lux.

       pfsin bridge.jpg --linear | pfsclamp --min 0.007 | pfstmo_mantiuk08 -v | pfsview

	      Enhance the low-dynamic range image 'bridge' and view the result. pfsclamp command reduces noise for low code values.

       pfsin frame%05d.exr | pfstmo_mantiuk08 -d pd=lcd_bright -t 1
       pfsin frame%05d.exr | pfstmo_mantiuk08 -d pd=lcd_bright -t 2 | pfsout out_frame%04d.png

	      Tone-map video sequence using 2-pass temporal filtering to avoid flicker.

       pfsin *.exr | pfstmo_mantiuk08 | pfsview

	      Tone-map and display *.exr HDR images in the current directory.

       pfsin *.exr | pfstmo_mantiuk06 | pfsgamma -g 0.8 | pfstmo_mantiuk08 | pfsview

	      It is possible to stack a TMO that sharpens images (pfstmo_mantiuk06) with the contrast preserving TMO (pfstmo_mantiuk08) to get new
	      interesting results.

SEE ALSO

       pfsin(1) pfsout(1) pfsview(1)

BUGS

       Please report bugs and comments to the pfstools discussion group (http://groups.google.com/group/pfstools).

															       pfstmo_mantiuk08(1)