Release 4.0 - Update code base to utilize Objects class

[HaleySchuhl]

Is your feature request related to a problem? Please describe. Objects and contours are pervasive cv2 concepts that would require a code base overhaul to update all at once. We want to break up this large change through multiple, smaller pull requests.

Describe the solution you'd like There are many places where "contours" and "hierarchies" are utilized, and we wish to update each of these instances to allow users to utilize the Objects class. Make sure to create branches and open PR's against the release-4.0 branch.

Make each function update it's own PR. Developers, please note here in this issue which functionality you are working on so that multiple people don't try to update the same function twice. Update the function inputs & outputs, document these params in .md files, update tests, and reflect param changes in updating.md. Add name when started, check off when finished.

List of Functionality to update

• [x] pcv.find_objects --> Haley #947
• [x] pcv.roi.from_binary_image --> Haley #980
• [x] pcv.roi.rectangle --> Haley #946
• [x] pcv.roi.circle & pcv.transform.create_color_card_mask (nested) #993
• [x] pcv.roi.ellipse --> Haley #951
• [x] pcv.roi.custom --> Haley #953
• [x] pcv.report_size_marker_area --> Haley #955
• [x] pcv.roi.filter --> Jorge #1147
• [x] pcv.create_labels --> Haley #1149
• [x] Helper function for iterative analysis --> Noah #1148

List of functions requiring iteration

• [x] pcv.roi.roi2mask --> @JorgeGtz #952
• [x] pcv.auto_crop --> Haley #954 #1192
• [x] pcv.scale_features (should move into homology? ) --> @nfahlgren #1200
• [x] pcv.x_axis_pseudolandmarks (should move into homology also) --> Haley #1169
• [x] pcv.y_axis_pseudolandmarks (should move into homology also) --> Haley #1185
• [x] pcv.homology.acute --> @nfahlgren #1186
• [x] pcv.visualize.pseudocolor --> @nfahlgren #1184
• [x] pcv.morphology.segment_... ?? hopefully not (assume Haley will make any changes needed for this sub-package)
• [x] pcv.analyze_object --> pcv.analyze.size Noah #1154
• [x] pcv.analyze_color && histogram plotting helper --> pcv.analyze.color Noah #1170
• [x] pcv.analyze_bound_horizontal --> Jorge #1161
• [x] pcv.analyze_bound_vertical --> Jorge #1161
• [x] pcv.analyze_thermal_values --> @nfahlgren #1177
• [x] pcv.analyze_nir_intensity --> pcv.analyze.grayscale Noah #1172
• [x] pcv.hyperspectral.analyze_spectral --> @nfahlgren #1178
• [x] pcv.hyperspectral.analyze_index --> @nfahlgren #1179
• [x] pcv.photosynthesis.reassign_frame_labels --> @nfahlgren #1201
• [x] pcv.photosynthesis.analyze_yii --> @nfahlgren #1201
• [x] pcv.photosynthesis.analyze_npq --> @nfahlgren #1201

Deprecating

• [x] pcv.acute_vertex --> @nfahlgren #1187
• [x] pcv.rectangle_mask --> @nfahlgren #1209
• [x] pcv.object_composition --> @nfahlgren #1216
• [x] pcv.roi_objects - @HaleySchuhl #1228
• [x] pcv.cluster_contours_splitimg--> @HaleySchuhl #1196
• [x] pcv.cluster_contours --> @HaleySchuhl #1195
• [x] pcv.visualize.clustered_contours --> @HaleySchuhl #1229
• [x] pcv.analyze_color --> @nfahlgren #1190
• [x] pcv.analyze_horizontal_bound --> @nfahlgren #1188
• [x] pcv.analyze_vertical_bound --> @nfahlgren #1189
• [x] pcv.analyze_nir_intensity --> @nfahlgren #1205
• [x] pcv.analyze_object --> @nfahlgren #1206
• [x] pcv.analyze_thermal_values --> @nfahlgren #1207
• [x] pcv.hyperspectral.analyze_index --> @nfahlgren #1208
• [x] pcv.hyperspectral.analyze_spectral
• [x] pcv.rotate --> @afinit #1222

Wait to fix tutorials until we are done breaking stuff

• [x] Analysis approaches documentation page

Additional context Add any other context, sample data, or code relevant to the feature request here.

[HaleySchuhl]

Naming conventions

• Name ROI outputs roi
• Use objects and make sure it's always plural. Matches function names and the class.

[HaleySchuhl]

# Single plant workflow
from plantcv import plantcv as pcv

# Open image - no change from v3
img = pcv.readimage()

# Convert image (ex.) - no change from v3
gray_img = pcv.rgb2gray_hsv()

# Threshold/segment - no change from v3
bin_img = pcv.threshold.binary()

# Define ROI (ex.) - utilizes Objects
roi = pcv.roi.rectangle()

# Filter binary image to make a clean mask
# What if we take the ROI and mask?
mask = pcv.roi_objects(mask=bin_img, roi=roi, roi_type="partial")

# Create a labeled mask (background = 0, then increment
# by one for each object
# This function would run findContours on the input mask
# then iterate over the ROIs and run roi_objects
labeled_mask = pcv.create_labels(mask=mask, rois=roi)

# Then jump directly to analysis
# For object and bound, object composition happens internally
# find_contours is done automatically, internally per label
shape_img = pcv.analyze_object(img=img, mask=labeled_mask)
hline_img = pcv.analyze_bound_horizontal(img=img, mask=labeled_mask, line_position=600)
color_hist = pcv.analyze_color(rgb_img=img, mask=labeled_mask, colorspaces="hsv")

• [ ] Reduce the need for find_objects and combine some steps.
• [ ] Update the use cases and name of roi_objects to maybe something like roi_filter. We think that we want to limit the functionality to the case where an ROI is used to filter during segmentation of subjects & background; NO longer would be appropriate to segment between multiple ROIs to separate multiple subjects. Instead, utilize helper functions across both cases, and use a different name for multi plant. Suggested above is pcv.create_labels but I'd argue that pcv.roi_filter_multi feels like the easiest direction regarding naming.
• [ ] analyze_object should no longer take obj, instead be able to analyze a single object or many objects. Function should be able to recognize that it's being fed a labeled mask. Check to match if label parameter is a singular string or a list of strings. If there is one label provided but a labeled mask with multiple objects, then use index for label.

[HaleySchuhl]

Updates to pcv.roi_objects. No longer want to input Objects. Instead, just take a mask and find_objects behind the scenes. Reduce visualizations to just the clean mask. Return only clean_mask instead of lots of stuff.