cv-pipeline-npec 0.1.0

NPEC plant organ segmentation and root tip detection pipeline

cv-pipeline

NPEC plant organ segmentation and root tip detection pipeline.

Accepts a Petri dish image, optionally auto-crops to the dish, runs a U-Net segmentation model to isolate plant organs, and returns root tip landmark coordinates with confidence scores.

---

Installation

pip install cv-pipeline

Requires Python ≥ 3.11. PyTorch is a dependency — if you need a specific CUDA version, install it separately before installing this package:

# Example: CUDA 12.1
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
pip install cv-pipeline

---

Quick start

Python API

from cv_pipeline import infer
from cv_pipeline.segmentation import SegmentationModel

# Load the model once and reuse across calls
model = SegmentationModel.from_checkpoint("path/to/best_model.pth")

result = infer(
    image_path="plate_001.tif",
    model=model,
    threshold=0.5,   # mask binarisation threshold
    crop=True,       # auto-detect and crop to Petri dish
)

print(result.landmarks)   # root tip (x, y) coordinates per plant
print(result.mask_b64)    # base64-encoded PNG segmentation mask

CLI

# Run inference on a single image
cv-pipeline infer \
    --image plate_001.tif \
    --output results/ \
    --model best_model.pth \
    --threshold 0.5

# Or reference a registered model version (downloaded and cached automatically)
cv-pipeline infer \
    --image plate_001.tif \
    --output results/ \
    --version v1

# Train a new model on image-mask pairs
cv-pipeline train \
    --data-dir data/train \
    --val-dir data/val \
    --output-dir models/ \
    --epochs 50 \
    --batch-size 16 \
    --lr 1e-4 \
    --device cuda

# Print package version
cv-pipeline version

infer flags

Flag	Default	Description
--image	required	Path to input image
--output	required	Directory to write results
--model	—	Path to a .pth checkpoint on disk
--version	—	Registered model version (mutually exclusive with --model)
--threshold	0.5	Mask binarisation threshold
--no-crop	off	Skip Petri dish detection and cropping
--plate-id	—	Optional plate identifier passed through to output
--experiment-id	—	Optional experiment identifier passed through to output
--timestamp	—	Optional ISO 8601 capture timestamp passed through to output

train flags

Flag	Default	Description
--data-dir	required	Training set directory (expects images/ and masks/ subdirs)
--val-dir	required	Validation set directory (same structure)
--output-dir	required	Where to write best_model.pth and run_metrics.json
--epochs	50	Number of training epochs
--batch-size	16	Batch size
--lr	1e-4	Initial learning rate
--device	cuda	Torch device: cuda, cpu, or cuda:N
--run-name	timestamp	Identifier for this run
--in-channels	1	Input channels: 1 for grayscale, 3 for RGB

---

Output format

infer writes two files to --output:

• <image_stem>_result.json — landmark coordinates, confidence scores, and metadata
• <image_stem>_mask.png — binary segmentation mask

The JSON schema follows the CV Pipeline Specification (task_328). Key fields:

{
  "version": "0.1.0",
  "landmarks": [
    {"plant_id": 1, "x": 412, "y": 890, "confidence": 0.94},
    ...
  ],
  "mask_b64": "<base64-encoded PNG>",
  "metadata": {
    "plate_id": "plate_001",
    "experiment_id": "exp_42",
    "timestamp": "2025-04-01T10:00:00Z"
  }
}

---

Development

git clone https://github.com/BredaUniversityADSAI/cv-pipeline
cd cv-pipeline
uv sync
uv run python -m pytest tests/unit/

---

License

MIT