From 7b6efdfb8c2006dee011d29a7f78326eb0b758f7 Mon Sep 17 00:00:00 2001 From: Tyr Wiesner-Hanks Date: Fri, 31 Jul 2026 09:59:54 -0400 Subject: [PATCH] Initial README edits First-round edits to README, prior to attempting installation --- README.md | 98 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 60 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index db33ef7..a1da84a 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,39 @@ # MATS — Morphometric Analysis Toolbox Measure leaf **area, length, and width** in real-world units from a photo of -leaves laid on a printed calibration template. MATS finds four fiducial markers -with RF-DETR, corrects perspective, segments each leaf with a fast Otsu -threshold by default (or the heavier BiRefNet model for tougher backgrounds), -and writes a measurements CSV. +leaves laid on a printed calibration template. -Pipeline in one line: **detect markers → perspective-correct → segment leaf → -measure → CSV**. +MATS has four main steps: +1. Locate four fiducial markers using an RF-DETR detection model. +2. Applies a transform to undo any perspective distortion. +3. Segments each leaf, using either a fast Otsu threshold (default option) or a BiRefNet segmentation model for tougher backgrounds. +4. Writes out a CSV of the measurements. > Companion code for the manuscript (target journal: *Plant Phenomics*). > BiRefNet is optional and runs entirely from a locally installed checkpoint (see [Model weights](#model-weights)). > For USDA users the model weights are hosted on Agdatacommons and the pipeline is available on SciNET +## Table of Contents + +1. [Installation](#installation) +3. [Model weights](#model-weights) +4. 2. [Setup??](#) + +5. [Outputs](#outputs) +6. [Running on a compute cluster](#running-on-a-compute-cluster) +7. [How it works](#how-it-works) +8. [Troubleshooting](#troubleshooting) +9. [Citing](#citing) +10. [License](#license) + --- -## Install -MATS needs only Python ≥ 3.9 — QR codes are decoded with OpenCV, so the default -install pulls everything from wheels with **no system libraries and no conda + +## Installation + +MATS requires only Python ≥ 3.9; the recommended `pip` installation method +pulls all required packages from wheels with **no system libraries and no conda required**. **pip (recommended):** @@ -29,9 +44,9 @@ cd Morphometric-Analysis-Toolbox-for-Segmentation pip install -e ".[app]" # ".[app]" adds the Streamlit GUI ``` -**Enhanced QR reading (optional).** OpenCV decodes clean codes reliably; for -tougher photos (glare, skew, blur) you can add the `pyzbar` + `qreader` -fallbacks. `pyzbar` needs the system library `zbar`: +**Enhanced QR reading (optional).** OpenCV reads QR codes well when they are oriented correctly and clearly +visible. For images with any issues affecting the QR codes (glare, skew, blur) you can add the `pyzbar` + `qreader` fallbacks. +`pyzbar` requires the system library `zbar`: ```bash pip install -e ".[app,qr]" @@ -44,17 +59,40 @@ If a code can't be read, the pipeline continues — just pass the template size manually with `-t` (e.g. `-t 10.5x9.5in`), so enhanced QR is a convenience, not a requirement. -Then fetch the model weights once and confirm the environment: +Finally, fetch the model weights and confirm the environment: ```bash mats fetch-weights # fetches the ~134 MB RF-DETR checkpoint (mandatory, default) mats fetch-weights --only birefnet --source lfs # optional: explicitly fetch the ~2.65 GB BiRefNet checkpoint mats doctor # checks weights, GPU/CPU device, QR backends ``` +--- + +## Model weights + +The checkpoints for both the marker detection model and the leaf segmentation model are located in this repository: + +| Model | File | Size | +|---|---|---| +| RF-DETR marker detector | `rf_detr_marker.pth` | ~134 MB | +| BiRefNet leaf segmenter | `birefnet_leaf.pth` | ~2.65 GB | + +By default, only the RF-DETR model checkpoint will be downloaded. +The BiRefNet checkpoint is LFS-tracked but excluded from the default clone, so it is +downloaded only through an explicit action: + +- **Otsu (default)** — needs no BiRefNet checkpoint and never downloads one. +- **BiRefNet (optional)** — fetch explicitly with + `mats fetch-weights --only birefnet --source lfs`, or use the setup page. +- **Shared filesystem** — set `MATS_WEIGHTS_DIR` (e.g. a SCINet `/project` path) + to read weights in place with no per-user copy. + +Full details and checksums: [docs/weights.md](docs/weights.md). + --- -## Choose your path +## Running MATS - **I want to click buttons →** [Using the app](#using-the-app) - **I want to script it →** [Using the command line](#using-the-command-line) @@ -63,20 +101,22 @@ Both run the exact same pipeline and produce the same measurements. --- -## Using the app +### Using the app + +MATS comes with a point-and-click user interface. To open it, simply run: ```bash mats app ``` -This opens the Streamlit GUI in your browser. From there: +This will open the Streamlit app locally in your web browser. From there: 1. **Pick images** — a local folder, or drag-and-drop uploads. 2. **Set the scale** — enter the printed sheet's width, height, and unit (e.g. `10.5 x 9.5 in`), or tick **Variable dimensions, read QR code** to read it from each image's template QR code automatically. -3. **Choose segmentation** — Otsu threshold (fast, default) or BiRefNet (accurate when its optional local checkpoint is installed). -4. **Choose workers** — the app detects the CPUs assigned to it. One worker uses +3. **Choose segmentation** — Otsu threshold (fast, default) or BiRefNet (accurate, must have local model checkpoint installed). +4. **Choose workers** — the app detects the number of CPUs available to it. One worker uses CUDA/MPS when available; two or more workers use parallel CPU processing and disable CUDA/MPS for that run. A colored warning light shows CPU allocation; counts above 75% require a one-run break-glass acknowledgement. @@ -91,7 +131,7 @@ photograph it flat. See [docs/templates.md](docs/templates.md). --- -## Using the command line +### Using the command line ```bash mats run -i ./images -o ./out -r results.csv -t 10.5x9.5in @@ -150,29 +190,11 @@ A `leaf_morpho_failures.csv` records per-image warnings and failures. --- -## Model weights - -The checkpoints are tracked in this repository with Git LFS: - -| Model | File | Size | -|---|---|---| -| RF-DETR marker detector | `rf_detr_marker.pth` | ~134 MB | -| BiRefNet leaf segmenter | `birefnet_leaf.pth` | ~2.65 GB | - -RF-DETR is available in a normal checkout. BiRefNet is LFS-tracked but excluded -from the default clone, so it is downloaded only through an explicit action: - -- **Otsu (default)** — needs no BiRefNet checkpoint and never downloads one. -- **BiRefNet (optional)** — fetch explicitly with - `mats fetch-weights --only birefnet --source lfs`, or use the setup page. -- **Shared filesystem** — set `MATS_WEIGHTS_DIR` (e.g. a SCINet `/project` path) - to read weights in place with no per-user copy. -Full detail and checksums: [docs/weights.md](docs/weights.md). --- -## On a cluster (HPC / Open OnDemand) +## Running on a compute cluster An Open OnDemand Batch Connect app that serves the GUI on a compute node is in [deploy/ondemand/mats/](deploy/ondemand/mats/). See its README and