1 Colour - HDRI¶

A Python package implementing various HDRI / Radiance image processing algorithms.

It is open source and freely available under the New BSD License terms.

https://raw.githubusercontent.com/colour-science/colour-hdri/master/docs/_static/Radiance_001.png

Table of Contents

1 Colour - HDRI

1.1 Features¶

The following features are available:

HDRI / Radiance Image Generation
Debevec (1997) Camera Response Function Computation
Grossberg (2003) Histogram Based Image Sampling
Variance Minimization Light Probe Sampling
Global Tonemapping Operators
Adobe DNG SDK Colour Processing
Absolute Luminance Calibration
Digital Still Camera (DSC) Exposure Model
Raw Processing Helpers

1.2 Installation¶

Because of their size, the resources dependencies needed to run the various examples and unit tests are not provided within the Pypi package. They are separately available as Git Submodules when cloning the repository.

1.2.1 Primary Dependencies¶

Colour - HDRI requires various dependencies in order to run:

1.2.2 Optional Features Dependencies¶

1.2.3 Pypi¶

Once the dependencies are satisfied, Colour - HDRI can be installed from the Python Package Index by issuing this command in a shell:

pip install --user colour-hdri

The optional features dependencies are installed as follows:

pip install --user 'colour-hdri[optional]'

The figures plotting dependencies are installed as follows:

pip install --user 'colour-hdri[plotting]'

The tests suite dependencies are installed as follows:

pip install --user 'colour-hdri[tests]'

The documentation building dependencies are installed as follows:

pip install --user 'colour-hdri[docs]'

The overall development dependencies are installed as follows:

pip install --user 'colour-hdri[development]'

1.3 Usage¶

1.3.1 API¶

The main reference for Colour - HDRI is the manual:

Colour - HDRI Manual¶

Reference¶

Colour - HDRI¶

Camera Calibration¶

Absolute Luminance - Lagarde (2016)
Debevec (1997)

Absolute Luminance - Lagarde (2016)¶

colour_hdri

`absolute_luminance_calibration_Lagarde2016`(…)	Performs absolute Luminance calibration of given RGB panoramic image using Lagarde (2016) method.
`upper_hemisphere_illuminance_weights_Lagarde2016`(…)	Computes upper hemisphere illuminance weights for use with applications unable to perform the computation directly, i.e. Adobe Photoshop.

Debevec (1997)¶

colour_hdri

`g_solve`(Z, B[, l_s, w, n])	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.
`camera_response_functions_Debevec1997`(…[, …])	Returns the camera response functions for given image stack using Debevec (1997) method.

Exposure Computation¶

Common
Digital Still Camera Exposure

Common ¶

colour_hdri

`average_luminance`(N, t, S[, k])	Computes the average luminance \(L\) in \(cd\cdot m^{-2}\) from given relative aperture F-Number \(N\), Exposure Time \(t\), ISO arithmetic speed \(S\) and reflected light calibration constant \(k\).
`average_illuminance`(N, t, S[, c])	Computes the average illuminance \(E\) in \(Lux\) from given relative aperture F-Number \(N\), Exposure Time \(t\), ISO arithmetic speed \(S\) and incident light calibration constant \(c\).
`luminance_to_exposure_value`(L, S[, k])	Computes the exposure value \(EV\) from given scene luminance \(L\) in \(cd\cdot m^{-2}\), ISO arithmetic speed \(S\) and reflected light calibration constant \(k\).
`illuminance_to_exposure_value`(E, S[, c])	Computes the exposure value \(EV\) from given scene illuminance \(E\) in \(Lux\), ISO arithmetic speed \(S\) and incident light calibration constant \(c\).
`adjust_exposure`(a, EV)	Adjusts given array exposure using given \(EV\) exposure value.

Digital Still Camera Exposure ¶

colour_hdri

`focal_plane_exposure`(L, A, t, F, i, H_f[, …])	Computes the focal plane exposure \(H\) in lux-seconds (\(lx.s\)).
`arithmetic_mean_focal_plane_exposure`(L_a, A, t)	Computes the arithmetic mean focal plane exposure \(H_a\) for a camera focused on infinity, \(H_f << H\), \(T=9/10\), \(\theta =10^{\circ}\) and \(f_v=98/100\).
`saturation_based_speed_focal_plane_exposure`(L, …)	Computes the Saturation-Based Speed (SBS) focal plane exposure \(H_{SBS}\) in lux-seconds (\(lx.s\)).
`exposure_index_values`(H_a)	Computes the exposure index values \(I_{EI}\) from given focal plane exposure \(H_a\).
`exposure_value_100`(N, t, S)	Computes the exposure value \(EV100\) from given relative aperture F-Number \(N\), Exposure Time \(t\) and ISO arithmetic speed \(S\).
`photometric_exposure_scale_factor_Lagarde2014`(EV100)	Converts the exposure value \(EV100\) to photometric exposure scale factor using Lagarde and de Rousiers (2014) formulation derived from the ISO 12232:2006 Saturation Based Sensitivity (SBS) recommendation.

HDRI / Radiance Image Generation¶

Generation
Weighting Functions

Generation ¶

colour_hdri

image_stack_to_radiance_image(image_stack[, …])

Generates a HDRI / radiance image from given image stack.

Weighting Functions ¶

colour_hdri

`normal_distribution_function`(a[, mu, sigma])	Returns given array weighted by a normal distribution function.
`hat_function`(a)	Returns given array weighted by a hat function.
`weighting_function_Debevec1997`(a[, …])	Returns given array weighted by Debevec (1997) function.

Colour Models¶

Adobe DNG SDK
RGB Models

Adobe DNG SDK ¶

colour_hdri

`xy_to_camera_neutral`(xy, …)	Converts given xy white balance chromaticity coordinates to Camera Neutral coordinates.
`camera_neutral_to_xy`(camera_neutral, …[, …])	Converts given Camera Neutral coordinates to xy white balance chromaticity coordinates.
`XYZ_to_camera_space_matrix`(xy, …)	Returns the CIE XYZ to Camera Space matrix for given xy white balance chromaticity coordinates.
`camera_space_to_XYZ_matrix`(xy, …[, …])	Returns the Camera Space to CIE XYZ matrix for given xy white balance chromaticity coordinates.

RGB Models ¶

colour_hdri

`camera_space_to_RGB`(RGB, …)	Converts given RGB array from camera space to given RGB colourspace.
`camera_space_to_sRGB`(RGB, M_XYZ_to_camera_space)	Converts given RGB array from camera space to sRGB colourspace.

Plotting¶

HDRI / Radiance Image
Tonemapping Operators

HDRI / Radiance Image ¶

colour_hdri.plotting

plot_radiance_image_strip(image[, count, …])

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

Tonemapping Operators ¶

colour_hdri.plotting

plot_tonemapping_operator_image(image, …)

Plots given tonemapped image with superimposed luminance mapping function.

Image Processing¶

Adobe DNG SDK
- Raw Files
- DNG Files

Adobe DNG SDK ¶

Raw Files ¶

colour_hdri

`convert_raw_files_to_dng_files`(raw_files, …)	Converts given raw files to dng files using given output directory.
`RAW_CONVERTER`	Command line raw conversion application, usually Dave Coffin’s dcraw.
`RAW_CONVERSION_ARGUMENTS`	Arguments for the command line raw conversion application for non demosaiced linear tiff file format output.
`RAW_D_CONVERSION_ARGUMENTS`	Arguments for the command line raw conversion application for demosaiced linear tiff file format output.

DNG Files ¶

colour_hdri

`convert_dng_files_to_intermediate_files`(…)	Converts given dng files to intermediate tiff files using given output directory.
`DNG_CONVERTER`
`DNG_CONVERSION_ARGUMENTS`	Arguments for the command line dng conversion application.
`DNG_EXIF_TAGS_BINDING`	Exif tags binding for a dng file.
`read_dng_files_exif_tags`(dng_files[, …])	Reads given dng files exif tags using given binding.

Highlights Recovery¶

Clipped Highlights Recovery

Clipped Highlights Recovery ¶

colour_hdri

`highlights_recovery_blend`(RGB, multipliers)	Performs highlights recovery using Coffin (1997) method from dcraw.
`highlights_recovery_LCHab`(RGB[, threshold, …])	Performs highlights recovery in CIE LCHab colourspace.

Image Sampling¶

Viriyothai (2009)
Grossberg (2013)

Viriyothai (2009)¶

colour_hdri

light_probe_sampling_variance_minimization_Viriyothai2009(…)

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

Grossberg (2013)¶

colour_hdri

samples_Grossberg2003(image_stack[, samples, n])

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

Tonemapping Operators¶

Global

Global ¶

Simple ¶

colour_hdri

tonemapping_operator_simple(RGB)

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

Normalisation ¶

colour_hdri

tonemapping_operator_normalisation(RGB[, …])

Performs given RGB array tonemapping using the normalisation method.

Gamma ¶

colour_hdri

tonemapping_operator_gamma(RGB[, gamma, EV])

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

Logarithmic ¶

colour_hdri

`tonemapping_operator_logarithmic`(RGB[, q, …])	Performs given RGB array tonemapping using the logarithmic method.
`tonemapping_operator_exponential`(RGB[, q, …])	Performs given RGB array tonemapping using the exponential method.
`tonemapping_operator_logarithmic_mapping`(RGB)	Performs given RGB array tonemapping using the logarithmic mapping method.
`tonemapping_operator_exponentiation_mapping`(RGB)	Performs given RGB array tonemapping using the exponentiation mapping method.
`tonemapping_operator_Schlick1994`(RGB[, p, …])	Performs given RGB array tonemapping using Schlick (1994) method.
`tonemapping_operator_Tumblin1999`(RGB[, …])	Performs given RGB array tonemapping using Tumblin, Hodgins and Guenter (1999) method.
`tonemapping_operator_Reinhard2004`(RGB[, f, …])	Performs given RGB array tonemapping using Reinhard and Devlin (2004) method.
`tonemapping_operator_filmic`(RGB[, …])	Performs given RGB array tonemapping using Habble (2010) method.

Logarithmic Mapping ¶

colour_hdri

tonemapping_operator_logarithmic_mapping(RGB)

Performs given RGB array tonemapping using the logarithmic mapping method.

Exponential ¶

colour_hdri

tonemapping_operator_exponential(RGB[, q, …])

Performs given RGB array tonemapping using the exponential method.

Exponentiation Mapping ¶

colour_hdri

`tonemapping_operator_exponentiation_mapping`(RGB)	Performs given RGB array tonemapping using the exponentiation mapping method.
`tonemapping_operator_Schlick1994`(RGB[, p, …])	Performs given RGB array tonemapping using Schlick (1994) method.
`tonemapping_operator_Tumblin1999`(RGB[, …])	Performs given RGB array tonemapping using Tumblin, Hodgins and Guenter (1999) method.
`tonemapping_operator_Reinhard2004`(RGB[, f, …])	Performs given RGB array tonemapping using Reinhard and Devlin (2004) method.
`tonemapping_operator_filmic`(RGB[, …])	Performs given RGB array tonemapping using Habble (2010) method.

Schlick (1994)¶

colour_hdri

tonemapping_operator_Schlick1994(RGB[, p, …])

Performs given RGB array tonemapping using Schlick (1994) method.

Tumblin, Hodgins and Guenter (1999)¶

colour_hdri

tonemapping_operator_Tumblin1999(RGB[, …])

Performs given RGB array tonemapping using Tumblin, Hodgins and Guenter (1999) method.

Reinhard and Devlin (2004)¶

colour_hdri

tonemapping_operator_Reinhard2004(RGB[, f, …])

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

Habble (2010) - Filmic ¶

colour_hdri

tonemapping_operator_filmic(RGB[, …])

Performs given RGB array tonemapping using Habble (2010) method.

Utilities¶

Common
EXIF Data Manipulation
Image Data & Metadata Utilities

Common ¶

colour_hdri

`vivification`()	Implements supports for vivification of the underlying dict like data-structure, magical!
`vivified_to_dict`(vivified)	Converts given vivified data-structure to dictionary.
`path_exists`(path)	Returns if given path exists.
`filter_files`(directory, extensions)	Filters given directory for files matching given extensions.

EXIF Data Manipulation ¶

colour_hdri

`EXIF_EXECUTABLE`	Command line exif manipulation application, usually Phil Harvey’s ExifTool.
`ExifTag`([group, name, value, identifier])	Hunt colour appearance model induction factors.
`parse_exif_string`(exif_tag)	Parses given exif tag assuming it is a string and return its value.
`parse_exif_numeric`(exif_tag[, dtype])	Parses given exif tag assuming it is a numeric type and return its value.
`parse_exif_fraction`(exif_tag[, dtype])	Parses given exif tag assuming it is a fraction and return its value.
`parse_exif_array`(exif_tag[, dtype, shape])	Parses given exif tag assuming it is an array and return its value.
`parse_exif_data`(data)	Parses given exif data output from exiftool.
`read_exif_tags`(image)	Returns given image exif image tags.
`copy_exif_tags`(source, target)	Copies given source image file exif tag to given image target.
`update_exif_tags`(images)	Updates given images siblings images pairs exif tags.
`delete_exif_tags`(image)	Deletes all given image exif tags.
`read_exif_tag`(image, tag)	Returns given image exif tag value.
`write_exif_tag`(image, tag, value)	Sets given image exif tag value.

Image Data & Metadata Utilities ¶

colour_hdri

`Metadata`(f_number, exposure_time, iso[, …])	Defines the base object for storing exif metadata relevant to HDRI / radiance image generation.
`Image`([path, data, metadata])	Defines the base object for storing an image along its path, pixel data and metadata needed for HDRI / radiance images generation.
`ImageStack`()	Defines a convenient stack storing a sequence of images for HDRI / radiance images generation.

Indices and tables¶

Bibliography¶

BADC11a: Francesco Banterle, Alessandro Artusi, Kurt Debattista, and Alan Chalmers. 2.1.1 Generating HDR Content by Combining Multiple Exposures. A K Peters/CRC Press, 2011. ISBN 978-1-56881-719-4.
BADC11b: Francesco Banterle, Alessandro Artusi, Kurt Debattista, and Alan Chalmers. 3.2.1 simple mapping methods. In Advanced High Dynamic Range Imaging, pages 38–41. A K Peters/CRC Press, 2011.
BB14: Francesco Banterle and Luca Benedetti. Piccante: an open and portable library for hdr imaging. 2014.
Cof15: Dave Coffin. Dcraw. 2015. URL: https://www.cybercom.net/~dcoffin/dcraw/.
DM97: Paul E. Debevec and Jitendra Malik. Recovering high dynamic range radiance maps from photographs. In Proceedings of the 24th annual conference on Computer graphics and interactive techniques - SIGGRAPH ‘97, 369–378. New York, New York, USA, 1997. ACM Press. doi:10.1145/258734.258884.
GN03: M.D. Grossberg and S.K. Nayar. Determining the camera response from images: what is knowable? IEEE Transactions on Pattern Analysis and Machine Intelligence, 25(11):1455–1467, November 2003. doi:10.1109/TPAMI.2003.1240119.
Hab10a: John Habble. Filmic tonemapping operators. 2010. URL: http://filmicgames.com/archives/75.
Hab10b: John Habble. Uncharted 2: hdr lighting. 2010. URL: http://www.slideshare.net/ozlael/hable-john-uncharted2-hdr-lighting.
LLJ16: Sebastien Lagarde, Sebastien Lachambre, and Cyril Jover. An artist-friendly workflow for panoramic hdri. 2016. URL: http://blog.selfshadow.com/publications/s2016-shading-course/unity/s2016_pbs_unity_hdri_notes.pdf.
LdeRousiers14: Sébastian Lagarde and Charles de Rousiers. Moving frostbite to physically based rendering 3.0. Siggraph 2014, pages 119, 2014.
McG12: Sandy McGuffog. Hue twists in dng camera profiles. 2012. URL: http://dcptool.sourceforge.net/Hue\%20Twists.html.
RD05: Erik Reinhard and Kate Devlin. Dynamic range reduction inspired by photoreceptor physiology. IEEE Transactions on Visualization and Computer Graphics, 11(01):13–24, January 2005. doi:10.1109/TVCG.2005.9.
Sch94: Christophe Schlick. Quantization techniques for visualization of high dynamic range pictures. Proceedings of the Fifth Eurographics Workshop on Rendering, pages 7–18, 1994.
THG99: Jack Tumblin, Jessica K. Hodgins, and Brian K. Guenter. Two methods for display of high contrast images. ACM Transactions on Graphics, 18(1):56–94, January 1999. doi:10.1145/300776.300783.
VD09: Kuntee Viriyothai and Paul Debevec. Variance minimization light probe sampling. In SIGGRAPH ‘09: Posters on - SIGGRAPH ‘09, 1–1. New York, New York, USA, 2009. ACM Press. doi:10.1145/1599301.1599393.
AdobeSystems12a: Adobe Systems. Camera to xyz (d50) transform. In Digital Negative (DNG) Specification, pages 81. 2012.
AdobeSystems12b: Adobe Systems. Digital negative (dng) specification. 2012.
AdobeSystems12c: Adobe Systems. Translating camera neutral coordinates to white balance xy coordinates. In Digital Negative (DNG) Specification, pages 80–81. 2012.
AdobeSystems12d: Adobe Systems. Translating white balance xy coordinates to camera neutral coordinates. In Digital Negative (DNG) Specification, pages 80. 2012.
AdobeSystems15a: Adobe Systems. Adobe dng sdk 1.4. 2015. URL: http://download.adobe.com/pub/adobe/dng/dng_sdk_1_4.zip.
AdobeSystems15b: Adobe Systems. Adobe dng sdk 1.4 - dng_sdk_1_4/dng_sdk/source/dng_camera_profile.cpp - dng_camera_profile::illuminanttotemperature. 2015. URL: http://download.adobe.com/pub/adobe/dng/dng_sdk_1_4.zip.
AdobeSystems15c: Adobe Systems. Adobe dng sdk 1.4 - dng_sdk_1_4/dng_sdk/source/dng_tag_values.h - lightsource tag. 2015. URL: http://download.adobe.com/pub/adobe/dng/dng_sdk_1_4.zip.
ISO06: ISO. International standard iso12232-2006 - photography - digital still cameras - determination of exposure index, iso speed ratings, standard output sensitivity, and recommended exposure index. 2006.
Wikipediaa: Wikipedia. Ev as a measure of luminance and illuminance. URL: https://en.wikipedia.org/wiki/Exposure_value\#EV_as_a_measure_of_luminance_and_illuminance.
Wikipediab: Wikipedia. Tonemapping - purpose and methods. URL: http://en.wikipedia.org/wiki/Tone_mapping\#Purpose_and_methods.

Indirect References¶

Some extra references used in the codebase but not directly part of the public api:

1.3.2 Examples¶

Various usage examples are available from the examples directory.

1.4 Contributing¶

If you would like to contribute to Colour - HDRI, please refer to the following Contributing guide for Colour.

1.5 Bibliography¶

The bibliography is available in the repository in BibTeX format.

1.6 Code of Conduct¶

The Code of Conduct, adapted from the Contributor Covenant 1.4, is available on the Code of Conduct page.

1.7 About¶

Colour - HDRI by Colour Developers
Copyright © 2015-2020 – Colour Developers – colour-developers@colour-science.org
This software is released under terms of New BSD License: https://opensource.org/licenses/BSD-3-Clause
https://github.com/colour-science/colour-hdri