Iray Programmer's Manual

Photographic tonemapper

The mia_exposure_photographic_tonemapper is controlled by the following attributes.

bool iray_internal_tonemapper = true

Additional control if the internal tonemapper is enabled, assuming tm_tonemapper is set to "mia_exposure_photographic". This is the case by default but it can be disabled if there is a clash with a tonemapper plugin which shares the parameters.

mi::Float32 mip_cm2_factor = 1.0

In "Photographic mode" (nonzero film_iso) cm2_factor is the conversion factor between pixel values and candela per square meter. This is discussed more in detail below.

In "Arbitrary" mode, cm2_factor is simply the multiplier applied to scale rendered pixel values to screen pixels. This is analogous to the gain parameter of mia_exposure_simple .

mi::Color mip_whitepoint = mi::Color(1.04287, 0.983863, 1.03358, 1.0)

Whitepoint is a color that will be mapped to "white" on output, i.e. an incoming color of this hue/saturation will be mapped to grayscale, but its intensity will remain unchanged.

mi::Float32 mip_film_iso = 100.0

The mip_film_iso should be the ISO number of the film, also known as "film speed". As mentioned above, if this is zero, the "Arbitrary" mode is enabled, and all color scaling is then strictly defined by the value of cm2_factor.

mi::Float32 mip_camera_shutter = 0.125

This is the camera shutter time expressed as fractional seconds, i.e. a value of 100 defines a camera shutter of 1/100. This value has no effect in "Arbitrary" mode.

mi::Float32 mip_f_number = 8.0

This is the fractional aperture number, i.e. 11 defines aperture "f/11". Aperture numbers on cameras go in specific standard series, i.e. "f/8", "f/11", "f/16", "f/22" etc. Each of these are referred to as a "stop" (from the fact that aperture rings on real lenses tend to have physical "clicks" for these values) and each such "stop" represents halving the amount of light hitting the film per increased stop2. It is important to note that this shader doesn't count "stops", but actually wants the f-number for that stop. This value has no effect in "Arbitrary" mode.

mi::Float32 mip_vignetting = 0.0

In a real camera the angle with which the light hits the film impacts the exposure, causing the image to go darker around the edges. The vignetting parameter simulates this. At 0.0 it is disabled, higher values cause stronger darkening around the edges. Note that this effect is based on the cosine of the angle with which the light ray would hit the film plane, and is hence affected by the field-of-view of the camera, and will not work at all for orthographic renderings. A good default is 3.0, which is similar to what a compact camera would generate.

mi::Float32 mip_crush_blacks = 0.2; mi::Float32 mip_burn_highlights = 0.25

The parameters burn_highlights and crush_blacks guide the actual "tone mapping" process of the image, i.e., exactly how the high dynamic range values are adapted to fit into the black-to-white range of current display devices.

If burn_highlights is set to one and crush_blacks to zero, the transfer is linear, i.e. the mapping behaves like a simple linear intensity scaler only.

burn_highlights can be considered the parameter defining how much "over exposure" is allowed. As it is decreased from 1 towards 0, high intensities will be more and more "compressed" to lower intensities. When it is 0, the compression curve is asymptotic, i.e. an infinite input value maps to white output value, i.e. over-exposure is no longer possible. A good default value is 0.5.

When the upper part of the dynamic range becomes compressed it naturally loses some of it's former contrast, and one often desires to regain some "punch" in the image by using the crush_blacks parameter. When 0, the lower intensity range is linear, but when raised towards 1, a strong "toe" region is added to the transfer curve so that low intensities get pushed more towards black, but in a gentle fashion.

bool mip_burn_highlights_per_component = true

Specifies how the burn_highlights parameter is applied to the different color components. By default it is applied separately to all channels, which can lead to saturation loss though. Disabling the parameter applies the burn_highlights to the luminance, keeping the output color as close as possible to the input color.

bool mip_burn_highlights_max_component = false

Specifies how the burn_highlights parameter is applied to the different color components. Enabling the parameter applies the burn_highlights depending on the maximum value of the different color components.

mi::Float32 mip_saturation = 1.0

Compressing bright color components inherently moves them towards a less saturated color. Sometimes, very strong compressions can leave the image in an unappealingly de-saturated state. The saturation parameter allows an artistic control over the final image saturation. 1.0 is the standard "unmodified" saturation, higher increases and lower decreases saturation.

mi::Float32 mip_gamma = 2.2

The gamma parameter applies a display gamma correction. If the image will be displayed as-is, without further post-processing by the application, this value should be set to match the displays characteristic, otherwise disabled by setting to 1.

Note: Note that the attributes have the prefix mip_, but apart from that their meaning is identical to the parameters of the mia_exposure_photographic shader.