colour_hdri.utilities Package — Colour - HDRI 0.1.0 documentation

# 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.` `linear_conversion`(a, old_range, new_range)

  Performs a simple linear conversion of given array between the old and new ranges.

  Parameters: | a (array_like) – Array to perform the linear conversion onto. old_range (array_like) – Old range. new_range (array_like) – New range.
  Returns: |
  Return type: | ndarray

  Examples

      >>> a = np.linspace(0, 1, 10)
      >>> linear_conversion(a, np.array([0, 1]), np.array([1, 10]))
      array([  1.,   2.,   3.,   4.,   5.,   6.,   7.,   8.,   9.,  10.])

`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

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

    Reads image pixel data at `Image.path` attribute.

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

    Returns a `ImageStack` instance with given image files.

    Parameters: | image_files (array_like) – Image files.
    Returns: |
    Return type: | ImageStack

  `insert`(index, value)

    Reimplements the `MutableSequence.insert()` method.

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