1 Colour - HDRI#

A Python package implementing various HDRI processing algorithms.

It is open source and freely available under the BSD-3-Clause terms.

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

1.1 Features#

The following features are available:

  • HDRI 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

  • Vignette Characterisation & Correction

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:

Optional Features Dependencies#
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.

[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. doi:10.1145/258734.258884.

[GN03]

Michael D. Grossberg and Shree K. Nayar. Determining the camera response from images: What is knowable? IEEE Transactions on Pattern Analysis and Machine Intelligence, 25(11):1455–1467, 2003. doi:10.1109/TPAMI.2003.1240119.

[Hab10a]

John Habble. Filmic Tonemapping Operators. http://filmicgames.com/archives/75, 2010.

[Hab10b]

John Habble. Uncharted 2: HDR Lighting. http://www.slideshare.net/ozlael/hable-john-uncharted2-hdr-lighting, 2010.

[KPB16]

Andrzej Kordecki, Henryk Palus, and Artur Bal. Practical vignetting correction method for digital camera with measurement of surface luminance distribution. Signal, Image and Video Processing, 10(8):1417–1424, November 2016. doi:10.1007/s11760-016-0941-2.

[LLJ16]

Sebastien Lagarde, Sebastien Lachambre, and Cyril Jover. An Artist-Friendly Workflow for Panoramic HDRI. 2016.

[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. http://dcptool.sourceforge.net/Hue%20Twists.html, 2012.

[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, number Egsr, 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.

[AdobeSystems15b]

Adobe Systems. Adobe DNG SDK 1.4 - dng_sdk_1_4/dng_sdk/source/dng_camera_profile.cpp - dng_camera_profile::IlluminantToTemperature. 2015.

[AdobeSystems15c]

Adobe Systems. Adobe DNG SDK 1.4 - dng_sdk_1_4/dng_sdk/source/dng_tag_values.h - LightSource tag. 2015.

[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. Tonemapping - Purpose and methods. http://en.wikipedia.org/wiki/Tone_mapping#Purpose_and_methods.

[Wikipediab]

Wikipedia. EV as a measure of luminance and illuminance. https://en.wikipedia.org/wiki/Exposure_value#EV_as_a_measure_of_luminance_and_illuminance.

[WonpilYu04]

Wonpil Yu. Practical anti-vignetting methods for digital cameras. IEEE Transactions on Consumer Electronics, 50(4):975–983, November 2004. doi:10.1109/TCE.2004.1362487.

Indirect References#

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

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 Generation#
Generation#

colour_hdri

image_stack_to_HDRI(image_stack[, ...])

Generate a HDRI 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.

matrix_XYZ_to_camera_space(xy, ...)

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

matrix_camera_space_to_XYZ(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#

colour_hdri.plotting

plot_HDRI_strip(image[, count, ev_steps, ...])

Plot given HDRI 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, typically Dave Coffin's dcraw.

RAW_CONVERTER_ARGUMENTS_BAYER_CFA

Arguments for the command line raw conversion application for non demosaiced linear tiff file format output.

RAW_CONVERTER_ARGUMENTS_DEMOSAICING

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

Command line DNG conversion application, typically Adobe DNG Converter.

DNG_CONVERTER_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 Generation.

Image([path, data, metadata])

Define the base object for storing an image along its path, pixel data and metadata needed for HDRIs generation.

ImageStack()

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

Indices and tables#

1.4 See Also#

1.4.1 Publications#

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++

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

Matlab

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:

1.7 About#

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