Add support for automatic size scaling using color cards

docs/analysis_approach.md

@@ -50,9 +50,10 @@ of different ways in PlantCV.
 ##### Image Normalization
 
 *  [White balancing](white_balance.md) an image can help to reduce variation between images due to overall lighting changes. This may help 
-downstream image processing steps like thresholding to be the same between images. Normalizing color across a dataset using a reference
-color card with [color correction](https://plantcv.org/tutorials/color-correction) is also recommended, especially when color analysis is one 
-of the analysis objectives. 
+downstream image processing steps like thresholding to be the same between images. 
+* Normalizing color across a dataset using a reference
+color card with [color correction](https://plantcv.org/tutorials/color-correction) is highly recommended, especially when color analysis is one 
+of the analysis objectives. See the [detect color card documentation](transform_detect_color_card.md) for more detail.
 
 #####Object Segmentation Approaches
 

docs/analyze_size.md

@@ -18,7 +18,7 @@ Size and shape analysis outputs numeric properties for individual plants, seeds,
 - **Output data stored:** Data ('area', 'convex_hull_area', 'solidity', 'perimeter', 'width', 'height', 'longest_path',
 'center_of_mass, 'convex_hull_vertices', 'object_in_frame', 'ellipse_center', 'ellipse_major_axis', 'ellipse_minor_axis',
 'ellipse_angle', 'ellipse_eccentricity') automatically gets stored to the [`Outputs` class](outputs.md) when this function is
-run. These data can be accessed during a workflow (example below). For more detail about data output see
+run. These data can be accessed during a workflow (example below). Length and area type measurements can be scaled to real world units (e.g. mm and mm<sup>2</sup> using the `unit`, `px_height`, and `px_width` [parameters](params.md). For more detail about data output see
 [Summary of Output Observations](output_measurements.md#summary-of-output-observations)
 
 **Original image**

docs/transform_auto_correct_color.md

@@ -5,18 +5,19 @@ in the RGB space after automatic detection of a color card within the image. A o
 [plantcv.transform.detect_color_card](transform_detect_color_card.md), [plantcv.transform.std_color_matrix](std_color_matrix.md),
 [plantcv.transform.get_color_matrix](get_color_matrix.md), and [plantcv.transform.affine_color_correction](transform_affine_color_correction.md).
 
-**plantcv.transform.auto_correct_color**(*rgb_img, label=None, \*\*kwargs*)
+**plantcv.transform.auto_correct_color**(*rgb_img, label=None, color_chip_size=None, \*\*kwargs*)
 
 **returns** corrected_img
 
 - **Parameters**
     - rgb_img          - Input RGB image data containing a color card.
     - label            - Optional label parameter, modifies the variable name of observations recorded. (default = `pcv.params.sample_label`)
+    - color_chip_size  - Type of color card to be detected, (case insensitive, either "classic", "passport", or "cameratrax", by default `None`). Or provide `(width, height)` of your specific color card in millimeters. If set then size scalings parameters `pcv.params.unit`, `pcv.params.px_width`, and `pcv.params.px_height` are automatically set, and utilized throughout linear and area type measurements stored to `Outputs`.
     - **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)
+        - min_size         - Minimum chip size for filtering objects after edge detection (default = 1000) 
 - **Returns**
     - corrected_img    - Color corrected image
 
@@ -29,14 +30,11 @@ from plantcv import plantcv as pcv
 
 rgb_img, imgpath, imgname = pcv.readimage(filename="top_view_plant.png")
 
-corrected_rgb = pcv.transform.auto_correct_color(rgb_img=old_card)
+corrected_rgb = pcv.transform.auto_correct_color(rgb_img=rgb_img, color_chip_size="Passport")
 
-# Scale length & area Outputs collected downstream
-# by updating size scaling parameters
-pcv.params.unit = "mm"
+# Or set `color_chip_size` can be defined explicitly
 # E.G. Given a square color card chips, (11mm x 11mm) in size
-pcv.params.px_width = 11 /  pcv.outputs.metadata['median_color_chip_width']['value'][0]
-pcv.params.px_height = 11 /  pcv.outputs.metadata['median_color_chip_height']['value'][0]
+corrected_rgb = pcv.transform.auto_correct_color(rgb_img=rgb_img, color_chip_size=(11, 11))
 ```
 
 **Debug Image: automatically detected and masked the color card**

docs/transform_detect_color_card.md

@@ -1,14 +1,16 @@
 ## Automatically Detect a Color Card
 
-Automatically detects a color card and creates a labeled mask. 
+Automatically detects a Macbeth ColorChecker style color card and creates a labeled mask. 
 
-**plantcv.transform.detect_color_card**(*rgb_img, label=None, \*\*kwargs*)
+**plantcv.transform.detect_color_card**(*rgb_img, label=None, color_chip_size=None, \*\*kwargs*)
 
 **returns** labeled_mask
 
 - **Parameters**
     - rgb_img          - Input RGB image data containing a color card.
     - label            - Optional label parameter, modifies the variable name of observations recorded. (default = `pcv.params.sample_label`)
+    - color_chip_size - Type of color card to be detected, ("classic", "passport", or "cameratrax", by default `None`) or a tuple of the `(width, height)` dimensions of the color card chips in millimeters. If set then size scalings parameters `pcv.params.unit`, `pcv.params.px_width`, and `pcv.params.px_height`
+            are automatically set, and utilized throughout linear and area type measurements stored to `Outputs`. 
     - **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`.
@@ -18,7 +20,9 @@ Automatically detects a color card and creates a labeled mask.
     - labeled_mask     - Labeled color card mask (useful downstream of this step in [`pcv.transform.get_color_matrix`](get_color_matrix.md) and [`pcv.transform.correct_color`](transform_correct_color.md) and [`pcv.transform.affine_color_correction`](transform_affine_color_correction.md)).
 
 - **Context**
-    - This mask output will be consistent in chip order regardless of orientation, where the white chip is detected and labeled first with index=0. In the case of `affine_color_correction` one will make a target color matrix.  
+    - If the goal is to color correct the image colorspace to the standard color card values, consider using [`pcv.transform.auto_correct_color`](transform_auto_correct_color.md) since this new function is a one-step wrapper of plantcv.transform.detect_color_card, [plantcv.transform.std_color_matrix](std_color_matrix.md),
+    and [plantcv.transform.affine_color_correction](transform_affine_color_correction.md).
+    - This mask output will be consistent in chip order regardless of orientation, where the white chip is detected and labeled first with index=0.
 - **Example use:**
     - [Color Correction Tutorial](https://plantcv.org/tutorials/color-correction) since this function is called during [`pcv.transform.auto_correct_color`](transform_auto_correct_color.md). 
 
@@ -28,13 +32,16 @@ Automatically detects a color card and creates a labeled mask.
     There are a few important assumptions that must be met in order to automatically detect color cards:
 
     - There is only one color card in the image.
-    - Color card should be 4x6 (like an X-Rite ColorChecker Passport Photo). 
+    - Color card should be 4x6 [Macbeth ColorChecker](https://en.wikipedia.org/wiki/ColorChecker) like one of the supported color cards described below. 
 
 ```python
 
 from plantcv import plantcv as pcv
 rgb_img, path, filename = pcv.readimage("target_img.png")
-cc_mask = pcv.transform.detect_color_card(rgb_img=rgb_img)
+# Using a supported color card size will automatically set size scaling parameters
+cc_mask = pcv.transform.detect_color_card(rgb_img=rgb_img, color_chip_size="passport")
+# Or if using another Macbeth ColorChecker you can explicitly set the color chip size (in millimeters)
+cc_mask = pcv.transform.detect_color_card(rgb_img=rgb_img, color_chip_size=(12, 12))
 
 avg_chip_size = pcv.outputs.metadata['median_color_chip_size']['value'][0]
 avg_chip_w = pcv.outputs.metadata['median_color_chip_width']['value'][0]
@@ -53,4 +60,24 @@ corrected_img = pcv.transform.affine_color_correction(rgb_img=rgb_img,
 
 ![Screenshot](img/documentation_images/correct_color_imgs/detect_color_card.png)
 
+### Suppored Color Cards
+
+**[Calibrite ColorChecker Passport](https://calibrite.com/us/product/colorchecker-passport-photo-2/)** 
+
+![Screenshot](img/documentation_images/correct_color_imgs/calibrite-passport.png)
+
+Chip dimensions: 12mm x 12mm
+
+**[Calibrite ColorChecker Classic](https://calibrite.com/us/product/colorchecker-classic/)** 
+
+![Screenshot](img/documentation_images/correct_color_imgs/classic.png)
+
+Chip dimensions: 40mm x 40mm
+
+**[CameraTrax 24ColorCard-2x3](https://www.cameratrax.com/cardorder.php)** 
+
+![Screenshot](img/documentation_images/correct_color_imgs/camera-trax.png)
+
+Chip dimensions: 11mm x 11mm
+
 **Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/main/plantcv/plantcv/transform/detect_color_card.py)

docs/updating.md

@@ -1229,6 +1229,7 @@ pages for more details on the input and output variable types.
 
 * pre v4.6: NA
 * post v4.6: corrected_img = **plantcv.transform.auto_correct_color**(*rgb_img, label=None, \*\*kwargs*)
+* post v4.9: corrected_img = **plantcv.transform.auto_correct_color**(*rgb_img, label=None, color_chip_size=None, \*\*kwargs*)
 
 #### plantcv.transform.correct_color
 
@@ -1244,6 +1245,7 @@ pages for more details on the input and output variable types.
 
 * pre v4.0.1: NA
 * post v4.0.1: labeled_mask = **plantcv.transform.detect_color_card**(*rgb_img, label=None, \*\*kwargs*)
+* post v4.9: labeled_mask = **plantcv.transform.detect_color_card**(*rgb_img, label=None, color_chip_size=None, \*\*kwargs*)
 
 #### plantcv.transform.find_color_card
 

plantcv/plantcv/transform/auto_correct_color.py

@@ -5,16 +5,20 @@
 from plantcv.plantcv.transform.color_correction import get_color_matrix, std_color_matrix, affine_color_correction
 
 
-def auto_correct_color(rgb_img, label=None, **kwargs):
+def auto_correct_color(rgb_img, label=None, color_chip_size=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).
+    color_chip_size: str, tuple, optional
+        "passport", "classic", "cameratrax"; or tuple formatted (width, height)
+        in millimeters (default = None)
     **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)
@@ -33,7 +37,8 @@ def auto_correct_color(rgb_img, label=None, **kwargs):
         "It will be removed in PlantCV v5.0."
         )
     # Get keyword arguments and set defaults if not set
-    labeled_mask = detect_color_card(rgb_img=rgb_img, min_size=kwargs.get("min_size", 1000),
+    labeled_mask = detect_color_card(rgb_img=rgb_img, color_chip_size=color_chip_size,
+                                     min_size=kwargs.get("min_size", 1000),
                                      radius=kwargs.get("radius", 20),
                                      adaptive_method=kwargs.get("adaptive_method", 1),
                                      block_size=kwargs.get("block_size", 51))

plantcv/plantcv/transform/detect_color_card.py

@@ -178,6 +178,58 @@ def _color_card_detection(rgb_img, **kwargs):
     return labeled_mask, debug_img, marea, mheight, mwidth, boundind_mask
 
 
+def _set_size_scale_from_chip(color_chip_width, color_chip_height, color_chip_size):
+    """Set the size scaling factors in Params from the known size of a given color card target.
+
+    Parameters
+    ----------
+    color_chip_width : float
+        Width in pixels of the detected color chips
+    color_chip_height : float
+        Height in pixels of the detected color chips
+    color_chip_size : str, tuple
+        Type of supported color card target ("classic", "passport", or "cameratrax"), or a tuple of
+        (width, height) of the color card chip real-world dimensions in milimeters.
+    """
+    # Define known color chip dimensions, all in milimeters
+    card_types = {
+        "CLASSIC": {
+            "chip_width": 40,
+            "chip_height": 40
+        },
+        "PASSPORT": {
+            "chip_width": 12,
+            "chip_height": 12
+        },
+        "CAMERATRAX": {
+            "chip_width": 11,
+            "chip_height": 11
+        }
+    }
+
+    # Check if user provided a valid color card type
+    if type(color_chip_size) is str and color_chip_size.upper() in card_types:
+        # Set size scaling parameters
+        params.px_width = card_types[color_chip_size.upper()]["chip_width"] / color_chip_width
+        params.px_height = card_types[color_chip_size.upper()]["chip_height"] / color_chip_height
+    # If not, check to make sure custom dimensions provided are numeric
+    else:
+        try:
+            # Set size scaling parameters
+            params.px_width = float(color_chip_size[0]) / color_chip_width
+            params.px_height = float(color_chip_size[1]) / color_chip_height
+        # Fail if provided color_chip_size is not supported
+        except ValueError:
+            fatal_error(f"Invalid input '{color_chip_size}'. Choose from {list(card_types.keys())}\
+            or provide your color card chip dimensions explicitly")
+        # Fail if provided color_chip_size is integer rather than tuple
+        except TypeError:
+            fatal_error(f"Invalid input '{color_chip_size}'. Choose from {list(card_types.keys())}\
+            or provide your color card chip dimensions explicitly as a tuple e.g. color_chip_size=(10,10).")
+    # If size scaling successful, set units to millimeters
+    params.unit = "mm"
+
+
 def mask_color_card(rgb_img, **kwargs):
     """Automatically detect a color card and create bounding box mask of the chips detected.
 
@@ -216,15 +268,18 @@ def mask_color_card(rgb_img, **kwargs):
     return bounding_mask
 
 
-def detect_color_card(rgb_img, label=None, **kwargs):
-    """Automatically detect a color card.
+def detect_color_card(rgb_img, label=None, color_chip_size=None, **kwargs):
+    """Automatically detect a Macbeth ColorChecker style 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).
+    color_chip_size: str, tuple, optional
+        "passport", "classic", "cameratrax"; or tuple formatted (width, height)
+        in millimeters (default = None)
     **kwargs
         Other keyword arguments passed to cv2.adaptiveThreshold and cv2.circle.
 
@@ -253,11 +308,15 @@ def detect_color_card(rgb_img, label=None, **kwargs):
     chip_height = np.median(mheight)
     chip_width = np.median(mwidth)
 
-    # Save out chip size for pixel to cm standardization
+    # Save out chip size for pixel to mm 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)
     outputs.add_metadata(term="median_color_chip_height", datatype=float, value=chip_height)
 
+    # Set size scaling factor if card type is provided
+    if color_chip_size:
+        _set_size_scale_from_chip(color_chip_height=chip_height, color_chip_width=chip_width, color_chip_size=color_chip_size)
+
     # Debugging
     _debug(visual=debug_img, filename=os.path.join(params.debug_outdir, f'{params.device}_color_card.png'))
 

tests/plantcv/transform/test_detect_color_card.py

@@ -9,7 +9,15 @@ def test_detect_color_card(transform_test_data):
     """Test for PlantCV."""
     # Load rgb image
     rgb_img = cv2.imread(transform_test_data.colorcard_img)
-    labeled_mask = detect_color_card(rgb_img=rgb_img)
+    labeled_mask = detect_color_card(rgb_img=rgb_img, color_chip_size="classic")
+    assert len(np.unique(labeled_mask)) == 25
+
+
+def test_detect_color_card_set_size(transform_test_data):
+    """Test for PlantCV."""
+    # Load rgb image
+    rgb_img = cv2.imread(transform_test_data.colorcard_img)
+    labeled_mask = detect_color_card(rgb_img=rgb_img, color_chip_size=(40, 40))
     assert len(np.unique(labeled_mask)) == 25
 
 
@@ -27,3 +35,19 @@ def test_detect_color_card_incorrect_block_size(transform_test_data):
     rgb_img = cv2.imread(transform_test_data.colorcard_img)
     with pytest.raises(RuntimeError):
         _ = detect_color_card(rgb_img=rgb_img, block_size=2)
+
+
+def test_detect_color_card_incorrect_card_size(transform_test_data):
+    """Test for PlantCV."""
+    # Load rgb image
+    rgb_img = cv2.imread(transform_test_data.colorcard_img)
+    with pytest.raises(RuntimeError):
+        _ = detect_color_card(rgb_img=rgb_img, color_chip_size=100)
+
+
+def test_detect_color_card_incorrect_card_type(transform_test_data):
+    """Test for PlantCV."""
+    # Load rgb image
+    rgb_img = cv2.imread(transform_test_data.colorcard_img)
+    with pytest.raises(RuntimeError):
+        _ = detect_color_card(rgb_img=rgb_img, color_chip_size="pantone")