Contents
The problem this solves
A single image in the 2018 Data Science Bowl nuclei set can hold dozens of nuclei, and the set has 670 images with 29,442 outlined by hand. Drawing every outline yourself is the slow part of building a segmentation set. Correcting a good model's outlines is much faster.
Cellpose is the model many microscopy labs already use for this. This page puts it behind a button in the DataTorch annotator, so a press outlines the nuclei on the image in front of you and you spend your time fixing the hard ones.
What you need
- a DataTorch project with a few nucleus images. Download some from the hosted DSB2018 dataset and upload them under Storages with Upload files, or use your own,
- a label named
nucleusin the project (or change the name in run.py below), - a runner on a Mac or Linux machine with the datatorch Python package 0.8.0 or later. If you have not set one up, follow Step 1 of Run a Hugging Face model from the annotator.
Step 1: create the action on your runner
On the runner's machine, run:
datatorch action create --local cellpose
This makes a folder at actions/local/cellpose/<tag> inside the runner's folder, with an action yaml file and a run.py. The yaml already declares what this page needs: an imagePath input and an annotations output. You can also do this in the pipeline editor: choose On my runner, then Write a new action.
Step 2: replace run.py
Open run.py (in your editor, or in the browser from the pipeline editor while the runner is online) and replace it with:
import datatorch
from cellpose import io, models, utils
image_path = datatorch.get_input("imagePath")
img = io.imread(image_path)
if img.ndim == 3 and img.shape[-1] == 4:
img = img[..., :3] # many DSB2018 PNGs carry an alpha channel
model = models.CellposeModel(gpu=False)
masks, flows, styles = model.eval(img)
annotations = []
for outline in utils.outlines_list(masks):
if len(outline) >= 3:
annotations.append({"label": "nucleus", "polygon": outline.tolist()})
datatorch.set_output("annotations", annotations)
Cellpose returns a mask where each nucleus has its own number. utils.outlines_list turns each one into a list of x, y points, which is the polygon shape DataTorch expects.
Next to run.py, add a requirements.txt with one line:
cellpose
An action with a requirements file gets its own Python environment on the runner, built on the first run and reused after that.
Step 3: wire it to a button
- 1
Create the pipeline
Open Pipelines in the project sidebar, press New pipeline, name it "Segment with Cellpose" and choose From the annotator under When should it run?
- 2
Customize the button
Pick an icon and leave Selection on The whole file, since Cellpose reads the whole image. Press Continue.
- 3
Pick your action
In Choose an action, stay on On my runner and pick
cellpose. The editor puts a Download file step in front of it, which hands the image toimagePath. - 4
Save
Press Save. The button appears in the annotator only once the pipeline is saved.
The pipeline uses a local action, so it runs only on the runner whose folder holds it.
Step 4: press it and correct
Open a nucleus image in the annotator. Your button is at the bottom of the left toolbar. Press it.
The first press installs Cellpose and PyTorch into the action's environment and downloads the model weights (about 1.2 GB), which takes several minutes. Later presses reuse both, and on a CPU a press then takes from one to several minutes depending on the image size.

Each polygon is saved under the person who pressed the button and records the run that made it. Keep the good outlines, fix merged or split nuclei, delete false ones and draw anything it missed. When the image is done, it is ready for the same review and sign-off as any hand-drawn file.
If something goes wrong
Open the Pipelines tab in the annotator's lower right panel and click the latest run.
- The run failed (red). Click the cellpose step to read its log. A Python error there is your run.py talking.
- The run finished but placed nothing. If it names missing labels, add
nucleusto the project or let the run create labels on the step. If it names nothing, Cellpose found no nuclei. Check the image opens and is not blank after the alpha channel is dropped. - Outlines are too small or too large. Cellpose guesses object size. Pass
diameter=in pixels tomodel.evalfor images where it guesses wrong. - Each press adds a new set. Pressing again does not replace the last run's polygons, so delete them before you try a new setting.
Use a model you trained
If you fine-tuned Cellpose on your own labels, copy the model file into the action's folder, next to run.py, and change one line:
model = models.CellposeModel(gpu=False, pretrained_model="nuclei_v1")
Use the full path to the file if the runner does not find it. Everything else stays the same: the button, the polygons and the record of which run made them. To keep track of versions, name the file for its training set and change the name here.
Where to go next
The same pattern runs any model you can install with pip: StarDist, a U-Net you trained on your own scored images, or a classifier. Change run.py, keep the button. For the dataset itself, see the nuclei segmentation tutorial.
Put your model behind a button
Create a project, connect a runner and write a twenty-line action.
Frequently asked questions
Why not use the Hugging Face action for Cellpose?
Cellpose ships as its own Python package with its own weights, not as a Transformers or YOLO repository on the Hub. A local action runs any Python you can install with pip, so it is the way to run Cellpose, StarDist or a model you trained yourself.
Does my image leave my machine?
The runner downloads the file from your project to run the model, and Cellpose runs on the runner. Nothing is sent to a third party. The code stays in the action's folder on the runner.
Do I need a GPU?
No, but it helps. On a laptop CPU (an Apple M4), one press took about a minute on a 350 by 260 pixel DSB2018 image and about six minutes on a 1024 by 1024 one. Set gpu=True in run.py on a machine with a supported GPU.
Can I tell Cellpose's outlines from my team's?
Yes. Each polygon a run places records the pipeline and the run that made it. Select one and the Annotation Metadata tab shows it under pipelineRun.
Can I run it on a whole dataset at once?
Not in this release. A press runs on the file open in the annotator.
Can I use Cellpose commercially?
Check before you rely on it. The Cellpose README says its models are trained on data licensed under CC-BY-NC, and the repository's code license is shown as both BSD-3-Clause and GPL v3 in different places. If you work at a company, read the current terms for the version you install.
Open the hosted copy on DataTorch.
Browse the files in your browser, then download the dataset with a free account.
