# Microscopy and Whole-Slide Image Annotation Software

Source: https://www.potatoannotator.com/use-cases/microscopy

**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](https://doi.org/10.1001/jama.2015.1405)). 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 reads a segmentation made elsewhere, such as a Cellpose or StarDist label image, and runs no segmentation model.

## Microscopy and pathology tasks in Potato

Fluorescence images use the `microscopy` scheme, new in Potato 2.13, and brightfield slides use the `image_annotation` scheme in the deep zoom viewer.

| 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](/docs/annotation-types/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](/docs/annotation-types/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](/docs/annotation-types/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](/docs/vision-spatial/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](/docs/annotation-types/microscopy#whole-slide-pathology-images) |
| Agreement on cell classes | Per-cell classes from every annotator in one CSV file, for Cohen's or Fleiss' kappa | [Inter-annotator agreement](/docs/guides/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, with the nuclei taken from the `nuclei` entry of the image's OME-Zarr `labels/` group. The [microscopy](/docs/annotation-types/microscopy) page has every option.

```yaml
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](https://ngff.openmicroscopy.org/) is the chunked, multiscale image format of the Open Microscopy Environment, and [OME-TIFF](https://ome-model.readthedocs.io/en/stable/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, so each item names a separate integer label TIFF.
- **Whole-slide images.** SVS, NDPI, MRXS, and the other formats openslide reads open with the `wsi` extra, 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:

```bash
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/qupath
```

The 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, the table that [Cohen's kappa](https://en.wikipedia.org/wiki/Cohen%27s_kappa) for two annotators or [Fleiss' kappa](https://en.wikipedia.org/wiki/Fleiss%27_kappa) for more needs. For slide regions drawn with the `image_annotation` scheme, Potato reports [agreement over geometry](/docs/measurement/geometry-agreement) on boxes and polygons.

## Working alongside QuPath, napari, and OMERO

[QuPath](https://qupath.github.io/) is open software for bioimage analysis with built-in cell and tissue detection, often used for digital pathology research, and suits detecting and measuring cells across many slides. [napari](https://napari.org/stable/) is a fast, interactive, multi-dimensional image viewer for Python that overlays points, polygons, and segmentations on NumPy or Zarr arrays for editing, and suits annotation done inside a scripted analysis. [OMERO](https://www.openmicroscopy.org/omero/) is a central repository for storing, viewing, organizing, analyzing, and sharing microscopy images, and 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](/docs/getting-started/quick-start-with-a-coding-agent) 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](/docs/annotation-types/microscopy) and [deep zoom](/docs/vision-spatial/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, such as `case_01.geojson` with `case_01.mrxs`, and shows the regions as pre-annotations in the deep zoom viewer.

### Do regions drawn at different zoom levels line up with the slide in QuPath?

Yes. Potato stores each region as fractions of the slide's full-resolution width and height, whatever magnification the annotator drew at, and 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>`, with each cell id replaced by the cell's class number and an `image-label` color for each class. 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](/docs/annotation-types/microscopy), for every format, scheme option, and export file
- [Gigapixel image annotation with deep zoom](/docs/vision-spatial/deep-zoom), for whole-slide images and tile pyramids
- [How many annotators do you need?](/docs/guides/how-many-annotators), for choosing the number of annotators per image
- [Air-gapped deployment](/docs/measurement/air-gap), for running Potato on a network with no route out
- [Life sciences](/use-cases/life-sciences) and [healthcare and clinical](/use-cases/healthcare), for neighboring fields on this site

## References

1. Elmore et al. (2015). Diagnostic Concordance Among Pathologists Interpreting Breast Biopsy Specimens. *JAMA* 313(11). https://doi.org/10.1001/jama.2015.1405