Metadata-Version: 2.4
Name: cv-pipeline-npec
Version: 0.1.0
Summary: NPEC plant organ segmentation and root tip detection pipeline
Project-URL: Homepage, https://github.com/BredaUniversityADSAI/cv-pipeline
Project-URL: Repository, https://github.com/BredaUniversityADSAI/cv-pipeline
Author-email: Filipp Lotsmanov <your@email.com>
License: MIT License
        
        Copyright (c) 2026 Filipp Lotsmanov
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: numpy>=1.24.0
Requires-Dist: opencv-python-headless>=4.8.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: requests>=2.31
Requires-Dist: segmentation-models-pytorch>=0.3.3
Requires-Dist: torch>=2.0.0
Requires-Dist: torchvision>=0.15.0
Description-Content-Type: text/markdown

# 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

```bash
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:

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

---

## Quick start

### Python API

```python
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

```bash
# 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:

```json
{
  "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

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

---

## License

MIT
