Add pcv.transform.mask_color_card function

docs/transform_mask_color_card.md

@@ -0,0 +1,47 @@
+## Mask out Color Card
+
+Automatically detects a color card and creates a bounding box mask. 
+
+**plantcv.transform.mask_color_card**(*rgb_img, \*\*kwargs*)
+
+**returns** color_card_mask
+
+- **Parameters**
+    - rgb_img          - Input RGB image data containing a color card.
+    - **kwargs         - Other keyword arguments passed to `cv2.adaptiveThreshold` and `cv2.circle`.
+        - adaptive_method - Adaptive threhold method. 0 (mean) or 1 (Gaussian) (default = 1).
+        - block_size      - Size of a pixel neighborhood that is used to calculate a threshold value (default = 51). We suggest using 127 if using `adaptive_method=0`.
+        - radius         - Radius of circle to make the color card labeled mask (default = 20).
+        - min_size         - Minimum chip size for filtering objects after edge detection (default = 1000)
+- **Returns**
+    - color_card_mask     - Bounding box mask of all detected color card chips 
+- **Context:**
+    - This function can be used with [`pcv.image_subtract`](image_subtract.md) to clean up noise in a plant mask that was introduced by the color card. This is helpful in cases where the color card placement is not consistent enough for region filters to clean the color card chips from all images in a dataset.
+- **Example use:**
+    - below 
+
+**RGB Image**
+
+![Screenshot](img/documentation_images/transform_mask_color_card/seedhead-rgb.jpg)
+
+**Seed head mask**
+
+![Screenshot](img/documentation_images/transform_mask_color_card/seedhead-with-cc.png)
+
+```python
+
+from plantcv import plantcv as pcv
+
+# Detect and mask the color card in the image
+cc_mask = pcv.transform.mask_color_card(rgb_img=img)
+
+# Remove color card chips from the plant mask with image subtract
+cleaned_mask = pcv.image_subtract(gray_img1=plant_mask, gray_img2=cc_mask)
+
+```
+
+**Cleaned mask**
+
+![Screenshot](img/documentation_images/transform_mask_color_card/seedhead-cleaned.png)
+
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/main/plantcv/plantcv/transform/detect_color_card.py)

docs/updating.md

@@ -973,6 +973,11 @@ pages for more details on the input and output variable types.
 * pre v4.2.1: NA
 * post v4.2.1: mtx, dist = **plantcv.transform.checkerboard_calib**(*img_path, col_corners, row_corners, out_dir*)
 
+#### plantcv.transform.mask_color_card 
+
+* pre v4.8:  NA 
+* post v4.8: color_card_mask = **plantcv.transform.mask_color_card**(*rgb_img, **kwargs*)
+
 #### plantcv.transform.rotate
 
 * post v3.12.0: rotated_img = **plantcv.transform.rotate**(*img, rotation_deg, crop*)

mkdocs.yml

@@ -187,6 +187,7 @@ nav:
           - 'Affine Color Correction': transform_affine_color_correction.md
           - 'Standard Color Matrix': std_color_matrix.md
           - 'Gamma Correction': transform_gamma_correct.md
+          - 'Mask Color Card': transform_mask_color_card.md
           - 'Merge Images': transform_merge_images.md
           - 'Nonuniform Illumination Correction': nonuniform_illumination.md
           - 'Perspective warp': transform_warp.md

plantcv/plantcv/transform/__init__.py

@@ -20,9 +20,10 @@
 from plantcv.plantcv.transform.checkerboard_calib import checkerboard_calib, calibrate_camera
 from plantcv.plantcv.transform.merge_images import merge_images
 from plantcv.plantcv.transform.auto_correct_color import auto_correct_color
+from plantcv.plantcv.transform.detect_color_card import mask_color_card
 
 __all__ = ["get_color_matrix", "get_matrix_m", "calc_transformation_matrix", "apply_transformation_matrix",
            "save_matrix", "load_matrix", "correct_color", "create_color_card_mask", "quick_color_check",
            "find_color_card", "std_color_matrix", "affine_color_correction", "rescale", "nonuniform_illumination", "resize",
            "resize_factor", "warp", "rotate", "warp", "warp_align", "gamma_correct", "detect_color_card", "checkerboard_calib",
-           "calibrate_camera", "merge_images", "auto_correct_color"]
+           "calibrate_camera", "merge_images", "auto_correct_color", "mask_color_card"]

plantcv/plantcv/transform/detect_color_card.py

@@ -8,7 +8,7 @@
 import numpy as np
 from plantcv.plantcv import params, outputs, fatal_error, deprecation_warning
 from plantcv.plantcv._debug import _debug
-from plantcv.plantcv._helpers import _rgb2gray
+from plantcv.plantcv._helpers import _rgb2gray, _cv2_findcontours, _object_composition
 
 
 def _is_square(contour, min_size):
@@ -83,8 +83,8 @@ def _draw_color_chips(rgb_img, new_centers, radius):
     return labeled_mask, debug_img
 
 
-def detect_color_card(rgb_img, label=None, **kwargs):
-    """Automatically detect a color card.
+def _color_card_detection(rgb_img, **kwargs):
+    """Algorithm to automatically detect a color card.
 
     Parameters
     ----------
@@ -103,16 +103,9 @@ def detect_color_card(rgb_img, label=None, **kwargs):
 
     Returns
     -------
-    numpy.ndarray
-        Labeled mask of chips.
+    list
+        Labeled mask of chips, debug img, detected chip areas, chip heights, chip widths, bounding box mask
     """
-    # Set lable to params.sample_label if None
-    if label is None:
-        label = params.sample_label
-    deprecation_warning(
-        "The 'label' parameter is no longer utilized, since color chip size is now metadata. "
-        "It will be removed in PlantCV v5.0."
-        )
     # Get keyword arguments and set defaults if not set
     min_size = kwargs.get("min_size", 1000)  # Minimum size for _is_square chip filtering
     radius = kwargs.get("radius", 20)  # Radius of circles to draw on the color chips
@@ -149,14 +142,15 @@ def detect_color_card(rgb_img, label=None, **kwargs):
     # Draw filtered contours on debug img
     debug_img = np.copy(rgb_img)
     cv2.drawContours(debug_img, filtered_contours, -1, color=(255, 50, 250), thickness=params.line_thickness)
+    # Find the bounding box of the detected chips
+    x, y, w, h = cv2.boundingRect(np.vstack(filtered_contours))
+
+    # Draw the bound box rectangle
+    boundind_mask = cv2.rectangle(np.zeros(rgb_img.shape[0:2]), (x, y), (x + w, y + h), (255), -1).astype(np.uint8)
+
     # Initialize chip shape lists
     marea, mwidth, mheight = _get_contour_sizes(filtered_contours)
 
-    # Create dataframe for easy summary stats
-    chip_size = np.median(marea)
-    chip_height = np.median(mheight)
-    chip_width = np.median(mwidth)
-
     # Concatenate all contours into one array and find the minimum area rectangle
     rect = np.concatenate([[np.array(cv2.minAreaRect(i)[0]).astype(int)] for i in filtered_contours])
     rect = cv2.minAreaRect(rect)
@@ -181,6 +175,84 @@ def detect_color_card(rgb_img, label=None, **kwargs):
     # Create labeled mask and debug image of color chips
     labeled_mask, debug_img = _draw_color_chips(debug_img, new_centers, radius)
 
+    return labeled_mask, debug_img, marea, mheight, mwidth, boundind_mask
+
+
+def mask_color_card(rgb_img, **kwargs):
+    """Automatically detect a color card and create bounding box mask of the chips detected.
+
+    Parameters
+    ----------
+    rgb_img : numpy.ndarray
+        Input RGB image data containing a color card.
+    **kwargs
+        Other keyword arguments passed to cv2.adaptiveThreshold and cv2.circle.
+
+        Valid keyword arguments:
+        adaptive_method: 0 (mean) or 1 (Gaussian) (default = 1)
+        block_size: int (default = 51)
+        radius: int (default = 20)
+        min_size: int (default = 1000)
+
+    Returns
+    -------
+
+    numpy.ndarray
+        Binary bounding box mask of the detected color card chips
+    """
+    _, _, _, _, _, bounding_mask = _color_card_detection(rgb_img, **kwargs)
+
+    if params.debug is not None:
+        # Find contours
+        cnt, cnt_str = _cv2_findcontours(bin_img=bounding_mask)
+
+        # Consolidate contours
+        obj = _object_composition(contours=cnt, hierarchy=cnt_str)
+        bb_debug = cv2.drawContours(np.copy(rgb_img), [obj], -1, (255, 0, 255), params.line_thickness)
+
+        # Debug image handling
+        _debug(visual=bb_debug, filename=os.path.join(params.debug_outdir, f'{params.device}_color_card.png'))
+
+    return bounding_mask
+
+
+def detect_color_card(rgb_img, label=None, **kwargs):
+    """Automatically detect a color card.
+
+    Parameters
+    ----------
+    rgb_img : numpy.ndarray
+        Input RGB image data containing a color card.
+    label : str, optional
+        modifies the variable name of observations recorded (default = pcv.params.sample_label).
+    **kwargs
+        Other keyword arguments passed to cv2.adaptiveThreshold and cv2.circle.
+
+        Valid keyword arguments:
+        adaptive_method: 0 (mean) or 1 (Gaussian) (default = 1)
+        block_size: int (default = 51)
+        radius: int (default = 20)
+        min_size: int (default = 1000)
+
+    Returns
+    -------
+    numpy.ndarray
+        Labeled mask of chips.
+    """
+    # Set lable to params.sample_label if None
+    if label is None:
+        label = params.sample_label
+    deprecation_warning(
+        "The 'label' parameter is no longer utilized, since color chip size is now metadata. "
+        "It will be removed in PlantCV v5.0."
+        )
+
+    labeled_mask, debug_img, marea, mheight, mwidth, _ = _color_card_detection(rgb_img, **kwargs)
+    # Create dataframe for easy summary stats
+    chip_size = np.median(marea)
+    chip_height = np.median(mheight)
+    chip_width = np.median(mwidth)
+
     # Save out chip size for pixel to cm standardization
     outputs.add_metadata(term="median_color_chip_size", datatype=float, value=chip_size)
     outputs.add_metadata(term="median_color_chip_width", datatype=float, value=chip_width)

tests/plantcv/transform/test_mask_color_card.py

@@ -0,0 +1,14 @@
+"""Tests for filters.color_card."""
+import cv2
+import numpy as np
+from plantcv.plantcv import params
+from plantcv.plantcv.transform.detect_color_card import mask_color_card
+
+
+def test_mask_color_card(transform_test_data):
+    """Test for PlantCV."""
+    # Load rgb image
+    params.debug = "plot"
+    rgb_img = cv2.imread(transform_test_data.colorcard_img)
+    cc_mask = mask_color_card(rgb_img=rgb_img)
+    assert np.array_equal(np.unique(cc_mask), np.array([0, 255]))