Upload 4 files

README.md

@@ -1,210 +1,72 @@
 ---
-title: CellposeCellCounter_Mobile_v3d
-emoji: 🚀
-colorFrom: purple
-colorTo: pink
+title: CellposeCellCounter
+emoji: 🔬
+colorFrom: blue
+colorTo: indigo
 sdk: gradio
 sdk_version: 5.35.0
 app_file: app.py
 pinned: false
-license: apache-2.0
-short_description: Hemocytometer cell counter with one-tap grid detection
 ---
 
-> **v3d (2026-08-24) — grid detection made zoom-invariant.**
-> `grid_seeded.py` is the only file that differs from v3c; `app.py` is byte-identical
-> and needs no change. v3c sized its analysis window as a fixed fraction of the
-> image, so a more zoomed-in photo starved the period/phase search: the eight
-> photos in `misgana/20260818datacollection/Photos` came back with periods 10–20%
-> short and were rejected 8/8. v3d sizes the window in ruling periods and solves
-> for the period as a fixed point, so framing no longer matters. Acceptance is now
-> gated only on quantities measured against the image (`tooth_snr` is reported but
-> never gated), and the de-drift correction is weighted by the significance of its
-> own estimate instead of hard-switched.
->
-> Measured: 12/12 photos and 108/108 jittered taps accepted across both sessions
-> (v3c: 4/12); interior ruling error median 0.027 of a square; 0/5 negative
-> controls accepted; on synthetic phantoms with exactly known corners, corner
-> error 0.003 of a square and block area 1.0003 of truth. See the module
-> docstring in `grid_seeded.py` for the full rationale and numbers.
-
-
-# CellposeCellCounter (mobile)
-
-Open-source, low-cost cell counting from a phone photo of a hemocytometer.
-Segmentation uses a fine-tuned Cellpose model; viability uses a separate
-classifier. Everything runs in this Space — no local install, no instrument.
-
-## Two counting modes
-
-| tab | touches for four squares | when to use it |
-|---|---|---|
-| **fast_counting** | **5** — one upload, one tap per square | routine counts |
-| **comprehensive_counting** | 5, or 4 + 32 by hand | awkward images, or when you want the settings |
-| **confluency** | — | single-image confluency |
-
-Both counting tabs previously needed 4 uploads and 32 taps (four corners per
-square, two taps per corner via the zoom).
-
-### fast_counting
-
-1. Upload all four squares at once.
-2. Tap the centre of the 4×4 block in each image. One tap places all four
-   corners of that square.
-3. Press **Run**.
-
-The layout is deliberately spare, because the point is speed:
-
-1. the four squares, **two per row** so each is large enough to aim at —
-   tap the block centre; tap again to re-place
-2. per-square counts: total, live, dead, viability
-3. the means, and the time taken — then the live-cell concentration
-
-There is no separate row of raw frames: until you tap it, each image *is* the
-raw frame, so a second copy only cost the screen space that made the tap target
-too small to judge.
-
-No settings are exposed here. It uses the same defaults the comprehensive tab
-ships with (automatic minimum cell size, 1%/1% stereological exclusion,
-viability on). Change them there if you need to.
-
-Nothing is saved automatically. CSV and PDF are checkboxes under **Export**,
-both **off** by default. A square you never tapped is **skipped**, not counted
-whole-frame — counting a whole frame would silently inflate the concentration.
-
-### Why the tap is required, and not just a convenience
-
-An earlier version seeded each square from the centre of its frame, so no taps
-were needed. It looked like it worked: all four validation images produced a
-plausible block, high confidence, and good QC numbers.
-
-**It was wrong on one of the four, and none of the built-in checks could tell.**
-In `Q3` the intended block sits about 0.8 of a cell below the frame centre, so
-the phase fit snapped to the *neighbouring* set of rulings and placed the block
-one row too high — at confidence 0.99. The correct placement, seeded from the
-real block centre, scored *lower* (0.80).
-
-That is not a tuning problem, it is structural: a block placed on rulings 2–6
-instead of 1–5 sits on real printed lines just as well, so every
-line-agreement metric scores it perfectly. Nothing downstream can flag it.
-
-The tap fixes it because it puts the seed inside the intended block, which is
-the half-cell window the phase fit needs. **Still look at each proposed square before running** —
-the tap makes the common case right, it does not make the check unnecessary.
-
-### comprehensive_counting
-
-The previous workflow, unchanged, plus the one-tap option. Per-square upload
-(or the same bulk upload), settings, label correction, and the full summary.
-Its crop picker offers **Auto** (one tap in the centre of the block) or
-**Manual** (the original tap-roughly-then-tap-precisely corner flow). A failed
-auto-detect drops you into Manual and says why.
-
-## How grid detection works
-
-The hard part is that in a phone-through-eyepiece photo the rulings are only
-about 5–10 grey levels darker than the background, inside a circular
-illuminated field, covered in bright cells. Thresholding, Canny and Hough all
-throw them away — three such prototypes each resolved only 1 of 4 test images.
-
-What works is averaging *along* a ruling, so the line signal adds coherently
-while cells do not:
-
-1. **Seed.** Your tap anchors the phase, because the centre of a 4×4 block sits
-   on the middle ruling intersection. Working in a window around the tap also
-   triples the effective resolution versus whole-frame detection.
-2. **Rotation** from a profile-contrast sweep. This matters: a 2° tilt smears a
-   1-px ruling across ~15 px over a 450-px averaging span.
-3. **Period** from autocorrelation; **phase** from a 5-tooth comb fit scored by
-   its *weakest* tooth, so all five rulings must really be present. The search
-   floor excludes periods below ~170 px, which keeps it off the 0.05 mm
-   subdivisions of the central square — the target is the 0.25 mm lattice.
-4. **Refine.** Relocate all 25 ruling intersections, then fit similarity (4
-   parameters), affine (6) and homography (8) and pick between them — a richer
-   model is only accepted if it beats the simpler one by more than its extra
-   parameters would gain by chance.
-5. **De-drift.** Rectify the block, find where the five rulings actually sit,
-   and shift/scale so the edges land on the outer ones. See below.
-6. **Verify.** An independent check that re-finds the darkest line near each of
-   the 10 fitted grid lines and reports the disagreement in pixels.
-
-Detection is pure OpenCV on the CPU (`grid_seeded.py`) and is deliberately
-**not** behind `@spaces.GPU`, so it costs no ZeroGPU quota. Because it crops to
-the block, Cellpose then sees roughly 7× fewer pixels than a full frame.
-
-### The size bias, and why step 5 exists
-
-Rectifying each detected block and re-measuring the rulings showed the block
-coming out systematically **too large** — 8 of 8 axes drifted the same way, 1–4%
-per axis, a **+1.2% to +6.5% area bias, mean +3.8%**. Area bias goes straight
-into the cell count and therefore into the reported concentration.
-
-Step 5 removes it where it is real. The drift is estimated from five offsets
-that each carry ~10 px of noise, and an ungated version of the correction made
-one of the four images *worse*, so an axis is only corrected when its slope
-reaches 2 standard errors. One pass; iterating oscillates.
-
-Result: **mean |area bias| 3.8% → 1.3%, worst 6.5% → 2.6%**, two images
-corrected, two left alone, none made worse.
-
-### On perspective distortion
-
-The block is a projective quadrilateral when the phone is not square-on, and
-the code fits that. But read the numbers carefully: bootstrapping the
-homography gives a keystone standard deviation of 0.011–0.020, so on a single
-image **any keystone below about 4% is not distinguishable from noise.** On the
-four validation photos the model selection therefore settles on a rotated
-square, which is the honest answer.
-
-Against synthetic tilt the model escalates as it should: 4% keystone selects
-affine and lands within ~19 px of ground truth; 10% selects the homography,
-flags the keystone as significant, but reports low confidence and hands over to
-manual rather than returning a bad crop.
-
-## Validation
-
-Real photos, `test1_hemocytometer_Q1..Q4.jpg` (4080×3060, Improved Neubauer),
-seeded from the block centre:
-
-| | |
-|---|---|
-| ruling period | 329.7–338.7 px, CV 1.1% across images |
-| tilt recovered | −1.0° to +4.5° |
-| line-offset QC | 3.6–13.5 px mean = 1–4% of one small square |
-| residual area bias | −0.8% to +2.6%, mean magnitude 1.3% |
-| runtime | ~0.45 s per image, CPU |
-
-Synthetic images with known ground truth (period 200 px, tilts −1.0/+1.5/+4.5/
-+0.7°, faint 6-grey-level rulings, 700 bright cells, circular field): period
-recovered as **200 px exactly**, tilts within **0.2°**.
-
-Tap robustness — 36 taps jittered ±67 px (±0.20 of a square) around the block
-centre: 35/36 detected, 35/35 on the same block, corner agreement median 2.8 px.
-**Displace the tap a full half-cell and it can snap to the neighbouring block**
-— that is the ambiguity described above, and why the tap should land near the
-middle of the intended square.
-
-## Files
-
-| file | purpose |
-|---|---|
-| `app.py` | Gradio app — the three tabs |
-| `grid_seeded.py` | grid detection (CPU, no GPU, no model weights) |
-| `requirements.txt` | dependencies |
-
-Models are pulled from the Hub at startup: the fine-tuned Cellpose weights and
-`LiangLabUMB/viability_model`.
-
-## Known limits
-
-- **Confidence and QC cannot detect a whole-cell phase error.** They measure
-  whether the block sits on rulings, and a block one row off does. Look at the
-  proposed square.
-- Tuned on one microscope / phone / eyepiece combination at ~333 px per 0.25 mm
-  square. The period search brackets roughly a 3× magnification range; a very
-  different setup means rechecking `PER_LO_FR` / `PER_HI_FR`, not new code.
-- A field of view can contain both a 0.25 mm corner square and the 0.05 mm
-  subdivisions of the central square. The period floor keeps detection on the
-  0.25 mm lattice, but your tap still has to be in the block you mean.
-- The `confidence` score is a heuristic calibrated on four images; the accept
-  threshold is exposed as `ACCEPT_CONF`.
+# 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.

requirements.txt

@@ -1,12 +1,24 @@
-cellpose
-gradio>=5.35.0
+# Pinned deliberately. Two of these have already broken this app once:
+#   gradio 6 removed show_download_button and the UI failed to build;
+#   cellpose 4.0.1 deprecated the channels= argument, and a future major version
+#   could change model loading again. The Space rebuilds from this file on every
+#   restart, so an unpinned range means the app can break with no code change.
+cellpose==4.1.1
+gradio==5.35.0
 spaces
 opencv-python
+numpy
+scipy
 matplotlib
 Pillow
-numpy
 huggingface_hub
+
+# joblib and scikit-learn are needed ONLY if VIABILITY_METHOD is set back to
+# "model". The default local-contrast rule uses neither. Kept so that switch
+# still works; the sklearn pin matches the version viability_clf.pkl was fitted
+# under, since unpickling across versions is not guaranteed.
 joblib
-scikit-learn==1.6.1   # pinned: viability_clf.pkl was fitted under 1.6.1
-xgboost
-scipy
+scikit-learn==1.6.1
+
+# xgboost removed: never imported by app.py. It was only used by an offline
+# comparison script, where it scored measurably worse than the linear model.