Potato shows multichannel fluorescence images and whole-slide pathology scans in the browser, where annotators classify segmented cells, outline regions on gigapixel slides, and correct regions imported from QuPath or ASAP. Potato is free and open source, runs on your own server, and exports each annotator's regions as GeoJSON that QuPath reads.
Reading a slide is a judgment that trained readers make differently. In a study of 115 pathologists who gave 6,900 diagnoses on breast biopsy slides, 75.3% of the diagnoses agreed with a reference diagnosis set by a panel of three expert pathologists, and agreement on atypia cases was 48% (Elmore et al., 2015). A study that reports cell counts by class or the area of a lesion therefore gains from several annotators per image and an agreement figure between the annotators. Potato runs that kind of study by sending each image or slide to the number of annotators you set and storing every annotator's cells and regions under that annotator's name. Potato runs no segmentation model and reads a segmentation made elsewhere, such as a Cellpose or StarDist label image.
Microscopy and pathology tasks in Potato
Fluorescence images use the microscopy scheme, and brightfield slides use the image_annotation scheme in the deep zoom viewer. The microscopy scheme is new in Potato 2.13.
| Task | How Potato handles the task | Docs |
|---|---|---|
| Classify segmented cells | Annotators click a cell from the label image and press a key from 1 to 9 to give the cell a class | Microscopy |
| Score phenotypes in a screen | A cells-only task with tools: [] on one field of a high-content screening plate, such as plate.ome.zarr/A/1/0 | Microscopy |
| Outline regions on fluorescence images | Rectangle, polygon, and point tools for areas such as damaged tissue or debris, each region tied to one z-slice and time point | Microscopy |
| Annotate whole-slide images | SVS, NDPI, MRXS, and the other slide formats openslide reads, opened tile by tile for boxes, polygons, and points | Deep zoom |
| Correct regions from QuPath or ASAP | potato import reads QuPath GeoJSON or ASAP XML and shows the regions on each slide as pre-annotations | Microscopy |
| Agreement on cell classes | Per-cell classes from every annotator in one CSV file, for Cohen's or Fleiss' kappa | Inter-annotator agreement |
A marker scoring study with three annotators
The config below has three annotators call every nucleus in each field marker-positive or marker-negative. The nuclei come from the nuclei entry of the image's OME-Zarr labels/ group. The microscopy page has every option.
annotation_task_name: "Marker scoring"
task_dir: .
media_directory: media
output_annotation_dir: annotation_output
data_files: [data/fields.json] # each item names one OME-Zarr image in "image"
item_properties: {id_key: id, text_key: note}
user_config:
allow_all_users: true
num_annotators_per_item: 3
annotation_schemes:
- annotation_type: microscopy
name: marker
description: "Call every nucleus in the field positive or negative for the marker."
tools: [] # cells only, no region tools
label_image: nuclei # entry of the image's labels/ group
labels:
- {name: "marker positive", color: "#f03e3e"}
- {name: "marker negative", color: "#4dabf7"}
channels:
- {name: DAPI, label: "DAPI (nuclei)"}
- {index: 1, contrast: [100, 3000]}
min_cells: 20
label_requirement: {required: true}num_annotators_per_item: 3 sends each field to three annotators. With tools: [], the region tools are hidden and the two classes apply to cells. The second channels entry sets a starting contrast window for the marker channel, counted from 0. With min_cells and label_requirement together, Next stays blocked until the annotator has classified 20 cells.
Getting images in and annotations out
OME-Zarr is the chunked, multiscale image format of the Open Microscopy Environment, and OME-TIFF is a TIFF file whose OME-XML header names the channels and dimensions. Image paths are relative to the media directory, and Potato picks the reader from the format:
- OME-Zarr. Versions 0.4 and 0.5 open through zarr-python, and the label image comes from the store's
labels/group. - OME-TIFF. Files open through tifffile, also when the pyramid is stored as SubIFDs. OME-TIFF has no standard place for a label image. Each item therefore names a separate integer label TIFF.
- Whole-slide images. SVS, NDPI, MRXS, and the other formats openslide reads open with the
wsiextra, one tile at a time from the slide's own pyramid.
The fluorescence readers need pip install 'potato-annotation[microscopy]'. For fluorescence images, the microscopy export writes microscopy_rois.geojson with a user_id on every region, microscopy_cells.csv with one row per classified cell, and each annotator's classes as an OME-Zarr label image. For slides, the first command below builds a correction project from a QuPath GeoJSON file and the slide with the same name, and the second writes each annotator's regions back to QuPath GeoJSON:
potato import -i case_01.geojson --image-dir /data/slides -o case-project
python -m potato.export -c case-project/config.yaml -f qupath_geojson -o out/qupathThe slide export writes one file per annotator and slide, and -f asap_xml writes ASAP XML instead. Potato's agreement metrics do not cover microscopy schemes. Matching the rows of microscopy_cells.csv on instance_id, label_image, and label_id gives one row per cell with every annotator's class. That table is the input to Cohen's kappa for two annotators or Fleiss' kappa for more. For slide regions drawn with the image_annotation scheme, Potato reports agreement over geometry on boxes and polygons.
Working alongside QuPath, napari, and OMERO
QuPath is open software for bioimage analysis with built-in cell and tissue detection. QuPath is often used for digital pathology research and suits detecting and measuring cells across many slides. napari is a fast, interactive, multi-dimensional image viewer for Python that overlays points, polygons, and segmentations on NumPy or Zarr arrays for editing. The napari viewer suits annotation done inside a scripted analysis. OMERO is a central repository for storing, viewing, organizing, analyzing, and sharing microscopy images. OMERO suits an imaging core that keeps every image on one server. Potato fits when several annotators label the same images, because Potato assigns each image or slide to a set number of annotators, trains annotators before the real items, and exports each annotator's work separately. One route is to segment cells in Cellpose or QuPath, classify the cells in Potato, and open the exported GeoJSON in QuPath.
Setting up the study with a coding agent
potato-skill 1.2.0 knows the microscopy scheme by name and guides Claude Code, Codex, or Cursor through the study-design side, such as what to ask annotators, how many annotators classify each image, training and attention checks, and export. The skill does not yet document the OME-Zarr, OME-TIFF, and slide formats, the scheme options, or the microscopy and wsi extras. Point the agent at the microscopy and deep zoom pages, or at the pages' Markdown copies such as https://www.potatoannotator.com/docs/annotation-types/microscopy.md, for the formats and options.
Frequently asked questions
Can I import existing annotations on MRXS or SVS slides for annotators to correct?
Yes, when the annotations are in QuPath GeoJSON or ASAP XML. potato import pairs each region file with the slide of the same name and shows the regions as pre-annotations in the deep zoom viewer. For example, case_01.geojson pairs with case_01.mrxs.
Do regions drawn at different zoom levels line up with the slide in QuPath?
Yes. Whatever magnification the annotator drew at, Potato stores each region as fractions of the slide's full-resolution width and height. The qupath_geojson export converts the fractions to level-0 slide pixels. QuPath's "Import objects" expects level-0 pixels for the same slide, and each label arrives as a QuPath classification.
Can each annotator's cell classes be saved as a label image in the OME-Zarr file?
Yes. The microscopy export writes each annotator's classes as an OME-Zarr label image at labels/<schema>__<user>. In that label image, each cell id is replaced by the cell's class number, and each class gets an image-label color. Copy the directory into the source image's labels/ directory and add the name to the labels list of the source image's labels/ group.
Further reading
- Microscopy, for every format, scheme option, and export file
- Gigapixel image annotation with deep zoom, for whole-slide images and tile pyramids
- How many annotators do you need?, for choosing the number of annotators per image
- Air-gapped deployment, for running Potato on a network with no route out
- Life sciences and healthcare and clinical, for neighboring fields on this site
- Gigapixel and Whole-Slide Image Annotation Tools Compared
References
- Elmore et al. (2015). Diagnostic Concordance Among Pathologists Interpreting Breast Biopsy Specimens. JAMA 313(11). https://doi.org/10.1001/jama.2015.1405