DOCSEARCHbyAlgolia
Submit Docs

PlantCV Documentation

repository·main·Indexed 21 days ago

https://github.com/danforthcenter/plantcv

An open-source computer vision library designed for plant phenotyping. PlantCV provides a modular framework for building image analysis workflows, featuring tools for image normalization, object segmentation (thresholding, background subtraction, and machine learning), and the extraction of shape, color, signal intensity, and morphological parameters. It supports transitioning from Jupyter Notebooks to parallelized Python scripts for large-scale dataset processing.

Tokens
99.5K
Snippets
330
Records
411
Agent score
72%

What's inside PlantCV

  1. Overview of PlantCV

    main

    PlantCV is an open-source image analysis software package designed for plant phenotyping. It provides a unified programming and documentation interface for a wide collection of image analysis techniques and algorithms.

    Key features include:

    • Modular Architecture: Allows for flexible design of analysis workflows and easy integration of new methods.
    • Integrated Algorithms: Combines techniques from various source packages into a single interface.
    • Extensibility: Designed for rapid assimilation of new computer vision methods for plant research.

  2. Overview of PlantCV capabilities

    main

    PlantCV is a modular computer vision library designed for plant phenotyping. It provides functions applicable to various plant types and imaging systems.

    Supported Image Types:

    • VIS: Standard RGB color images.
    • NIR: Standard grayscale images (e.g., near-infrared).
    • Thermal: Thermal infrared images.
    • PSII: Grayscale images from chlorophyll fluorescence imaging systems.
    • ENVI: Hyperspectral images.

    Development is ongoing, and support for additional image types is being actively worked on.

  4. Group images for multi-image workflows

    main

    If your workflow requires co-analyzing multiple images (e.g., an RGB image and a NIR image of the same plant), use the groupby and group_name parameters.

    1. groupby: A list of metadata keys that are shared by the images you want to group together (e.g., ["timestamp"]).
    2. group_name: The metadata key that distinguishes the different images within that group (e.g., "imgtype" to distinguish rgb from nir).

    When these are set, PlantCV will collect all images sharing the same groupby values and pass them to the workflow as a single group.

    {
    "filename_metadata": ["imgtype", "timestamp", "id", "other"],
    "groupby": ["timestamp"],
    "group_name": "imgtype"
}

  5. Access thermal observation data from pcv.outputs

    main

    Data generated by pcv.analyze.thermal is stored in the pcv.outputs.observations dictionary. The keys are structured by the sample label and the specific metric.

    If pcv.params.sample_label is set to "plant", you can access the temperature range like this:

    temp_range = pcv.outputs.observations['plant_1']['max_temp']['value'] - pcv.outputs.observations['plant_1']['min_temp']['value']
    temp_range = pcv.outputs.observations['plant_1']['max_temp']['value'] - pcv.outputs.observations['plant_1']['min_temp']['value']

  6. Calculate spectral indices from hyperspectral or RGB data

    main

    The plantcv.spectral_index subpackage provides functions to calculate various vegetation and pigment indices.

    Input Requirements

    • Hyperspectral Data: Most functions require a Spectral_data class instance, typically created using pcv.readimage with mode='envi' or mode='arcgis'.
    • RGB Data: Certain indices (like egi and gli) accept standard color images.
    • Flexibility: Most functions include a distance parameter (in nanometers) that allows the algorithm to select the closest available bands if the exact required wavelengths are not present in the input data.

    Return Value

    All functions return a calculated index array as an instance of the Spectral_data class.

    from plantcv import plantcv as pcv

# Example: Extract NDVI index from a hyperspectral datacube
ndvi_array = pcv.spectral_index.ndvi(hsi=spectral_data, distance=20)

  7. Use the plantcv.Objects class to manage image contours

    main

    The plantcv.Objects class is used to manage image contours/objects and their hierarchical relationships. While many PlantCV functions (especially in the roi sub-package) use this class implicitly, you can use it directly to manually manage, save, and load contour data.

    Attributes

    Access these via Objects.attribute:

    • contours: A list of contours (the points forming the outline of a shape, based on OpenCV contours).
    • hierarchy: A list of hierarchies (an array containing the relationship between contours, based on OpenCV hierarchies).

    Methods

    • append(contour, h): Append a specific contour and its hierarchy to the Objects instance.
    • save(filename): Save the current Objects instance to a file.
    • load(filename): Load an Objects instance from a file.
    from plantcv import plantcv as pcv

# Example of creating objects via an ROI function
roi_objects = pcv.roi.multi(img=img1, coord=(25,120), radius=20, 
                                      spacing=(70, 70), nrows=3, ncols=6)

# Saving and loading
roi_objects.save(filename="test.npz")
roi_object_copy = pcv.Objects.load(filename="test.npz")

  8. Access YII measurement observations

    main

    When plantcv.analyze.yii is executed, the resulting data is automatically stored in the pcv.outputs.observations dictionary. The keys follow a specific pattern based on the measurement type and the label parameter.

    Key Patterns:

    • yii_hist_{measurement_label}
    • yii_max_{measurement_label}
    • yii_median_{measurement_label}

    If pcv.params.sample_label is set to "plant", the observations are accessed via the plant index (e.g., ['plant_1']).

    # Accessing the median Fv/Fm value for plant 1 at time t0
# Assuming pcv.params.sample_label = "plant"
val = pcv.outputs.observations['plant_1']['yii_median_t0']['value']

  9. How the plantcv.params global configuration works

    main

    PlantCV uses a global parameters class, plantcv.params, to manage settings across the library. An instance of Params is automatically created when you import plantcv.

    Most updated PlantCV functions access this instance implicitly. This means that modifying an attribute on plantcv.params will change the behavior of subsequent function calls without you having to pass those arguments explicitly to every function. This is particularly useful for controlling debugging outputs, line styles in plots, and unit conversions.

    from plantcv import plantcv as pcv

# Modifying a global parameter affects subsequent function calls
pcv.params.debug = "plot"
pcv.params.line_thickness = 3

# These functions will now use the settings defined above
img, imgpath, imgname = pcv.readimage(filename="test.png")
roi = pcv.roi.rectangle(x=100, y=100, h=200, w=200, img=img)

  10. Isolate target objects using segmentation methods

    main

    Object segmentation (detection/isolation) is the first major step in a PlantCV workflow. You can use several approaches depending on your image type:

    1. Image Normalization

    • White Balancing: Reduces variation due to lighting changes.
    • Color Correction: Uses a reference color card to normalize color across a dataset (highly recommended for color analysis).
    • Scaling: Supported color cards can automatically convert pixel measurements to millimeters or $mm^2$.

    2. Segmentation Approaches

    • Thresholding: Selects a single channel (often after converting RGB to HSV or LAB) to perform binary thresholding or auto-thresholding (e.g., Gaussian, Otsu).
    • Background Subtraction: Uses 'null' images (images containing only the background) to isolate the object. See background_subtraction.md.
    • Machine Learning: Uses trained classifiers (e.g., naive Bayes) to segment features after a training set is built.

    3. Refinement

    • Noise Reduction: Use fill.md or blur modules (median_blur.md, gaussian_blur.md) to remove non-target spots.
    • Region of Interest (ROI): Define an area using roi_rectangle.md and filter objects using the roi.filter function.
    • Splitting/Connecting: Use functions to split multiple plants into individual objects for independent analysis.

  11. Understand the PlantCV hierarchical JSON output structure

    main

    When using parallel processing, PlantCV collects analysis outputs into a hierarchical JSON file. This structure is designed to be flexible, allowing different entities (like individual images) to have different sets of observations without requiring a rigid schema.

    The JSON file consists of two top-level sections:

    1. variables: A collection of all observation names found across the entire dataset, defining their category (either metadata or observations) and datatype.
    2. entities: A list of data blocks for each unit of analysis (e.g., an image or sub-region). Each entity contains:
      • metadata: Key-value pairs for image or experimental metadata (e.g., timestamp, treatment).
      • observations: A set of data blocks containing measurements. Each observation contains samples that follow the MIAPPE guidelines, including:
        • trait: The name of the observation.
        • method: The PlantCV function used.
        • scale: The units of measurement.
        • datatype: The Python data type.
        • value: The actual measurement value(s).
        • label: The data/category label.

    You can convert this JSON structure into tables for downstream analysis using the plantcv-utils json2csv command.

    {
    "variables": {
        "area": {
            "category": "observations",
            "datatype": "<class 'int'>"
        }
    },
    "entities": [
        {
            "metadata": {
                "image": {
                    "label": "image file",
                    "datatype": "<class 'str'>",
                    "value": "./images/snapshot57393/VIS_SV_0_z1_h1_g0_e65_117881.png"
                }
            },
            "observations": {
                "sample1": {
                    "pixel_area": {
                        "trait": "area",
                        "method": "plantcv.plantcv.analyze.size",
                        "scale": "pixels",
                        "datatype": "<class 'int'>",
                        "value": 10000,
                        "label": "pixels"
                    }
                }
            }
        }
    ]
}

  12. Access grayscale analysis data from plantcv.outputs

    main

    When plantcv.analyze.grayscale is executed, the resulting data is automatically stored in the pcv.outputs.observations dictionary.

    Stored Data Keys:

    • gray_frequencies: The proportion of pixels in each bin.
    • gray_mean: The mean grayscale value.
    • gray_median: The median grayscale value.
    • gray_stdev: The standard deviation of grayscale values.

    To access the data, use the pattern: pcv.outputs.observations['<label>_<index>']['<key>']['value'].

    # If sample_label was set to 'plant'
# and n_labels was 1
frequencies = pcv.outputs.observations['plant_1']['gray_frequencies']['value']