Merge pull request #10 from agfianf/docs/processor

Docs/processor

Author: agfianf

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [v0.0.1-rc2] - 2025-02-10
+**Release Candidate with Full Feature Set and Documentation**
+This release introduces several improvements:
+
+- Updated documentation to include interactive Google Colab demos and online documentation links.
+- Refactored the detection module by renaming the detection file and introducing the new `DetectionProcessor` class for clearer structure.
+- Enhanced image processing utilities with improved docstrings and comments for better code readability and maintainability.
+
 ## [v0.0.1-rc1] - 2025-02-10
 **Release Candidate with Full Feature Set and Documentation**
 - Add docs page build with mkdocs-material. Read more [https://agfianf.github.io/color-correction/](https://agfianf.github.io/color-correction/)

README.md

@@ -10,7 +10,8 @@
 [![version](https://badge.fury.io/py/color-correction.svg)](https://badge.fury.io/py/color-correction)
 [![downloads](https://img.shields.io/pypi/dm/color-correction)](https://pypistats.org/packages/color-correction)
 [![python-version](https://img.shields.io/pypi/pyversions/color-correction)](https://badge.fury.io/py/color-correction)
-
+[![Try color-correction using - Google Colab](https://img.shields.io/badge/Try_color--correction_using-Google_Colab-blue?logo=googlecolab)](https://colab.research.google.com/drive/146SXHHihMmGLzaTSwdBXncVr3SU_I-Dm?usp=sharing)
+[![read - docs](https://img.shields.io/badge/read-docs-blue?logo=materialformkdocs)](https://agfianf.github.io/color-correction/)
 
 </div>
 

color_correction/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.0.1-rc1"
+__version__ = "0.0.1-rc2"
 
 # fmt: off
 from .constant.color_checker import reference_color_d50_bgr as REFERENCE_COLOR_D50_BGR  # noqa: N812, I001

color_correction/processor/__init__.py

@@ -1,6 +1,7 @@
 import cv2
 import numpy as np
 
+from color_correction.schemas.custom_types import BoundingBox, ColorPatchType, ImageBGR
 from color_correction.schemas.det_yv8 import DetectionResult
 from color_correction.utils.geometry_processing import (
     extract_intersecting_patches,
@@ -12,36 +13,34 @@
     crop_region_with_margin,
 )
 
-# Type aliases for better readability
-BoundingBox = tuple[int, int, int, int]
-RGB = tuple[float, float, float]
-BGR = tuple[float, float, float]
-
 
 class DetectionProcessor:
     """
-    A class to process color calibration card detections and extract color patches.
-
-    This class handles the detection and processing of color calibration cards and their
-    individual color patches, including visualization and RGB value extraction.
+    A class for processing detection results and transforming them using
+    available utility methods. This class takes the output from an object
+    detection model (e.g., YOLOv8) and provides functionality to separate,
+    process, and visualize detected color checker cards and their patches.
     """
 
     @staticmethod
     def get_each_class_box(
         prediction: DetectionResult,
     ) -> tuple[list[BoundingBox], list[BoundingBox]]:
         """
-        Separate detection boxes by class (cards and patches).
+        Separates detection boxes into card boxes and patch boxes.
 
         Parameters
         ----------
         prediction : DetectionResult
-            Detection results containing boxes and class IDs
+            The detection output that includes bounding boxes and class IDs.
 
         Returns
         -------
-        Tuple[List[BoundingBox], List[BoundingBox]]
-            Two lists containing card boxes and patch boxes respectively
+        tuple[list[BoundingBox], list[BoundingBox]]
+            A tuple containing:
+
+            - a list of card boxes (class id 1)
+            - a list of patch boxes (class id 0).
         """
         ls_cards = [
             box
@@ -66,36 +65,41 @@ def get_each_class_box(
     @staticmethod
     def print_summary(prediction: DetectionResult) -> None:
         """
-        Print a summary of detected objects.
+        Prints a summary of the detected cards and patches.
 
         Parameters
         ----------
         prediction : DetectionResult
-            Detection results to summarize
+            The detection result to summarize.
         """
         ls_cards, ls_patches = DetectionProcessor.get_each_class_box(prediction)
         print(f"Number of cards detected: {len(ls_cards)}")
         print(f"Number of patches detected: {len(ls_patches)}")
 
     @staticmethod
     def process_patches(
-        input_image: np.ndarray,
+        input_image: ImageBGR,
         ordered_patches: list[tuple[BoundingBox, tuple[int, int]] | None],
-    ) -> tuple[list[RGB], np.ndarray]:
+    ) -> tuple[list[ColorPatchType], ImageBGR]:
         """
-        Process detected patches to extract RGB values and create a visualization.
+        Processes each detected patch by extracting its region from the image,
+        computing its mean BGR color, and building a visualization grid.
 
         Parameters
         ----------
-        input_image : np.ndarray
-            Input image containing the patches
-        ordered_patches : List[Optional[BoundingBox]]
-            List of ordered patch coordinates
+        input_image : ImageBGR
+            The original image containing detected patches.
+        ordered_patches : list[tuple[BoundingBox, tuple[int, int]] | None]
+            The list of ordered patch coordinates paired with their center
+            points, possibly with missing entries as None.
 
         Returns
         -------
-        Tuple[List[RGB], np.ndarray]
-            List of RGB values and visualization image
+        tuple[list[ColorPatchType], ImageBGR]
+            a tuple containing:
+
+            - list of mean BGR color values for each patch.
+            - an image visualizing these patches in a grid layout.
         """
         patch_size = (50, 50, 1)
         ls_bgr_mean_patch = []
@@ -129,31 +133,42 @@ def process_patches(
 
     @staticmethod
     def extract_color_patches(
-        input_image: np.ndarray,
+        input_image: ImageBGR,
         prediction: DetectionResult,
         draw_processed_image: bool = False,
-    ) -> tuple[list[BGR], np.ndarray, np.ndarray | None]:
+    ) -> tuple[list[ColorPatchType], ImageBGR, ImageBGR | None]:
         """
-        Extract and process color patches from the detected calibration card.
+        Extracts and processes color patches from detected color checker cards,
+        transforming the detection results with available methods.
+
+        The method first separates detected cards and patches, generates an expected
+        patch grid, and then matches the detected patches with this grid. If patches
+        are missing, it attempts to auto-fill them with suggested coordinates.
+        Finally, it computes the mean color for each patch and builds a visualization.
 
         Parameters
         ----------
-        input_image : np.ndarray
-            Input image containing the color calibration card
+        input_image : ImageBGR
+            The original image containing the color checker card.
         prediction : DetectionResult
-            Detection results from YOLOv8
+            The detection result output from the model.
         draw_processed_image : bool, optional
-            Whether to create a visualization image, by default False
+            If True, returns an additional image with visualized detections.
+            Otherwise, only patch processing is performed. Defaults to False.
 
         Returns
         -------
-        Tuple[List[BGR], np.ndarray, Optional[np.ndarray]]
-            BGR values, patch visualization, and optional detection visualization
+        tuple[list[ColorPatchType], ImageBGR, ImageBGR | None]
+            a tuple containing:
+
+            - a list of mean BGR color values for each patch.
+            - an image visualizing these patches in a grid layout.
+            - an optional image with visualized detection results.
 
         Raises
         ------
         ValueError
-            If no cards or patches are detected
+            If no cards or patches are detected.
         """
         ls_cards, ls_patches = DetectionProcessor.get_each_class_box(prediction)
 
@@ -206,30 +221,34 @@ def extract_color_patches(
 
     @staticmethod
     def draw_preprocess(
-        image: np.ndarray,
+        image: ImageBGR,
         expected_boxes: list[BoundingBox],
         prediction: DetectionResult,
         ls_ordered_patch_bbox: list[BoundingBox | None],
         suggested_patches: dict[int, BoundingBox] | None = None,
-    ) -> np.ndarray:
+    ) -> ImageBGR:
         """
-        Draw detection visualizations on the image.
+        Draws visualizations on the input image to compare the detected patches with
+        the expected positions. It overlays expected boxes, connects detected patches to
+        their corresponding expected boxes, and highlights individual patch detections.
 
         Parameters
         ----------
-        image : np.ndarray
-            Input image to draw on
-        boxes : List[BoundingBox]
-            List of bounding boxes to draw
-        patch_indices : Optional[List[int]]
-            Indices to label the patches
-        suggested_patches : Optional[Dict[int, BoundingBox]]
-            Additional suggested patch locations to draw
+        image : ImageBGR
+            The original image to draw on.
+        expected_boxes : list[BoundingBox]
+            List of expected bounding boxes for patches.
+        prediction : DetectionResult
+            The detection results containing predicted bounding boxes.
+        ls_ordered_patch_bbox : list[BoundingBox | None]
+            The list of ordered patch bounding boxes.
+        suggested_patches : dict[int, BoundingBox], optional
+            Dictionary of suggested patch coordinates for missing patches.
 
         Returns
         -------
-        np.ndarray
-            Image with visualizations
+        ImageBGR
+            The image with drawn detection and patch visualizations.
         """
         color_green = (0, 255, 0)
         color_cyan = (255, 255, 10)
@@ -249,7 +268,7 @@ def draw_preprocess(
                 thickness=2,
             )
 
-            # draw connection lines between expected and intersecting patches
+            # Draw connection lines between expected and detected patch boxes
             patch = ls_ordered_patch_bbox[idx_b]
             if patch is None:
                 continue
@@ -263,7 +282,7 @@ def draw_preprocess(
                 thickness=1,
             )
 
-        # draw all predicted boxes
+        # Draw all predicted boxes
         for pbox, pids, pscore in zip(
             prediction.boxes,
             prediction.class_ids,

color_correction/processor/det_yv8.py color_correction/processor/detection.pycolor_correction/processor/det_yv8.py renamed to color_correction/processor/detection.py

@@ -1,52 +1,32 @@
 """
-Images Schema Module
---------------------
+Image Schema Module
+-------------------
 This module defines type annotations for image processing.
 
 Attributes
 ----------
 ColorPatchType : numpy.typing.NDArray[np.uint8]
-    Represents a color patch extracted from an image. Usually a mean of a region patch.
+    Represents a color patch extracted from an image,
+    typically the mean of a region patch.
 
     Example
     -------
     ```python
     np.array(
-        [
-            [68, 82, 115],  # 1. Dark skin
-            [128, 149, 195],  # 2. Light skin
-            [157, 123, 93],  # 3. Blue sky
-            [65, 108, 91],  # 4. Foliage
-            [175, 129, 130],  # 5. Blue flower
-            [171, 191, 99],  # 6. Bluish green
-            [46, 123, 220],  # 7. Orange
-            [168, 92, 72],  # 8. Purplish blue
-            [97, 84, 194],  # 9. Moderate red
-            [104, 59, 91],  # 10. Purple
-            [62, 189, 161],  # 11. Yellow green
-            [40, 161, 229],  # 12. Orange yellow
-            [147, 63, 42],  # 13. Blue
-            [72, 149, 72],  # 14. Green
-            [57, 50, 175],  # 15. Red
-            [22, 200, 238],  # 16. Yellow
-            [150, 84, 188],  # 17. Magenta
-            [166, 137, 0],  # 18. Cyan
-            [240, 245, 245],  # 19. White 9.5
-            [201, 202, 201],  # 20. Neutral 8
-            [162, 162, 161],  # 21. Neutral 6.5
-            [121, 121, 120],  # 22. Neutral 5
-            [85, 85, 83],  # 23. Neutral 3.5
-            [51, 50, 50],  # 24. Black 2
-        ],
+        [68, 82, 115],  # 1. Dark skin
     )
     ```
 ImageType : numpy.typing.NDArray[np.uint8]
-    Represents an image 3D array with shape (H, W, C) in uint8 format.
+    Represents a 3D image array with shape (H, W, C) in uint8 format.
 ImageBGR : numpy.typing.NDArray[np.uint8]
     Represents an image in BGR format (OpenCV default).
 ImageRGB : numpy.typing.NDArray[np.uint8]
     Represents an image in RGB format.
-
+ImageGray : numpy.typing.NDArray[np.uint8]
+    Represents a grayscale image.
+BoundingBox : tuple[int, int, int, int]
+    Represents a bounding box as (x1, y1, x2, y2).
+    The top-left and bottom-right corners of the detection.
 """
 
 from typing import Literal
@@ -68,3 +48,4 @@
 ImageBGR = NDArray[np.uint8]
 ImageRGB = NDArray[np.uint8]
 ImageGray = NDArray[np.uint8]
+BoundingBox = tuple[int, int, int, int]

color_correction/schemas/custom_types.py

@@ -20,14 +20,13 @@ class DetectionResult(BaseModel):
     A data model that encapsulates YOLOv8 detection results for a standardized color
     card and its color patches. The model handles two distinct classes:
     patches (label 0) and card (label 1). In a typical detection scenario,
-    the model captures one color calibration card and 24 color patches.
-
+    the model captures one card and 24 color patches inside/outside the card.
 
     Notes
     -----
     The detection typically yields 25 objects:
 
-    - 1 calibration card (class_id: 1)
+    - 1 color checker card 24 Patches (class_id: 1)
     - 24 color patches (class_id: 0)
 
     Attributes
@@ -38,7 +37,7 @@ class DetectionResult(BaseModel):
         Class identifiers for each detected object where:
 
         - 0: represents color patches
-        - 1: represents the calibration card
+        - 1: represents the color checker card 24 Patches
 
     scores : list[float]
         List of confidence scores for each detection.

color_correction/schemas/det_yv8.py

@@ -8,7 +8,7 @@
     YOLOv8CardDetector,
 )
 from color_correction.core.correction import CorrectionModelFactory
-from color_correction.processor.det_yv8 import DetectionProcessor
+from color_correction.processor.detection import DetectionProcessor
 from color_correction.schemas.custom_types import (
     ColorPatchType,
     ImageBGR,
@@ -153,6 +153,7 @@ def _extract_color_patches(
         Returns
         -------
         tuple[list[ColorPatchType], ImageType, ImageType | None]
+
             - List of BGR mean values for each detected patch
             - Grid visualization of detected patches
             - Debug visualization (if debug=True)