Shady.Contrast Sub-module

This module contains various optional (but useful) utility functions that relate specifically to computation and conversion of contrast and luminance values.

Note that everything exported from this module is also available in the top-level Shady.* namespace.

Brief definitions for terms used in this submodule are as follows, but for full details, see Luminance and Contrast in the online documentation or the docstring of Shady.Documentation.LuminanceAndContrast.

Ideal luminance:

a value from 0 (corresponding to the screen’s minimum luminance) to 1 (corresponding to the screen’s maximum luminance).

Physical luminance:

a true physical measure of screen luminance, including the effect of reflected ambient light. Will not ever reach 0 unless your setup is very expensive…

Ideal contrast ratio:

a contrast ratio (RMS or Michelson) computed from ideal luminance values.

Physical contrast ratio:

a contrast ratio (RMS or Michelson) computed from physical luminance values.

Normalized contrast:

not a contrast ratio, but rather a scaling factor from 0 to 1 that is applied to a signal’s amplitude, such that a normalized contrast of 1 allows the signal to fill the screen’s entire luminance range.

Shady.Contrast.IdealContrastRatioToNormalizedContrast(idealContrastRatio, idealBackgroundLuminance)

Convert one or more ideal contrast ratios to normalized contrast scaling factors. For more details, see Luminance and Contrast in the online documentation or the docstring of Shady.Documentation.LuminanceAndContrast.

Parameters:

  • idealContrastRatio – “ideal” contrast ratio(s) to convert

  • idealBackgroundLuminance – “ideal” background luminance (scalar, in the range 0 to 1)

Returns:

Normalized contrast scaling factors(s) corresponding to the input ideal contrast ratio(s).

Shady.Contrast.IdealToPhysicalContrastRatio(idealContrastRatio, idealBackgroundLuminance, physicalScreenRange)

Convert one or more ideal contrast ratios to physical contrast ratios. For more details, see Luminance and Contrast in the online documentation or the docstring of Shady.Documentation.LuminanceAndContrast.

Parameters:

  • idealContrastRatio – “ideal” contrast ratio(s) to convert

  • idealBackgroundLuminance – “ideal” background luminance (scalar, in the range 0 to 1)

  • physicalScreenRange – sequence of [min, max] physical luminance values measured from the screen with a photometer

Returns:

Physical contrast ratio(s) corresponding to the ideal input value(s).

Shady.Contrast.IdealToPhysicalLuminance(idealLuminance, physicalScreenRange)

Convert ideal luminance (from 0 to 1) to physical luminance. For more details, see Luminance and Contrast in the online documentation or the docstring of Shady.Documentation.LuminanceAndContrast.

Parameters:

  • idealLuminance – “ideal” luminance value(s) to convert (in the range 0 to 1)

  • physicalScreenRange – sequence of [min, max] physical luminance values measured from the screen with a photometer

Returns:

Physical luminance value(s) corresponding to the ideal input value(s).

Shady.Contrast.MichelsonContrastRatio(pixels, background=None)

Compute the Michelson contrast ratio of a pixel array, \(\frac{L_{\max} - L_{\min}}{L_{\max} + L_{\min}}\), or in plain text:

(pixels.max() - pixels.min()) / (pixels.max() + pixels.min())

The input argument background is unused but it is included in the prototype for compatibility with RMSContrastRatio().

If pixels is a three-dimensional array, two preprocessing steps are performed: first, if its extent in the third dimension is 2 or 4, the last layer is assumed to be an alpha channel and is excluded from the computation; second, “luminance” is computed as the mean-across-(remaining)-layers. In reality, red, green and blue channels will not contribute equally to luminance, so for more accurate results, you may wish to perform your own computations to convert the array into a single-channel array of luminances before calling this function.

This function will work on any kind of luminance scale: if you feed it ideal luminances (in the 0 to 1 range), you will get an “ideal” contrast ratio. If you feed it physical luminances (in candelas / m^2) you will get a physical contrast ratio. For more details, see Luminance and Contrast in the online documentation or the docstring of Shady.Documentation.LuminanceAndContrast.

See also

Shady.Contrast.NormalizedContrastToIdealContrastRatio(normalizedContrast, idealBackgroundLuminance)

Convert one or more normalized contrast values to ideal contrast ratios. For more details, see Luminance and Contrast in the online documentation or the docstring of Shady.Documentation.LuminanceAndContrast.

Parameters:

  • normalizedContrast – normalized contrast scaling factor(s) (in the range 0 to 1) to convert

  • idealBackgroundLuminance – “ideal” background luminance (scalar, in the range 0 to 1)

Returns:

Ideal contrast ratio(s) corresponding to the input normalized contrast scaling factor(s).

Shady.Contrast.PhysicalToIdealContrastRatio(physicalContrast, idealBackgroundLuminance, physicalScreenRange)

Convert one or more physical contrast ratios to ideal contrast ratios. For more details, see Luminance and Contrast in the online documentation or the docstring of Shady.Documentation.LuminanceAndContrast.

Parameters:

  • physicalContrastRatio – physical contrast ratio(s) to convert

  • idealBackgroundLuminance – “ideal” background luminance (scalar, in the range 0 to 1)

  • physicalScreenRange – sequence of [min, max] physical luminance values measured from the screen with a photometer

Returns:

Ideal contrast ratio(s) corresponding to the physical input ratio(s).

Shady.Contrast.PhysicalToIdealLuminance(physicalLuminance, physicalScreenRange)

Convert physical luminance to ideal luminance (from 0 to 1). For more details, see Luminance and Contrast in the online documentation or the docstring of Shady.Documentation.LuminanceAndContrast.

Parameters:

  • physicalLuminance – physical luminance value(s) to convert

  • physicalScreenRange – sequence of [min, max] physical luminance values measured from the screen with a photometer

Returns:

Ideal luminance value(s) (in the range 0 to 1) corresponding to the physical input value(s).

Shady.Contrast.RMSContrastRatio(pixels, background=None)

Compute the root-mean-square contrast ratio of a pixel array. \(\frac{\sqrt{\frac{1}{N}\sum_x\sum_y (L_{xy} - L_{\mu})^2}}{L_{\mu}}\), or in plain text:

( (pixels - background) ** 2 ).mean() ** 0.5   /   background

where background (\(=L_{\mu}\)) defaults to pixels.mean().

If pixels is a three-dimensional array, two preprocessing steps are performed: first, if its extent in the third dimension is 2 or 4, the last layer is assumed to be an alpha channel and is excluded from the computation; second, “luminance” is computed as the mean-across-(remaining)-layers. In reality, red, green and blue channels will not contribute equally to luminance, so for more accurate results, you may wish to perform your own computations to convert the array into a single-channel array of luminances before calling this function.

This function will work on any kind of luminance scale: if you feed it ideal luminances (in the 0 to 1 range), you will get an “ideal” contrast ratio. If you feed it physical luminances (in candelas / m^2) you will get a physical contrast ratio. For more details, see Luminance and Contrast in the online documentation or the docstring of Shady.Documentation.LuminanceAndContrast.

See also