colour_hdri Package¶

Sub-Packages¶

colour_hdri.calibration Package
- Sub-Modules
  - colour_hdri.calibration.absolute_luminance Module
    - Absolute Luminance Calibration - Lagarde (2016)
  - 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
colour_hdri.plotting Package
- Sub-Modules
  - colour_hdri.plotting.radiance Module
    - HDRI / Radiance Image Plotting
  - colour_hdri.plotting.tonemapping Module
    - Tonemapping Operators Plotting
- Module Contents
colour_hdri.process Package
- Sub-Modules
  - colour_hdri.process.dng Module
    - Adobe DNG SDK 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
  - colour_hdri.sampling.variance_minimization Module
    - Viriyothai (2009) Variance Minimization Light Probe 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
- 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.vivification()[source]¶

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']  # doctest: +ELLIPSIS
defaultdict(<function vivification at 0x...>, {u'attribute': 1})
>>> vivified['my']['attribute']
1

colour_hdri.vivified_to_dict(vivified)[source]¶

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)[source]¶

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)[source]¶

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

class colour_hdri.ExifTag[source]¶

Bases: colour_hdri.utilities.exif.ExifTag

Hunt colour appearance model induction factors.

Parameters:	group (unicode, optional) – Exif tag group name. name (unicode, optional) – Exif tag name. value (object, optional) – Exif tag value. identifier (numeric, optional) – Exif tag identifier.

Returns a new instance of the ExifTag class.

colour_hdri.parse_exif_string(exif_tag)[source]¶

Parses given exif tag assuming it is a string and return its value.

Parameters:	exif_tag (ExifTag) – Exif tag to parse.
Returns:	Parsed exif tag value.
Return type:	unicode

colour_hdri.parse_exif_numeric(exif_tag, dtype=<class 'numpy.float64'>)[source]¶

Parses given exif tag assuming it is a numeric type and return its value.

Parameters:	exif_tag (ExifTag) – Exif tag to parse. dtype (object, optional) – Return value data type.
Returns:	Parsed exif tag value.
Return type:	numeric

colour_hdri.parse_exif_fraction(exif_tag, dtype=<class 'numpy.float64'>)[source]¶

Parses given exif tag assuming it is a fraction and return its value.

Parameters:	exif_tag (ExifTag) – Exif tag to parse. dtype (object, optional) – Return value data type.
Returns:	Parsed exif tag value.
Return type:	numeric

colour_hdri.parse_exif_array(exif_tag, dtype=<class 'numpy.float64'>, shape=None)[source]¶

Parses given exif tag assuming it is an array and return its value.

Parameters:	exif_tag (ExifTag) – Exif tag to parse. dtype (object, optional) – Return value data type. shape (array_like, optional) – Shape of
Returns:	Parsed exif tag value.
Return type:	ndarray

colour_hdri.parse_exif_data(data)[source]¶

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)[source]¶

Returns given image exif image tags.

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

colour_hdri.copy_exif_tags(source, target)[source]¶

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)[source]¶

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)[source]¶

Deletes all given image exif tags.

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

colour_hdri.read_exif_tag(image, tag)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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[source]¶

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)[source]¶

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()[source]¶

read_metadata()[source]¶

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(decoding_cctf=None)[source]

Reads image pixel data at Image.path attribute.

Parameters:	decoding_cctf (object, optional) – Decoding colour component transfer function (Decoding CCTF) or electro-optical transfer function (EOTF / EOCF).
Returns:	Image pixel data.
Return type:	ndarray

read_metadata()[source]

Reads image relevant exif metadata at Image.path attribute.

Returns:	Image relevant exif metadata.
Return type:	Metadata

class colour_hdri.ImageStack[source]¶

Bases: collections.abc.MutableSequence

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

ImageStack()¶

__init__()[source]¶

__getitem__()[source]¶

__setitem__()[source]¶

__delitem__()[source]¶

__len__()[source]¶

__getattr__()[source]¶

__setattr__()[source]¶

sort()[source]¶

insert()[source]¶

from_files()[source]¶

static from_files(image_files, decoding_cctf=None)[source]

Returns a ImageStack instance with given image files.

Parameters:	image_files (array_like) – Image files. decoding_cctf (object, optional) – Decoding colour component transfer function (Decoding CCTF) or electro-optical transfer function (EOTF / EOCF).
Returns:
Return type:	ImageStack

insert(index, value)[source]

Reimplements the MutableSequence.insert() method.

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

sort(key=None)[source]

Sorts the underlying data structure.

Parameters:	key (callable) – Function of one argument that is used to extract a comparison key from each data structure.

colour_hdri.samples_Grossberg2003(image_stack, samples=1000, n=256)[source]¶

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.light_probe_sampling_variance_minimization_Viriyothai2009(light_probe, lights_count=16, colourspace=None)[source]¶

Sample given light probe to find lights using Viriyothai (2009) variance minimization light probe sampling algorithm.

Parameters:	light_probe (array_like) – Array to sample for lights. lights_count (int) – Amount of lights to generate. colourspace (colour.RGB_Colourspace, optional) – RGB colourspace used for internal Luminance computation.
Returns:	list of `Light_Specification` lights.
Return type:	list

colour_hdri.normal_distribution_function(a, mu=0.5, sigma=0.15)[source]¶

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)[source]¶

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)[source]¶

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>, weighting_average=False, camera_response_functions=None)[source]¶

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

Warning

If the image stack contains images with negative or equal to zero values, unpredictable results may occur and NaNs might be generated. It is thus recommended to encode the images in a wider RGB colourspace or clamp negative values.

colour_hdri.upper_hemisphere_illuminance_weights_Lagarde2016(height, width)[source]¶

Computes upper hemisphere illuminance weights for use with applications unable to perform the computation directly, i.e. Adobe Photoshop.

Parameters:	height (int) – Output array height. width (int) – Output array width.
Returns:	Upper hemisphere illuminance weights.
Return type:	ndarray

Examples

>>> upper_hemisphere_illuminance_weights_Lagarde2016(  # doctest: +ELLIPSIS
...    16, 1)
array([[ 0...        ],
       [ 4.0143297...],
       [ 7.3345454...],
       [ 9.3865515...],
       [ 9.8155376...],
       [ 8.5473281...],
       [ 5.8012079...],
       [ 2.0520061...],
       [ 0...        ],
       [ 0...        ],
       [ 0...        ],
       [ 0...        ],
       [ 0...        ],
       [ 0...        ],
       [ 0...        ],
       [ 0...        ]])

colour_hdri.absolute_luminance_calibration_Lagarde2016(RGB, measured_illuminance, colourspace=None)[source]¶

Performs absolute Luminance calibration of given RGB panoramic image using Lagarde (2016) method.

Parameters:	RGB (array_like) – RGB panoramic image to calibrate. measured_illuminance (numeric) – Measured illuminance \(E_v\). colourspace (colour.RGB_Colourspace, optional) – RGB colourspace used for internal Luminance computation.
Returns:	Absolute Luminance calibrated RGB panoramic image.
Return type:	ndarray

Examples

>>> RGB = np.ones((4, 8, 3))
>>> absolute_luminance_calibration_Lagarde2016(  # doctest: +ELLIPSIS
...     RGB, 500)
array([[[ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...]],
<BLANKLINE>
       [[ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...]],
<BLANKLINE>
       [[ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...]],
<BLANKLINE>
       [[ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...],
        [ 233.9912506...,  233.9912506...,  233.9912506...]]])

colour_hdri.g_solve(Z, B, l=30, w=<function weighting_function_Debevec1997>, n=256)[source]¶

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>, samples=1000, l=30, w=<function weighting_function_Debevec1997>, n=256, normalise=True)[source]¶

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.xy_to_camera_neutral(xy, CCT_calibration_illuminant_1, CCT_calibration_illuminant_2, M_color_matrix_1, M_color_matrix_2, M_camera_calibration_1, M_camera_calibration_2, analog_balance)[source]¶

Converts given xy white balance chromaticity coordinates to Camera Neutral coordinates.

Parameters:	xy (array_like) – xy white balance chromaticity coordinates. CCT_calibration_illuminant_1 (numeric) – Correlated colour temperature of CalibrationIlluminant1. CCT_calibration_illuminant_2 (numeric) – Correlated colour temperature of CalibrationIlluminant2. M_color_matrix_1 (array_like) – ColorMatrix1 tag matrix. M_color_matrix_2 (array_like) – ColorMatrix2 tag matrix. M_camera_calibration_1 (array_like) – CameraCalibration1 tag matrix. M_camera_calibration_2 (array_like) – CameraCalibration2 tag matrix. analog_balance (array_like) – AnalogBalance tag vector.
Returns:	Camera Neutral coordinates.
Return type:	ndarray

References

[4]	Adobe Systems. (2012). Translating White Balance xy Coordinates to Camera Neutral Coordinates. In Digital Negative (DNG) Specification (p. 80).

Examples

>>> M_color_matrix_1 = np.array([
...     [0.5309, -0.0229, -0.0336],
...     [-0.6241, 1.3265, 0.3337],
...     [-0.0817, 0.1215, 0.6664]])
>>> M_color_matrix_2 = np.array([
...     [0.4716, 0.0603, -0.0830],
...     [-0.7798, 1.5474, 0.2480],
...     [-0.1496, 0.1937, 0.6651]])
>>> M_camera_calibration_1 = np.identity(3)
>>> M_camera_calibration_2 = np.identity(3)
>>> analog_balance = np.ones(3)
>>> xy_to_camera_neutral(  # doctest: +ELLIPSIS
...     np.array([0.32816244, 0.34698169]),
...     2850,
...     6500,
...     M_color_matrix_1,
...     M_color_matrix_2,
...     M_camera_calibration_1,
...     M_camera_calibration_2,
...     analog_balance)
array([ 0.4130699...,  1...        ,  0.646465...])

colour_hdri.camera_neutral_to_xy(camera_neutral, CCT_calibration_illuminant_1, CCT_calibration_illuminant_2, M_color_matrix_1, M_color_matrix_2, M_camera_calibration_1, M_camera_calibration_2, analog_balance, epsilon=<Mock name='mock.EPSILON' id='139671442442560'>)[source]¶

Converts given Camera Neutral coordinates to xy white balance chromaticity coordinates.

Parameters:	camera_neutral (array_like) – Camera Neutral coordinates. CCT_calibration_illuminant_1 (numeric) – Correlated colour temperature of CalibrationIlluminant1. CCT_calibration_illuminant_2 (numeric) – Correlated colour temperature of CalibrationIlluminant2. M_color_matrix_1 (array_like) – ColorMatrix1 tag matrix. M_color_matrix_2 (array_like) – ColorMatrix2 tag matrix. M_camera_calibration_1 (array_like) – CameraCalibration1 tag matrix. M_camera_calibration_2 (array_like) – CameraCalibration2 tag matrix. analog_balance (array_like) – AnalogBalance tag vector. epsilon (numeric, optional) – Threshold value for computation convergence.
Returns:	xy white balance chromaticity coordinates.
Return type:	ndarray
Raises:	`RuntimeError` – If the given Camera Neutral coordinates did not converge to xy white balance chromaticity coordinates.

References

[5]	Adobe Systems. (2012). Translating Camera Neutral Coordinates to White Balance xy Coordinates. In Digital Negative (DNG) Specification (pp. 80–81).

Examples

>>> M_color_matrix_1 = np.array([
...     [0.5309, -0.0229, -0.0336],
...     [-0.6241, 1.3265, 0.3337],
...     [-0.0817, 0.1215, 0.6664]])
>>> M_color_matrix_2 = np.array([
...     [0.4716, 0.0603, -0.0830],
...     [-0.7798, 1.5474, 0.2480],
...     [-0.1496, 0.1937, 0.6651]])
>>> M_camera_calibration_1 = np.identity(3)
>>> M_camera_calibration_2 = np.identity(3)
>>> analog_balance = np.ones(3)
>>> camera_neutral_to_xy(  # doctest: +ELLIPSIS
...     np.array([0.413070, 1.000000, 0.646465]),
...     2850,
...     6500,
...     M_color_matrix_1,
...     M_color_matrix_2,
...     M_camera_calibration_1,
...     M_camera_calibration_2,
...     analog_balance)
array([ 0.3281624...,  0.3469816...])

colour_hdri.XYZ_to_camera_space_matrix(xy, CCT_calibration_illuminant_1, CCT_calibration_illuminant_2, M_color_matrix_1, M_color_matrix_2, M_camera_calibration_1, M_camera_calibration_2, analog_balance)[source]¶

Returns the CIE XYZ to Camera Space matrix for given xy white balance chromaticity coordinates. [4]_

Parameters:	xy (array_like) – xy white balance chromaticity coordinates. CCT_calibration_illuminant_1 (numeric) – Correlated colour temperature of CalibrationIlluminant1. CCT_calibration_illuminant_2 (numeric) – Correlated colour temperature of CalibrationIlluminant2. M_color_matrix_1 (array_like) – ColorMatrix1 tag matrix. M_color_matrix_2 (array_like) – ColorMatrix2 tag matrix. M_camera_calibration_1 (array_like) – CameraCalibration1 tag matrix. M_camera_calibration_2 (array_like) – CameraCalibration2 tag matrix. analog_balance (array_like) – AnalogBalance tag vector.
Returns:	CIE XYZ to Camera Space matrix.
Return type:	ndarray

Notes

The reference illuminant is D50 as defined per ADOBE_DNG_XYZ_ILLUMINANT attribute.

Examples

>>> M_color_matrix_1 = np.array([
...     [0.5309, -0.0229, -0.0336],
...     [-0.6241, 1.3265, 0.3337],
...     [-0.0817, 0.1215, 0.6664]])
>>> M_color_matrix_2 = np.array([
...     [0.4716, 0.0603, -0.0830],
...     [-0.7798, 1.5474, 0.2480],
...     [-0.1496, 0.1937, 0.6651]])
>>> M_camera_calibration_1 = np.identity(3)
>>> M_camera_calibration_2 = np.identity(3)
>>> analog_balance = np.ones(3)
>>> XYZ_to_camera_space_matrix(  # doctest: +ELLIPSIS
...     np.array([0.34510414, 0.35162252]),
...     2850,
...     6500,
...     M_color_matrix_1,
...     M_color_matrix_2,
...     M_camera_calibration_1,
...     M_camera_calibration_2,
...     analog_balance)
array([[ 0.4854908...,  0.0408106..., -0.0714282...],
       [-0.7433278...,  1.4956549...,  0.2680749...],
       [-0.1336946...,  0.1767874...,  0.6654045...]])

colour_hdri.camera_space_to_XYZ_matrix(xy, CCT_calibration_illuminant_1, CCT_calibration_illuminant_2, M_color_matrix_1, M_color_matrix_2, M_camera_calibration_1, M_camera_calibration_2, analog_balance, M_forward_matrix_1, M_forward_matrix_2, chromatic_adaptation_transform='Bradford')[source]¶

Returns the Camera Space to CIE XYZ matrix for given xy white balance chromaticity coordinates.

Parameters:	xy (array_like) – xy white balance chromaticity coordinates. CCT_calibration_illuminant_1 (numeric) – Correlated colour temperature of CalibrationIlluminant1. CCT_calibration_illuminant_2 (numeric) – Correlated colour temperature of CalibrationIlluminant2. M_color_matrix_1 (array_like) – ColorMatrix1 tag matrix. M_color_matrix_2 (array_like) – ColorMatrix2 tag matrix. M_camera_calibration_1 (array_like) – CameraCalibration1 tag matrix. M_camera_calibration_2 (array_like) – CameraCalibration2 tag matrix. analog_balance (array_like) – AnalogBalance tag vector. M_forward_matrix_1 (array_like) – ForwardMatrix1 tag matrix. M_forward_matrix_2 (array_like) – ForwardMatrix2 tag matrix. chromatic_adaptation_transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild’, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform.
Returns:	Camera Space to CIE XYZ matrix.
Return type:	ndarray

Notes

The reference illuminant is D50 as defined per ADOBE_DNG_XYZ_ILLUMINANT attribute.

References

[6]	Adobe Systems. (2012). Camera to XYZ (D50) Transform. In Digital Negative (DNG) Specification (p. 81).

Examples

>>> M_color_matrix_1 = np.array([
...     [0.5309, -0.0229, -0.0336],
...     [-0.6241, 1.3265, 0.3337],
...     [-0.0817, 0.1215, 0.6664]])
>>> M_color_matrix_2 = np.array([
...     [0.4716, 0.0603, -0.0830],
...     [-0.7798, 1.5474, 0.2480],
...     [-0.1496, 0.1937, 0.6651]])
>>> M_camera_calibration_1 = np.identity(3)
>>> M_camera_calibration_2 = np.identity(3)
>>> analog_balance = np.ones(3)
>>> M_forward_matrix_1 = np.array([
...     [0.8924, -0.1041, 0.1760],
...     [0.4351, 0.6621, -0.0972],
...     [0.0505, -0.1562, 0.9308]])
>>> M_forward_matrix_2 = np.array([
...     [0.8924, -0.1041, 0.1760],
...     [0.4351, 0.6621, -0.0972],
...     [0.0505, -0.1562, 0.9308]])
>>> camera_space_to_XYZ_matrix(  # doctest: +ELLIPSIS
...     np.array([0.32816244, 0.34698169]),
...     2850,
...     6500,
...     M_color_matrix_1,
...     M_color_matrix_2,
...     M_camera_calibration_1,
...     M_camera_calibration_2,
...     analog_balance,
...     M_forward_matrix_1,
...     M_forward_matrix_2)
array([[ 2.1604087..., -0.1041...    ,  0.2722498...],
       [ 1.0533324...,  0.6621...    , -0.1503561...],
       [ 0.1222553..., -0.1562...    ,  1.4398304...]])

colour_hdri.camera_space_to_RGB(RGB, M_XYZ_to_camera_space, RGB_to_XYZ_matrix)[source]¶

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])
>>> M_XYZ_to_camera_space = 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,
...     M_XYZ_to_camera_space,
...     RGB_to_XYZ_matrix)  # doctest: +ELLIPSIS
array([ 0.7564180...,  0.8683192...,  0.6044589...])

colour_hdri.camera_space_to_sRGB(RGB, M_XYZ_to_camera_space)[source]¶

Converts given RGB array from camera space to sRGB colourspace.

Parameters:	RGB (array_like) – Camera space RGB colourspace array. M_XYZ_to_camera_space (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])
>>> M_XYZ_to_camera_space = 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, M_XYZ_to_camera_space)  # doctest: +ELLIPSIS
array([ 0.7564350...,  0.8683155...,  0.6044706...])

colour_hdri.convert_raw_files_to_dng_files(raw_files, output_directory)[source]¶

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)[source]¶

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.read_dng_files_exif_tags(dng_files, exif_tags_binding=<Mock name='mock.CaseInsensitiveMapping()' id='139671434648320'>)[source]¶

Reads given dng files exif tags using given binding.

Parameters:	dng_files (array_like) – dng files to read the exif tags from. exif_tags_binding (dict_like) – Exif tags binding.
Returns:	dng files exif tags.
Return type:	list

colour_hdri.highlights_recovery_blend(RGB, multipliers, threshold=0.99)[source]¶

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 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.highlights_recovery_LCHab(RGB, threshold=None, RGB_colourspace=<Mock name='mock.sRGB_COLOURSPACE' id='139671442522744'>)[source]¶

Performs highlights recovery in CIE LCHab colourspace.

Parameters:	RGB (array_like) – RGB colourspace array. threshold (numeric, optional) – Threshold for highlights selection, automatically computed if not given. RGB_colourspace (RGB_Colourspace, optional) – Working RGB colourspace to perform the CIE LCHab to and from.
Returns:	Highlights recovered RGB colourspace array.
Return type:	ndarray

colour_hdri.tonemapping_operator_simple(RGB)[source]¶

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]]]))  # doctest: +ELLIPSIS
array([[[ 0.3245382...,  0.2601156...,  0.1911532...],
        [ 0.5830618...,  0.3567839...,  0.2808993...]],
<BLANKLINE>
       [[ 0.8150290...,  0.6831692...,  0.5733340...],
        [ 0.8683127...,  0.7746486...,  0.6893211...]]])

colour_hdri.tonemapping_operator_normalisation(RGB, colourspace=None)[source]¶

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]]]))  # doctest: +ELLIPSIS
array([[[ 0.1194997...,  0.0874388...,  0.0587783...],
        [ 0.3478122...,  0.1379590...,  0.0971544...]],
<BLANKLINE>
       [[ 1.0959009...,  0.5362936...,  0.3342115...],
        [ 1.6399638...,  0.8549608...,  0.5518382...]]])

colour_hdri.tonemapping_operator_gamma(RGB, gamma=1, EV=0)[source]¶

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)  # doctest: +ELLIPSIS
array([[[ 0.0600585...,  0.0439453...,  0.0295410...],
        [ 0.1748046...,  0.0693359...,  0.0488282...]],
<BLANKLINE>
       [[ 0.5507817...,  0.2695323...,  0.1679692...],
        [ 0.8242187...,  0.4296892...,  0.2773447...]]])

colour_hdri.tonemapping_operator_logarithmic(RGB, q=1, k=1, colourspace=None)[source]¶

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)  # doctest: +ELLIPSIS
array([[[ 0.0884587...,  0.0647259...,  0.0435102...],
        [ 0.2278222...,  0.0903652...,  0.0636376...]],
<BLANKLINE>
       [[ 0.4717487...,  0.2308565...,  0.1438669...],
        [ 0.5727396...,  0.2985858...,  0.1927235...]]])

colour_hdri.tonemapping_operator_exponential(RGB, q=1, k=1, colourspace=None)[source]¶

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)  # doctest: +ELLIPSIS
array([[[ 0.0148082...,  0.0108353...,  0.0072837...],
        [ 0.0428669...,  0.0170031...,  0.0119740...]],
<BLANKLINE>
       [[ 0.1312736...,  0.0642404...,  0.0400338...],
        [ 0.1921684...,  0.1001830...,  0.0646635...]]])

colour_hdri.tonemapping_operator_logarithmic_mapping(RGB, p=1, q=1, colourspace=None)[source]¶

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]]]))  # doctest: +ELLIPSIS
array([[[ 0.2532899...,  0.1853341...,  0.1245857...],
        [ 0.6523387...,  0.2587489...,  0.1822179...]],
<BLANKLINE>
       [[ 1.3507897...,  0.6610269...,  0.4119437...],
        [ 1.6399638...,  0.8549608...,  0.5518382...]]])

colour_hdri.tonemapping_operator_exponentiation_mapping(RGB, p=1, q=1, colourspace=None)[source]¶

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]]]))  # doctest: +ELLIPSIS
array([[[ 0.1194997...,  0.0874388...,  0.0587783...],
        [ 0.3478122...,  0.1379590...,  0.0971544...]],
<BLANKLINE>
       [[ 1.0959009...,  0.5362936...,  0.3342115...],
        [ 1.6399638...,  0.8549608...,  0.5518382...]]])

colour_hdri.tonemapping_operator_Schlick1994(RGB, p=1, colourspace=None)[source]¶

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]]]))  # doctest: +ELLIPSIS
array([[[ 0.1194997...,  0.0874388...,  0.0587783...],
        [ 0.3478122...,  0.1379590...,  0.0971544...]],
<BLANKLINE>
       [[ 1.0959009...,  0.5362936...,  0.3342115...],
        [ 1.6399638...,  0.8549608...,  0.5518382...]]])

colour_hdri.tonemapping_operator_Tumblin1999(RGB, L_da=20, C_max=100, L_max=100, colourspace=None)[source]¶

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]]]))  # doctest: +ELLIPSIS
array([[[ 0.0400492...,  0.0293043...,  0.0196990...],
        [ 0.1019768...,  0.0404489...,  0.0284852...]],
<BLANKLINE>
       [[ 0.2490212...,  0.1218618...,  0.0759427...],
        [ 0.3408366...,  0.1776880...,  0.1146895...]]])

colour_hdri.tonemapping_operator_Reinhard2004(RGB, f=0, m=0.3, a=0, c=0, colourspace=None)[source]¶

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)  # doctest: +ELLIPSIS
array([[[ 0.0216792...,  0.0159556...,  0.0107821...],
        [ 0.0605894...,  0.0249445...,  0.0176972...]],
<BLANKLINE>
       [[ 0.1688972...,  0.0904532...,  0.0583584...],
        [ 0.2331935...,  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)[source]¶

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]]]))  # doctest: +ELLIPSIS
array([[[ 0.4507954...,  0.3619673...,  0.2617269...],
        [ 0.7567191...,  0.4933310...,  0.3911730...]],
<BLANKLINE>
       [[ 0.9725554...,  0.8557374...,  0.7465713...],
        [ 1.0158782...,  0.9382937...,  0.8615161...]]])