Make color card chip size a metadata term & Enhance debug pcv.transform.detect_color_card

docs/std_color_matrix.md

@@ -18,6 +18,10 @@ Source: [https://en.wikipedia.org/wiki/ColorChecker](https://en.wikipedia.org/wi
         - pos = 2: top-right corner
         - pos = 3: top-left corner
 
+- **Context**
+    - A standard matrix can be used most readily while doing [affine](transform_affine_color_correction.md) color correction. 
+    Where possible it's recommended to use [`pcv.transform.detect_color_card`](transform_detect_color_card.md) which orders the color card mask as if the white chip were in the top-left corner, or `pos = 3`. 
+
 - **Returns**
     - color_matrix - a *n* x 4 matrix containing the standard red, green, and blue
     values for each color chip

docs/transform_detect_color_card.md

@@ -15,7 +15,10 @@ Automatically detects a color card and creates a labeled mask.
         - 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**
-    - labeled_mask     - Labeled color card mask (useful downstream of this step in `pcv.transform.get_color_matrix` and `pcv.transform.correct_color`)
+    - 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.  
 - **Example use:**
     - [Color Correction Tutorial](tutorials/transform_color_correction_tutorial.md)
 
@@ -33,9 +36,16 @@ 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)
 
-avg_chip_size = pcv.outputs.observations['default']['median_color_chip_size']['value']
-avg_chip_w = pcv.outputs.observations['default']['median_color_chip_width']['value']
-avg_chip_h = pcv.outputs.observations['default']['median_color_chip_height']['value']
+avg_chip_size = pcv.outputs.metadata['median_color_chip_size']['value'][0]
+avg_chip_w = pcv.outputs.metadata['median_color_chip_width']['value'][0]
+avg_chip_h = pcv.outputs.metadata['median_color_chip_height']['value'][0]
+
+# When using detect_color_card, you will always set pos=3
+tgt_matrix = pcv.transform.std_color_matrix(pos=3)
+headers, card_matrix = pcv.transform.get_color_matrix(rgb_img=rgb_img, mask=cc_mask)
+corrected_img = pcv.transform.affine_color_correction(rgb_img=rgb_img,
+                                                      source_matrix=card_matrix,
+                                                      target_matrix=tgt_matrix)
 
 ```
 

plantcv/plantcv/transform/detect_color_card.py

@@ -142,6 +142,9 @@ def detect_color_card(rgb_img, label=None, **kwargs):
     if len(filtered_contours) == 0:
         fatal_error('No color card found')
 
+    # 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)
     # Initialize chip shape lists
     marea, mwidth, mheight = _get_contour_sizes(filtered_contours)
 
@@ -172,18 +175,12 @@ def detect_color_card(rgb_img, label=None, **kwargs):
     new_centers = cv2.transform(np.array([centers]), m_transform)[0][:, 0:2]
 
     # Create labeled mask and debug image of color chips
-    labeled_mask, debug_img = _draw_color_chips(rgb_img, new_centers, radius)
+    labeled_mask, debug_img = _draw_color_chips(debug_img, new_centers, radius)
 
     # Save out chip size for pixel to cm standardization
-    outputs.add_observation(sample=label, variable='median_color_chip_size', trait='size of color card chips identified',
-                            method='plantcv.plantcv.transform.detect_color_card', scale='square pixels',
-                            datatype=float, value=chip_size, label="median")
-    outputs.add_observation(sample=label, variable='median_color_chip_width', trait='width of color card chips identified',
-                            method='plantcv.plantcv.transform.detect_color_card', scale='pixels',
-                            datatype=float, value=chip_width, label="width")
-    outputs.add_observation(sample=label, variable='median_color_chip_height', trait='height of color card chips identified',
-                            method='plantcv.plantcv.transform.detect_color_card', scale='pixels',
-                            datatype=float, value=chip_height, label="height")
+    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)
 
     # Debugging
     _debug(visual=debug_img, filename=os.path.join(params.debug_outdir, f'{params.device}_color_card.png'))