cv2_group Documentation

This project provides tools for processing petri dish images of plant roots and extracting root segmentation masks using computer vision and machine learning models.

It includes modules for data preprocessing, feature extraction, model training, and utility functions.

Installation

You can use cv2_group in your Python environment either by installing it directly from PyPI or by using Poetry for dependency management.

Option 1: Install via PyPI

If you’re using pip, simply run:

pip install cv2_group

This will automatically install all required dependencies listed in the package.

Option 2: Install via Poetry

If you have cloned the cv2_group repository (e.g., from GitHub) and want to set up its development environment or run it directly from the source code, navigate to the root directory of the repository (which contains the pyproject.toml file).

Then, simply run:

poetry install

This command will read the pyproject.toml file, create a dedicated virtual environment (if it doesn’t exist), and install all necessary project dependencies within it.

To activate the virtual environment shell, run:

poetry shell

Usage

Run the prediction pipeline on your petri dish images through CLI:

poetry run root-predictor path/to/image.jpg

The cv2_group package offers various functions organized into modules to help you analyze plant roots in petri dish images.

Command Line Interface (CLI)

For a quick start, you can run the main prediction pipeline directly from your terminal:

poetry run root-predictor path/to/image.jpg

Python API

You can also integrate cv2_group functions directly into your Python scripts for more customized workflows. Below is an overview of the key functions organized by their respective subpackages:

Load image

cv2_group.data.data_ingestion.load_image(image_path: str) -> ndarray

Loads an image from image_path and converts it to a grayscale NumPy array. Useful as the first step for processing.

from cv2_group.data.data_ingestion import load_image
image = load_image("path/to/your/image.jpg")

Create patches

cv2_group.data.data_processing.create_patches(image: ndarray, patch_size: int) -> Tuple[ndarray, int, int, ndarray]

Divides a grayscale image into non-overlapping square RGB patches of patch_size. Essential for processing large images with deep learning models.

from cv2_group.data.data_processing import create_patches
patches, num_rows, num_cols, padded_rgb_image = create_patches(image, patch_size=256)

Load trained model

load_trained_model(model_path)

Loads a pre-trained U-Net or other compatible model from a specified file path.

from cv2_group.models import load_trained_model
model = load_trained_model("path/to/your/model.h5")

Analyze primary root

cv2_group.features.feature_extraction.analyze_primary_root(root_instances: List[ndarray | None], original_roi_indices: List[int]) -> List[Dict[str, Any]]

Analyzes primary root characteristics from a list of individual root mask instances. Provides biological insights from segmented roots.

from cv2_group.features.feature_extraction import analyze_primary_root
analysis_results = analyze_primary_root(list_of_root_masks, corresponding_indices)

Map identified root labels

cv2_group.features.feature_extraction.find_labels_in_rois(label_ids: ndarray, totalLabels: int, stats: ndarray, centroids: ndarray, rois: List[Tuple[int, int, int, int]]) -> Tuple[Dict[str, int | None], List[int]]

Maps identified root labels (individual components) to predefined Regions of Interest (ROIs). Useful for spatially organizing analysis results.

from cv2_group.features.feature_extraction import find_labels_in_rois
mapped_labels, unassigned = find_labels_in_rois(labels, total, stats, centroids, rois_list)

Visualize overlay

cv2_group.utils.visualization.display_overlay(cropped_image: ndarray, predicted_mask: ndarray, alpha: float = 0.5, show: bool = False, return_png_bytes: bool = True) -> bytes | None

Creates a visual overlay of the predicted binary root mask on the original image, useful for quick visual validation or for web display.

from cv2_group.utils.visualization import display_overlay
overlay_bytes = display_overlay(original_image, predicted_mask, return_png_bytes=True)

Modules

• Data Subpackage
  • load_image()
  • rename_pairs()
  • upload_data()
  • upload_to_azure_datastore()
  • create_patches()
  • create_patches_alternative()
  • crop_image()
  • crop_image_with_bbox()
  • pad_image()
  • pad_image_alternative()
  • remove_padding()
  • uncrop_mask()
  • unpatch_image()
  • check_size_match()
  • is_binary_mask()
• Models Subpackage
  • load_trained_model()
  • save_model()
• Features Subpackage
  • analyze_primary_root()
  • extract_root_instances()
  • find_labels_in_rois()
  • process_predicted_mask()
• Utilities Subpackage
  • SaveImageRequest
  • get_azure_datastore()
  • get_azure_workspace()
  • initialize_azure_workspace()
  • is_azure_available()
  • load_model_from_azure_registry()
  • ensure_binary_mask()
  • get_dashboard_stats()
  • reset_dashboard_stats()
  • track_download()
  • track_image_processed()
  • track_mask_reanalyzed()
  • FeedbackAnalysisData
  • FeedbackEntry
  • FeedbackImageData
  • FeedbackSubmission
  • add_feedback_entry()
  • delete_feedback_entry()
  • get_blob_client()
  • get_blob_url()
  • get_feedback_entries()
  • get_feedback_entries_for_image()
  • initialize_feedback_storage()
  • load_feedback_data()
  • save_base64_image_to_blob()
  • save_feedback_data()
  • decode_b64_png_to_ndarray()
  • unpack_model_response()
  • LlamaRequest
  • LlamaResponse
  • LlamaService
  • predict_from_array()
  • predict_root()
  • create_side_by_side_visualization()
  • draw_all_root_skeletons_on_image()

About

This package consists of functions used to process images of petri dishes containing plant roots and generate predicted root segmentation masks.

It was developed as part of the 2024–2025 FAI2 ADSAI group project.

Authors: CV2

License: MIT