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.

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.1.1 Examples

Various usage examples are available from the examples directory.

1.2 User Guide

User Guide

The user guide provides an overview of Colour - HDRI and explains important concepts and features, details can be found in the API Reference.

Installation Guide

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:

• python >= 3.8, < 4

• colour-science

• recordclass

Optional Features Dependencies

• colour-demosaicing

• Adobe DNG Converter

• dcraw

• ExifTool

• rawpy

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 overall development dependencies are installed as follows:

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

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 (visited on 2015-03-15).

Hab10b

John Habble. Uncharted 2: hdr lighting. 2010. URL: http://www.slideshare.net/ozlael/hable-john-uncharted2-hdr-lighting (visited on 2015-03-15).

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 (visited on 2016-10-29).

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 (visited on 2015-11-14).

Wikipediab

Wikipedia. Tonemapping - purpose and methods. URL: http://en.wikipedia.org/wiki/Tone_mapping\#Purpose_and_methods (visited on 2015-03-15).

Indirect References

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

• [AdobeSystems15b]

• [AdobeSystems15c]

1.3 API Reference

API Reference

Colour - HDRI

Camera Calibration

Absolute Luminance - Lagarde (2016)

colour_hdri

absolute_luminance_calibration_Lagarde2016(...)	Perform absolute Luminance calibration of given RGB panoramic image using Lagarde (2016) method.
upper_hemisphere_illuminance_weights_Lagarde2016(...)	Compute 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(...[, ...])	Return the camera response functions for given image stack using Debevec (1997) method.

Exposure Computation

Common

colour_hdri

average_luminance(N, t, S[, k])	Compute 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])	Compute 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])	Compute 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])	Compute 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)	Adjust given array exposure using given \(EV\) exposure value.

Digital Still Camera Exposure

colour_hdri

focal_plane_exposure(L, A, t, F, i, H_f[, ...])	Compute the focal plane exposure \(H\) in lux-seconds (\(lx.s\)).
arithmetic_mean_focal_plane_exposure(L_a, A, t)	Compute 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, ...)	Compute the Saturation-Based Speed (SBS) focal plane exposure \(H_{SBS}\) in lux-seconds (\(lx.s\)).
exposure_index_values(H_a)	Compute the exposure index values \(I_{EI}\) from given focal plane exposure \(H_a\).
exposure_value_100(N, t, S)	Compute 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)	Convert 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

colour_hdri

image_stack_to_radiance_image(image_stack[, ...])

Generate a HDRI / radiance image from given image stack.

Weighting Functions

colour_hdri

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

Colour Models

Adobe DNG SDK

colour_hdri

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

RGB Models

colour_hdri

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

Plotting

HDRI / Radiance Image

colour_hdri.plotting

plot_radiance_image_strip(image[, count, ...])

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

Tonemapping Operators

colour_hdri.plotting

plot_tonemapping_operator_image(image, ...)

Plot given tonemapped image with superimposed luminance mapping function.

Image Processing

Adobe DNG SDK

Raw Files

colour_hdri

convert_raw_files_to_dng_files(raw_files, ...)	Convert 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(...)	Convert 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[, ...])	Read given dng files exif tags using given binding.

Highlights Recovery

Clipped Highlights Recovery

colour_hdri

highlights_recovery_blend(RGB, multipliers)	Perform highlights recovery using Coffin (1997) method from dcraw.
highlights_recovery_LCHab(RGB[, threshold, ...])	Perform 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])

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

Tonemapping Operators

Global

Simple

colour_hdri

tonemapping_operator_simple(RGB)

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

Normalisation

colour_hdri

tonemapping_operator_normalisation(RGB[, ...])

Perform given RGB array tonemapping using the normalisation method.

Gamma

colour_hdri

tonemapping_operator_gamma(RGB[, gamma, EV])

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

Logarithmic

colour_hdri

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

Logarithmic Mapping

colour_hdri

tonemapping_operator_logarithmic_mapping(RGB)

Perform given RGB array tonemapping using the logarithmic mapping method.

Exponential

colour_hdri

tonemapping_operator_exponential(RGB[, q, ...])

Perform given RGB array tonemapping using the exponential method.

Exponentiation Mapping

colour_hdri

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

Schlick (1994)

colour_hdri

tonemapping_operator_Schlick1994(RGB[, p, ...])

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

Tumblin, Hodgins and Guenter (1999)

colour_hdri

tonemapping_operator_Tumblin1999(RGB[, ...])

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

Reinhard and Devlin (2004)

colour_hdri

tonemapping_operator_Reinhard2004(RGB[, f, ...])

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

Habble (2010) - Filmic

colour_hdri

tonemapping_operator_filmic(RGB[, ...])

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

Utilities

Common

colour_hdri

vivification()	Implement supports for vivification of the underlying dict like data-structure, magical!
vivified_to_dict(vivified)	Convert given vivified data-structure to dictionary.
path_exists(path)	Return whether given path exists.
filter_files(directory, extensions)	Filter 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)	EXIF tag data.
parse_exif_string(exif_tag)	Parse given EXIF tag assuming it is a string and return its value.
parse_exif_number(exif_tag[, dtype])	Parse given EXIF tag assuming it is a number type and return its value.
parse_exif_fraction(exif_tag[, dtype])	Parse given EXIF tag assuming it is a fraction and return its value.
parse_exif_array(exif_tag[, dtype, shape])	Parse given EXIF tag assuming it is an array and return its value.
parse_exif_data(data)	Parse given EXIF data output from exiftool.
read_exif_tags(image)	Return given image EXIF image tags.
copy_exif_tags(source, target)	Copy given source image file EXIF tag to given image target.
update_exif_tags(images)	Update given images pairs EXIF tags.
delete_exif_tags(image)	Delete all given image EXIF tags.
read_exif_tag(image, tag)	Return given image EXIF tag value.
write_exif_tag(image, tag, value)	Set given image EXIF tag value.

Image Data & Metadata Utilities

colour_hdri

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

Indices and tables

• Index

• Search Page

1.4 See Also

1.4.1 Publications

• Advanced High Dynamic Range Imaging: Theory and Practice by Banterle, F. et al.

Advanced High Dynamic Range Imaging: Theory and Practice was used as a reference for some of the algorithms of Colour - HDRI.

1.4.2 Software

C/C++

• OpenCV by Bradski, G.

• Piccante by Banterle, F. and Benedetti, L.,

Piccante was used to verify the Grossberg (2003) Histogram Based Image Sampling.

Matlab

• HDR Toolbox by Banterle, F. et al.

1.5 Code of Conduct

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

1.6 Contact & Social

The Colour Developers can be reached via different means:

• Email

• Discourse

• Facebook

• Github Discussions

• Gitter

• Twitter

1.7 About

Colour - HDRI by Colour Developers

Copyright 2015 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