Colour - HDRI

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

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

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

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
  • Raw Processing Helpers

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.

Primary Dependencies

Colour - HDRI requires various dependencies in order to run:

Pypi

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

pip install colour-hdri

The optional features dependencies are installed as follows:

pip install 'colour-hdri[optional]'

The figures plotting dependencies are installed as follows:

pip install 'colour-hdri[plotting]'

The tests suite dependencies are installed as follows:

pip install 'colour-hdri[tests]'

The documentation building dependencies are installed as follows:

pip install 'colour-hdri[docs]'

The overall development dependencies are installed as follows:

pip install 'colour-hdri[development]'

Usage

API

The main reference for Colour - HDRI is the manual:

Colour - HDRI Manual

Reference
Colour - HDRI
Camera Calibration
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.
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.
HDRI / Radiance Image Generation
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

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.
Image Processing
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

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 L*C*Hab colourspace.
Image Sampling
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
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

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 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 Exposure Value Computation

colour_hdri

exposure_value(f_number, exposure_time, iso) Computes the average illuminance in \(Lux\) from given image F-Number \(N\), Exposure Time \(t\) and ISO speed \(S\) and reflected light calibration constant \(k\).
adjust_exposure(a, EV) Adjusts given array exposure using given \(EV\) exposure value.
average_luminance(f_number, exposure_time, iso) Computes the average luminance in \(cd\cdot m^{-2}\) from given image F-Number \(N\), Exposure Time \(t\), ISO speed \(S\) and reflected light calibration constant \(k\).
Image Data & Metadata Utilities

colour_hdri

Metadata 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-1568817194.
[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/$\sim$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, number August, 369–378. New York, New York, USA, 1997. ACM Press. URL: http://portal.acm.org/citation.cfm?doid=258734.258884, 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. URL: http://ieeexplore.ieee.org/document/1240119/, 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.
[McG12]Sandy McGuffog. Hue Twists in DNG Camera Profiles. 2012. URL: http://dcptool.sourceforge.net/Hue Twists.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. URL: http://ieeexplore.ieee.org/document/1359728/, 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. URL: http://portal.acm.org/citation.cfm?doid=300776.300783, doi:10.1145/300776.300783.
[VD09]Kuntee Viriyothai and Paul Debevec. Variance minimization light probe sampling. In SIGGRAPH ‘09: Posters on - SIGGRAPH ‘09, number Egsr, 1–1. New York, New York, USA, 2009. ACM Press. URL: http://dl.acm.org/citation.cfm?id=1599393, doi:10.1145/1599301.1599393.
[Wika]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.
[Wikb]Wikipedia. Tonemapping - Purpose and methods. URL: http://en.wikipedia.org/wiki/Tone_mapping#Purpose_and_methods.
[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 - 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.
[AdobeSystems15b]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.
[AdobeSystems15c]Adobe Systems. Adobe DNG SDK 1.4. 2015. URL: http://download.adobe.com/pub/adobe/dng/dng_sdk_1_4.zip.

Indirect References

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

Examples

Various usage examples are available from the examples directory.

Contributing

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

Bibliography

The bibliography is available in the repository in BibTeX format.

About

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