Update various docstrings in "colour.colorimetry.luminance" module an…

…d change "colour.colorimetry.luminance_1976" definition signature.

colour/colorimetry/__init__.py

@@ -38,8 +38,8 @@
 from .luminance import luminance
 from .luminance import (
     luminance_newhall1943,
-    luminance_1976,
-    luminance_ASTM_D1535_08)
+    luminance_ASTM_D1535_08,
+    luminance_1976)
 from .transformations import RGB_10_degree_cmfs_to_LMS_10_degree_cmfs
 from .transformations import RGB_2_degree_cmfs_to_XYZ_2_degree_cmfs
 from .transformations import RGB_10_degree_cmfs_to_XYZ_10_degree_cmfs
@@ -75,8 +75,8 @@
 __all__ += ['LUMINANCE_METHODS']
 __all__ += ['luminance']
 __all__ += ['luminance_newhall1943',
-            'luminance_1976',
-            'luminance_ASTM_D1535_08']
+            'luminance_ASTM_D1535_08',
+            'luminance_1976']
 __all__ += ['RGB_10_degree_cmfs_to_LMS_10_degree_cmfs']
 __all__ += ['RGB_2_degree_cmfs_to_XYZ_2_degree_cmfs']
 __all__ += ['RGB_10_degree_cmfs_to_XYZ_10_degree_cmfs']

colour/colorimetry/luminance.py

@@ -12,10 +12,10 @@
 -   :func:`luminance_newhall1943`: *luminance* :math:`Y` computation of given
     *Munsell* value :math:`V` using *Newhall, Nickerson, and Judd (1943)*
     method.
--   :func:`luminance_1976`: *luminance* :math:`Y` computation of given
-    *Lightness* :math:`L^*` as per *CIE Lab* implementation.
 -   :func:`luminance_ASTM_D1535_08`: *luminance* :math:`Y` computation of given
     *Munsell* value :math:`V` using *ASTM D1535-08e1 (2008)* method.
+-   :func:`luminance_1976`: *luminance* :math:`Y` computation of given
+    *Lightness* :math:`L^*` as per *CIE Lab* implementation.
 
 See Also
 --------
@@ -36,16 +36,17 @@
 __status__ = 'Production'
 
 __all__ = ['luminance_newhall1943',
-           'luminance_1976',
            'luminance_ASTM_D1535_08',
+           'luminance_1976',
            'LUMINANCE_METHODS',
            'luminance']
 
 
 def luminance_newhall1943(V, **kwargs):
     """
-    Returns the *luminance* :math:`Y` of given *Munsell* value :math:`V` using
-    *Newhall, Nickerson, and Judd (1943)* method.
+    Returns the *luminance* :math:`R_Y` of given *Munsell* value :math:`V`
+    using *Sidney M. Newhall, Dorothy Nickerson, and Deane B. Judd (1943)*
+    method.
 
     Parameters
     ----------
@@ -58,41 +59,45 @@ def luminance_newhall1943(V, **kwargs):
     Returns
     -------
     numeric
-        *luminance* :math:`Y`.
+        *luminance* :math:`R_Y`.
 
     Notes
     -----
     -   Input *Munsell* value :math:`V` is in domain [0, 10].
-    -   Output *luminance* :math:`Y` is in domain [0, 100].
+    -   Output *luminance* :math:`R_Y` is in domain [0, 100].
 
     References
     ----------
-    .. [1]  http://en.wikipedia.org/wiki/Lightness
-            (Last accessed 13 April 2014)
+    .. [1]  **Sidney M. Newhall, Dorothy Nickerson, and Deane B. Judd**,
+            *Final Report of the O.S.A. Subcommittee on the Spacing of the
+            Munsell Colors*,
+            *JOSA, Vol. 33, Issue 7, pp. 385-411 (1943)*,
+            DOI: http://dx.doi.org/10.1364/JOSA.33.000385
 
     Examples
     --------
     >>> luminance_newhall1943(3.74629715382)  # doctest: +ELLIPSIS
     10.4089874...
     """
 
-    Y = 1.2219 * V - 0.23111 * (V * V) + 0.23951 * (V ** 3) - 0.021009 * (
+    R_Y = 1.2219 * V - 0.23111 * (V * V) + 0.23951 * (V ** 3) - 0.021009 * (
         V ** 4) + 0.0008404 * (V ** 5)
 
-    return Y
+    return R_Y
 
 
-def luminance_1976(L, Yn=100):
+def luminance_ASTM_D1535_08(V, **kwargs):
     """
-    Returns the *luminance* :math:`Y` of given *Lightness* :math:`L^*` with
-    given reference white *luminance* :math:`Y_n`.
+    Returns the *luminance* :math:`Y` of given *Munsell* value :math:`V` using
+    *ASTM D1535-08e1 (2008)* method.
 
     Parameters
     ----------
-    L : numeric
-        *Lightness* :math:`L^*`
-    Yn : numeric
-        White reference *luminance* :math:`Y_n`.
+    V : numeric
+        *Munsell* value :math:`V`.
+    \*\*kwargs : \*\*, optional
+        Unused parameter provided for signature compatibility with other
+        *luminance* computation objects.
 
     Returns
     -------
@@ -101,39 +106,39 @@ def luminance_1976(L, Yn=100):
 
     Notes
     -----
-    -   Input *Lightness* :math:`L^*` is in domain [0, 100].
+    -   Input *Munsell* value :math:`V` is in domain [0, 10].
     -   Output *luminance* :math:`Y` is in domain [0, 100].
 
     References
     ----------
-    .. [2]  http://www.poynton.com/PDFs/GammaFAQ.pdf
-            (Last accessed 12 April 2014)
+    .. [4]  `ASTM D1535-08e1 - Standard Practice for Specifying Color by the
+            Munsell System
+            <http://www.scribd.com/doc/89648322/ASTM-D1535-08e1-Standard-Practice-for-Specifying-Color-by-the-Munsell-System>`_,  # noqa
+            DOI: http://dx.doi.org/10.1520/D1535-13
 
     Examples
     --------
-    >>> luminance_1976(37.9856290977)  # doctest: +ELLIPSIS
-    10.0800000...
+    >>> luminance_ASTM_D1535_08(3.74629715382)  # doctest: +ELLIPSIS
+    10.1488096...
     """
 
-    Y = ((((L + 16) / 116) ** 3) * Yn
-         if L > CIE_K * CIE_E else
-         (L / CIE_K) * Yn)
+    Y = (1.1914 * V - 0.22533 * (V ** 2) + 0.23352 * (V ** 3) - 0.020484 *
+         (V ** 4) + 0.00081939 * (V ** 5))
 
     return Y
 
 
-def luminance_ASTM_D1535_08(V, **kwargs):
+def luminance_1976(Lstar, Y_n=100):
     """
-    Returns the *luminance* :math:`Y` of given *Munsell* value :math:`V` using
-    *ASTM D1535-08e1 (2008)* method.
+    Returns the *luminance* :math:`Y` of given *Lightness* :math:`L^*` with
+    given reference white *luminance* :math:`Y_n`.
 
     Parameters
     ----------
-    V : numeric
-        *Munsell* value :math:`V`.
-    \*\*kwargs : \*\*, optional
-        Unused parameter provided for signature compatibility with other
-        *luminance* computation objects.
+    L : numeric
+        *Lightness* :math:`L^*`
+    Yn : numeric
+        White reference *luminance* :math:`Y_n`.
 
     Returns
     -------
@@ -142,44 +147,55 @@ def luminance_ASTM_D1535_08(V, **kwargs):
 
     Notes
     -----
-    -   Input *Munsell* value :math:`V` is in domain [0, 10].
+    -   Input *Lightness* :math:`L^*` and reference white *luminance*
+        :math:`Y_n` are in domain [0, 100].
     -   Output *luminance* :math:`Y` is in domain [0, 100].
 
     References
     ----------
-    -  http://www.scribd.com/doc/89648322/ASTM-D1535-08e1-Standard-Practice-for-Specifying-Color-by-the-Munsell-System  # noqa
+    .. [2]  **Wyszecki & Stiles**,
+            *Color Science - Concepts and Methods Data and Formulae -
+            Second Edition*,
+            Wiley Classics Library Edition, published 2000,
+            ISBN-10: 0-471-39918-3,
+            page 167.
+    .. [3]  http://brucelindbloom.com/index.html?LContinuity.html
+            (Last accessed 24 February 2014)
 
     Examples
     --------
-    >>> luminance_ASTM_D1535_08(3.74629715382)  # doctest: +ELLIPSIS
-    10.1488096...
+    >>> luminance_1976(37.9856290977)  # doctest: +ELLIPSIS
+    10.0800000...
+    >>> luminance_1976(37.9856290977, 95)  # doctest: +ELLIPSIS
+    9.5760000...
     """
 
-    Y = 1.1914 * V - 0.22533 * (V * V) + 0.23352 * (V ** 3) - 0.020484 * (
-        V ** 4) + 0.00081939 * (V ** 5)
+    Y = (Y_n * ((Lstar + 16) / 116) ** 3
+         if Lstar > CIE_K * CIE_E else
+         Y_n * (Lstar / CIE_K))
 
     return Y
 
 
 LUMINANCE_METHODS = CaseInsensitiveMapping(
     {'Newhall 1943': luminance_newhall1943,
-     'CIE 1976': luminance_1976,
-     'ASTM D1535-08': luminance_ASTM_D1535_08})
+     'ASTM D1535-08': luminance_ASTM_D1535_08,
+     'CIE 1976': luminance_1976})
 """
 Supported *luminance* computations methods.
 
 LUMINANCE_METHODS : dict
-    ('Newhall 1943', 'CIE 1976', 'ASTM D1535-08')
+    ('Newhall 1943', 'ASTM D1535-08', 'CIE 1976')
 
 Aliases:
 
--   'cie1976': 'CIE 1976'
 -   'astm2008': 'ASTM D1535-08'
+-   'cie1976': 'CIE 1976'
 """
-LUMINANCE_METHODS['cie1976'] = (
-    LUMINANCE_METHODS['CIE 1976'])
 LUMINANCE_METHODS['astm2008'] = (
     LUMINANCE_METHODS['ASTM D1535-08'])
+LUMINANCE_METHODS['cie1976'] = (
+    LUMINANCE_METHODS['CIE 1976'])
 
 
 def luminance(LV, method='CIE 1976', **kwargs):
@@ -192,7 +208,7 @@ def luminance(LV, method='CIE 1976', **kwargs):
     LV : numeric
         *Lightness* :math:`L^*` or *Munsell* value :math:`V`.
     method : unicode, optional
-        ('Newhall 1943', 'CIE 1976', 'ASTM D1535-08')
+        ('Newhall 1943', 'ASTM D1535-08', 'CIE 1976')
         Computation method.
     \*\*kwargs : \*\*
         Keywords arguments.
@@ -212,9 +228,9 @@ def luminance(LV, method='CIE 1976', **kwargs):
     --------
     >>> luminance(37.9856290977)  # doctest: +ELLIPSIS
     10.0800000...
-    >>> luminance(37.9856290977, Yn=100)  # doctest: +ELLIPSIS
+    >>> luminance(37.9856290977, Y_n=100)  # doctest: +ELLIPSIS
     10.0800000...
-    >>> luminance(37.9856290977, Yn=95)  # doctest: +ELLIPSIS
+    >>> luminance(37.9856290977, Y_n=95)  # doctest: +ELLIPSIS
     9.5760000...
     >>> luminance(3.74629715382, method='Newhall 1943')  # doctest: +ELLIPSIS
     10.4089874...

colour/colorimetry/tests/tests_luminance.py

@@ -27,8 +27,8 @@
 __status__ = 'Production'
 
 __all__ = ['TestLuminanceNewhall1943',
-           'TestLuminance1976',
-           'TestLuminanceASTM_D1535_08']
+           'TestLuminanceASTM_D1535_08',
+           'TestLuminance1976']
 
 
 class TestLuminanceNewhall1943(unittest.TestCase):
@@ -57,6 +57,32 @@ def test_luminance_newhall1943(self):
             places=7)
 
 
+class TestLuminanceASTM_D1535_08(unittest.TestCase):
+    """
+    Defines :func:`colour.colorimetry.luminance.luminance_ASTM_D1535_08`
+    definition unit tests methods.
+    """
+
+    def test_luminance_1976(self):
+        """
+        Tests :func:`colour.colorimetry.luminance.luminance_ASTM_D1535_08`
+        definition.
+        """
+
+        self.assertAlmostEqual(
+            luminance_ASTM_D1535_08(3.74629715382),
+            10.1488096782,
+            places=7)
+        self.assertAlmostEqual(
+            luminance_ASTM_D1535_08(8.64728711385),
+            69.5324092373,
+            places=7)
+        self.assertAlmostEqual(
+            luminance_ASTM_D1535_08(1.52569021578),
+            2.01830631474,
+            places=7)
+
+
 class TestLuminance1976(unittest.TestCase):
     """
     Defines :func:`colour.colorimetry.luminance.luminance_1976` definition
@@ -94,31 +120,5 @@ def test_luminance_1976(self):
             places=7)
 
 
-class TestLuminanceASTM_D1535_08(unittest.TestCase):
-    """
-    Defines :func:`colour.colorimetry.luminance.luminance_ASTM_D1535_08`
-    definition unit tests methods.
-    """
-
-    def test_luminance_1976(self):
-        """
-        Tests :func:`colour.colorimetry.luminance.luminance_ASTM_D1535_08`
-        definition.
-        """
-
-        self.assertAlmostEqual(
-            luminance_ASTM_D1535_08(3.74629715382),
-            10.1488096782,
-            places=7)
-        self.assertAlmostEqual(
-            luminance_ASTM_D1535_08(8.64728711385),
-            69.5324092373,
-            places=7)
-        self.assertAlmostEqual(
-            luminance_ASTM_D1535_08(1.52569021578),
-            2.01830631474,
-            places=7)
-
-
 if __name__ == '__main__':
     unittest.main()