# colour_hdri.utilities Package

## Sub-Modules

- colour_hdri.utilities.common Module
  - Common Utilities
- colour_hdri.utilities.exif Module
  - EXIF Manipulation
- colour_hdri.utilities.exposure Module
  - Image Exposure Value Computation
- colour_hdri.utilities.image Module
  - Image Data & Metadata Utilities

## Module Contents

`colour_hdri.utilities.``vivification`()

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

`colour_hdri.utilities.``vivified_to_dict`(vivified)

  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.utilities.``path_exists`(path)

  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.utilities.``filter_files`(directory, extensions)

  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.utilities.``ExifTag`

  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.

`colour_hdri.utilities.``parse_exif_string`(exif_tag)

  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.utilities.``parse_exif_numeric`(exif_tag, dtype=<type 'numpy.float64'>)

  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.utilities.``parse_exif_fraction`(exif_tag, dtype=<type 'numpy.float64'>)

  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.utilities.``parse_exif_array`(exif_tag, dtype=<type 'numpy.float64'>, shape=None)

  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.utilities.``parse_exif_data`(data)

  Parses given exif data output from exiftool.

  Parameters: | data (unicode) – Exif data.
  Returns: | Parsed exif data.
  Return type: | list

`colour_hdri.utilities.``read_exif_tags`(image)

  Returns given image exif image tags.

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

`colour_hdri.utilities.``copy_exif_tags`(source, target)

  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.utilities.``update_exif_tags`(images)

  Updates given images siblings images pairs exif tags.

  Parameters: | images (list) – Image files to update.
  Returns: | Definition success.
  Return type: | bool

`colour_hdri.utilities.``delete_exif_tags`(image)

  Deletes all given image exif tags.

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

`colour_hdri.utilities.``read_exif_tag`(image, tag)

  Returns given image exif tag value.

  Parameters: | image (unicode) – Image file. tag (unicode) – Tag.
  Returns: | Tag value.
  Return type: | unicode

`colour_hdri.utilities.``write_exif_tag`(image, tag, value)

  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.utilities.``exposure_value`(f_number, exposure_time, iso)

  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.utilities.``adjust_exposure`(a, EV)

  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.utilities.``average_luminance`(f_number, exposure_time, iso, k=12.5)

  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.utilities.``Metadata`

  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.utilities.``Image`(path=None, data=None, metadata=None)

  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`()
  `read_metadata`()
  `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)

    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`()

    Reads image relevant exif metadata at `Image.path` attribute.

    Returns: | Image relevant exif metadata.
    Return type: | Metadata

class `colour_hdri.utilities.``ImageStack`

  Bases: `_abcoll.MutableSequence`

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

  `ImageStack`()
  `__init__`()
  `__getitem__`()
  `__setitem__`()
  `__delitem__`()
  `__len__`()
  `__getattr__`()
  `__setattr__`()
  `sort`()
  `insert`()
  `from_files`()
  `__delitem__`(index)

    Reimplements the `MutableSequence.__delitem__()` method.

    Parameters: | index (int) – Item index.

  `__getattr__`(attribute)

    Reimplements the `MutableSequence.__getattr__()` method.

    Parameters: | attribute (unicode) – Attribute to retrieve the value.
    Returns: | Attribute value.
    Return type: | object

  `__getitem__`(index)

    Reimplements the `MutableSequence.__getitem__()` method.

    Parameters: | index (int) – Item index.
    Returns: | Item at given index.
    Return type: | Image

  `__len__`()

    Reimplements the `MutableSequence.__len__()` method.

  `__setattr__`(attribute, value)

    Reimplements the `MutableSequence.__getattr__()` method.

    Parameters: | attribute (unicode) – Attribute to set the value. value (object) – Value to set.

  `__setitem__`(index, value)

    Reimplements the `MutableSequence.__setitem__()` method.

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

  static `from_files`(image_files, decoding_cctf=None)

    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)

    Reimplements the `MutableSequence.insert()` method.

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

  `sort`(key=None)

    Sorts the underlying data structure.

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