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.

.. contents:: Table of Contents
   :local:
   :depth: 2

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:

.. code-block:: bash

   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:

.. code-block:: bash

   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:

.. code-block:: bash

   poetry shell

Usage
-----

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

.. code-block:: bash

   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:

.. code-block:: bash

   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.

.. code-block:: python

   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.

.. code-block:: python

   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.

.. code-block:: python

   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.

.. code-block:: python

   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.

.. code-block:: python

   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.

.. code-block:: python

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

.. toctree::
   :maxdepth: 2
   :caption: Modules

   data/index
   models/index
   features/index
   utils/index

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