Tutorial

Segment nuclei with Cellpose from a button in the annotator

Put Cellpose behind a button in the DataTorch annotator. Press it on a microscopy image and its nucleus outlines land on the file as polygons, marked as the model's, ready to correct.

Contents

  1. The problem this solves
  2. What you need
  3. Step 1: create the action on your runner
  4. Step 2: replace run.py
  5. Step 3: wire it to a button
  6. Step 4: press it and correct
  7. If something goes wrong
  8. Use a model you trained
  9. Where to go next
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 nucleus in 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. 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. 2

    Customize the button

    Pick an icon and leave Selection on The whole file, since Cellpose reads the whole image. Press Continue.

  3. 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 to imagePath.

  4. 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.

A DSB2018 fluorescence image in the annotator after one press of Segment with Cellpose: a nucleus polygon on every nucleus, one selected, with its pipelineRun entry in Annotation Metadata and the run in the Pipelines tab
One press: every nucleus Cellpose found, each marked with the run that made it

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 nucleus to 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 to model.eval for 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.

Get the data

Open the hosted copy on DataTorch.

Browse the files in your browser, then download the dataset with a free account.

Open the datasetStart free

Related

Tutorial

Fine-tune Cellpose on your own labels, with no GPU of your own

Tutorial

Run a Hugging Face model on your images from the annotator

Tutorial

Nuclei segmentation tutorial with the DSB2018 dataset

Release

Release 0.1.0: Pipelines, rebuilt

Tools and community for image annotation: label, review, and share datasets, from everyday photos to the imagery only specialists can read.

Platform

PlatformImaging labsExplore datasetsEnterprisePricing

© 2026 DataTorch. All rights reserved.