Merge branch 'release/v0.1.3'

README.rst

@@ -9,7 +9,7 @@ Colour - HDRI
     * - Status
       - |waffle| |travis| |coveralls| |scrutinizer| |landscape| |gemnasium|
     * - Package
-      - |version| |downloads|
+      - |version|
 
 .. |waffle| image:: https://badge.waffle.io/colour-science/colour-hdri.svg?label=ready&title=Ready
     :target: https://github.com/colour-science/colour-hdri/issues
@@ -32,9 +32,6 @@ Colour - HDRI
 .. |version| image:: https://badge.fury.io/py/colour-hdri.svg
     :target: https://pypi.python.org/pypi/colour-hdri
     :alt: Package Version
-.. |downloads| image:: https://img.shields.io/pypi/dm/colour-hdri.svg
-    :target: https://pypi.python.org/pypi/colour-hdri
-    :alt: Package Downloads
 
 .. end-badges
 

colour_hdri/__init__.py

@@ -71,7 +71,7 @@
 
 __major_version__ = '0'
 __minor_version__ = '1'
-__change_version__ = '2'
+__change_version__ = '3'
 __version__ = '.'.join((__major_version__,
                         __minor_version__,
                         __change_version__))

colour_hdri/examples/examples_absolute_luminance_calibration.ipynb

@@ -47,6 +47,7 @@
     "    absolute_luminance_calibration_Lagarde2016,\n",
     "    upper_hemisphere_illuminance_weights_Lagarde2016)\n",
     "\n",
+    "colour.filter_warnings(True, False)\n",
     "colour_plotting_defaults()\n",
     "\n",
     "OETF = colour.RGB_COLOURSPACES['sRGB'].encoding_cctf\n",
@@ -137,7 +138,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 2",
+   "display_name": "Python [default]",
    "language": "python",
    "name": "python2"
   },

colour_hdri/examples/examples_global_tonemapping_operators.ipynb

@@ -79,6 +79,7 @@
     "    tonemapping_operator_filmic)\n",
     "from colour_hdri.plotting import tonemapping_operator_image_plot\n",
     "\n",
+    "colour.filter_warnings(True, False)\n",
     "colour_plotting_defaults()\n",
     "\n",
     "OETF = colour.RGB_COLOURSPACES['sRGB'].encoding_cctf\n",
@@ -600,7 +601,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 2",
+   "display_name": "Python [default]",
    "language": "python",
    "name": "python2"
   },

colour_hdri/examples/examples_variance_minimization_light_probe_sampling.ipynb

@@ -51,6 +51,7 @@
     "    find_regions_variance_minimization_Viriyothai2009,\n",
     "    highlight_regions_variance_minimization)\n",
     "\n",
+    "colour.filter_warnings(True, False)\n",
     "colour_plotting_defaults()\n",
     "\n",
     "OETF = colour.sRGB_COLOURSPACE.encoding_cctf\n",
@@ -204,7 +205,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 2",
+   "display_name": "Python [default]",
    "language": "python",
    "name": "python2"
   },

colour_hdri/generation/radiance.py

@@ -26,7 +26,7 @@
 
 import numpy as np
 
-from colour import tsplit, tstack
+from colour import tsplit, tstack, warning
 
 from colour_hdri.generation import weighting_function_Debevec1997
 from colour_hdri.utilities import average_luminance
@@ -68,11 +68,18 @@ def image_stack_to_radiance_image(
     -------
     ndarray
         Radiance image.
+
+    Warning
+    -------
+    If the image stack contains images with negative or equal to zero values,
+    unpredictable results may occur and NaNs might be generated. It is
+    thus recommended to encode the images in a wider RGB colourspace or clamp
+    negative values.
     """
 
     image_c = None
     weight_c = None
-    for image in image_stack:
+    for i, image in enumerate(image_stack):
         if image_c is None:
             image_c = np.zeros(image.data.shape)
             weight_c = np.zeros(image.data.shape)
@@ -82,11 +89,28 @@ def image_stack_to_radiance_image(
             image.metadata.exposure_time,
             image.metadata.iso)
 
+        if np.any(image.data <= 0):
+            warning(
+                '"{0}" image channels contain negative or equal to zero '
+                'values, unpredictable results may occur! Please consider '
+                'encoding your images in a wider gamut RGB colourspace or '
+                'clamp negative values.'.format(image.path))
+
         if weighting_average and image.data.ndim == 3:
-            weight = weighting_function(np.average(image.data, axis=-1))
-            weight = np.rollaxis(weight[np.newaxis], 0, 3)
+            average = np.average(image.data, axis=-1)
+
+            weights = weighting_function(average)
+            weights = np.rollaxis(weights[np.newaxis], 0, 3)
+            if i == 0:
+                weights[average >= 0.5] = 1
+            if i == len(image_stack) - 1:
+                weights[average <= 0.5] = 1
         else:
-            weight = weighting_function(image.data)
+            weights = weighting_function(image.data)
+            if i == 0:
+                weights[image.data >= 0.5] = 1
+            if i == len(image_stack) - 1:
+                weights[image.data <= 0.5] = 1
 
         image_data = image.data
         if camera_response_functions is not None:
@@ -98,11 +122,10 @@ def image_stack_to_radiance_image(
             B = np.interp(B, samples, camera_response_functions[..., 2])
             image_data = tstack((R, G, B))
 
-        image_c += weight * image_data / L
-        weight_c += weight
+        image_c += weights * image_data / L
+        weight_c += weights
 
     if image_c is not None:
         image_c /= weight_c
-        image_c[np.isnan(image_c)] = 0
 
     return image_c

colour_hdri/generation/tests/tests_radiance.py

@@ -54,6 +54,7 @@ def test_radiance_image(self):
         image_stack = ImageStack.from_files(JPG_IMAGES)
         image_stack.data = RGB_COLOURSPACES['sRGB'].decoding_cctf(
             image_stack.data)
+
         np.testing.assert_almost_equal(
             image_stack_to_radiance_image(image_stack),
             np.load(os.path.join(

colour_hdri/utilities/image.py

@@ -19,13 +19,14 @@
 from collections import MutableSequence
 from recordclass import recordclass
 
-from colour import is_string, read_image, tsplit, tstack
+from colour import is_string, read_image, tsplit, tstack, warning
 
 from colour_hdri.utilities.exif import (
     parse_exif_array,
     parse_exif_fraction,
     parse_exif_numeric,
     read_exif_tags)
+from colour_hdri.utilities.exposure import average_luminance
 
 __author__ = 'Colour Developers'
 __copyright__ = 'Copyright (C) 2015-2017 - Colour Developers'
@@ -213,10 +214,16 @@ def metadata(self, value):
 
         self._metadata = value
 
-    def read_data(self):
+    def read_data(self, decoding_cctf=None):
         """
         Reads image pixel data at :attr:`Image.path` attribute.
 
+        Parameters
+        ----------
+        decoding_cctf : object, optional
+            Decoding colour component transfer function (Decoding CCTF) or
+            electro-optical transfer function (EOTF / EOCF).
+
         Returns
         -------
         ndarray
@@ -225,6 +232,8 @@ def read_data(self):
 
         LOGGER.info('Reading "{0}" image.'.format(self._path))
         self.data = read_image(str(self._path))
+        if decoding_cctf is not None:
+            self.data = decoding_cctf(self.data)
 
         return self.data
 
@@ -298,6 +307,7 @@ class ImageStack(MutableSequence):
     __len__
     __getattr__
     __setattr__
+    sort
     insert
     from_files
     """
@@ -427,15 +437,31 @@ def insert(self, index, value):
 
         self._list.insert(index, value)
 
+    def sort(self, 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.
+        """
+
+        self._list = sorted(self._list, key=key)
+
     @staticmethod
-    def from_files(image_files):
+    def from_files(image_files, decoding_cctf=None):
         """
         Returns a :class:`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
         -------
@@ -445,8 +471,26 @@ def from_files(image_files):
         image_stack = ImageStack()
         for image_file in image_files:
             image = Image(image_file)
-            image.read_data()
+            image.read_data(decoding_cctf)
             image.read_metadata()
             image_stack.append(image)
 
+        def luminance_average_key(image):
+            """
+            Comparison key function.
+            """
+
+            f_number = image.metadata.f_number
+            exposure_time = image.metadata.exposure_time
+            iso = image.metadata.iso
+
+            if None in (f_number, exposure_time, iso):
+                warning('"{0}" exposure data is missing, average luminance '
+                        'sorting is inapplicable!'.format(image.path))
+                return None
+
+            return average_luminance(f_number, exposure_time, iso)
+
+        image_stack.sort(luminance_average_key)
+
         return image_stack

colour_hdri/utilities/tests/tests_image.py

@@ -261,6 +261,15 @@ def test__setattr__(self):
 
         self.assertEqual(image_stack[0].metadata.black_level, 2048)
 
+    def test_from_files(self):
+        """
+        Tests :attr:`colour_hdri.utilities.image.ImageStack.test_from_files`
+        method.
+        """
+
+        image_stack = ImageStack().from_files(reversed(self._test_jpg_images))
+        self.assertListEqual(list(image_stack.path), self._test_jpg_images)
+
 
 if __name__ == '__main__':
     unittest.main()

docs/conf.py

@@ -83,7 +83,7 @@
 # The short X.Y version.
 version = '0.1'
 # The full version, including alpha/beta/rc tags.
-release = '0.1.2'
+release = '0.1.3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

setup.py

@@ -49,7 +49,7 @@
     INSTALLATION_REQUIREMENTS += ['mock']
 
 setup(name='colour-hdri',
-      version='0.1.2',
+      version='0.1.3',
       author=__author__,
       author_email=__email__,
       include_package_data=True,