metrics-petri

Petri dish colony segmentation and morphometric analysis.

metrics-petri measures how a biological sample grows on a petri dish: area, diameter, edge roughness, crack burden, texture entropy, and time-series growth rates — all in physical units calibrated from the dish geometry.

Workflow

  📁 Image folder
       │
       ▼
  metrics-petri-metadata          ← optional but recommended
       Step 1 · select folder (dates auto-detected)
       Step 2 · experiment name · start date · plates
       Step 3 · review and assign day codes per image
       Step 4 · export
       │
       │ writes
       ▼
  image_metadata.csv
       │ --metadata
       └───────────────────────────────────────┐
                                               │
  📁 Image folder ─────────────────────────► metrics-petri
                                               │
                                               ▼
                                          results.zip
                                          ├── analysis_full.csv
                                          ├── analysis_full.json
                                          ├── provenance.json
                                          ├── overlays/
                                          └── charts/  ← growth curves with day codes

metrics-petri-metadata is optional — metrics-petri can run on images alone, but supplying metadata enables growth-rate calculations and day-coded charts.

Four entry points, one package

Model checkpoint

The package bundles the SmallUNet checkpoint (best_area_w_0.7.pt, ~23 MB) inside the wheel. No separate download is needed after pip install. The bundled and downloaded checkpoint is verified against its packaged SHA-256 before use. The model was trained and validated using petrimodel — a companion repository covering training, annotation, sweep evaluation, and manual diameter validation against model-generated masks.

At run time the checkpoint is located in this order:

1. UNET_MODEL environment variable or --model flag
2. metrics_petri/models/best_area_w_0.7.pt in the current working directory
3. The installed package location (bundled in the wheel)
4. Hugging Face Hub fallback download from the pinned model revision, followed by SHA-256 verification

CLI batch pipeline

Use Python 3.10–3.13. If your system python3 is newer than that, call a supported interpreter explicitly, such as python3.12.

python3.12 -m venv petrienv
source petrienv/bin/activate
python -m pip install --upgrade pip
python -m pip install metrics-petri
metrics-petri input_images/

Processes every image in the folder and writes a ZIP containing result tables, provenance, overlays, and charts.

Images are resized internally to 256 × 256 RGB for SmallUNet inference, then the mask is mapped back to the source image. The default mask-confidence threshold is 0.5; lower values can include weaker colony signal but may add false positives, while higher values are stricter and may under-segment faint edges.

# With metadata for growth rate calculations and day-code charts
metrics-petri input_images/ --metadata input_images/image_metadata.csv

# JSON metadata is also accepted
metrics-petri input_images/ --metadata input_images/image_metadata.json

# Custom output path
metrics-petri input_images/ --output results/run01.zip

# Adjust segmentation threshold (default: 0.5)
metrics-petri input_images/ --threshold 0.45

# Use the actual outside diameter for non-standard dishes
metrics-petri input_images/ --dish-size-mm 60

# Set the PyTorch seed recorded in provenance (default: 0)
metrics-petri input_images/ --seed 123

# Custom model checkpoint
metrics-petri input_images/ --model /path/to/checkpoint.pt

Output ZIP

<user_or_experiment_name>.zip
├── analysis_full.csv         one row per image, all metrics
├── analysis_full.json        same data as a JSON array
├── provenance.json           run settings, versions, device, and model checksum
├── image_metadata.csv        copy of the input metadata (if supplied)
├── image_metadata.json       same metadata as JSON
├── overlays/                 per-image colony mask composites
└── charts/                   growth-rate charts (requires dates in metadata)

Example dataset

The source repository includes three example images under input_images/06FEB for smoke-testing and tutorials:

metrics-petri input_images/06FEB --output /tmp/metrics-petri-06feb.zip --seed 0

Metadata desktop GUI

metrics-petri-metadata is a native tkinter application for creating the image_metadata.csv that drives growth rate calculations and chart labelling.

Requirements: tkinter is part of the Python standard library.

• macOS / Windows: bundled with the official Python installer.
• Linux: sudo apt install python3-tk (or sudo dnf install python3-tkinter)

metrics-petri-metadata

Four-step flow:

1. Select Folder — browse to the image folder; dates are auto-detected from filenames, EXIF data, or file modification time.
2. Settings — enter experiment name, experiment start date, user name, and plate count.
3. Review & Edit Dates — a table lists every image with its date and day code (d01, d02, …); click any row to correct a date or set a reminder.
4. Export — writes image_metadata.csv, image_metadata.json, and optionally reminders.ics into the image folder.

Pass the exported file to the CLI with --metadata.

Dish cropper

metrics-petri-crop automatically detects and crops individual petri dishes from photos where several dishes were captured together in a single image (2–8+ per photo). It is a standalone utility — independent of the analysis pipeline.

metrics-petri-crop -i input_images/

Only fully visible dishes are extracted. Output filenames follow the pattern {stem}_dish_{NN}.png (or {YYYYMMDD}_{stem}_dish_{NN}.png with --date).

Measured metrics

Scale is derived from the detected dish circumference and the configured outside dish diameter. The default is 90 mm; pass --dish-size-mm when using another size. No separate calibration target is required.

Diagnostics

metrics-petri doctor

Checks Python, NumPy, Torch, accelerator (MPS/CUDA/CPU), model path, and all dependencies. Exits with code 1 on any issue.

At run time the pipeline selects CUDA first when available, then Apple MPS, then CPU.

Notebook walkthrough

An interactive notebook is available in the GitHub repository at notebooks/example_metrics-petri.ipynb. It traces the full pipeline — mask inference, dish detection, crack analysis, and growth metrics — with inline plots at each step.

The notebook is not distributed with the pip package. Clone the repository to use it.

Requirements

• Python ≥ 3.10
• PyTorch ≥ 2.1 (CPU works; MPS used automatically on Apple Silicon)
• tkinter — stdlib, bundled on macOS/Windows; sudo apt install python3-tk on Linux

License

MIT — full text

Citation

@software{Rohan_R_Metrics_Petri,
author = {{Rohan R}},
title = {{Metrics Petri: petri dish colony segmentation and morphometric analysis}},
url = {https://github.com/rotsl/metrics-petri},
version = {3.0.0},
year = {2026}
}