Merge branch 'feature/v0.2.2' into develop

Author: KelSolaar

.github/workflows/continuous-integration-quality-unit-tests.yml

@@ -7,7 +7,7 @@ jobs:
     name: ${{ matrix.os }} - Python ${{ matrix.python-version }}
     strategy:
       matrix:
-        os: [macOS-latest, ubuntu-latest, windows-2019]
+        os: [macOS-latest, ubuntu-latest, windows-latest]
         python-version: ["3.10", 3.11, 3.12, 3.13]
       fail-fast: false
     runs-on: ${{ matrix.os }}

.pre-commit-config.yaml

@@ -15,17 +15,17 @@ repos:
       - id: requirements-txt-fixer
       - id: trailing-whitespace
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.3.0
+    rev: v2.4.1
     hooks:
       - id: codespell
         args: ["--ignore-words-list=socio-economic"]
         exclude: "BIBLIOGRAPHY.bib|CONTRIBUTORS.rst|.*.ipynb"
   - repo: https://github.com/PyCQA/isort
-    rev: "5.13.2"
+    rev: "6.0.1"
     hooks:
       - id: isort
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.8.2"
+    rev: "v0.12.4"
     hooks:
       - id: ruff-format
       - id: ruff

colour_checker_detection/__init__.py

@@ -4,13 +4,15 @@
 
 Colour checker detection algorithms for *Python*.
 
+This package provides computer vision algorithms to detect and extract colour
+checkers from images using both segmentation-based and machine learning
+inference approaches.
+
 Subpackages
 -----------
--   detection : Colour checker detection.
+-   detection : Colour checker detection algorithms and utilities.
 """
 
-# isort: skip_file
-
 from __future__ import annotations
 
 import contextlib
@@ -21,6 +23,8 @@
 import cv2
 import numpy as np
 
+# isort: split
+
 from .detection import (
     SETTINGS_INFERENCE_COLORCHECKER_CLASSIC,
     SETTINGS_INFERENCE_COLORCHECKER_CLASSIC_MINI,
@@ -71,7 +75,7 @@
 
 try:
     _version = (
-        subprocess.check_output(  # noqa: S603
+        subprocess.check_output(
             ["git", "describe"],  # noqa: S607
             cwd=os.path.dirname(__file__),
             stderr=subprocess.STDOUT,

colour_checker_detection/detection/__init__.py

@@ -1,75 +1,88 @@
-# isort: skip_file
+"""
+Detection
+=========
+
+Colour checker detection algorithms and utilities.
+
+This subpackage provides common utilities, segmentation-based detection
+methods, and machine learning inference approaches for identifying colour
+checkers in images.
+"""
 
 from .common import (
-    DTYPE_INT_DEFAULT,
     DTYPE_FLOAT_DEFAULT,
+    DTYPE_INT_DEFAULT,
+    SETTINGS_CONTOUR_DETECTION_DEFAULT,
     SETTINGS_DETECTION_COLORCHECKER_CLASSIC,
     SETTINGS_DETECTION_COLORCHECKER_SG,
-    SETTINGS_CONTOUR_DETECTION_DEFAULT,
-    as_int32_array,
+    DataDetectionColourChecker,
+    approximate_contour,
     as_float32_array,
-    swatch_masks,
-    swatch_colours,
-    reformat_image,
-    transform_image,
+    as_int32_array,
+    contour_centroid,
     detect_contours,
     is_square,
-    contour_centroid,
-    scale_contour,
-    approximate_contour,
     quadrilateralise_contours,
+    reformat_image,
     remove_stacked_contours,
-    DataDetectionColourChecker,
     sample_colour_checker,
+    scale_contour,
+    swatch_colours,
+    swatch_masks,
+    transform_image,
 )
+
+# isort: split
+
 from .inference import (
     SETTINGS_INFERENCE_COLORCHECKER_CLASSIC,
     SETTINGS_INFERENCE_COLORCHECKER_CLASSIC_MINI,
-    inferencer_default,
     detect_colour_checkers_inference,
+    inferencer_default,
 )
 
+# isort: split
+
 from .segmentation import (
     SETTINGS_SEGMENTATION_COLORCHECKER_CLASSIC,
-    SETTINGS_SEGMENTATION_COLORCHECKER_SG,
     SETTINGS_SEGMENTATION_COLORCHECKER_NANO,
-    segmenter_default,
+    SETTINGS_SEGMENTATION_COLORCHECKER_SG,
     detect_colour_checkers_segmentation,
+    segmenter_default,
 )
 
 __all__ = [
-    "DTYPE_INT_DEFAULT",
     "DTYPE_FLOAT_DEFAULT",
+    "DTYPE_INT_DEFAULT",
+    "SETTINGS_CONTOUR_DETECTION_DEFAULT",
     "SETTINGS_DETECTION_COLORCHECKER_CLASSIC",
     "SETTINGS_DETECTION_COLORCHECKER_SG",
-    "SETTINGS_CONTOUR_DETECTION_DEFAULT",
-    "as_int32_array",
+    "DataDetectionColourChecker",
+    "approximate_contour",
     "as_float32_array",
-    "swatch_masks",
-    "swatch_colours",
-    "reformat_image",
-    "transform_image",
+    "as_int32_array",
+    "contour_centroid",
     "detect_contours",
     "is_square",
-    "contour_centroid",
-    "scale_contour",
-    "approximate_contour",
     "quadrilateralise_contours",
+    "reformat_image",
     "remove_stacked_contours",
-    "DataDetectionColourChecker",
     "sample_colour_checker",
-]
-__all__ += [
-    "SETTINGS_SEGMENTATION_COLORCHECKER_CLASSIC",
-    "SETTINGS_SEGMENTATION_COLORCHECKER_SG",
-    "SETTINGS_SEGMENTATION_COLORCHECKER_NANO",
-    "segmenter_default",
-    "extract_colour_checkers_segmentation",
-    "detect_colour_checkers_segmentation",
+    "scale_contour",
+    "swatch_colours",
+    "swatch_masks",
+    "transform_image",
 ]
 __all__ += [
     "SETTINGS_INFERENCE_COLORCHECKER_CLASSIC",
     "SETTINGS_INFERENCE_COLORCHECKER_CLASSIC_MINI",
-    "inferencer_default",
     "detect_colour_checkers_inference",
+    "inferencer_default",
+]
+__all__ += [
+    "SETTINGS_SEGMENTATION_COLORCHECKER_CLASSIC",
+    "SETTINGS_SEGMENTATION_COLORCHECKER_NANO",
+    "SETTINGS_SEGMENTATION_COLORCHECKER_SG",
+    "detect_colour_checkers_segmentation",
+    "segmenter_default",
 ]

colour_checker_detection/detection/common.py

@@ -2,7 +2,7 @@
 Common Utilities
 ================
 
-Define the common utilities objects that don't fall in any specific category.
+Define common utility objects that support colour checker detection algorithms.
 
 References
 ----------
@@ -180,7 +180,7 @@
 
 def as_int32_array(a: ArrayLike) -> NDArrayInt:
     """
-    Convert given variable :math:`a` to :class:`numpy.ndarray` using
+    Convert specified variable :math:`a` to :class:`numpy.ndarray` using
     `np.int32` :class:`numpy.dtype`.
 
     Parameters
@@ -205,7 +205,7 @@ def as_int32_array(a: ArrayLike) -> NDArrayInt:
 
 def as_float32_array(a: ArrayLike) -> NDArrayFloat:
     """
-    Convert given variable :math:`a` to :class:`numpy.ndarray` using
+    Convert specified variable :math:`a` to :class:`numpy.ndarray` using
     `np.float32` :class:`numpy.dtype`.
 
     Parameters
@@ -236,7 +236,7 @@ def swatch_masks(
     samples: int,
 ) -> NDArrayInt:
     """
-    Return swatch masks for given image width and height and swatches count.
+    Return swatch masks for specified image width and height and swatches count.
 
     Parameters
     ----------
@@ -293,7 +293,7 @@ def swatch_masks(
 
 def swatch_colours(image: ArrayLike, masks: ArrayLike) -> NDArrayFloat:
     """
-    Extract the swatch colours from given image using given masks.
+    Extract the swatch colours from specified image using specified masks.
 
     Parameters
     ----------
@@ -356,8 +356,8 @@ def reformat_image(
     ] = cv2.INTER_CUBIC,
 ) -> NDArrayReal:
     """
-    Reformat given image so that it is horizontal and resizes it to given target
-    width.
+    Reformat specified image so that it is horizontal and resizes it to specified
+    target width.
 
     Parameters
     ----------
@@ -452,7 +452,7 @@ def transform_image(
     ] = cv2.INTER_CUBIC,
 ) -> NDArrayReal:
     """
-    Transform given image using given translation, rotation and scale values.
+    Transform specified image using specified translation, rotation and scale values.
 
     The transformation is performed relatively to the image center and in the
     following order:
@@ -552,7 +552,7 @@ def transform_image(
     transform += as_float32_array([[0, 0, t_x], [0, 0, t_y]])
 
     return cast(
-        NDArrayReal,
+        "NDArrayReal",
         cv2.warpAffine(
             image,
             transform,
@@ -567,7 +567,7 @@ def detect_contours(
     image: ArrayLike, additional_data: bool = False, **kwargs: Any
 ) -> Tuple[NDArrayInt] | Tuple[Tuple[NDArrayInt], NDArrayReal]:
     """
-    Detect the contours of given image using given settings.
+    Detect the contours of specified image using specified settings.
 
     The process is a follows:
 
@@ -650,14 +650,14 @@ def detect_contours(
         iterations=settings.convolution_iterations,
     )
 
-    image_k = cast(NDArrayReal, image_k)
+    image_k = cast("NDArrayReal", image_k)
 
     # Detecting contours.
     contours, _hierarchy = cv2.findContours(
         image_k, cv2.RETR_TREE, cv2.CHAIN_APPROX_NONE
     )
 
-    contours = cast(Tuple[NDArrayInt], contours)
+    contours = cast("Tuple[NDArrayInt]", contours)
 
     if additional_data:
         return contours, image_k
@@ -666,7 +666,7 @@ def detect_contours(
 
 def is_square(contour: ArrayLike, tolerance: float = 0.015) -> bool:
     """
-    Return if given contour is a square.
+    Return if specified contour is a square.
 
     Parameters
     ----------
@@ -678,7 +678,7 @@ def is_square(contour: ArrayLike, tolerance: float = 0.015) -> bool:
     Returns
     -------
     :class:`bool`
-        Whether given contour is a square.
+        Whether specified contour is a square.
 
     Examples
     --------
@@ -703,7 +703,7 @@ def is_square(contour: ArrayLike, tolerance: float = 0.015) -> bool:
 
 def contour_centroid(contour: ArrayLike) -> Tuple[float, float]:
     """
-    Return the centroid of given contour.
+    Return the centroid of specified contour.
 
     Parameters
     ----------
@@ -739,7 +739,7 @@ def contour_centroid(contour: ArrayLike) -> Tuple[float, float]:
 
 def scale_contour(contour: ArrayLike, factor: ArrayLike) -> NDArrayFloat:
     """
-    Scale given contour by given scale factor.
+    Scale specified contour by specified scale factor.
 
     Parameters
     ----------
@@ -779,7 +779,7 @@ def approximate_contour(
     contour: ArrayLike, points: int = 4, iterations: int = 100
 ) -> NDArrayInt:
     """
-    Approximate given contour to have given number of points.
+    Approximate specified contour to have specified number of points.
 
     The process uses binary search to find the best *epsilon* value
     producing a contour approximation with exactly ``points``.
@@ -827,7 +827,7 @@ def approximate_contour(
             contour, center * cv2.arcLength(contour, True), True
         )
 
-        approximation = cast(NDArrayInt, approximation)
+        approximation = cast("NDArrayInt", approximation)
 
         if len(approximation) > points:
             low = (low + high) / 2
@@ -839,7 +839,7 @@ def approximate_contour(
 
 def quadrilateralise_contours(contours: ArrayLike) -> Tuple[NDArrayInt, ...]:
     """
-    Convert given to quadrilaterals.
+    Convert specified contours to quadrilaterals.
 
     Parameters
     ----------
@@ -880,7 +880,7 @@ def remove_stacked_contours(
     contours: ArrayLike, keep_smallest: bool = True
 ) -> Tuple[NDArrayInt, ...]:
     """
-    Remove amd filter out the stacked contours from given contours keeping
+    Remove and filter out the stacked contours from specified contours keeping
     either the smallest or the largest ones.
 
     Parameters
@@ -999,8 +999,8 @@ def sample_colour_checker(
     **kwargs: Any,
 ) -> DataDetectionColourChecker:
     """
-    Sample the colour checker using the given source quadrilateral, i.e.,
-    detected colour checker in the image, and the given target rectangle.
+    Sample the colour checker using the specified source quadrilateral, i.e.,
+    detected colour checker in the image, and the specified target rectangle.
 
     Parameters
     ----------
@@ -1155,7 +1155,7 @@ def sample_colour_checker(
                 colour_checker = colour_checker_candidate
                 quadrilateral = candidate_quadrilateral
 
-    colour_checker = cast(NDArrayFloat, colour_checker)
+    colour_checker = cast("NDArrayFloat", colour_checker)
 
     return DataDetectionColourChecker(
         sampled_colours, masks, colour_checker, quadrilateral