Labels
A label is a segmentation mask: one integer per pixel, where each integer is an object ID. Labels live alongside your image and render as a coloured overlay so you can see what was detected by your segmentation tool (CellProfiler, Cellpose, StarDist, InstanSeg, and anything else that writes OME-Zarr or bare Zarr masks).
This guide covers the foundational workflow: load labels, control how they look, organise them, attach metadata. For per-object coloring by measurement CSVs (heatmap, category, phenotypes), see the Analytics & Phenotyping guide.
Loading labels
The buttons at the top of the Labels tab:
| Button | What it does |
|---|---|
| Add Local | Pick a folder on your disk that contains a Zarr label array. Chrome / Edge only. |
| Add URL | Paste a URL pointing at a Zarr label array. Works in any browser. |
| Discover | Scan an HCS plate's fields for labels. Only appears on plates, and only runs when you click it. See below. |
| Refresh | Re-scan the current image's OME-Zarr for embedded labels. Useful if a segmentation job has just written a new label and you don't want to reload the whole image. |
Embedded labels
Labels written inside your OME-Zarr (under the /labels/ group, per the OME-NGFF spec) are discovered automatically on image load. No clicking required. They appear in the Embedded group in the list.
Plates: press Discover
On an HCS plate, labels are not discovered automatically. You get a Discover button instead, and nothing is scanned until you press it.
This is deliberate. The scan asks every well whether it has a labels/ group, so a 384-well plate is 384 requests before a single pixel is drawn. Ten run in parallel, and only field 0 of each well is checked, but the count still scales with the plate. Against a local disk that is merely slow. Against S3 it is 384 billed requests every time anyone opens the plate, whether or not they wanted labels at all. So the scan is something you ask for, not something that happens to you.
Because it visits every well, the result knows which wells actually carry each label, rather than assuming the whole plate matches the first one.
Press Discover once and the labels stay attached for the session. If a segmentation job writes new masks while you have the plate open, press it again.
Local folders (Add Local)
Click Add Local, pick any folder containing a Zarr label. The folder stays on your disk. The viewer reads it directly via the File System Access API. Use this when you've run a segmentation tool that wrote a Zarr mask next to (but not inside) your image.
Remote URLs (Add URL)
Click Add URL and paste the URL of a Zarr label array. Works from any storage that serves HTTP range requests and the right CORS headers: S3, Cloudflare R2, GCS, Azure Blob, an on-premise nginx, a data server running locally. See the Data Server guide for hosting your own.
External labels (not embedded in the image's OME-Zarr) show an EXT badge in the list so you can tell them apart from the embedded ones.
Try it on a public dataset
Open IDR image 6001240 with its segmentation showing. Nothing is downloaded to a server, and nothing is installed. The viewer reads the OME-Zarr straight from the Image Data Resource's public bucket, which serves range requests and CORS. Credit and licence for that image are at the bottom of this page.
Label rows
Every label renders as a row with the essentials on a single line:
toggle visibility- Color swatch: click to open the style popover
- Label name: double-click to rename
- Filter count badge: appears when analytics is loaded, showing how many filters are active
- EXT badge: only on external labels
Click the row to expand its detail panel below. There you'll find Metadata (Source / Notes / Tags / Key-values), plus the Analytics section if analytics is loaded.
Style: solid, random, or per-object
Click the color swatch on a label row to open the style popover. It holds the display controls for that label:
| Control | Effect |
|---|---|
| Solid | Every object in the label shares a single colour (the one you pick below). Default for newly loaded labels. |
| Random | Each object gets a colour hashed from its ID. Different objects look different; the same object gets the same colour across reloads. Useful for visually distinguishing neighbouring cells without a segmentation-quality judgement. |
| Heatmap | Colour by a numeric column. Requires an analytics CSV. See the Analytics guide. |
| Category | Colour by a string column. Requires an analytics CSV. |
| Opacity slider | Blends the label layer with the image underneath. 0 hides the label; 1 makes it fully opaque. |
| FILL / CONTOUR | Two independent toggles for polygon labels. Fill paints the interior; contour draws a 1-px outline. Turn fill off for "outlines-only" view. Useful when you want to see the image through your segmentation. |
| Presets grid | 16 curated colours: RGB primaries on top, muted variants on the bottom row. One click applies. |
| Hex / RGB inputs | Type #FF00AA or type the three RGB values directly. Synced bidirectionally. |
| More colors… | Opens the OS-native picker for any colour + eyedropper (Chrome / Edge). |
Grouping
The Labels list groups by Source by default. Embedded labels sit under "Embedded", and each external label gets its own group header. You can switch to Group By key-value using the toolbar:
A key-value describes the whole mask, not the objects inside it, so useful keys are properties of the segmentation run: segmenter: stardist, model: nuclei_v2, version: 2026-03-11. Tag a dozen masks with segmenter and the list reorganises into a StarDist group and a Cellpose group, which is what you want when you are comparing runs on the same image.
Things that vary per object, like a cell's tissue class, do not belong here. Those live in an analytics table, one row per object. See Analytics & Phenotyping.
Drag the grip handle on the left of each group header to reorder groups. The group order also controls rendering z-order on the canvas. Later groups draw on top.
Search and filter
The toolbar row has a Filter dropdown and a Search input:
- Filter: show All / only Visible / only Hidden labels.
- Search: type part of a label name, tag, or metadata value. The list narrows to matches live.
Metadata: Source, Notes, Tags, Key-values
Expand a label's row and open the METADATA section. Four fields live here:
- Source: read-only, shows where the label came from (embedded path, local folder, URL).
- Notes: free-form text. "Run 2 from Cellpose, threshold 0.65."
- Tags: short chips you can add / remove. "validated", "needs-review".
- Key-values: structured
key: valuerows describing the mask as a whole.segmenter: cellpose,model: cyto3,version: 2026-03-11. Add one, then switch to Group By on the toolbar and the list reorganises by that key.
Metadata persists to IndexedDB per-label and survives reloads.
HCS plates
When you open a high-content-screening plate, labels work the same way but apply at the plate level. A label named nuclei is discovered on every populated well and renders consistently across all fields. See the HCS Plates guide for plate-specific controls (well navigation, field grid, plate overview).
Persistence
Everything you do in the Labels tab persists to your browser's IndexedDB, keyed by the image's URL or local folder handle:
- Visibility, colour mode, opacity, fill/contour state
- Notes, tags, key-values
- Which labels you've added external / URL-based
- Current group-by mode
Reload the page, reopen the image. Your label configuration is still there. The URL query string captures viewport state (zoom, center, active channels) but not label configuration; that lives in the browser locally.
Mobile
On phone viewports the Labels tab shows the row list and basic visibility toggles, but heatmap / category / phenotype coloring tabs are disabled. Per-object coloring needs an analytics CSV, and the File System Access API required to pick one doesn't exist on phones. Tablets show the full desktop UI.
Image credits
The screenshots on this page use a public whole-slide H&E section, a high-content screen and a fluorescence image from IDR. See Sample Data and Credits.
Next steps
- Want to colour cells by area, intensity, or any measurement? Analytics & Phenotyping.
- Drawing your own regions (not from a segmentation mask)? Annotations.
- Sharing your view with a reviewer? Sharing Views.
- Hosting your own label data? Data Server.