pfstmo_mantiuk08(1)

💖 NAME 💖

Okay so this is the pfstmo_mantiuk08(1) page, straight outta the General Commands Manual, and it's about one thing and one thing only:

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>] [--fps=<frames-per-second>] [--output-tone-curve=<file name>] [--verbose] [--help]

---

🌸 DESCRIPTION 🌸

Bestie. Sit down. This command applies the display adaptive tone mapping, and what it's doing is trying to preserve the contrast of an input (HDR) image as close as possible, given the characteristics of whatever output display you're throwing it at. That's the whole vibe.

Reach for this tone mapping operator when you wanna preserve the original image appearance, or slightly enhance contrast (that's the -e option, we'll get there) while still keeping the natural look of your images. No crunchy over-processed nonsense here.

It can also compensate for:

• ambient light reflections on a screen 🪞
• varying dynamic range of a display
• varying brightness of a display

And yes, it's suitable for video sequences, because it prevents high-frequency changes in the tone-curve between consecutive frames — which would otherwise show up as flickering. Nobody wants that. 💀

Not me reminding you: the temporal filtering is always active, and there is no need to specify an argument to switch it on. It's just on. Periodt.

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. Academic besties, you know what to do. 🎀

This operator also employs a 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/

And the big one — the result of this TMO does not require gamma correction. Let that sink in. 💅

---

✨ 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 (peep 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>]

The 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 a pre-defined display type. These options are for convenience only and they do not mean to accurately model the response of a particular 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 it requires measuring it with a luminance meter. The lookup table should account also for ambient light, so it is recommended to use a luminance meter that can measure screen luminance from a distance, such as Minolta LS-100 (as opposed to those that use a rubber tube touching a display, which eliminates the influence of ambient light). The <file> must be a comma-separated text file in a format (CSV) with two columns: the 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.

• --display-size=<size-spec>, -s=<size_spec> — Specifies how large the image appears to a viewer and what the viewing distance is. If no parameter is given, -s ppd=30 is assumed. Since this tone-mapper is global, display size has a 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 multiples 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 the 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, the tone-mapper does not know how bright the scene should be. This option is meant to fix that problem by providing the tone-mapper with the information of 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 the 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 also be 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.
• --fps=<frames-per-second>, -f=<frames-per-second> — Set the frame rate of the input sequence. Default is 25. Currently only 3 values are supported: 25, 30 and 60. This parameter controls the temporal filter that makes sure the resulting sequence is coherent in time. This reduces the likelihood of a visible flicker. 🎬
• --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 luminance 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 the memorial image for a CRT display and store the result in the PNG format. Iconic.

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

Tone map the 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. The pfsclamp command reduces noise for low code values. ✨

pfsin frame%05d.exr | pfstmo_mantiuk08 -d pd=lcd_bright --fps 30 | pfsout out_frame%04d.png

Tone-map a video sequence at 30 frame-per-second frame rate. 👑

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. Stacked TMOs are main character energy, fr fr. 🌈

---

💫 SEE ALSO 💫

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

💀 BUGS 💀

okay bestie, so here's the tea on the rough edges 🫖 — and lowkey, there aren't even any actual bugs listed here, it's just the "please tell us stuff" section, which is honestly the most wholesome vibe ✨

• 🐛 Found something janky? Got a comment? A hot take? A "bestie this looks broken" moment? You don't suffer in silence, you report it to the pfstools discussion group:

http://groups.google.com/group/pfstools

• 🫶 That's the whole list. No secret cursed behaviours, no "don't do this or the universe collapses" warnings hiding down here — just the invitation to talk to actual humans who care about this tool. iykyk 💅

fr fr, if pfstmo_mantiuk08 ever acts up on you, that link is the move. Screenshots, command lines, the whole receipts folder — the more deets you drop, the faster the group can help. no gatekeeping, periodt 👑

---

and that's a wrap on the whole page, bestie 🎀 you made it to the very end, main character energy fr 🌈

Little sign-off moment: this lil legend lives in the wild as pfstmo_mantiuk08(1) — that's the manual page name down at the bottom of the original, the whole source/version-and-date footer situation 🦋. So when you're citing it, quoting it, or just manifesting it in your shell, that's the handle. Slay, go tone-map something gorgeous 💖✨