Count Cells With a Ready-Made Model and Check It by Hand | Heidelberg AI Curriculum
T18-L01
Count Cells With a Ready-Made Model and Check It by Hand
Run Cellpose, a free pretrained cell-segmentation model, on a public microscopy image on your own laptop. Check its outlines by eye, compare its count with your own count of one region, and learn the signals that tell you not to trust a count before it goes into your notebook.
You have twelve fluorescence images from yesterday's experiment. Your supervisor wants the number of cells per field by Friday. Counting by hand, clicking once on every cell with Fiji's multi-point tool, takes you twenty minutes per image, and by image eight you're no longer sure you counted the same way as in image one.
A colleague says there's a free model that outlines every cell in seconds. You try it, and it gives a number. But is it the right number? Did it count the cell cut in half by the image edge? The two cells that touch? The bright speck of debris in the corner?
In an imaging lab this is a cell count for a proliferation or spreading assay. In a molecular-biology lab it's a nuclei count to normalise a transfection or a knock-down. Either way, a ready-made model can save you hours, but only if you know where it goes wrong. This book shows you how to run one on your own laptop, check it against your own count of one region, and spot the images where you shouldn't trust it. You are at Level 1 User: the count is for your own notebook, so a wrong number costs you a recount, not a paper.
After this you can
Install Cellpose on an ordinary laptop and segment a public sample image with its default pretrained model.
Check the masks by eye and name what the model got wrong: merges, splits, fragments and missed cells.
Compare the model's count with your own manual count of one region, using a counting rule you wrote down first.
Say for a new image whether you would trust the count, and why.
Cellpose, a free pretrained model (already trained, so you use it as it comes) that outlines each cell, a job called segmentation. Each outline is called a mask. You use it through its graphical interface: a normal window with buttons, so you don't write any code. It runs offline once installed, and your images never leave your laptop. That matters for unpublished data.
Fiji, optional: a free image-analysis program, needed only if you have to split an image's colour channels. Download it from the Fiji download page, unzip it and start it; there's no installer.
(opens in a new tab)
Hardware: an ordinary Windows, Mac or Linux laptop with at least 8 GB of memory (RAM, shown on your computer's About page) and about 4 GB of free disk space for Python (the programming language Cellpose runs on), the software and the model. No graphics card is needed; without one, a small image takes minutes instead of seconds.
About 60 minutes: 14 to read, about 15 to install, about 30 to do.
Last verified 23 September 2026. Cellpose 4.2.1.1 is the current version, and the software is free. Its models were trained on data licensed for non-commercial use, so ask your institution before commercial work. The model downloads once, about 1.2 GB. Details for experts at the end of this book.
Set up (15 minutes)
This is the one part of the book that uses typed commands. Type each line exactly as shown and press Enter.
No terminal? If you can't or may not type commands on your computer, use QuPath instead: a free image-analysis program with an ordinary installer for Windows and Mac. Its InstanSeg extension, a ready-made model for fluorescence and brightfield images, installs from inside QuPath: open Extensions → Manage extensions and click the green + next to Deep Java Library first, then next to InstanSeg. It downloads its model by itself. The buttons differ from this book, but the method doesn't: a written counting rule, one region counted by hand, and a comparison.
Download and install Miniforge from its GitHub page (opens in a new tab): scroll to Install and pick the file for your system. Miniforge installs Python and a tool called conda, which keeps Cellpose in its own separate space so it can't disturb other software. On Windows, take the file ending Windows-x86_64.exe, run it and keep the option to create Start-menu shortcuts. On a Mac, take the .pkg file ending arm64 for a Mac with an Apple chip or x86_64 for an Intel Mac (Apple menu → About This Mac tells you which), and double-click it; under Customise, tick Add conda initialization to the shell. On Linux, follow the two commands on that page.
Open the Miniforge Prompt (Windows Start menu) or the Terminal app (on a Mac, in Applications → Utilities). This is a window where you type commands.
Run the three commands below, one at a time, and let each finish. The first creates a separate space called cellpose, the second switches into it, and the third downloads and installs Cellpose with its window. On a Mac, type the last line with quotes: python -m pip install 'cellpose[gui]'.
Start the interface with python -m cellpose. A window opens. Leave the prompt window open: Cellpose writes its progress there. The first time you run the model, Cellpose downloads it, so stay online.
Download demo_images.zip and unzip it into a folder you can write to, such as Documents: on Windows right-click it and choose Extract All, on a Mac double-click it. Cellpose saves its results next to the image.
Next time, you only need conda activate cellpose and python -m cellpose.
The idea in one page
A segmentation model looks at an image and draws one outline, a mask, around each object it takes for a cell. The count is simply the number of masks. It doesn't know your counting rules. Five facts decide how far you can trust it:
What the model does
What you do about it
1. It learned from images like its training set. Cellpose's models were trained on stained cells and nuclei, and on tissue sections, with cells mostly 7.5 to 120 pixels across (on average 30).
On images like that it's usually very good. On anything else (crystals, colonies, very large cells, unusual stains) treat every count as unchecked until you've counted by hand.
2. It looks at up to three colour channels, a channel being the image of one stain, shown in one colour. It was trained on a cytoplasm stain plus a nuclear stain, in either order.
Give it the channels that show the cells. A third stain can confuse it. For nuclei only, give it the nuclear channel alone.
3. It outlines what it sees, not what you mean. A cell cut by the image edge becomes a mask. So can a piece of debris.
Decide your counting rule before you look at the result: what counts, what doesn't, what happens at the edge.
4. It struggles where cells crowd. Touching cells can merge into one mask or one cell can split into two.
Check the densest part of the image, not the easy part. That's where the count drifts.
5. It sounds exactly as sure on a bad image as on a good one. "112 ROIs" looks the same whether it's right or wrong.
Count one region by hand every time you meet a new kind of image. If your count and the model's agree, the rest of that kind of image is probably fine.
So you don't recount the whole image. You count one region, big enough to hold 10 to 30 cells, counted with your rule, compared with the masks in the same region. The difference, and the reason for it, is the real result of this book.
When not to trust the count at all: the masks don't follow the cells when you look; the image is out of focus or saturated (so bright that parts are pure white); the cells are much larger or smaller than usual (set the diameter and check again); or the objects aren't cells. A count you can't check is a count you don't report.
Research situation 1: an imaging lab counting cells per field
Structure it."I need the number of cells per field in fluorescence images with a green cytoplasm stain and a blue nuclear stain, so I can compare conditions. A useful result: a count I'd defend to my supervisor, made the same way in every image."
Understand it. She opens img04.png from the demo folder: about thirty cells, green bodies and blue nuclei, some touching, several cut off by the edge. She drags it into the Cellpose window. In the Segmentation box she leaves the model drop-down on the default, cpsam_v2, and clicks run. After a few minutes on her laptop, coloured masks appear and the panel says 31 ROIs: 31 masks, since ROI means "region of interest". She presses Z to show outlines. Most outlines follow the cells well. But 8 of the 31 masks touch the image border, and some of those are only slivers of a cell. One pair of touching cells has a boundary that runs through the green where she can't see one. She realises that "cells per field" was never defined. Does a half cell at the edge count? Back to Structure it: "Count a cell if its nucleus is fully inside the field. Cells whose nucleus is cut by the edge don't count. Report the edge cells separately so nobody thinks they were forgotten."
Build it. She zooms into the top-left quarter of the image with the scroll wheel. With masks off (X), she counts cells by her rule and marks them in her notebook sketch: 9. With masks on, she finds 10 masks in the same quarter. One is an edge sliver her rule excludes, which leaves 9. They match. She checks the touching pair in the middle and decides the model's split is plausible: two nuclei, two cells. She takes a screenshot with outlines on and saves the masks with File → Save masks as PNG/tif. Her notebook line: "img04, Cellpose 4.2.1.1, cpsam_v2, default settings. 31 masks, 8 touch the edge. Top-left quarter: manual 9, model 9 (10 masks, 1 excluded by the nucleus-inside rule). Where it failed: edge slivers counted as cells; one boundary between touching cells to watch."
What it taught her: the model's count was fine in the middle. The number that would have been wrong was hers, because she had no rule for the edge.
Research situation 2: a molecular-biology lab counting nuclei
Structure it."I transfect cells in a 24-well plate and need the number of nuclei per field to normalise my reporter signal. A useful result: nuclei counts I can trust across wells, including the crowded ones."
Understand it. He opens a demo image with a blue nuclear stain and green cells, img20.png, and runs the default model. It outlines the whole cells, not the nuclei. That's fact 2: it segments what the channels show. So he gives it the nuclear stain alone. On his own microscope that's easy, because each channel is saved as a separate TIFF, a common microscope image file. For the demo image he splits the channels in Fiji (Image → Color → Split Channels), saves the blue one, and runs Cellpose on that. Now the masks sit on nuclei, and on the well-spread demo cells they look clean. Then he tries one field of his own, stained with DAPI, the usual blue nuclear stain, from a well so full that the cells cover the whole surface. There, in the corner where nuclei pile up, two touching nuclei come out as one mask, and one large nucleus is split in two. Back to Structure it: "Nuclei per field, with the check done in the densest region, because that's where the count drifts."
Choose tools. Fiji to split channels and for the manual count; Cellpose to outline. He leaves the diameter at the default, since the nuclei are of ordinary size: one change at a time.
Build it. He picks the crowded corner of his own field as his check region, counts the nuclei by hand (17), then counts the masks in the same region (16): one merge, one split and one missed dim nucleus, which nets to minus one. In the sparser parts of the field, a quick look shows no problems. His notebook line: "Nuclei channel only, cpsam_v2, default settings. Crowded corner: manual 17, model 16. Where it failed: touching nuclei merged, one large nucleus split, one dim nucleus missed. Sparse fields fine." He decides to use the model for his sparse wells, and to check every crowded well by eye until he knows how large the drift is.
What it taught him: the check region has to be the hardest region, or it only tells you what you already hoped.
In both situations the model did the slow part well. The judgement about what counts as a cell stayed with the person.
What goes wrong
Counting edge fragments as cells.Symptom: the count is a little high, and some masks are thin slivers along the border. Fix: write an edge rule before you run (for example "nucleus fully inside") and apply it in both your manual count and your reading of the masks.
Checking the easy region.Symptom: your manual check matches perfectly, and later a labmate finds the crowded wells are off. Fix: choose the densest or dimmest region as your check region. Agreement there means something.
Feeding it the wrong channels.Symptom: you wanted nuclei and got whole cells, or the outlines follow a third stain. Fix: give it only the channels that show the objects you count. For nuclei, the nuclear channel alone.
Very large or very small cells.Symptom: big cells come out as several pieces, or tiny cells are missed. Fix: measure a typical cell's diameter in pixels, enter it under additional settings → diameter, run again, and redo the region check.
Trusting the web demo's number.Symptom: the count from cellpose.org differs from your local run. Fix: the web demo shrinks images to at most 224 × 224 pixels. Use it to see what Cellpose does, never for a number, and never with unpublished images.
Forgetting what you ran.Symptom: two weeks later you can't say which settings produced the count. Fix: one notebook line per image: Cellpose version, model, settings, count, region check, where it failed.
Do it yourself (30 minutes)
Use a demo image first. If it goes well, repeat with one of your own images.
Structure it (5 min). Write down what you're counting and your counting rule: what counts as one cell, and what happens at the edge.
Understand it (10 min). Drag the image into the Cellpose window, keep the default model and click run. Press Z for outlines. Note every place where the masks don't match what you see: merges, splits, fragments, misses. Rewrite your rule if you learned something.
Choose tools (2 min). Decide your check region: the densest or dimmest part of the image, with 10 to 30 cells. Decide whether you need to split channels or set the diameter.
Build it (13 min). Count the region by hand with masks off (X). Count the masks in the same region with your rule. Take a screenshot with outlines on and save the masks. Write your notebook line with both counts and where it failed.
Exit check
What you hand in: one segmented image, plus:
the screenshot with outlines on, and the saved masks;
your counting rule, in one or two sentences;
the manual and model counts for one named region;
one sentence on where the model failed, or why you're satisfied it didn't.
It passes when a labmate can recount the same region with your rule and get your manual number.
Rule to remember
Count one region yourself, with your rule, before you trust the model's number.
Details for experts
Checked on 23 September 2026. You don't need this to follow the book; it's for setting things up or answering a colleague.
What
Details
What it means for you
Version
Cellpose 4.2.1.1, released 14 June 2026, from PyPI, the public catalogue that the install command downloads from.
Write the version into every notebook line, so a colleague can repeat your count.
Licences
The software is under BSD-3-Clause, a permissive open-source licence. Its README says all built-in models were trained on data licensed CC-BY-NC, which rules out commercial use.
Research use in your lab is the normal case. For paid or company work, ask your institution first.
Default model
cpsam_v2 (Cellpose-SAM, June 2026). It downloads automatically the first time, about 1.2 GB, from Hugging Face, a public site that hosts AI models.
Stay online the first time. After that it runs offline.
Other built-in models
cpdino and cpdino-vitb need an extra package.
Stay with the default for this book.
System
The docs name Windows, Linux and macOS, with 8 GB of memory as the minimum. The install uses Python 3.12 through Miniforge.
An older laptop with less memory may not cope.
Where things are
The Segmentation box holds the model drop-down and run; the count appears below as "N ROIs". X turns masks on and off, Z outlines. The diameter sits under additional settings.
Enough to find your way round the window.
Saving
File → Save masks as PNG/tif (Ctrl+N) saves the masks as an image. Ctrl+S saves a _seg.npy file, Cellpose's own results file, next to the image.
Keep the masks image with your screenshot for the exit check.
Web demo
cellpose.org takes one PNG or JPG under 10 MB and shrinks it to at most 224 × 224 pixels.
A first look at a public image only. Never use its count, never with unpublished images.
Cellpose: Taught. The pretrained model and its graphical interface used in this book.
Fiji: Catalogued. For splitting channels and for manual counts; its plugins also run other segmentation models.
napari: Catalogued. A Python image viewer with plugins, including one for Cellpose, for when you want to look at masks and images together.
QuPath: Catalogued. The route if you can't use a terminal, since it installs like any other program, and the better pick for whole-slide histology.
Watch
Cellpose SAM Tutorial
Cellpose SAM TutorialMarius Pachitariu
T18-L01: Understand what Cellpose-SAM does when it outlines cells. Then use the book's counting rule and hand-counted region to judge your own images; benchmark performance cannot validate your count.
