Merge pull request #13 from agfianf/docs/mcc

agfianf · web-flow · commit 7ff4b6fa84c3 · 2025-04-16T10:23:31.000+07:00
Docs/mcc
diff --git a/Makefile b/Makefile
@@ -28,3 +28,6 @@ sync-docs:
 
 sync-all:
 	uv sync --all-groups  --no-group dev-model
+
+docs-run:
+	uv run mkdocs serve -a localhost:8000
diff --git a/color_correction/__init__.py b/color_correction/__init__.py
@@ -1,10 +1,11 @@
-__version__ = "0.0.1-rc4"
+__version__ = "0.0.1-rc5"
 
 # fmt: off
 from .constant.color_checker import reference_color_d50_bgr as REFERENCE_COLOR_D50_BGR  # noqa: N812, I001
 from .constant.color_checker import reference_color_d50_rgb as REFERENCE_COLOR_D50_RGB  # noqa: N812, I001
 from .core.card_detection.det_yv8_onnx import YOLOv8CardDetector
-from .schemas.det_yv8 import DetectionResult as YOLOv8DetectionResult
+from .core.card_detection.mcc_det import MCCardDetector
+from .schemas.det_yv8 import DetectionResult
 from .services.color_correction import ColorCorrection
 from .services.correction_analyzer import ColorCorrectionAnalyzer
 # fmt: on
@@ -16,5 +17,6 @@
     "ColorCorrection",
     "ColorCorrectionAnalyzer",
     "YOLOv8CardDetector",
-    "YOLOv8DetectionResult",
+    "MCCardDetector",
+    "DetectionResult",
 ]
diff --git a/color_correction/core/card_detection/mcc_det.py b/color_correction/core/card_detection/mcc_det.py
@@ -8,11 +8,55 @@
 
 
 class MCCardDetector(BaseCardDetector):
+    """MCCardDetector implements card detection using OpenCV's ColorChecker detector (cv2.mcc).
+
+    This class detects ColorChecker cards and their color patches in an image using OpenCV's
+    built-in MCC ([Macbeth ColorChecker](https://docs.opencv.org/4.11.0/dd/d19/group__mcc.html)) detection module.
+    It provides methods to detect cards, extract patch coordinates, and visualize detections.
+
+    Parameters
+    ----------
+    use_gpu : bool, optional
+        Whether to use GPU for detection (not used in OpenCV MCC), by default False.
+    conf_th : float, optional
+        Confidence threshold for detection filtering, by default 0.15.
+    """
+
     def __init__(self, use_gpu: bool = False, conf_th: float = 0.15) -> None:
+        """
+        Initialize the MCCardDetector.
+
+        Parameters
+        ----------
+        use_gpu : bool, optional
+            Whether to use GPU for detection (not used in OpenCV MCC), by default False.
+        conf_th : float, optional
+            Confidence threshold for detection filtering, by default 0.15.
+        """
         self.use_gpu = use_gpu
         self.conf_th = conf_th
 
-    def detect(self, image: np.ndarray, conf: float = 0.15) -> DetectionResult:
+    def detect(self, image: np.ndarray, conf: float | None = None) -> DetectionResult:
+        """
+        Detect ColorChecker cards and their color patches in the input image.
+
+        Parameters
+        ----------
+        image : np.ndarray
+            Input image (BGR) in which to detect ColorChecker cards.
+        conf : float, optional
+            Confidence threshold for detection filtering, by default 0.15.
+
+        Returns
+        -------
+        DetectionResult
+            A dataclass containing detected segments (card and patch polygons),
+            confidence scores, and class IDs. Boxes are not used in this case (None).
+        """
+
+        if conf is None:
+            conf = self.conf_th
+
         ls_segments = []
         ls_class_ids = []
         ls_scores = []
@@ -63,6 +107,21 @@ def detect(self, image: np.ndarray, conf: float = 0.15) -> DetectionResult:
         )
 
     def _extract_chart_coordinates(self, image_copy: np.ndarray, charts_rgb: np.ndarray) -> list[list[tuple[int, int]]]:
+        """
+        Extracts the coordinates of color patches from the detected ColorChecker.
+
+        Parameters
+        ----------
+        image_copy : np.ndarray
+            Copy of the input image for visualization (patch points drawn).
+        charts_rgb : np.ndarray
+            Array of shape (N, 2) containing the (x, y) coordinates of patch corners.
+
+        Returns
+        -------
+        list of list of tuple of int
+            List of patches, each patch is a list of 4 (x, y) tuples.
+        """
         random_color = (np.random.randint(0, 255), np.random.randint(0, 255), np.random.randint(0, 255))
         ls_chart_coord = []
         ls_group_patch = []
@@ -94,6 +153,18 @@ def _extract_chart_coordinates(self, image_copy: np.ndarray, charts_rgb: np.ndar
         return ls_chart_coord
 
     def _draw_box_color_path(self, image_copy: np.ndarray, i: int, group_patch: list[tuple[int, int]]) -> None:
+        """
+        Draws a polygon and label for a color patch on the image.
+
+        Parameters
+        ----------
+        image_copy : np.ndarray
+            Image on which to draw the patch.
+        i : int
+            Index or label for the patch.
+        group_patch : list of tuple of int
+            List of 4 (x, y) tuples representing the patch corners.
+        """
         random_color = (np.random.randint(0, 255), np.random.randint(0, 255), np.random.randint(0, 255))
         # draw patch
         cv2.polylines(image_copy, [np.int32(group_patch)], True, random_color, 2)
diff --git a/color_correction/schemas/det_yv8.py b/color_correction/schemas/det_yv8.py
@@ -81,5 +81,5 @@ def draw_detections(
         """
         if self.boxes is not None:
             return draw_detections(image, self.boxes, self.scores, self.class_ids)
-        elif self.segment is not None:
+        if self.segment is not None:
             return draw_segmentation(image, self.segment, self.scores, self.class_ids)
diff --git a/color_correction/services/color_correction.py b/color_correction/services/color_correction.py
@@ -69,7 +69,7 @@ class ColorCorrection:
 
     def __init__(
         self,
-        detection_model: LiteralModelDetection = "yolov8",
+        detection_model: LiteralModelDetection = "mcc",
         detection_conf_th: float = 0.25,
         correction_model: LiteralModelCorrection = "least_squares",
         reference_image: ImageBGR | None = None,
diff --git a/color_correction/utils/yolo_utils.py b/color_correction/utils/yolo_utils.py
@@ -198,13 +198,18 @@ def draw_segmentation(
         color = COLORS[class_id]
         cv2.polylines(image, [np.int32(segment)], True, color, 2)
 
-        draw_text(
+        font_size = min(image.shape[:2]) * 0.0005
+        text_thickness = int(min(image.shape[:2]) * 0.001)
+
+        cv2.putText(
             image,
             f"{class_names[class_id]} {int(score * 100)}%",
             segment[0],
-            color,
-            font_size=0.001,
-            text_thickness=2,
+            cv2.FONT_HERSHEY_SIMPLEX,
+            font_size,
+            (255, 255, 255),
+            text_thickness,
+            cv2.LINE_AA,
         )
     return image
 
diff --git a/docs/assets/drawed_detection_mcc.jpg b/docs/assets/drawed_detection_mcc.jpg
diff --git a/docs/index.md b/docs/index.md
@@ -49,7 +49,7 @@ pip install color-correction
 ## 🤸 TODO
 
 - [ ] Add Loggers
-- [ ] Add detection MCC:CCheckerDetector from opencv
+- [x] Add detection MCC:CCheckerDetector from opencv
 - [ ] Add Segmentation Color Checker using YOLOv11 ONNX
 - [ ] Improve validation preprocessing (e.g., auto-match-orientation CC)
 - [ ] Add more analysis and evaluation metrics _(still thinking...)_
diff --git a/docs/reference/core/card_detection/mcc_detector.md b/docs/reference/core/card_detection/mcc_detector.md
@@ -0,0 +1,4 @@
+# `MCCardDetector` class
+
+
+::: color_correction.core.card_detection.mcc_det.MCCardDetector
diff --git a/docs/tutorial/color_correction.md b/docs/tutorial/color_correction.md
@@ -47,7 +47,7 @@ This is the main feature of this package. Its capture to color correct an image
 
     # Step 3: Initialize the color correction model with specified parameters
     color_corrector = ColorCorrection(
-        detection_model="yolov8",
+        detection_model="yolov8", # or "mcc"
         detection_conf_th=0.25,
         correction_model="affine_reg", # (1)
         degree=3,  # (2)
diff --git a/docs/tutorial/correction_analyzer.md b/docs/tutorial/correction_analyzer.md
@@ -2,7 +2,7 @@
 
 ## Introduction
 
-This package provides a class for analyzing color correction by combining various correction methods with object detection models. The analyzer offers multiple correction methods and customizable parameters that you can experiment with. For object detection, it currently supports `YOLOv8` (ONNX), with plans to expand to more models in the future. For correction methods, it supports `least squares`, `linear regression`, `affine regression`, and `polynomial regression`.
+This package provides a class for analyzing color correction by combining various correction methods with object detection models. The analyzer offers multiple correction methods and customizable parameters that you can experiment with. For object detection, it currently supports `YOLOv8` (ONNX) and [`Macbeth Detector`](../reference/core/card_detection/mcc_detector.md), with plans to expand to more models in the future. For correction methods, it supports `least squares`, `linear regression`, `affine regression`, and `polynomial regression`.
 
 The analyzer automatically runs all defined methods and generates a comprehensive report comparing visual results and `ΔE CIE 2000` values. You don't need to write complex code - simply define your desired methods and parameters, and let the analyzer do the work for you. This makes it easy to find the best color correction approach for your specific needs.
 
@@ -18,13 +18,14 @@ The analyzer automatically runs all defined methods and generates a comprehensiv
         curl -L -o input_image.jpg "https://drive.google.com/uc?export=download&id=1syOqw9kC0tt01p7yEobU4MeLfh336DZA"
         ```
 
-    ```python
+    ```python title="analyzer.py" linenums="1"
     # your_script.py
     import cv2
 
     from color_correction import ColorCorrectionAnalyzer
 
     input_image_path = "your_path_image"
+    ref_image_path = "your_path_ref_image"
 
     report = ColorCorrectionAnalyzer(
         list_correction_methods=[
@@ -38,20 +39,22 @@ The analyzer automatically runs all defined methods and generates a comprehensiv
         ],
         list_detection_methods=[
             ("yolov8", {"detection_conf_th": 0.25}),
+            ("mcc", {"detection_conf_th": 0.15}),
         ],
         use_gpu=False,
     )
 
     df_report = report.run(
         input_image=cv2.imread(input_image_path),
-        reference_image=None,
+        reference_image=cv2.imread(ref_image_path), # (2)
         output_dir="report-output", # (1)
     )
 
     df_report.head()
     ```
 
     1. 💬 The output directory where the report files will be saved.
+    2. 💬 The reference image is used for color correction and comparison. **This is Optional**
 
 === "Project Structure"
 
diff --git a/docs/tutorial/detect_card.md b/docs/tutorial/detect_card.md
@@ -1,20 +1,20 @@
 # Card Patches Detection
 
 ## Introduction
-This package has built-in support for detecting card patches in an image. This feature is useful for detecting color checker cards in an image. The detection is based on the YOLOv8 model. You can use the [`YOLOv8CardDetector`](../reference/core/card_detection/yv8_onnx.md) class to detect card patches in an image.
+This package has built-in support for detecting card patches in an image. This feature is useful for detecting color checker cards in an image. The detection is based on the YOLOv8 model. You can use the [`YOLOv8CardDetector`](../reference/core/card_detection/yv8_onnx.md) or [`MCCardDetector`](../reference/core/card_detection/mcc_detector.md)  class to detect card patches in an image.
 
 | :simple-onnx: | :simple-python: | :simple-opencv: | :simple-pydantic: |
 
-## Usage
+??? tip "If you don't have image to test"
 
-=== "Code"
+    You can download the sample image from the following link:
+    ```bash
+    curl -L -o input_image.jpg "https://drive.google.com/uc?export=download&id=1syOqw9kC0tt01p7yEobU4MeLfh336DZA"
+    ```
+## Usage YOLOv8CardDetector
 
-    ??? tip "If you don't have image to test"
+=== "Code"
 
-        You can download the sample image from the following link:
-        ```bash
-        curl -L -o input_image.jpg "https://drive.google.com/uc?export=download&id=1syOqw9kC0tt01p7yEobU4MeLfh336DZA"
-        ```
 
 
     ```python
@@ -49,6 +49,7 @@ This package has built-in support for detecting card patches in an image. This f
             ...,
             (248, 138, 805, 545),
         ],
+        "segments": null,
         "scores": [
             0.9755859375,
             ...,
@@ -73,8 +74,75 @@ This package has built-in support for detecting card patches in an image. This f
     The model detects two types of objects: a complete `card` and individual color `patches` (24 patches per card). Click the image to view full resolution detection results.
     ///
 
+## Usage MCCardDetector
+
+=== "Code"
+
+    ```python
+    import cv2
+
+    from color_correction import MCCardDetector
+    from color_correction.schemas.det_yv8 import DetectionResult
+
+    image = cv2.imread("your_image_path")
+    detector = MCCardDetector(conf_th=0.15)
+
+    result: DetectionResult = detector.detect(image=image)
+    drawed_image = result.draw_detections(image=image)
+    cv2.imwrite("drawed_detection.jpg", drawed_image)
+    ```
+
+
+
+    1. 💬 The model runs using onnx :simple-onnx:, which supports both CPU and GPU. The model will be **automatically downloaded** if not already present on your system.
+
+=== "output: DetectionResult"
+
+    ```json
+
+    {
+        "boxes": null,
+        "segment": [
+            [
+                [0.0, 0.0],
+                [0.0, 1.0],
+                [1.0, 1.0],
+                [1.0, 0.0],
+            ],
+            ...
+            [
+                [0.0, 0.0],
+                [0.0, 1.0],
+                [1.0, 1.0],
+                [1.0, 0.0],
+            ],
+        ], // (1)
+        "scores": [
+            0.9755859375,
+            ...,
+            0.8583984375,
+        ],
+        "class_ids": [
+            0, // (2)
+            ...,
+            1, // (3)
+        ],
+    }
+    ```
+
+    1.  💬 [`x1`, `y1`, `x2`, `y2`]: coordinates segment
+    2.  💬 for `patch` object
+    3.  💬 for `card` object
+
+=== "output: Drawed Detection"
+
+    ![Detection result](../assets/drawed_detection_mcc.jpg){ loading=lazy }
+    /// caption
+    The model detects two types of objects: a complete `card` and individual color `patches` (24 patches per card). Click the image to view full resolution detection results.
+    ///
 
 ## Reference
 
 - [`class` YOLOv8CardDetector](../reference/core/card_detection/yv8_onnx.md)
+- [`class` MCCardDetector](../reference/core/card_detection/mcc_detector.md)
 - [`class` DetectionResult](../reference/schemas/yv8_onnx.md)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -164,6 +164,7 @@ nav:
       - core:
         - card_detection:
           - YoloV8 ONNX: reference/core/card_detection/yv8_onnx.md
+          - MCC Detector: reference/core/card_detection/mcc_detector.md
         - correction:
           - Least Squares: reference/core/correction/least_squares.md
           - Linear Regression: reference/core/correction/linear_reg.md
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "color-correction"
-version = "0.0.1-rc4"
+version = "0.0.1-rc5"
 description = "help to do color correction on images based on color checker card classic 24 patch."
 keywords = ["color correction", "color-correction", "color consistency", "color-consistency", "vision", "computer vision"]
 readme = "README.md"
diff --git a/uv.lock b/uv.lock

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +# `MCCardDetector` class
++
++
 +::: color_correction.core.card_detection.mcc_det.MCCardDetector