# colour_hdri.tonemapping.global_operators Package

## Sub-Modules

- colour_hdri.tonemapping.global_operators.operators Module
  - Global Tonemapping Operators

## Module Contents

`colour_hdri.tonemapping.global_operators.``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.global_operators.``tonemapping_operator_normalisation`(RGB, colourspace=None)

  Performs given RGB array tonemapping using the normalisation method.

  Parameters: | RGB (array_like) – RGB array to perform tonemapping onto. colourspace (colour.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.1194997...,  0.0874388...,  0.0587783...],
              [ 0.3478122...,  0.1379590...,  0.0971544...]],

             [[ 1.0959009...,  0.5362936...,  0.3342115...],
              [ 1.6399638...,  0.8549608...,  0.5518382...]]])

`colour_hdri.tonemapping.global_operators.``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.global_operators.``tonemapping_operator_logarithmic`(RGB, q=1, k=1, colourspace=None)

  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 (colour.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.0647259...,  0.0435102...],
              [ 0.2278222...,  0.0903652...,  0.0636376...]],

             [[ 0.4717487...,  0.2308565...,  0.1438669...],
              [ 0.5727396...,  0.2985858...,  0.1927235...]]])

`colour_hdri.tonemapping.global_operators.``tonemapping_operator_exponential`(RGB, q=1, k=1, colourspace=None)

  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 (colour.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.0428669...,  0.0170031...,  0.0119740...]],

             [[ 0.1312736...,  0.0642404...,  0.0400338...],
              [ 0.1921684...,  0.1001830...,  0.0646635...]]])

`colour_hdri.tonemapping.global_operators.``tonemapping_operator_logarithmic_mapping`(RGB, p=1, q=1, colourspace=None)

  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 (colour.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.2532899...,  0.1853341...,  0.1245857...],
              [ 0.6523387...,  0.2587489...,  0.1822179...]],

             [[ 1.3507897...,  0.6610269...,  0.4119437...],
              [ 1.6399638...,  0.8549608...,  0.5518382...]]])

`colour_hdri.tonemapping.global_operators.``tonemapping_operator_exponentiation_mapping`(RGB, p=1, q=1, colourspace=None)

  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 (colour.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.1194997...,  0.0874388...,  0.0587783...],
              [ 0.3478122...,  0.1379590...,  0.0971544...]],

             [[ 1.0959009...,  0.5362936...,  0.3342115...],
              [ 1.6399638...,  0.8549608...,  0.5518382...]]])

`colour_hdri.tonemapping.global_operators.``tonemapping_operator_Schlick1994`(RGB, p=1, colourspace=None)

  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 (colour.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.1194997...,  0.0874388...,  0.0587783...],
              [ 0.3478122...,  0.1379590...,  0.0971544...]],

             [[ 1.0959009...,  0.5362936...,  0.3342115...],
              [ 1.6399638...,  0.8549608...,  0.5518382...]]])

`colour_hdri.tonemapping.global_operators.``tonemapping_operator_Tumblin1999`(RGB, L_da=20, C_max=100, L_max=100, colourspace=None)

  Performs given RGB array tonemapping using Tumblin, Hodgins and Guenter (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 (colour.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.0400492...,  0.0293043...,  0.0196990...],
              [ 0.1019768...,  0.0404489...,  0.0284852...]],

             [[ 0.2490212...,  0.1218618...,  0.0759427...],
              [ 0.3408366...,  0.1776880...,  0.1146895...]]])

`colour_hdri.tonemapping.global_operators.``tonemapping_operator_Reinhard2004`(RGB, f=0, m=0.3, a=0, c=0, colourspace=None)

  Performs given RGB array tonemapping using Reinhard and Devlin (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 (colour.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.0605894...,  0.0249445...,  0.0176972...]],

             [[ 0.1688972...,  0.0904532...,  0.0583584...],
              [ 0.2331935...,  0.1368456...,  0.0928316...]]])

`colour_hdri.tonemapping.global_operators.``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 Habble (2010) 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...]]])