Merge branch 'feature/v0.4.2' into develop

berchan · Nov 6, 2022 · aa28736 · aa28736
2 parents 64da92a + 60b3425
commit aa28736
Show file tree

Hide file tree

Showing 172 changed files with 4,365 additions and 2,845 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -14,6 +14,11 @@ repos:
     hooks:
     - id: black
       language_version: python3.8
+-   repo: https://github.com/keewis/blackdoc
+    rev: v0.3.8
+    hooks:
+    - id: blackdoc
+      language_version: python3.8
 -   repo: https://github.com/PyCQA/flake8
     rev: 5.0.4
     hooks:

diff --git a/README.rst b/README.rst
diff --git a/colour/__init__.py b/colour/__init__.py
@@ -28,7 +28,7 @@
 -   corresponding: Corresponding colour chromaticities computations.
 -   difference: Colour difference computations.
 -   examples: Examples for the sub-packages.
--   geometry: Geometry primitives generation.
+-   geometry: Geometry computations.
 -   graph: Graph for automatic colour conversions.
 -   hints: Type hints for annotations.
 -   io: Input / output objects for reading and writing data.

diff --git a/colour/adaptation/__init__.py b/colour/adaptation/__init__.py
@@ -254,7 +254,8 @@ def chromatic_adaptation(
     >>> Y_o = 0.20
     >>> E_o = 1000
     >>> chromatic_adaptation(
-    ...     XYZ, XYZ_w, XYZ_wr, method='CIE 1994', Y_o=Y_o, E_o1=E_o, E_o2=E_o)
+    ...     XYZ, XYZ_w, XYZ_wr, method="CIE 1994", Y_o=Y_o, E_o1=E_o, E_o2=E_o
+    ... )
     ... # doctest: +ELLIPSIS
     array([ 0.2403379...,  0.2115621...,  0.1764301...])
 
@@ -265,7 +266,8 @@ def chromatic_adaptation(
     >>> XYZ_wr = np.array([0.9481, 1.0000, 1.0730])
     >>> L_A = 200
     >>> chromatic_adaptation(
-    ...     XYZ, XYZ_w, XYZ_wr, method='CMCCAT2000', L_A1=L_A, L_A2=L_A)
+    ...     XYZ, XYZ_w, XYZ_wr, method="CMCCAT2000", L_A1=L_A, L_A2=L_A
+    ... )
     ... # doctest: +ELLIPSIS
     array([ 0.1952698...,  0.2306834...,  0.2497175...])
 
@@ -274,7 +276,8 @@ def chromatic_adaptation(
     >>> XYZ = np.array([0.1953, 0.2307, 0.2497])
     >>> Y_n = 200
     >>> chromatic_adaptation(
-    ...     XYZ, XYZ_w, XYZ_wr, method='Fairchild 1990', Y_n=Y_n)
+    ...     XYZ, XYZ_w, XYZ_wr, method="Fairchild 1990", Y_n=Y_n
+    ... )
     ... # doctest: +ELLIPSIS
     array([ 0.2332526...,  0.2332455...,  0.7611593...])
 
@@ -283,12 +286,17 @@ def chromatic_adaptation(
     >>> XYZ = np.array([0.20654008, 0.12197225, 0.05136952])
     >>> XYZ_w = np.array([0.95045593, 1.00000000, 1.08905775])
     >>> XYZ_wr = np.array([0.96429568, 1.00000000, 0.82510460])
-    >>> chromatic_adaptation(XYZ, XYZ_w, XYZ_wr, method='Zhai 2018')
+    >>> chromatic_adaptation(XYZ, XYZ_w, XYZ_wr, method="Zhai 2018")
     ... # doctest: +ELLIPSIS
     array([ 0.2163881...,  0.1257    ,  0.0384749...])
     >>> chromatic_adaptation(
-    ...     XYZ, XYZ_w, XYZ_wr, method='Zhai 2018', D_b=0.9,
-    ...     XYZ_wo=np.array([100, 100, 100]))
+    ...     XYZ,
+    ...     XYZ_w,
+    ...     XYZ_wr,
+    ...     method="Zhai 2018",
+    ...     D_b=0.9,
+    ...     XYZ_wo=np.array([100, 100, 100]),
+    ... )
     ... # doctest: +ELLIPSIS
     array([ 0.2152436...,  0.1253522...,  0.0388406...])
     """

diff --git a/colour/adaptation/cmccat2000.py b/colour/adaptation/cmccat2000.py
@@ -260,8 +260,9 @@ def chromatic_adaptation_inverse_CMCCAT2000(
     >>> XYZ_wr = np.array([94.81, 100.00, 107.30])
     >>> L_A1 = 200
     >>> L_A2 = 200
-    >>> chromatic_adaptation_inverse_CMCCAT2000(XYZ_c, XYZ_w, XYZ_wr, L_A1,
-    ...                                         L_A2)
+    >>> chromatic_adaptation_inverse_CMCCAT2000(
+    ...     XYZ_c, XYZ_w, XYZ_wr, L_A1, L_A2
+    ... )
     ... # doctest: +ELLIPSIS
     array([ 22.4839876...,  22.7419485...,   8.5393392...])
     """
@@ -364,7 +365,8 @@ def chromatic_adaptation_CMCCAT2000(
     >>> L_A1 = 200
     >>> L_A2 = 200
     >>> chromatic_adaptation_CMCCAT2000(
-    ...     XYZ, XYZ_w, XYZ_wr, L_A1, L_A2, direction='Forward')
+    ...     XYZ, XYZ_w, XYZ_wr, L_A1, L_A2, direction="Forward"
+    ... )
     ... # doctest: +ELLIPSIS
     array([ 19.5269832...,  23.0683396...,  24.9717522...])
 
@@ -376,7 +378,8 @@ def chromatic_adaptation_CMCCAT2000(
     >>> L_A1 = 200
     >>> L_A2 = 200
     >>> chromatic_adaptation_CMCCAT2000(
-    ...     XYZ, XYZ_w, XYZ_wr, L_A1, L_A2, direction='Inverse')
+    ...     XYZ, XYZ_w, XYZ_wr, L_A1, L_A2, direction="Inverse"
+    ... )
     ... # doctest: +ELLIPSIS
     array([ 22.48,  22.74,   8.54])
     """

diff --git a/colour/adaptation/vonkries.py b/colour/adaptation/vonkries.py
@@ -109,7 +109,7 @@ def matrix_chromatic_adaptation_VonKries(
 
     >>> XYZ_w = np.array([0.95045593, 1.00000000, 1.08905775])
     >>> XYZ_wr = np.array([0.96429568, 1.00000000, 0.82510460])
-    >>> method = 'Bradford'
+    >>> method = "Bradford"
     >>> matrix_chromatic_adaptation_VonKries(XYZ_w, XYZ_wr, method)
     ... # doctest: +ELLIPSIS
     array([[ 1.0479297...,  0.0229468..., -0.0501922...],
@@ -221,7 +221,7 @@ def chromatic_adaptation_VonKries(
     >>> XYZ = np.array([0.20654008, 0.12197225, 0.05136952])
     >>> XYZ_w = np.array([0.95045593, 1.00000000, 1.08905775])
     >>> XYZ_wr = np.array([0.96429568, 1.00000000, 0.82510460])
-    >>> transform = 'Bradford'
+    >>> transform = "Bradford"
     >>> chromatic_adaptation_VonKries(XYZ, XYZ_w, XYZ_wr, transform)
     ... # doctest: +ELLIPSIS
     array([ 0.2166600...,  0.1260477...,  0.0385506...])

diff --git a/colour/adaptation/zhai2018.py b/colour/adaptation/zhai2018.py
@@ -134,11 +134,13 @@ def chromatic_adaptation_Zhai2018(
     >>> D_d = 0.9800
     >>> XYZ_wo = np.array([100, 100, 100])
     >>> chromatic_adaptation_Zhai2018(
-    ...     XYZ_b, XYZ_wb, XYZ_wd, D_b, D_d, XYZ_wo)  # doctest: +ELLIPSIS
+    ...     XYZ_b, XYZ_wb, XYZ_wd, D_b, D_d, XYZ_wo
+    ... )  # doctest: +ELLIPSIS
     array([ 39.1856164...,  42.1546179...,  19.2367203...])
     >>> XYZ_d = np.array([39.18561644, 42.15461798, 19.23672036])
     >>> chromatic_adaptation_Zhai2018(
-    ...     XYZ_d, XYZ_wd, XYZ_wb, D_d, D_b, XYZ_wo)  # doctest: +ELLIPSIS
+    ...     XYZ_d, XYZ_wd, XYZ_wb, D_d, D_b, XYZ_wo
+    ... )  # doctest: +ELLIPSIS
     array([ 48.9 ,  43.62,   6.25])
     """
 

diff --git a/colour/algebra/__init__.py b/colour/algebra/__init__.py
@@ -1,3 +1,10 @@
+import sys
+
+from colour.utilities.deprecation import ModuleAPI, build_API_changes
+from colour.utilities.documentation import is_documentation_building
+
+from colour.hints import Any
+
 from .common import (
     get_sdiv_mode,
     set_sdiv_mode,
@@ -7,9 +14,12 @@
     set_spow_enable,
     spow_enable,
     spow,
+    normalise_vector,
     normalise_maximum,
     vector_dot,
     matrix_dot,
+    euclidean_distance,
+    manhattan_distance,
     linear_conversion,
     linstep_function,
     lerp,
@@ -20,20 +30,6 @@
 )
 from .coordinates import *  # noqa
 from . import coordinates
-from .geometry import (
-    normalise_vector,
-    euclidean_distance,
-    manhattan_distance,
-    extend_line_segment,
-    LineSegmentsIntersections_Specification,
-    intersect_line_segments,
-    ellipse_coefficients_general_form,
-    ellipse_coefficients_canonical_form,
-    point_at_angle_on_ellipse,
-    ellipse_fitting_Halir1998,
-    ELLIPSE_FITTING_METHODS,
-    ellipse_fitting,
-)
 from .interpolation import (
     kernel_nearest_neighbour,
     kernel_linear,
@@ -67,9 +63,12 @@
     "set_spow_enable",
     "spow_enable",
     "spow",
+    "normalise_vector",
     "normalise_maximum",
     "vector_dot",
     "matrix_dot",
+    "euclidean_distance",
+    "manhattan_distance",
     "linear_conversion",
     "linstep_function",
     "lerp",
@@ -79,20 +78,6 @@
     "eigen_decomposition",
 ]
 __all__ += coordinates.__all__
-__all__ += [
-    "normalise_vector",
-    "euclidean_distance",
-    "manhattan_distance",
-    "extend_line_segment",
-    "LineSegmentsIntersections_Specification",
-    "intersect_line_segments",
-    "ellipse_coefficients_general_form",
-    "ellipse_coefficients_canonical_form",
-    "point_at_angle_on_ellipse",
-    "ellipse_fitting_Halir1998",
-    "ELLIPSE_FITTING_METHODS",
-    "ellipse_fitting",
-]
 __all__ += [
     "kernel_nearest_neighbour",
     "kernel_linear",
@@ -121,3 +106,66 @@
 __all__ += [
     "least_square_mapping_MoorePenrose",
 ]
+
+
+# ----------------------------------------------------------------------------#
+# ---                API Changes and Deprecation Management                ---#
+# ----------------------------------------------------------------------------#
+class algebra(ModuleAPI):
+    """Define a class acting like the *algebra* module."""
+
+    def __getattr__(self, attribute) -> Any:
+        """Return the value from the attribute with given name."""
+
+        return super().__getattr__(attribute)
+
+
+# v0.4.2
+API_CHANGES = {
+    "ObjectFutureAccessChange": [
+        [
+            "colour.algebra.ellipse_coefficients_general_form",
+            "colour.geometry.ellipse_coefficients_general_form",
+        ],
+        [
+            "colour.algebra.ellipse_coefficients_canonical_form",
+            "colour.geometry.ellipse_coefficients_canonical_form",
+        ],
+        [
+            "colour.algebra.point_at_angle_on_ellipse",
+            "colour.geometry.point_at_angle_on_ellipse",
+        ],
+        [
+            "colour.algebra.ellipse_fitting_Halir1998",
+            "colour.geometry.ellipse_fitting_Halir1998",
+        ],
+        [
+            "colour.algebra.ELLIPSE_FITTING_METHODS",
+            "colour.geometry.ELLIPSE_FITTING_METHODS",
+        ],
+        [
+            "colour.algebra.ellipse_fitting",
+            "colour.geometry.ellipse_fitting",
+        ],
+        [
+            "colour.algebra.extend_line_segment",
+            "colour.geometry.extend_line_segment",
+        ],
+        [
+            "colour.algebra.extend_line_segment",
+            "colour.geometry.intersect_line_segments",
+        ],
+        [
+            "colour.algebra.extend_line_segment",
+            "colour.geometry.LineSegmentsIntersections_Specification",
+        ],
+    ]
+}
+"""Defines the *colour.algebra* sub-package API changes."""
+
+if not is_documentation_building():
+    sys.modules["colour.algebra"] = algebra(  # type: ignore[assignment]
+        sys.modules["colour.algebra"], build_API_changes(API_CHANGES)
+    )
+
+    del ModuleAPI, is_documentation_building, build_API_changes, sys