danforthcenter · joshqsumner · Sep 8, 2025 · Sep 8, 2025 · Sep 8, 2025 · Sep 8, 2025
diff --git a/docs/img/documentation_images/deltaE/calibrated.png b/docs/img/documentation_images/deltaE/calibrated.png
diff --git a/docs/img/documentation_images/deltaE/uncalibrated.png b/docs/img/documentation_images/deltaE/uncalibrated.png
diff --git a/docs/img/documentation_images/qc_color_chip_comparison/input.png b/docs/img/documentation_images/qc_color_chip_comparison/input.png
diff --git a/docs/img/documentation_images/qc_color_chip_comparison/output.png b/docs/img/documentation_images/qc_color_chip_comparison/output.png
diff --git a/..._color_correction_scatter/am003_sv_ex.png → ..._color_correction_scatter/am003_sv_ex.png b/..._color_correction_scatter/am003_sv_ex.png → ..._color_correction_scatter/am003_sv_ex.png
diff --git a/...lor_correction_scatter/am003_sv_input.png → ...lor_correction_scatter/am003_sv_input.png b/...lor_correction_scatter/am003_sv_input.png → ...lor_correction_scatter/am003_sv_input.png
diff --git a/docs/img/documentation_images/qc_plot_delta_e/dataset_output.png b/docs/img/documentation_images/qc_plot_delta_e/dataset_output.png
diff --git a/docs/img/documentation_images/qc_plot_delta_e/uncalibrated_output.png b/docs/img/documentation_images/qc_plot_delta_e/uncalibrated_output.png
diff --git a/docs/params.md b/docs/params.md
@@ -57,6 +57,9 @@ the morphology sub-package. Default = 2.
 **px_height** Set the size scaling factor to enable automatic conversion between pixels and a real world unit, such as centimeters. Users can scale size measurements by updating the `unit`, `px_height` and `px_width` Default: `1`
 
 **px_width** Set the size scaling factor to enable automatic conversion between pixels and a real world unit, such as centimeters. Users can scale size measurements by updating the `unit`, `px_height` and `px_width` Default: `1`
+
+**deltaE** Set the deltaE calculation function for optional use throughout the `transform` submodule when detecting color cards or correcting color. Users can evaluate color correction and image quality using these delta E values per details in the [`transform.deltaE` docs](transform_deltaE.md). Default `deltaE_ciede2000`.
+
 ### Example
 
 Updated PlantCV functions use `params` implicitly, so overriding the `params` defaults will alter the behavior of

diff --git a/docs/qc_color_chip_comparison.md b/docs/qc_color_chip_comparison.md
@@ -0,0 +1,45 @@
+## Color Chip Comparison
+
+This function makes a plot comparing observed versus expected values from 1 or more color cards against a standard color card matrix via a "greenness rank". The greenness rank is useful in checking color card quality. The ninth (red) color chip is known to fade most quickly and the proportion of green light that it reflects can vary dramatically as the color card ages. The color of each bar is determined by the standard color matrix on the left side of the bar and by the observed color matrix on the right side of the bar. The order along the x axis is conserved from the order of `*args`.
+
+**plantcv.qc.color_chip_comparison**(*std_matrix, \*args*)
+
+**returns** plot, a altair.vegalite.v5.api.VConcatChart object
+
+- **Parameters:**
+    - std_matrix       - A numpy.ndarray as returned from [`pcv.transform.std_color_matrix`](std_color_matrix.md).
+	- \*args       - Any number of numpy.ndarrays as returned from [`pcv.transform.get_color_matrix`](get_color_matrix.md)
+
+- **Context:**
+    - The aim of this visualization is to help evaluate the condition of a color card or set of color cards.
+
+
+- **Example use:**
+    - Below
+
+**Dataset images:**
+
+![Screenshot](img/documentation_images/qc_color_chip_comparison/input.png)
+
+```python
+
+from plantcv import plantcv as pcv
+
+tgt_matrix = pcv.transform.std_color_matrix(pos=3)
+_, cc1_matrix = pcv.transform.get_color_matrix(rgb_img=img, mask=cc_mask)
+# ... masking more color cards for example
+_, cc6_matrix = pcv.transform.get_color_matrix(rgb_img=img, mask=cc_mask6)
+
+plot = pcv.qc.color_chip_comparison(tgt_matrix, cc1_matrix,
+                                           cc2_matrix, cc3_matrix,
+                                           cc4_matrix, cc5_matrix,
+                                           cc6_matrix)
+
+```
+
+**Color chip comparison visualizations:**
+
+![Screenshot](img/documentation_images/qc_color_chip_comparison/output.png)
+
+
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/qc/color_chip_comparison.py)
diff --git a/docs/visualize_color_correction_scatter.md → docs/qc_color_correction_scatter.md b/docs/visualize_color_correction_scatter.md → docs/qc_color_correction_scatter.md
@@ -2,7 +2,7 @@
 
 This function plots 4 panels of 2D scatter plot visualizations showing RGB and grayscale values of an input image, the expected color card, and optionally a color corrected image. The horizontal and vertical coordinates are defined by the intensity of the pixels in the specified channels. The color of each dot is given by the original RGB color of the image, ideal color card, or corrected image.
 
-**plantcv.visualize.color_correction_plot**(*color_matrix, std_matrix, corrected_matrix=None*)
+**plantcv.qc.color_correction_plot**(*color_matrix, std_matrix, corrected_matrix=None*)
 
 **returns** fig, axs
 
@@ -20,19 +20,19 @@ This function plots 4 panels of 2D scatter plot visualizations showing RGB and g
 
 **Dataset images:**
 
-![Screenshot](img/documentation_images/visualize_color_correction_scatter/am003_sv_input.png)
+![Screenshot](img/documentation_images/qc_color_correction_scatter/am003_sv_input.png)
 
 ```python
 
 from plantcv import plantcv as pcv
 
-fig, axs = pcv.visualize.color_correction_plot(colmat, stdmat, ccmat)
+fig, axs = pcv.qc.color_correction_plot(colmat, stdmat, ccmat)
 
 ```
 
 **Color correction scatter visualizations:**
 
-![Screenshot](img/documentation_images/visualize_color_correction_scatter/am003_sv_ex.png)
+![Screenshot](img/documentation_images/qc_color_correction_scatter/am003_sv_ex.png)
 
 
-**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/visualize/color_correction_scatter.py)
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/master/plantcv/plantcv/qc/color_correction_scatter.py)
diff --git a/docs/qc_plot_delta_e.md b/docs/qc_plot_delta_e.md
@@ -0,0 +1,56 @@
+## Plot Delta E
+
+This function creates an interactive chart visualizing per-chip Delta E (color difference) values from a color checker card. Each bar or point is colored by a standard interpretation category: green (<1) indicates imperceptible differences, progressing through yellow (<2, <10) to orange and red (<49, >49) for increasingly noticeable differences. Reference lines at the category boundaries are drawn for quick visual assessment. Standard chip color swatches from the target color matrix are displayed below the x-axis to aid chip identification.
+
+When passed a single `numpy.ndarray` of Delta E values, a bar chart is produced for that image. When passed a directory path or list of image paths, the function reads each image, computes Delta E, and returns a layered boxplot with jittered points so per-image variation is visible alongside the distribution.
+
+**plantcv.qc.plot_deltaE**(*source, n=20, ext="png", \*\*kwargs*)
+
+**returns** chart, an altair.vegalite.v5.api.LayerChart object
+
+- **Parameters:**
+    - source - one of:
+        - `numpy.ndarray` of per-chip Delta E values shaped to match the color card layout (e.g., (6, 4) for a 24-chip Macbeth card or (3, 5) for a 15-chip AstroBotany card), as returned from [`pcv.transform.deltaE`](https://github.com/danforthcenter/plantcv/blob/main/plantcv/plantcv/transform/detect_color_card.py). A bar chart is produced.
+        - `str` path to a directory of images (walked recursively). A boxplot is produced.
+        - `list` of file path strings to individual images. A boxplot is produced.
+    - n - (default: 20) maximum number of images to read when `source` is a directory path
+    - ext - (default: `"png"`) file extension filter when `source` is a directory path
+    - \*\*kwargs - additional arguments forwarded to [`pcv.transform.deltaE`](https://github.com/danforthcenter/plantcv/blob/main/plantcv/plantcv/transform/detect_color_card.py): `color_chip_size`, `roi`, `adaptive_method`, `block_size`, `radius`, `min_size`, `aspect_ratio`, `solidity`
+
+- **Context:**
+    - Used to evaluate the quality of color calibration by visualizing how closely observed chip colors match their expected values. Lower Delta E values indicate better color fidelity. The single-image bar chart is best used during workflow development to inspect calibration results interactively. The multi-image boxplot is useful for assessing calibration consistency across an experiment or imaging session.
+
+- **Example use:**
+    - Below
+
+**Dataset image:**
+
+![Screenshot](img/documentation_images/qc_plot_delta_e/input.png)
+
+```python
+from plantcv import plantcv as pcv
+from plantcv.plantcv.transform.detect_color_card import deltaE
+
+# Single image — bar chart
+de_matrix = deltaE(rgb_img=img, color_chip_size="classic")
+chart = pcv.qc.plot_deltaE(source=de_matrix)
+```
+
+**Delta E bar chart:**
+
+![Screenshot](img/documentation_images/qc_plot_delta_e/uncalibrated_output.png)
+
+```python
+# Directory of images — boxplot with jittered points
+chart = pcv.qc.plot_deltaE(source="/path/to/images", n=50, ext="png")
+
+# List of image paths — boxplot with jittered points
+image_paths = ["/path/to/img1.png", "/path/to/img2.png"]
+chart = pcv.qc.plot_deltaE(source=image_paths)
+```
+
+**Delta E boxplot:**
+
+![Screenshot](img/documentation_images/qc_plot_delta_e/dataset_output.png)
+
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/main/plantcv/plantcv/qc/plot_delta_e.py)
diff --git a/docs/quick_color_check.md b/docs/quick_color_check.md
@@ -5,16 +5,15 @@ be better off excluded from analysis . A quick way to examine this is by plottin
 masked in the color card.
 
 
-**plantcv.transform.quick_color_check**(*source_matrix, target_matrix, num_chips*)
+**plantcv.qc.quick_color_check**(*source_matrix, target_matrix=None, num_chips=None*)
 
 **returns** Altair chart
 
 - **Parameters**
-    - source_matrix - a 22x4 matrix containing the average red value, average green value, and
+    - source_matrix - an Nx4 matrix containing the average red value, average green value, and. See output of `plantcv.plantcv.transform.detect_color_card`.
                              average blue value for each color chip of the source image
-    - target_matrix - a 22x4 matrix containing the average red value, average green value, and
-                             average blue value for each color chip of the target image
-    - num_chips     - the number of color card chips included in the matrices (integer)
+    - target_matrix - an Nx4 matrix containing the average red value, average green value, and average blue value for each color chip of the target image. If `None`, the default, this will use output of `plantcv.plantcv.transform.std_color_matrix(pos=3)` or `plantcv.plantcv.transform.astro_color_matrix()` depending on the number of chips in the source matrix.
+    - num_chips     - the number of color card chips included in the matrices. Defaults to `None` which will use all rows of the target matrix.
 
 - **Context:**
     - Use the [`get_color_matrix`](get_color_matrix.md)
@@ -23,9 +22,8 @@ masked in the color card.
 
 from plantcv import plantcv as pcv
 
-chart = pcv.transform.quick_color_check(source_matrix=s_matrix,
-                                        target_matrix=t_matrix,
-                                        num_chips=24)
+chart = pcv.qc.quick_color_check(source_matrix=s_matrix,
+                                 target_matrix=t_matrix)
 
 ```
 **Perfect Color Correlation**
@@ -36,4 +34,4 @@ chart = pcv.transform.quick_color_check(source_matrix=s_matrix,
 
 ![Screenshot](img/documentation_images/quick_color_check/quick_color_plot2.png)
 
-**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/main/plantcv/plantcv/transform/color_correction.py)
+**Source Code:** [Here](https://github.com/danforthcenter/plantcv/blob/main/plantcv/plantcv/qc/quick_color_check.py)
diff --git a/docs/transform_deltaE.md b/docs/transform_deltaE.md
@@ -0,0 +1,66 @@
+## Calculate Delta E between observed and expected color cards
+
+Calculates Delta E between a Macbeth ColorChecker or Astrobotany.com Calibration sticker style color card and the expected color values.
+
+**plantcv.transform.deltaE**(*rgb_img, color_chip_size=None, roi=None, obs="calibrated", method="deltaE_ciede2000", \*\*kwargs*)
+
+**returns** Delta E matrix
+
+- **Parameters**
+    - rgb_img          - Input RGB image data containing a color card.
+    - color_chip_size - Type of color card to be detected, ("classic", "passport", "nano", "mini", "cameratrax", or "astro", 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`. 
+    - roi              - Optional rectangular ROI as returned by [`pcv.roi.rectangle`](roi_rectangle.md) within which to look for the color card. (default = None)
+	- obs              - label for metadata and debug images, typically "calibrated" or "uncalibrated" depending on whether the `rgb_img` has been color corrected.
+	- method           - Function name from `skimage.color` as a string to use to calculate delta E. Currently `deltaE_cie76`, `deltaE_ciede2000`, `deltaE_ciede94`, and `deltaE_cmc` are supported
+    - **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)
+        - aspect_ratio   - Optional aspect ratio (width / height) below which objects will get removed. Orientation agnostic since automatically set to the reciprocal if <1 (default = 1.27)
+        - solidity - Optional solidity (object area / convex hull area) filter (default = 0.8)
+
+- **Returns**
+    - deltaE            - Delta E values per each color chip as a matrix.
+
+- **Context**
+    - Delta E is a perception-based metric for the difference between colors. 0 indicates no perceptual difference and higher values indicate more difference. Generally a delta E value less than 1 is imperceptibly different and values greater than 3.5 are clearly distinct. Whether a particular color chip's delta E value matters for your experimental goals depends on your hypothesis and analysis plan.
+
+
+!!! note
+    Delta E is calculated when a color card is detected with `plantcv.transform.detect_color_card` by default
+	and a debug image is generated showing the differences in the color card against the expected colors.
+	This function will use `plantcv.transform.detect_color_card` to find the color card, potentially in an image that has already
+	been color-corrected so that the delta E values can be compared pre vs post calibration.
+	Delta E is also calculated by color correction functions in `plantcv.transform` if `deltaE` metrics exist in the outputs,
+	which is the default. Running `plantcv.transform.auto_correct_color` will add uncalibrated and corrected deltaE metrics by default.
+
+```python
+from plantcv import plantcv as pcv
+rgb_img, path, filename = pcv.readimage("target_img.png")
+
+pcv.params.debug = "plot"
+# Delta E debug visualization shown below
+cc_matrix = pcv.transform.detect_color_card(rgb_img=rgb_img)
+
+# Next we may color correct the image
+tgt_matrix = pcv.transform.std_color_matrix(pos=3)
+corrected_img = pcv.transform.affine_color_correction(rgb_img=rgb_img,
+                                                      source_matrix=cc_matrix,
+                                                      target_matrix=tgt_matrix)
+
+# Delta E on the corrected image
+e_matrix = pcv.transform.deltaE(corrected_img)
+# outputs metadata will have min, mean, max, std dev of deltaE
+print(pcv.outputs.metadata["deltaE_uncalibrated"])  # the uncalibrated metadata is added by detect_color_card
+print(pcv.outputs.metadata["deltaE_calibrated"]) # the calibrated metadata is added by deltaE
+```
+
+Calling `plantcv.transform.detect_color_card` on the uncorrected image:
+
+![Uncalibrated Color Card](img/documentation_images/deltaE/uncalibrated.png)
+
+Using `plantcv.transform.deltaE` on the corrected image to check the new Delta E values:
+
+![Calibrated Color Card](img/documentation_images/deltaE/calibrated.png)
diff --git a/docs/transform_detect_color_card.md b/docs/transform_detect_color_card.md
@@ -2,7 +2,7 @@
 
 Automatically detects a Macbeth ColorChecker or Astrobotany.com Calibration Sticker style color card and creates a labeled mask.
 
-**plantcv.transform.detect_color_card**(*rgb_img, color_chip_size=None, roi=None, \*\*kwargs*)
+**plantcv.transform.detect_color_card**(*rgb_img, color_chip_size=None, roi=None, delta_E=True, \*\*kwargs*)
 
 **returns** color_matrix
 
@@ -12,6 +12,7 @@ Automatically detects a Macbeth ColorChecker or Astrobotany.com Calibration Stic
     - color_chip_size - Type of color card to be detected, ("classic", "passport", "nano", "mini", "cameratrax", or "astro", 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`. 
     - roi              - Optional rectangular ROI as returned by [`pcv.roi.rectangle`](roi_rectangle.md) within which to look for the color card. (default = None)
+	- delta_E           - Boolean, should Delta E be calculated between the observed and expected color card values? This will add mean, std deviation, max, and min delta E values to `outputs.metadata`. See [`pcv.transform.deltaE`](transform_deltaE.md)
     - **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`.
@@ -45,19 +46,18 @@ Automatically detects a Macbeth ColorChecker or Astrobotany.com Calibration Stic
 from plantcv import plantcv as pcv
 rgb_img, path, filename = pcv.readimage("target_img.png")
 # 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")
+cc_matrix = 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))
+cc_matrix = 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]
 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,
+                                                      source_matrix=cc_matrix,
                                                       target_matrix=tgt_matrix)
 
 ```