Applying a slide's annotations in OMERO

Any slide with annotations on its detail page has a Download annotations (OME-XML) button in the "Slide annotations" section. This generates an OME-XML file recreating that slide's stored annotations - rectangles, ellipses, arrows, measurements, pins, and freehand/polygon shapes - as real ROIs, ready to import straight into OMERO. If this slide isn't being cropped, QuPath isn't needed anywhere in this process at all.

Downloading the file

Next to the download button you can set some options before generating the file:

• Apply zoom scaling (ticked by default) - some older annotations were recorded at a zoomed-in view rather than full image resolution, and need their coordinates multiplied by a per-annotation zoom factor to land in the right place. If the annotations come in badly offset, wrongly sized, or sitting in blank slide background, untick this box, download again, and try the other mode.
• Annotation colour (bright green by default) - pick any colour; it's applied to every shape in the file.
• Arrow style (only shown if the slide has any arrow annotations; head at start by default) - OME-XML has no separate "arrow" shape; an arrow becomes a Line shape with a MarkerStart/MarkerEnd="Arrow" attribute, chosen from < (head at start), > (head at end), or <> (double-headed). The original recording only ever stored a start and end point, not which end had the arrowhead, so this is a default you choose per download, not something recovered from the source data.

The downloaded filename includes a short, cleaned-up hint from the slide's own filename, and - if the slide has any arrows - the chosen arrow style, e.g. slide_7_Slide_41_Skin_Human_HE_..._arrow-end_annotations.ome.xml. The slide ID alone doesn't make it obvious which slide, or which arrow style, a given file matches.

A sysadmin-only bulk export of every slide's annotations in one zip is also available on the Annotations Export sysadmin page, and as a standalone export_annotations_ome_xml.py script for offline/archival runs against the database directly.

Importing directly into OMERO

In OMERO.web, right-click the matching image and choose Open with → ROI Importer. Upload the downloaded file there, review the preview it shows against the image, and commit - this creates the ROIs directly, with no QuPath step in between.

If you're also cropping this slide

Stored annotations are recorded as coordinates on the original, full-size image. A cropped export has its own coordinate system starting at (0, 0) in the crop's top-left, so annotations need repositioning to line up with the crop before they're imported into OMERO. If this slide has no annotations, this section doesn't apply - skip straight to exporting.

Tip. Select the Annotations tab in QuPath's left-hand panel for this whole process - it lists every annotation on the image (the crop mask included, shown in red), making it much easier to select, check, and delete the right one at each step.

Draw the crop as usual (Steps 3 and 4) - it appears in the Annotations list as its own annotation. With it still selected, export the crop's pixels next: File → Export Images → OME-TIFF. Use the default settings unless instructed otherwise, save using the slide ID where possible, and note the destination folder - large exports may take several minutes. Once it completes, verify the file was created successfully; it's now ready for import into OMERO using OMERO.insight.

Now import this slide's annotations from the file downloaded above. Open the script editor (Automate → Show script editor), load import-annotations-from-ome-xml.groovy, run it, and select the downloaded .ome.xml file. This rebuilds every annotation directly from the file's own coordinates on the same local image the crop mask is on - it doesn't use QuPath's drag-and-drop GeoJSON import, which was found to sometimes silently reorder a line's two endpoints and flip which end an arrow's head was on. The crop mask stays on the image alongside them, unaffected.

Note. The imported annotation colour is applied via QuPath's own setColor(), which is confirmed to colour each annotation's entry in the Annotations list - whether it also changes the shape's colour as drawn on the slide itself can vary, and hasn't been confirmed against every QuPath version. If the on-slide colour doesn't match, this is a QuPath display setting to check locally (e.g. a display/classification override), not something wrong with the imported file.

With the crop mask selected, run reposition-annotations-for-crop.groovy. This shifts every other annotation on the image to line up with the crop mask's own (0, 0) origin, updating each annotation in place (its name, colour, and description are all preserved).

Still with the crop mask selected, run export-annotations-as-ome-xml.groovy from the script editor and choose where to save the file. It exports every other annotation's now-repositioned coordinates as a standalone OME-XML file - the same standard format OMERO itself uses for ROIs, including a real arrowhead marker on arrows, not something bolted on afterwards. These scripts are reused for every slide, so it's worth keeping all three in QuPath's own scripts folder (Automate → Shared scripts... → Open Script directory) rather than downloading them again each time.

Import the crop into OMERO (OMERO import). Once it exists there, right-click that image in OMERO.web and choose Open with → ROI Importer, then upload the file you just saved - the same direct import described above, just against the crop instead of the full image.