colour_hdri Package — Colour - HDRI 0.1.0 documentation

# colour_hdri Package

## Sub-Packages

- colour_hdri.calibration Package
  - Sub-Modules
    - colour_hdri.calibration.debevec1997 Module
      - Debevec (1997) Camera Response Function Computation
  - Module Contents
- colour_hdri.generation Package
  - Sub-Modules
    - colour_hdri.generation.radiance Module
      - HDRI / Radiance Image Generation
    - colour_hdri.generation.weighting_functions Module
      - Weighting Functions
  - Module Contents
- colour_hdri.models Package
  - Sub-Modules
    - colour_hdri.models.rgb Module
      - RGB Colourspace & Transformations
  - Module Contents
- colour_hdri.plotting Package
  - Sub-Modules
    - colour_hdri.plotting.radiance Module
      - HDRI / Radiance Image Plotting
  - Module Contents
- colour_hdri.process Package
  - Sub-Modules
    - colour_hdri.process.conversion Module
      - Conversion Process
  - Module Contents
- colour_hdri.recovery Package
  - Sub-Modules
    - colour_hdri.recovery.highlights Module
      - Clipped Highlights Recovery
  - Module Contents
- colour_hdri.sampling Package
  - Sub-Modules
    - colour_hdri.sampling.grossberg2003 Module
      - Grossberg (2003) Histogram Based Image Sampling
  - Module Contents
- colour_hdri.tonemapping Package
  - Sub-Packages
    - colour_hdri.tonemapping.global_operators Package
      - Sub-Modules
        - colour_hdri.tonemapping.global_operators.operators Module
          - Global Tonemapping Operators
      - Module Contents
  - Module Contents
- colour_hdri.utilities Package
  - Sub-Modules
    - colour_hdri.utilities.common Module
      - Common Utilities
    - colour_hdri.utilities.exif Module
      - EXIF Manipulation
    - colour_hdri.utilities.exposure Module
      - Image Exposure Value Computation
    - colour_hdri.utilities.image Module
      - Image Data & Metadata Utilities
  - Module Contents

## Module Contents

### Colour - HDRI

HDRI - Radiance image processing algorithms for Python.

#### Subpackages

- calibration: Camera calibration computations.
- examples: Examples for the sub-packages.
- generation: HDRI / radiance image generation.
- models: Colour models conversion.
- plotting: Diagrams, figures, etc...
- process: Image conversion helpers.
- recovery: Clipped highlights recovery.
- resources: Resources sub-modules.
- sampling: Image sampling routines.
- tonemapping: Tonemapping operators.
- utilities: Various utilities and data structures.

`colour_hdri.` `linear_conversion`(a, old_range, new_range)

  Performs a simple linear conversion of given array between the old and new ranges.

  Parameters: | a (array_like) – Array to perform the linear conversion onto. old_range (array_like) – Old range. new_range (array_like) – New range.
  Returns: |
  Return type: | ndarray

  Examples

      >>> a = np.linspace(0, 1, 10)
      >>> linear_conversion(a, np.array([0, 1]), np.array([1, 10]))
      array([  1.,   2.,   3.,   4.,   5.,   6.,   7.,   8.,   9.,  10.])

`colour_hdri.` `vivification`()

  Implements supports for vivification of the underlying dict like data-structure, magical!

  Returns: |
  Return type: | defaultdict

  Examples

      >>> vivified = vivification()
      >>> vivified['my']['attribute'] = 1
      >>> vivified['my']
      defaultdict(<function vivification at 0x...>, {u'attribute': 1})
      >>> vivified['my']['attribute']
      1

`colour_hdri.` `vivified_to_dict`(vivified)

  Converts given vivified data-structure to dictionary.

  Parameters: | vivified (defaultdict) – Vivified data-structure.
  Returns: |
  Return type: | dict

  Examples

      >>> vivified = vivification()
      >>> vivified['my']['attribute'] = 1
      >>> vivified_to_dict(vivified)
      {u'my': {u'attribute': 1}}

`colour_hdri.` `path_exists`(path)

  Returns if given path exists.

  Parameters: | path (unicode) – Path to check the existence.
  Returns: |
  Return type: | bool

  Examples

      >>> path_exists(__file__)
      True
      >>> path_exists('')
      False

`colour_hdri.` `filter_files`(directory, extensions)

  Filters given directory for files matching given extensions.

  Parameters: | directory (unicode) – Directory to filter. extensions (tuple or list) – Extensions to filter on.
  Returns: | Filtered files.
  Return type: | list

`colour_hdri.` `parse_exif_data`(data)

  Parses given exif data output from exiftool.

  Parameters: | data (unicode) – Exif data.
  Returns: | Parsed exif data.
  Return type: | list

`colour_hdri.` `read_exif_tags`(image)

  Returns given image exif image tags.

  Parameters: | image (unicode) – Image file.
  Returns: | Exif tags.
  Return type: | defaultdict

`colour_hdri.` `copy_exif_tags`(source, target)

  Copies given source image file exif tag to given image target.

  Parameters: | source (unicode) – Source image file. target (unicode) – Target image file.
  Returns: | Definition success.
  Return type: | bool

`colour_hdri.` `update_exif_tags`(images)

  Updates given images siblings images pairs exif tags.

  Parameters: | images (list) – Image files to update.
  Returns: | Definition success.
  Return type: | bool

`colour_hdri.` `delete_exif_tags`(image)

  Deletes all given image exif tags.

  Parameters: | image (unicode) – Image file.
  Returns: | Definition success.
  Return type: | bool

`colour_hdri.` `read_exif_tag`(image, tag)

  Returns given image exif tag value.

  Parameters: | image (unicode) – Image file. tag (unicode) – Tag.
  Returns: | Tag value.
  Return type: | unicode

`colour_hdri.` `write_exif_tag`(image, tag, value)

  Sets given image exif tag value.

  Parameters: | image (unicode) – Image file. tag (unicode) – Tag. value (unicode) – Value.
  Returns: | Definition success.
  Return type: | bool

`colour_hdri.` `exposure_value`(f_number, exposure_time, iso)

  Computes the exposure value from given image FNumber, Exposure Time and ISO values.

  Parameters: | f_number (array_like) – Image FNumber. exposure_time (array_like) – Image Exposure Time. iso (array_like) – Image ISO.
  Returns: | Image exposure value.
  Return type: | ndarray

  Examples

      >>> exposure_value(8, 1, 100)
      6.0

`colour_hdri.` `adjust_exposure`(a, EV)

  Adjusts given array exposure using given \(EV\) exposure value.

  Parameters: | a (array_like) – Array to adjust the exposure. EV (numeric) – Exposure adjustment value.
  Returns: | Exposure adjusted array.
  Return type: | ndarray

  Examples

      >>> adjust_exposure(np.array([0.25, 0.5, 0.75, 1]), 1)
      array([ 0.5,  1. ,  1.5,  2. ])

`colour_hdri.` `average_luminance`(f_number, exposure_time, iso, k=12.5)

  Computes the average luminance from given image FNumber, Exposure Time and ISO values.

  Parameters: | f_number (array_like) – Image FNumber. exposure_time (array_like) – Image Exposure Time. iso (array_like) – Image ISO. k (numeric, optional) – Reflected light calibration constant \(K\).
  Returns: | Image average luminance.
  Return type: | ndarray

  References

  [1] | Wikipedia. (n.d.). EV as a measure of luminance and illuminance. Retrieved November 14, 2015, from https://en.wikipedia.org/wiki/Exposure_value#EV_as_a_measure_of_luminance_and_illuminance

  Examples

      >>> average_luminance(8, 1, 100)
      0.125

class `colour_hdri.` `Metadata`

  Bases: `colour_hdri.utilities.image.Metadata`

  Defines the base object for storing exif metadata relevant to HDRI / radiance image generation.

  Parameters: | f_number (array_like) – Image FNumber. exposure_time (array_like) – Image Exposure Time. iso (array_like) – Image ISO. black_level (array_like) – Image Black Level. white_level (array_like) – Image White Level. white_balance_multipliers (array_like) – Image white balance multipliers, usually the As Shot Neutral matrix.

class `colour_hdri.` `Image`(path=None, data=None, metadata=None)

  Bases: `object`

  Defines the base object for storing an image along its path, pixel data and metadata needed for HDRI / radiance images generation.

  Parameters: | path (unicode, optional) – Image path. data (array_like, optional) – Image pixel data array. metadata (Metadata, optional) – Image exif metadata.

  `path`
  `data`
  `metadata`
  `read_data`()
  `read_metadata`()
  `data`

    Property for self.__data private attribute.

    Returns: | self.__data.
    Return type: | unicode

  `metadata`

    Property for self.__metadata private attribute.

    Returns: | self.__metadata.
    Return type: | unicode

  `path`

    Property for self.__path private attribute.

    Returns: | self.__path.
    Return type: | unicode

  `read_data`()

    Reads image pixel data at `Image.path` attribute.

    Returns: | Image pixel data.
    Return type: | ndarray

  `read_metadata`()

    Reads image relevant exif metadata at `Image.path` attribute.

    Returns: | Image relevant exif metadata.
    Return type: | Metadata

class `colour_hdri.` `ImageStack`

  Bases: `_abcoll.MutableSequence`

  Defines a convenient stack storing a sequence of images for HDRI / radiance images generation.

  `ImageStack`()
  `__init__`()
  `__getitem__`()
  `__setitem__`()
  `__delitem__`()
  `__len__`()
  `__getattr__`()
  `__setattr__`()
  `insert`()
  `from_files`()
  `__delitem__`(index)

    Reimplements the `MutableSequence.__delitem__()` method.

    Parameters: | index (int) – Item index.

  `__getattr__`(attribute)

    Reimplements the `MutableSequence.__getattr__()` method.

    Parameters: | attribute (unicode) – Attribute to retrieve the value.
    Returns: | Attribute value.
    Return type: | object

  `__getitem__`(index)

    Reimplements the `MutableSequence.__getitem__()` method.

    Parameters: | index (int) – Item index.
    Returns: | Item at given index.
    Return type: | Image

  `__len__`()

    Reimplements the `MutableSequence.__len__()` method.

  `__setattr__`(attribute, value)

    Reimplements the `MutableSequence.__getattr__()` method.

    Parameters: | attribute (unicode) – Attribute to set the value. value (object) – Value to set.

  `__setitem__`(index, value)

    Reimplements the `MutableSequence.__setitem__()` method.

    Parameters: | index (int) – Item index. value (int) – Item value.

  static `from_files`(image_files)

    Returns a `ImageStack` instance with given image files.

    Parameters: | image_files (array_like) – Image files.
    Returns: |
    Return type: | ImageStack

  `insert`(index, value)

    Reimplements the `MutableSequence.insert()` method.

    Parameters: | index (int) – Item index. value (object) – Item value.

`colour_hdri.` `samples_Grossberg2003`(image_stack, samples=1000, n=256)

  Returns the samples for given image stack intensity histograms using Grossberg (2003) method.

  Parameters: | image_stack (array_like) – Stack of single channel or multi-channel floating point images. samples (int, optional) – Samples count. n (int, optional) – Histograms bins count.
  Returns: | Intensity histograms samples.
  Return type: | ndarray

`colour_hdri.` `normal_distribution_function`(a, mu=0.5, sigma=0.15)

  Returns given array weighted by a normal distribution function.

  Parameters: | a (array_like) – Array to apply the weighting function onto. mu (numeric, optional) – Mean or expectation. sigma (numeric, optional) – Standard deviation.
  Returns: | Weighted array.
  Return type: | ndarray

  Examples

      >>> normal_distribution_function(np.linspace(0, 1, 10))
      array([ 0.00386592,  0.03470859,  0.18002174,  0.53940751,  0.93371212,
              0.93371212,  0.53940751,  0.18002174,  0.03470859,  0.00386592])

`colour_hdri.` `hat_function`(a)

  Returns given array weighted by a hat function.

  Parameters: | a (array_like) – Array to apply the weighting function onto.
  Returns: | Weighted array.
  Return type: | ndarray

  Examples

      >>> hat_function(np.linspace(0, 1, 10))
      array([ 0.        ,  0.95099207,  0.99913557,  0.99999812,  1.        ,
              1.        ,  0.99999812,  0.99913557,  0.95099207,  0.        ])

`colour_hdri.` `weighting_function_Debevec1997`(a, domain_l=0.01, domain_h=0.99)

  Returns given array weighted by Debevec (1997) function.

  Parameters: | a (array_like) – Array to apply the weighting function onto. domain_l (numeric, optional) – Domain lowest possible value, values less than `domain_l` will be set to zero. domain_h (numeric, optional) – Domain highest possible value, values greater than `domain_h` will be set to zero.
  Returns: | Weighted array.
  Return type: | ndarray

  References

  [1] | Debevec, P., & Malik, J. (1997). Recovering High Dynamic Range Radiance Maps from Photographs, (August), 1–10. doi:10.1145/258734.258884

  Examples

      >>> weighting_function_Debevec1997(np.linspace(0, 1, 10))
      array([ 0.        ,  0.23273657,  0.48849105,  0.74424552,  1.        ,
              1.        ,  0.74424552,  0.48849105,  0.23273657,  0.        ])

`colour_hdri.` `image_stack_to_radiance_image`(image_stack, weighting_function=<function weighting_function_Debevec1997 at 0x10ae70f50>, weighting_average=False, camera_response_functions=None)

  Generates a HDRI / radiance image from given image stack.

  Parameters: | image_stack (ImageStack) – Stack of single channel or multi-channel floating point images. The stack is assumed to be representing linear values except if `camera_response_functions` argument is provided. weighting_function (callable, optional) – Weighting function \(w\). weighting_average (bool, optional) – Enables weighting function \(w\) computation on channels average instead of on a per channel basis. camera_response_functions (array_like, optional) – Camera response functions \(g(z)\) of the imaging system / camera if the stack is representing non linear values.
  Returns: | Radiance image.
  Return type: | ndarray

`colour_hdri.` `g_solve`(Z, B, l=30, w=<function weighting_function_Debevec1997 at 0x10ae70f50>, n=256)

  Given a set of pixel values observed for several pixels in several images with different exposure times, this function returns the imaging system’s response function \(g\) as well as the log film irradiance values \(lE\) for the observed pixels.

  Parameters: | Z (array_like) – Set of pixel values observed for several pixels in several images. B (array_like) – Log \(\Delta t\), or log shutter speed for images. l (numeric, optional) – \(\lambda\) smoothing term. w (callable, optional) – Weighting function \(w\). n (int, optional) – \(n\) constant.
  Returns: | Camera response functions \(g(z)\) and log film irradiance values \(lE\).
  Return type: | tuple

`colour_hdri.` `camera_response_functions_Debevec1997`(image_stack, s=<function samples_Grossberg2003 at 0x10ae70de8>, samples=1000, l=30, w=<function weighting_function_Debevec1997 at 0x10ae70f50>, n=256, normalise=True)

  Returns the camera response functions for given image stack using Debevec (1997) method.

  Image channels are sampled with \(s\) sampling function and the output samples are passed to `g_solve()`.

  Parameters: | image_stack (ImageStack) – Stack of single channel or multi-channel floating point images. s (callable, optional) – Sampling function \(s\). samples (int, optional) – Samples count per images. l (numeric, optional) – \(\lambda\) smoothing term. w (callable, optional) – Weighting function \(w\). n (int, optional) – \(n\) constant. normalise (bool, optional) – Enables the camera response functions normalisation. Uncertain camera response functions values resulting from \(w\) function are set to zero.
  Returns: | Camera response functions \(g(z)\).
  Return type: | ndarray

`colour_hdri.` `camera_space_to_RGB`(RGB, XYZ_to_camera_matrix, RGB_to_XYZ_matrix)

  Converts given RGB array from camera space to given RGB colourspace.

  Parameters: | RGB (array_like) – Camera space RGB colourspace array. XYZ_to_camera_matrix (array_like) – Matrix converting from CIE XYZ tristimulus values to camera space. RGB_to_XYZ_matrix (array_like) – Matrix converting from RGB colourspace to CIE XYZ tristimulus values.
  Returns: | RGB colourspace array.
  Return type: | ndarray

  Examples

      >>> RGB = np.array([0.80660, 0.81638, 0.65885])
      >>> XYZ_to_camera_matrix = np.array([
      ...     [0.47160000, 0.06030000, -0.08300000],
      ...     [-0.77980000, 1.54740000, 0.24800000],
      ...     [-0.14960000, 0.19370000, 0.66510000]])
      >>> RGB_to_XYZ_matrix = np.array([
      ...     [0.41238656, 0.35759149, 0.18045049],
      ...     [0.21263682, 0.71518298, 0.07218020],
      ...     [0.01933062, 0.11919716, 0.95037259]])
      >>> camera_space_to_RGB(
      ...     RGB,
      ...     XYZ_to_camera_matrix,
      ...     RGB_to_XYZ_matrix)
      array([ 0.7564180...,  0.8683192...,  0.6044589...])

`colour_hdri.` `camera_space_to_sRGB`(RGB, XYZ_to_camera_matrix)

  Converts given RGB array from camera space to sRGB colourspace.

  Parameters: | RGB (array_like) – Camera space RGB colourspace array. XYZ_to_camera_matrix (array_like) – Matrix converting from CIE XYZ tristimulus values to camera space.
  Returns: | sRGB colourspace array.
  Return type: | ndarray

  Examples

      >>> RGB = np.array([0.80660, 0.81638, 0.65885])
      >>> XYZ_to_camera_matrix = np.array([
      ...     [0.47160000, 0.06030000, -0.08300000],
      ...     [-0.77980000, 1.54740000, 0.24800000],
      ...     [-0.14960000, 0.19370000, 0.66510000]])
      >>> camera_space_to_sRGB(RGB, XYZ_to_camera_matrix)
      array([ 0.7564180...,  0.8683192...,  0.6044589...])

`colour_hdri.` `radiance_image_strip_plot`(image, count=5, ev_steps=-2, transfer_function=<function _srgb_transfer_function at 0x1092570c8>)

  Plots given HDRI / radiance image as strip of images of varying exposure.

  Parameters: | image (array_like) – HDRI / radiance image to plot. count (int, optional) – Strip images count. ev_steps (numeric, optional) – Exposure variation for each image of the strip. transfer_function (callable, optional) – OECF / transfer function used for plotting.
  Returns: | Definition success.
  Return type: | bool

`colour_hdri.` `convert_raw_files_to_dng_files`(raw_files, output_directory)

  Converts given raw files to dng files using given output directory.

  Parameters: | raw_files (array_like) – Raw files to convert to dng files. output_directory (unicode) – Output directory.
  Returns: | dng files.
  Return type: | list

`colour_hdri.` `convert_dng_files_to_intermediate_files`(dng_files, output_directory, demosaicing=False)

  Converts given dng files to intermediate tiff files using given output directory.

  Parameters: | dng_files (array_like) – dng files to convert to intermediate tiff files. output_directory (str) – Output directory. demosaicing (bool) – Perform demosaicing on conversion.
  Returns: | Intermediate tiff files.
  Return type: | list

`colour_hdri.` `highlights_recovery_blend`(RGB, multipliers, threshold=0.99)

  Performs highlights recovery using Coffin (1997) method from dcraw.

  Parameters: | RGB (array_like) – RGB colourspace array. multipliers (array_like) – Normalised camera white level or white balance multipliers. threshold (numeric, optional) – Threshold for the highlights selection.
  Returns: | Highlights recovered RGB colourspace array.
  Return type: | ndarray

  References

  [1] | Coffin, D. (2015). dcraw. Retrieved from https://www.cybercom.net/~dcoffin/dcraw/

`colour_hdri.` `tonemapping_operator_simple`(RGB)

  Performs given RGB array tonemapping using the simple method: \(\cfrac{RGB}{RGB + 1}\).

  Parameters: | RGB (array_like) – RGB array to perform tonemapping onto.
  Returns: | Tonemapped RGB array.
  Return type: | ndarray

  References

  [1] | Wikipedia. (n.d.). Tonemapping - Purpose and methods. Retrieved March 15, 2015, from http://en.wikipedia.org/wiki/Tone_mapping#Purpose_and_methods

  Examples

      >>> tonemapping_operator_simple(np.array(
      ...     [[[0.48046875, 0.35156256, 0.23632812],
      ...       [1.39843753, 0.55468757, 0.39062594]],
      ...      [[4.40625388, 2.15625895, 1.34375372],
      ...       [6.59375023, 3.43751395, 2.21875829]]]))
      array([[[ 0.3245382...,  0.2601156...,  0.1911532...],
              [ 0.5830618...,  0.3567839...,  0.2808993...]],

             [[ 0.8150290...,  0.6831692...,  0.5733340...],
              [ 0.8683127...,  0.7746486...,  0.6893211...]]])

`colour_hdri.` `tonemapping_operator_normalisation`(RGB, colourspace=<colour.models.rgb.RGB_Colourspace object at 0x109250bd0>)

  Performs given RGB array tonemapping using the normalisation method.

  Parameters: | RGB (array_like) – RGB array to perform tonemapping onto. colourspace (RGB_Colourspace, optional) – RGB colourspace used for internal Luminance computation.
  Returns: | Tonemapped RGB array.
  Return type: | ndarray

  References

  [2] | (1, 2, 3, 4) Banterle, F., Artusi, A., Debattista, K., & Chalmers, A. (2011). 3.2.1 Simple Mapping Methods. In Advanced High Dynamic Range Imaging (pp. 38–41). A K Peters/CRC Press. ISBN:978-1568817194

  Examples

      >>> tonemapping_operator_normalisation(np.array(
      ...     [[[0.48046875, 0.35156256, 0.23632812],
      ...       [1.39843753, 0.55468757, 0.39062594]],
      ...      [[4.40625388, 2.15625895, 1.34375372],
      ...       [6.59375023, 3.43751395, 2.21875829]]]))
      array([[[ 0.1194995...,  0.0874386...,  0.0587782...],
              [ 0.3478115...,  0.1379587...,  0.0971542...]],

             [[ 1.0958987...,  0.5362926...,  0.3342109...],
              [ 1.6399606...,  0.8549592...,  0.5518371...]]])

`colour_hdri.` `tonemapping_operator_gamma`(RGB, gamma=1, EV=0)

  Performs given RGB array tonemapping using the gamma and exposure correction method [2].

  Parameters: | RGB (array_like) – RGB array to perform tonemapping onto. gamma (numeric, optional) – \(\gamma\) correction value. EV (numeric, optional) – Exposure adjustment value.
  Returns: | Tonemapped RGB array.
  Return type: | ndarray

  Examples

      >>> tonemapping_operator_gamma(np.array(
      ...     [[[0.48046875, 0.35156256, 0.23632812],
      ...       [1.39843753, 0.55468757, 0.39062594]],
      ...      [[4.40625388, 2.15625895, 1.34375372],
      ...       [6.59375023, 3.43751395, 2.21875829]]]),
      ...      1.0, -3.0)
      array([[[ 0.0600585...,  0.0439453...,  0.0295410...],
              [ 0.1748046...,  0.0693359...,  0.0488282...]],

             [[ 0.5507817...,  0.2695323...,  0.1679692...],
              [ 0.8242187...,  0.4296892...,  0.2773447...]]])

`colour_hdri.` `tonemapping_operator_logarithmic`(RGB, q=1, k=1, colourspace=<colour.models.rgb.RGB_Colourspace object at 0x109250bd0>)

  Performs given RGB array tonemapping using the logarithmic method [2].

  Parameters: | RGB (array_like) – RGB array to perform tonemapping onto. q (numeric, optional) – \(q\). k (numeric, optional) – \(k\). colourspace (RGB_Colourspace, optional) – RGB colourspace used for internal Luminance computation.
  Returns: | Tonemapped RGB array.
  Return type: | ndarray

  Examples

      >>> tonemapping_operator_logarithmic(np.array(
      ...     [[[0.48046875, 0.35156256, 0.23632812],
      ...       [1.39843753, 0.55468757, 0.39062594]],
      ...      [[4.40625388, 2.15625895, 1.34375372],
      ...       [6.59375023, 3.43751395, 2.21875829]]]),
      ...       1.0, 25)
      array([[[ 0.0884587...,  0.0647258...,  0.0435101...],
              [ 0.2278221...,  0.0903652...,  0.0636376...]],

             [[ 0.4717481...,  0.2308562...,  0.1438667...],
              [ 0.5727388...,  0.2985854...,  0.1927232...]]])

`colour_hdri.` `tonemapping_operator_exponential`(RGB, q=1, k=1, colourspace=<colour.models.rgb.RGB_Colourspace object at 0x109250bd0>)

  Performs given RGB array tonemapping using the exponential method [2].

  Parameters: | RGB (array_like) – RGB array to perform tonemapping onto. q (numeric, optional) – \(q\). k (numeric, optional) – \(k\). colourspace (RGB_Colourspace, optional) – RGB colourspace used for internal Luminance computation.
  Returns: | Tonemapped RGB array.
  Return type: | ndarray

  Examples

      >>> tonemapping_operator_exponential(np.array(
      ...     [[[0.48046875, 0.35156256, 0.23632812],
      ...       [1.39843753, 0.55468757, 0.39062594]],
      ...      [[4.40625388, 2.15625895, 1.34375372],
      ...       [6.59375023, 3.43751395, 2.21875829]]]),
      ...       1.0, 25)
      array([[[ 0.0148082...,  0.0108353...,  0.0072837...],
              [ 0.0428668...,  0.0170030...,  0.0119740...]],

             [[ 0.1312733...,  0.0642403...,  0.0400338...],
              [ 0.1921681...,  0.1001828...,  0.0646634...]]])

`colour_hdri.` `tonemapping_operator_logarithmic_mapping`(RGB, p=1, q=1, colourspace=<colour.models.rgb.RGB_Colourspace object at 0x109250bd0>)

  Performs given RGB array tonemapping using the logarithmic mapping method.

  Parameters: | RGB (array_like) – RGB array to perform tonemapping onto. p (numeric, optional) – \(p\). q (numeric, optional) – \(q\). colourspace (RGB_Colourspace, optional) – RGB colourspace used for internal Luminance computation.
  Returns: | Tonemapped RGB array.
  Return type: | ndarray

  References

  [3] | Schlick, C. (1994). Quantization Techniques for Visualization of High Dynamic Range Pictures. Proceedings of the Fifth Eurographics Workshop on Rendering, (Section 5), 7–18.

  Examples

      >>> tonemapping_operator_logarithmic_mapping(np.array(
      ...     [[[0.48046875, 0.35156256, 0.23632812],
      ...       [1.39843753, 0.55468757, 0.39062594]],
      ...      [[4.40625388, 2.15625895, 1.34375372],
      ...       [6.59375023, 3.43751395, 2.21875829]]]))
      array([[[ 0.2532896...,  0.1853338...,  0.1245855...],
              [ 0.6523381...,  0.2587486...,  0.1822177...]],

             [[ 1.3507873...,  0.6610257...,  0.4119430...],
              [ 1.6399606...,  0.8549592...,  0.5518371...]]])

`colour_hdri.` `tonemapping_operator_exponentiation_mapping`(RGB, p=1, q=1, colourspace=<colour.models.rgb.RGB_Colourspace object at 0x109250bd0>)

  Performs given RGB array tonemapping using the exponentiation mapping method [3].

  Parameters: | RGB (array_like) – RGB array to perform tonemapping onto. p (numeric, optional) – \(p\). q (numeric, optional) – \(q\). colourspace (RGB_Colourspace, optional) – RGB colourspace used for internal Luminance computation.
  Returns: | Tonemapped RGB array.
  Return type: | ndarray

  Examples

      >>> tonemapping_operator_exponentiation_mapping(np.array(
      ...     [[[0.48046875, 0.35156256, 0.23632812],
      ...       [1.39843753, 0.55468757, 0.39062594]],
      ...      [[4.40625388, 2.15625895, 1.34375372],
      ...       [6.59375023, 3.43751395, 2.21875829]]]))
      array([[[ 0.1194995...,  0.0874386...,  0.0587782...],
              [ 0.3478115...,  0.1379587...,  0.0971542...]],

             [[ 1.0958987...,  0.5362926...,  0.3342109...],
              [ 1.6399606...,  0.8549592...,  0.5518371...]]])

`colour_hdri.` `tonemapping_operator_Schlick1994`(RGB, p=1, colourspace=<colour.models.rgb.RGB_Colourspace object at 0x109250bd0>)

  Performs given RGB array tonemapping using Schlick (1994) method [2]_[3]_.

  Parameters: | RGB (array_like) – RGB array to perform tonemapping onto. p (numeric, optional) – \(p\). colourspace (RGB_Colourspace, optional) – RGB colourspace used for internal Luminance computation.
  Returns: | Tonemapped RGB array.
  Return type: | ndarray

  Examples

      >>> tonemapping_operator_Schlick1994(np.array(
      ...     [[[0.48046875, 0.35156256, 0.23632812],
      ...       [1.39843753, 0.55468757, 0.39062594]],
      ...      [[4.40625388, 2.15625895, 1.34375372],
      ...       [6.59375023, 3.43751395, 2.21875829]]]))
      array([[[ 0.1194995...,  0.0874386...,  0.0587782...],
              [ 0.3478115...,  0.1379587...,  0.0971542...]],

             [[ 1.0958987...,  0.5362926...,  0.3342109...],
              [ 1.6399606...,  0.8549592...,  0.5518371...]]])

`colour_hdri.` `tonemapping_operator_Tumblin1999`(RGB, L_da=20, C_max=100, L_max=100, colourspace=<colour.models.rgb.RGB_Colourspace object at 0x109250bd0>)

  Performs given RGB array tonemapping using Tumblin (1999) method [2].

  Parameters: | RGB (array_like) – RGB array to perform tonemapping onto. L_da (numeric, optional) – \(L_{da}\) display adaptation luminance, a mid-range display value. C_max (numeric, optional) – \(C_{max}\) maximum contrast available from the display. L_max (numeric, optional) – \(L_{max}\) maximum display luminance. colourspace (RGB_Colourspace, optional) – RGB colourspace used for internal Luminance computation.
  Returns: | Tonemapped RGB array.
  Return type: | ndarray

  References

  [4] | Tumblin, J., Hodgins, J. K., & Guenter, B. K. (1999). Two methods for display of high contrast images. ACM Transactions on Graphics. doi:10.1145/300776.300783

  Examples

      >>> tonemapping_operator_Tumblin1999(np.array(
      ...     [[[0.48046875, 0.35156256, 0.23632812],
      ...       [1.39843753, 0.55468757, 0.39062594]],
      ...      [[4.40625388, 2.15625895, 1.34375372],
      ...       [6.59375023, 3.43751395, 2.21875829]]]))
      array([[[ 0.0400491...,  0.0293042...,  0.0196989...],
              [ 0.1019767...,  0.0404488...,  0.0284851...]],

             [[ 0.2490208...,  0.1218616...,  0.0759426...],
              [ 0.3408361...,  0.1776878...,  0.1146893...]]])

`colour_hdri.` `tonemapping_operator_Reinhard2004`(RGB, f=0, m=0.3, a=0, c=0, colourspace=<colour.models.rgb.RGB_Colourspace object at 0x109250bd0>)

  Performs given RGB array tonemapping using Reinhard (2004) method.

  Parameters: | RGB (array_like) – RGB array to perform tonemapping onto. f (numeric, optional) – \(f\). m (numeric, optional) – \(m\). a (numeric, optional) – \(a\). c (numeric, optional) – \(c\). colourspace (RGB_Colourspace, optional) – RGB colourspace used for internal Luminance computation.
  Returns: | Tonemapped RGB array.
  Return type: | ndarray

  References

  [5] | Reinhard, E., & Devlin, K. (2005). Dynamic range reduction inspired by photoreceptor physiology. IEEE Transactions on Visualization and Computer Graphics, 11(1), 13–24. doi:10.1109/TVCG.2005.9

  Examples

      >>> tonemapping_operator_Reinhard2004(np.array(
      ...     [[[0.48046875, 0.35156256, 0.23632812],
      ...       [1.39843753, 0.55468757, 0.39062594]],
      ...      [[4.40625388, 2.15625895, 1.34375372],
      ...       [6.59375023, 3.43751395, 2.21875829]]]),
      ...     -10)
      array([[[ 0.0216792...,  0.0159556...,  0.0107821...],
              [ 0.0605893...,  0.0249445...,  0.0176971...]],

             [[ 0.1688971...,  0.0904532...,  0.0583583...],
              [ 0.2331934...,  0.1368456...,  0.0928316...]]])

`colour_hdri.` `tonemapping_operator_filmic`(RGB, shoulder_strength=0.22, linear_strength=0.3, linear_angle=0.1, toe_strength=0.2, toe_numerator=0.01, toe_denominator=0.3, exposure_bias=2, linear_whitepoint=11.2)

  Performs given RGB array tonemapping using Reinhard (2004) method.

  Parameters: | RGB (array_like) – RGB array to perform tonemapping onto. shoulder_strength (numeric, optional) – Shoulder strength. linear_strength (numeric, optional) – Linear strength. linear_angle (numeric, optional) – Linear angle. toe_strength (numeric, optional) – Toe strength. toe_numerator (numeric, optional) – Toe numerator. toe_denominator (numeric, optional) – Toe denominator. exposure_bias (numeric, optional) – Exposure bias. linear_whitepoint (numeric, optional) – Linear whitepoint.
  Returns: | Tonemapped RGB array.
  Return type: | ndarray

  References

  [6] | Habble, J. (2010). Filmic Tonemapping Operators. Retrieved March 15, 2015, from http://filmicgames.com/archives/75

  [7] | Habble, J. (2010). Uncharted 2: HDR Lighting. Retrieved March 15, 2015, from http://www.slideshare.net/ozlael/hable-john-uncharted2-hdr-lighting

  Examples

      >>> tonemapping_operator_filmic(np.array(
      ...     [[[0.48046875, 0.35156256, 0.23632812],
      ...       [1.39843753, 0.55468757, 0.39062594]],
      ...      [[4.40625388, 2.15625895, 1.34375372],
      ...       [6.59375023, 3.43751395, 2.21875829]]]))
      array([[[ 0.4507954...,  0.3619673...,  0.2617269...],
              [ 0.7567191...,  0.4933310...,  0.3911730...]],

             [[ 0.9725554...,  0.8557374...,  0.7465713...],
              [ 1.0158782...,  0.9382937...,  0.8615161...]]])