README.md

---
title: CellposeCellCounter_v5
emoji: 🔬
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.35.0
app_file: app.py
pinned: false
---

# CellposeCellCounter

Cell counting and viability from a phone photograph of a hemocytometer, using a
fine-tuned Cellpose-SAM model for segmentation and a single interpretable contrast
threshold for viability.

## How to use it

1. Photograph one 4×4 counting block through the phone adaptor.
2. Upload it and **tap once in the centre of the block**. The app detects the four
   corners and crops to it. This step is not optional — an uncropped frame covers far
   more than one block and the concentration would be wrong.
3. Run segmentation. Live/dead and concentration are reported together.

## Segmentation

Cellpose-SAM fine-tuned on 13 hand-corrected images (1,069 annotated cells) from this
imaging setup. Held-out performance on 6 further images (556 annotated cells, IoU 0.5):

| model | count error | precision | recall | F1 |
|---|---|---|---|---|
| **this model** | **−1.1%** | **0.940** | 0.926 | **0.933** |
| previous fine-tune | +40.6% | 0.656 | 0.932 | 0.768 |
| Cellpose-SAM, off the shelf | −63.7% | 0.741 | 0.238 | 0.319 |

The dominant error of the previous model was over-segmentation of debris: correcting
its output required 336 deletions against 79 additions.

## Viability

Each cell's mean grey level is divided by the median grey of a background annulus
around it (20 px wide, 2 px gap, neighbouring cells excluded). Cells scoring below
**1.0** — no brighter than the medium surrounding them — are called dead.

The threshold is not fitted: 1.0 means the cell has lost all refractile contrast
against its own local background. It was chosen from that reasoning and then tested
against 1,625 hand-labelled cells. On 556 held-out cells: **accuracy 0.993**, AUC
0.984, and per-field viability within **0.3 percentage points** of expert annotation.

Accuracy is insensitive to the annulus geometry: across widths of 8–40 px and gaps of
0–8 px, held-out accuracy varied by 0.7 points (four cells of 556).

No training data, calibration, scaler or colour information is used for viability.

## Note on the minimum size filter

It is **off by default** and should stay off. When enabled without an explicit value
it uses the 25th percentile of each image, so it always deletes a quarter of the
objects however clean the field is — measured on this dataset it removed 18–25% of
real cells, cut the count by the same fraction, and inflated viability by ~2 points
because dead cells are the smaller ones.

## Limitations

- Viability assumes brightfield imaging with an exclusion stain (live cells refractile,
  dead cells stained). It does not apply to fluorescence viability assays.
- The threshold is calibration-free *given a segmentation convention*. Changing what
  the mask covers — a different model, a different working resolution — shifts the
  measured ratio even though the cell has not changed.
- Any dark object accepted as a cell by segmentation will be called dead, so accuracy
  is bounded by segmentation quality.