XMLAnnotation, StructuredAnnotations and extending Annotation types for Python API

I’m writting a web application that saves / retrieves annotations to/from OMERO.server and I’m using omero-py to connect to the server. I’m also aware this is in development and if there will be future features resolving what I wrote below please let me know! I’m trying to understand how extensible annotations are for OMERO.server. Currently I append FileAnnotations to Images and metadata is stored as an OriginalFile. I’m looking for:

  • MapAnnotation instance that store a mix of string, numbers and tuples
  • MapAnnotation with MapAnnotation as values for example storing the data in variable dictionary as metadata. It seems like XMLAnnotation can help.
let dictionary = {
    'light-grade': { name: 'Light Grade', slug: 'light-grade', colour: '#FFDDFF' },

Question 1:

When I compare the OME-XML docs for XMLAnnotation

and the Python BlitzGatway API docs I see some contradictory details.

XMLAnnotation has an XML (or complexType) value

However XMLAnnotationWrapper extends CommentAnnotationWrapper so does that mean XML annotations are saved as plaintext?

I don’t have very much experience using XML but I read they are stored differently than plaintext here https://stackoverflow.com/a/514848

Question 2:

It is not clear which values are possible for MapAnnotationWrapper in the (key, value) pairs.

Sets value of the Map Annotation where val is a list of (key, value) tuples or [key, value] lists.

Question 3:

How do you create StructuredAnnotations with the Python API? Is that possible?

Question 4:

What is the relationship between Hibernate (HQL), the APIs (i.e. Python API) and OMERO-CLI? I assume HQL the backend for all data?


Question 1:

The OME data model is used as the basis for the OMERO database (and the corresponding OMERO model objects) but it is not an exact match. There are some differences in terms of naming and structure simply because of the nature of XML vv Database.

In OMERO, XML annotations are simply stored as text in the Postgres Database. OMERO doesn’t give you any extra functionality by using XML Annotations instead of Comments (no extra search or validation of XML etc). The only difference is when you come to read an XML Annotation, you’ll know it contained XML.

Question 2 & 3.

MapAnnotation keys and values are both strings. You can’t create a hierarchy of nested objects (as in your example dictionary). StructuredAnnotations are just Annotations in OMERO. You can create a “structure” because Annotations can be linked to other Annotations (although Annotations on Annotations are not shown in the webclient).
There are some examples of creating a MapAnnotation, Tag, FileAnnotation at https://docs.openmicroscopy.org/omero/5.5.1/developers/Python.html#write-data.
Creating a Comment or XMLAnnotation is similar to creating a Tag.
You can add a “namespace” to Annotations. This is simply a string that allows you to identify where they came from or what data they contain. You can also use it to find Annotations with a particular namespace.

Question 4:

Hibernate is used to map between the Postgres Database and the OMERO model objects in the server. HQL (Hibernate Query Language) is a flavour of SQL for querying these objects from the Database. The OMERO API (https://docs.openmicroscopy.org/omero/5.5.1/developers/Modules/Api.html) that is code-generated in Python and Java (same API in both) is used to communicate between the server omero.model objects (in Java) and corresponding objects on the client (Python or Java). We also have hand-written client-side libraries to make it easier to work with the objects e.g. Python BlitzGateway.

The CLI is simply a Python client that can be called via the command line.

Hope that helps. Let us know if you need any more guidance on choosing the most suitable option to use for a particular function.



Thanks, that sentence clarifies a lot.

Hi @will-moore, a follow up question:

My lab has ‘region annotations’ that define the locations of cancer cells in the tissue, similar to this example http://www.orbit.bio/annotations/. They are currently text files that contain closed paths which are sequences of line segments composed of (x,y) coordinate points like so:

Tumor [Point: 84332.8046875, 68421.28125, Point: 84332.8046875, 68421.28125,...]
  1. I understand there is no ‘coordinate based’ annotation objects in OMERO.server, instead these should be saved/viewed as ROI objects, which can be stored programmically like so?

  2. Are there any clients that save ROIs to OMERO.server? I understand QuPath has viewing only support, OMERO.web doesn’t have them and I don’t see any options for this in OMERO.insight


  1. Correct: ROIs in OMERO are a collection of Shapes (e.g. Polygons, Lines, Rectangles etc).

  2. The OMERO.iviewer is a web app (can be added to your OMERO.web installation) that can draw, edit & save ROIs to OMERO: https://www.openmicroscopy.org/omero/iviewer/
    There’s a better demo video of it at https://www.youtube.com/watch?v=aBMH2qihWm4
    OMERO.insight can also draw and save ROIs (Look for “Measurement tool” under http://help.openmicroscopy.org/getting-started-5.html#viewing-data).

Hope that helps,


1 Like