cv2_group 1.0.0

A versatile toolkit to analyze roots within petri dishes.

---

cv2_group: Python toolkit for analyzing plant roots

Category	Badges
Testing
Package
License
Docker

About

cv2_group is a Python package that provides robust computer vision tools specifically designed for automated organ segmentation and landmark detection in images of plants grown in Petri dishes.

Modern plant science increasingly relies on high-throughput image analysis, but manually processing these images is often time-consuming and prone to inconsistency. This package addresses that challenge by offering a scalable and reliable solution. Built upon advanced computer vision models, cv2_group transforms raw plant images into valuable data, enabling researchers to efficiently track plant development, analyze organ morphology, and identify key anatomical landmarks.

At its core, cv2_group leverages a U-Net model to accurately segment plant organs and detect specific landmarks. The package is developed with a focus on modularity, ensuring it's easy to maintain, test, and extend for future research needs. It provides a powerful foundation for automated plant phenotyping, moving beyond manual analysis to deliver consistent and precise results at scale.

This system is designed to streamline data extraction from plant imagery, offering a crucial tool for accelerating research in plant biology, agriculture, and related fields.

Table of Contents

• cv2_group: Python toolkit for analyzing plant roots
  • About
  • Table of Contents
  • Main Features
  • Where to get it
  • Dependencies
  • Installing the package
    • Option 1: Install via PyPI
    • Option 2: Install via Poetry
  • Using the package
    • Command Line Interface (CLI)
    • Python API
      • Load image
      • Create patches
      • Load trained model
      • Analyize primary root
      • Map identified root labels
      • Visualize overlay
  • License
  • Documentation
  • Background
  • Contact

Main Features

The cv2_group package allows you to analyze roots within a petri dish, here are some of the most useful features:

• Cropping images based on the petri dish: Precisely isolates the area of interest in the image.
• Automated organ segmentation: Accurately identifies and delineates specific plant organs within the images using advanced U-Net models.
• Landmark detection: Pinpoints key anatomical points on the plants for detailed analysis.
• Support for image uploads: Facilitates easy integration of your image datasets for processing.
• Modular and maintainable design: Built as a fully modular Python package for easy maintenance, testing, and future extensions.
• API and CLI access: Provides flexible interfaces for users to interact with the system and perform analyses.
• Automated model performance tracking and continuous training support: Ensures the system remains accurate and up-to-date by monitoring prediction accuracy and triggering retraining with new data.

Where to get it

The latest release of cv2_group is available on PyPI:

pip install cv2_group

Dependencies

The cv2_group package relies on the following core dependencies to provide its functionality:

• numpy==1.23.5
• opencv-python==4.10.0.84
• scikit-image==0.22.0
• patchify==0.2.3
• tensorflow==2.10.0
• matplotlib==3.8.4
• pillow==10.3.0
• scikit-learn (version compatible with ^1.6.1)
• fastapi==0.110.0
• uvicorn==0.29.0
• typer==0.9.0
• click==8.1.3

These dependencies will be installed automatically when you install the cv2_group package using pip or Poetry

Installing the package

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.

poetry shell

Using the package

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

This command will process the specified image, applying the underlying models to generate predictions.

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")

Analyize 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)

License

MIT

Documentation

The official documentation is hosted on Github Pages

Background

Work on cv2_group started at Breda University of Applied Sciences BUas in 2025 and has been under development since then.

Contact

For questions, feedback, or contributions, feel free to reach out to the team:

• Martin Simons – Frontend Specialist – [e-mail]
• Yorbe Heeren – DMP Specialist – [e-mail]
• Arnout Opfergelt – Deployment Specialist – [e-mail]
• Victor Oorthuis – GitHub / Unit Testing / Documentation Specialist – [e-mail]
• Teun van der Wolf – Azure ML Specialist – [e-mail]

---

Go to Top