Add more opts support for getObjects('Annotation') by will-moore · Pull Request #489 · ome/omero-py

will-moore · 2025-11-24T22:48:25Z

This adds support for various options for conn.getObjects("Annotation", opts), in preparation for JSON api:

Supported opts - All are optional (but parent_ids needs parent_type)

"parent_type": "dataset"
"parent_ids": [1, 2]
"ann_type': "tag"
"ns": "my.namespace"

E.g. /api/annotations/?type=tag&project=1&project=2 would be backed by:

conn.getObjects("Annotation", opts={
  "ann_type": "tag",
  "parent_type": "project",
  "parent_ids": [1,2]
})

Known issue: Loading Parents

For webclient/api/annotations/ we get the annotations along with links to the parents and the parent objects too.
E.g.

  "link": {
    "id": 39752336,
    "owner": {
      "id": 2
    },
    "parent": {
      "id": 3414011,
      "class": "ImageI",
      "name": "10percent-Wt1-GFP-spheroid-MV.czi [0]"
    },
    "date": "2017-11-27T14:13:19+00:00",
    "permissions": {
      "canDelete": false,
      "canAnnotate": false,
      "canLink": false,
      "canEdit": false
    }
  }

This is useful to have permissions, timestamp, owner etc on the link but it is particularly essential when we are loading annotations on multiple objects. E.g. /api/annotations/?type=tag&project=1&project=2 would load annotations for 2 projects, BUT we without links, we don't know which Annotations are linked to which Project.

But, it doesn't appear possible to achieve this with omero_marshal, since for Annotations, there is no handling of links to Parent objects. Annotations are "Annotatable", so we check for annotations ON the object https://github.com/ome/omero-marshal/blob/f8ff1c2e439f0599d96423b7f64898864548ba9f/omero_marshal/encode/encoders/annotation.py#L68
but not whether the Object (annotation) is annotating a Parent.
In fact, I don't see that it's possible for e.g. an Annotation to have links loaded (in the same way that a Project or Dataset can have obj.copyAnnotationLinks(), since the possible links for an Annotation object are stored in a different Table for each parent, e.g. ProjectAnnotationLinks, DatasetAnnotationLinks etc.

will-moore · 2026-06-30T15:22:57Z

Tests added in ome/openmicroscopy#6458

will-moore · 2026-06-30T15:32:08Z

Comment on what changed after first commit....

The problem with the getObjects() is that we can't easily handle OR logic. E.g. "get Annotations with links to Project:1 OR Dataset:2". Currently, for each obj_type we add a clause, so we get AND logic:

                    clauses.append(
                        "exists (from %sAnnotationLink as link "
                        "where link.child.id = obj.id "
                        "and link.parent.id in (:%s_ids))" % (obj_type, plural))
                    params.add("%s_ids" % plural, rlist([rlong(i) for i in ids]))

Therefore,
conn.getObjects("Annotation", opts={"ann_type": "tag", "projects": [1,2], "datasets": [3,4]}) won't give you annotations on all objects, as you currently get with e.g. https://idr.openmicroscopy.org/webclient/api/annotations/?type=map&screen=3&image=3414011

Do we ever need to load annotations for more that 1 type of Object? E.g. webclient almost never allows you to select multiple different Object types, (e.g. Dataset and Image, except maybe in the search results)

The webclient/api endpoint does a series of queries select oal from %sAnnotationLink as oal for each obj_type requested. Each Database query only supports 1 object type. So it's probably OK for the getObjects("Annotation") to also support just ONE parent type. Same behaviour in E.g.

conn.getAnnotationLinks(...parent_type, parent_ids=None)

So, let's instead go for:

conn.getObjects("Annotation", opts={
  "ann_type": "tag",
  "parent_type": "project",
  "parent_ids": [1,2]
})

We may be loading file annotations even without using ann_type of 'file'

knabar · 2026-07-02T13:27:37Z

Do we ever need to load annotations for more that 1 type of Object? E.g. webclient almost never allows you to select multiple different Object types, (e.g. Dataset and Image, except maybe in the search results)

The webclient/api endpoint does a series of queries select oal from %sAnnotationLink as oal for each obj_type requested. Each Database query only supports 1 object type. So it's probably OK for the getObjects("Annotation") to also support just ONE parent type.

It makes sense to me to limit the parent type to one per request, if a client requires annotations on different parent types, the client can make multiple requests.

I think it could even be justified to limit requests to a single parent object if that simplifies the requests and responses significantly.

will-moore · 2026-07-30T10:53:58Z

@knabar Anything else to address here?

I think it could even be justified to limit requests to a single parent object if that simplifies the requests and responses significantly.

There is no additional logic associated with supporting multiple parent objects (IDs) of the same type, and it could be useful so I'd like to leave this in.

sbesson

A few initial comments. I think the extensibility to support the filtering by annotation type, parent and namespace is useful but we will need additional changes to handle more generically all relevant objects.

sbesson · 2026-07-30T12:09:02Z

+        elif ann_type == "map":
+            clauses.append("obj.class=MapAnnotation")
+        elif ann_type is not None:
+            msg = ("ann_type '%s' not recognised. Must be one of 'tag', 'file', "


This should be implemented for all supported annotations (BooleanAnnotation, TermAnnotation, XmlAnnotation...)

sbesson · 2026-07-30T12:10:28Z


        :param opts:        Dictionary of optional parameters.
-                            NB: No options supported for this class.
+                            ann_type: (optional) "tag", "file", "comment", "long", "map"


Arguably this could use the full annotation type TagAnnotation, FileAnnotation and save the mapping below.

Do you mean "TagAnnotation" (string) or omero.model.TagAnnotation (class)?

I feel that it's more user-friendly for the BlitzGateway methods to take strings rather than omero.model objects. E.g. conn.getObject("Image") rather than conn.getObject(omero.model.ImageI).
So I'd like to do the mapping here. Otherwise we'd have to do the mapping in omero-web for ome/omero-web#682 and probably other places too.

I have just realised that the more natural way to do this (since we only support a single ann type) is to do:

e.g. get Tags on datasets... NB: we already support conn.getObject("TagAnnotation")

conn.getObject("TagAnnotation", opts={"parent_type": "dataset", "parent_ids": [1, 2]})

instead of

conn.getObject("Annotation", opts={"ann_type": "tag", "parent_type": "dataset", "parent_ids": [1, 2]})

Agreed, that's a more natural extension of the existing API and substantially simplifies the logic.
I think it would make sense to use the same semantics for the parent_type e.g. when retrieving all the tags under a tagset, one could use

conn.getObjects("TagAnnotation", opts={"parent_type": "TagAnnotation", "parent_ids": [1], ns: omero.constants.metadata.NSINSIGHTTAGSET})

This would remove the special casing discussed in #489 (comment)

Actually, conn.getObjects("dataset') or conn.getObjects("tagannotation") is already case-insensitive, so lets stick with that here too for consistency.

sbesson · 2026-07-30T12:12:57Z

        :param opts:        Dictionary of optional parameters.
-                            NB: No options supported for this class.
+                            ann_type: (optional) "tag", "file", "comment", "long", "map"
+                            parent_type: (optional) "project", "dataset", "image" etc


Is there a list of all objects that can be annotated?

I don't actually know where to find such a list or if it's possible to create one?

https://omero.readthedocs.io/en/stable/developers/Model/EveryObject.html#annotation seems like a good start...

sbesson · 2026-07-30T12:16:56Z

+            raise AttributeError(msg)
+
+        if 'parent_type' in opts:
+            obj_type = opts['parent_type'].title().replace("Plateacquisition", "PlateAcquisition")


Unfortunately, PlateAcquisition is not the only object that will need this special handling to convert from its lowercase version. Other examples include all annotation types (which can be annotated themselves), some instrument objects (LightPath, LightSource...) as well as OriginalFile.

Using this list (from https://omero.readthedocs.io/en/stable/developers/Model/EveryObject.html#annotation)

AnnotationAnnotationLink ChannelAnnotationLink DatasetAnnotationLink DetectorAnnotationLink DichroicAnnotationLink ExperimenterAnnotationLink ExperimenterGroupAnnotationLink FilesetAnnotationLink FilterAnnotationLink FolderAnnotationLink ImageAnnotationLink InstrumentAnnotationLink LightPathAnnotationLink LightSourceAnnotationLink NamespaceAnnotationLink NodeAnnotationLink ObjectiveAnnotationLink OriginalFileAnnotationLink PlaneInfoAnnotationLink PlateAcquisitionAnnotationLink PlateAnnotationLink ProjectAnnotationLink ReagentAnnotationLink RoiAnnotationLink ScreenAnnotationLink SessionAnnotationLink ShapeAnnotationLink WellAnnotationLink

I see only these cases:

ExperimenterGroup LightPath LightSource OriginalFile PlaneInfo PlateAcquisition

If the parent_type is annotation then this will query for AnnotationAnnotationLink without any other handling needed.

sbesson

This is getting much better in particular with the removal of the duplicated _getQueryString to use OMERO_CLASS (with the additional clause for fetching OriginalFile).

Reviewing the list of structured annotations, the only concrete instantiation that misses a wrapper is ListAnnotation. Is that something we want to quickly implement as part of this PR to be feature complete?

sbesson · 2026-07-31T13:38:22Z

+                if obj_type == otype.title():
+                    obj_type = otype
+            ids_clause = ""
+            if 'parent_ids' in opts:


What is the real-world use case associated with specifying parent_type but no parent_ids?
I think it should be easy to enforce that parent_ids must be supplied if parent_type is specified. And that can always be relaxed later on if there is a real need.

sbesson · 2026-07-31T13:39:49Z

+
+        # We want to make parent_type case-insensitive...
+        if 'parent_type' in opts:
+            # Title case works for most objects...


Can we move this utility to a separate utility method for transforming lower-case strings into case-sensitive object types with associated unit tests ?

I see a few places in the gateway that can use it. There might be use cases elsewhere in OMERO.py.

pwalczysko · 2026-08-04T10:39:54Z

@will-moore excluding - this PR is causing the test_show.py errors in https://merge-ci.openmicroscopy.org/jenkins/job/OMERO-test-integration/43/testReport/

sbesson · 2026-08-04T10:44:10Z

More specifically, the addition of OMERO_CLASS static variable to the various annotation wrapper classes is at odds with the implementation of ‎_BlitzGateway.getAnnotationLinks - see

omero-py/src/omero/gateway/__init__.py

Lines 3551 to 3554 in 5d0974d

    
           class_string = wrapper().OMERO_CLASS 
        
           # E.g. AnnotationWrappers have no OMERO_CLASS 
        
           if class_string is None and "annotation" in parent_type.lower(): 
        
               class_string = "Annotation"

which will need to be updated accordingly.

Start to add more opts support for getObjects('Annotation')

c86f8e2

will-moore mentioned this pull request Jan 6, 2026

JSON API support for Annotations ome/omero-web#532

Open

will-moore closed this Feb 24, 2026

will-moore reopened this Jun 30, 2026

will-moore added 3 commits June 30, 2026 08:55

Merge remote-tracking branch 'origin/master' into getObjects_Annotations

16dc35a

Support parent_type and parent_ids for getObjects('Annotation')

4d6c32e

Support ns for getObjects('Annotation')

559eb61

will-moore mentioned this pull request Jun 30, 2026

Add test for conn.getObjects('Annotations', opts={...}) ome/openmicroscopy#6458

Open

will-moore marked this pull request as ready for review June 30, 2026 15:22

will-moore changed the title ~~Start to add more opts support for getObjects('Annotation')~~ Add more opts support for getObjects('Annotation') Jun 30, 2026

will-moore mentioned this pull request Jun 30, 2026

Initial support for JSON api /annotations endpoint ome/omero-web#682

Open

will-moore added 2 commits July 1, 2026 09:56

load File for FileAnnotations

4c1ee1d

Always try to load annotation.File

b0e6410

We may be loading file annotations even without using ann_type of 'file'

will-moore mentioned this pull request Jul 1, 2026

RoiWrapper load_shapes includes externalInfo #495

Merged

knabar reviewed Jul 2, 2026

View reviewed changes

Comment thread src/omero/gateway/__init__.py Outdated

will-moore mentioned this pull request Jul 2, 2026

Zarr layers ome/omero-iviewer#532

Open

will-moore added 3 commits July 2, 2026 22:24

Remove special handling of 'rating' annotation

367e22e

Fix docstring

97c30cc

raise AttributeError for invalid ann_type

9a2ce90

will-moore mentioned this pull request Jul 30, 2026

Marshal AnnotationLink ome/omero-marshal#91

Open

sbesson requested changes Jul 30, 2026

View reviewed changes

will-moore added 3 commits July 30, 2026 16:05

Use conn.getObject('TagAnnotation'...) to load Tags

513ce54

Add XmlAnnotationWrapper to KNOWN_WRAPPERS

2ce949c

getObject('Annotation') parent_type case insensitive

d16cce3

sbesson requested changes Jul 31, 2026

View reviewed changes

pwalczysko added the exclude label Aug 4, 2026

Uh oh!

Conversation

will-moore commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Known issue: Loading Parents

Uh oh!

will-moore commented Jun 30, 2026

Uh oh!

will-moore commented Jun 30, 2026

Uh oh!

knabar commented Jul 2, 2026

Uh oh!

Uh oh!

will-moore commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sbesson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbesson Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sbesson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pwalczysko commented Aug 4, 2026

Uh oh!

sbesson commented Aug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

will-moore commented Nov 24, 2025 •

edited

Loading

will-moore commented Jul 30, 2026 •

edited

Loading

sbesson Jul 30, 2026 •

edited

Loading