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

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

conn.getObjects("Annotation")

This adds support for various options for conn.getObjects("Annotation", opts), in preparation for JSON api:
The OMERO_CLASS is now set on AnnotationWrapper objects.
Also Fixes #433.

This is used by ome/omero-web#682

Tests added in ome/openmicroscopy#6458

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

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

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

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

%sAnnotationLink

This also improves the formulation of %sAnnotationLink (E.g. ImageAnnotationLink, ExperimenterGroupAnnotationLink, AnnotationAnnotationLink) in multiple places:

conn.getObjectsByMapAnnotations("Dataset", key="foo")
obj._loadAnnotationLinks() / _getAnnotationLinks()
- unlinkAnnotations()
- removeAnnotations()
- getAnnotation()
- listAnnotations()
obj._linkAnnotation() / _linkObject unused?
conn.getAnnotationLinks()
conn.countAnnotations()
conn.listOrphanedAnnotations()
AnnotationWrapper._getQueryString()

We can now do getObject() and listAnnotations() etc with many more object types:

E.g:

tag = omero.gateway.TagAnnotationWrapper(conn)
tag.setValue("Test Tag on Group")

group = conn.getGroupFromContext()
group.linkAnnotation(tag)

group.listAnnotations()

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: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 You may want to search for all omero.figure.json (ns) annotations that are on Datasets rather than on Images, or look for Tags on ROIs rather than on other objects etc. It's possible to imagine various use-cases.

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.

will-moore · 2026-08-14T15:22:52Z

@sbesson Thanks for catching that. I realise (since no tests failed) that we don't have tests for this, so I added that to ome/openmicroscopy@2084d18
That also revealed that e.g. ann.linkAnnotation(tag) didn't work for linking annotations to annotations because ann is expected to have OMERO_CLASS so I fixed that too.

sbesson · 2026-08-14T15:25:44Z

That also revealed that e.g. ann.linkAnnotation(tag) didn't work for linking annotations to annotations because ann is expected to have OMERO_CLASS so I fixed that too.

👍 does this mean this PR is incidentally fixing #433 as well?

will-moore · 2026-08-18T09:11:28Z

Updated the %sAnnotationLink logic in these methods:

conn.getObjectsByMapAnnotations("Dataset", key="foo")
obj._loadAnnotationLinks() / _getAnnotationLinks()
- unlinkAnnotations()
- removeAnnotations()
- getAnnotation()
- listAnnotations()
obj._linkAnnotation() / _linkObject unused?
conn.getAnnotationLinks()
conn.countAnnotations()
conn.listOrphanedAnnotations()
AnnotationWrapper._getQueryString()

will-moore · 2026-08-19T15:01:15Z

Currently 1 test failure at https://merge-ci.openmicroscopy.org/jenkins/job/OMERO-test-integration/60/

def testGetAnnotations(self, gatewaywrapper, author_testimg_tiny):
...
# Check links to Tag on the Comment
        for obj_type in ["CommentAnnotation", "Annotation"]:
>           annLinks = list(gatewaywrapper.gateway.getAnnotationLinks(
                obj_type, parent_ids=[ann.getId()]))

        wrapper = KNOWN_WRAPPERS.get(parent_type.lower(), None)
>       link_name = wrapper.ann_link_name()
                    ^^^^^^^^^^^^^^^^^^^^^
E       AttributeError: 'function' object has no attribute 'ann_link_name'

../../../../.venv3/lib64/python3.11/site-packages/omero/gateway/__init__.py:3556: AttributeError

pwalczysko · 2026-08-20T12:18:27Z

A new failing test - freshly from today is https://merge-ci.openmicroscopy.org/jenkins/job/OMERO-test-integration/62/testReport/OmeroPy.test.integration.gatewaytest.test_get_objects/TestGetObject/testGetObjectsAnnotation/

cls = <class 'omero.gateway.AnnotationWrapper'>
opts = {'parent_type': 'Dataset', 'parent_ids': [572]}

    @classmethod
    def _getQueryString(cls, opts=None):
        """
        Used for building queries in generic methods such as
        getObjects("Annotation")
        Returns a tuple of (query, clauses, params).
    
        :param opts:        Dictionary of optional parameters.
                            parent_type: (optional) "Project", "Dataset", "Image" etc
                            parent_ids: (optional) list of IDs for the parent type
                            ns: (optional) namespace string to filter by
        :return:            Tuple of string, list, ParametersI
        """
    
        query, clauses, params = super(
            AnnotationWrapper, cls)._getQueryString(opts)
        if opts is None:
            opts = {}
    
        fetch_file = ""
        if cls.OMERO_CLASS in ("Annotation", "FileAnnotation"):
            fetch_file = "left outer join fetch obj.file as file"
    
        query = (f"select obj from {cls.OMERO_CLASS} obj "
                 f"{fetch_file} "
                 "join fetch obj.details.owner as owner "
                 "join fetch obj.details.creationEvent")
    
        # We want to make parent_type case-insensitive...
        if 'parent_type' in opts:
>           ann_link_name = ann_link_name(opts['parent_type'])
                            ^^^^^^^^^^^^^
E           UnboundLocalError: cannot access local variable 'ann_link_name' where it is not associated with a value

will-moore · 2026-08-25T11:14:40Z

@sbesson ready for another review, thanks.
I updated the %sAnnotationLink logic everywhere that uses it in the BlitzGateway.
So you can now do e.g:

        tag = omero.gateway.TagAnnotationWrapper(conn)
        tag.setValue("Test")
        group = conn.getGroupFromContext()
        group.linkAnnotation(tag)

        # also link annotations
        tag.linkAnnotation(anotherAnnotation)

        # listAnnotations works too
        group.listAnnotations()

and the ExperimenterGroupAnnotationLink and AnnotationAnnotationLink objects will be created.

Tests for both of these are in PR at ome/openmicroscopy#6458

snoopycrimecop · 2026-08-28T08:17:06Z

Conflicting PR. Removed from build OMERO-python-superbuild-push#54. See the console output for more details.
Possible conflicts:

PR Wrapper improvements for ROIs #459 Tom-TBT 'Wrapper improvements for ROIs'
- src/omero/gateway/init.py
Upstream changes
- src/omero/gateway/init.py

--conflicts

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

will-moore removed the exclude label Aug 13, 2026

will-moore added 2 commits August 14, 2026 16:17

Fix ann.linkAnnotation(tag) usage of self.OMERO_CLASS

0b1aeaa

Fix conn.getAnnotationLinks('TagAnnotation')

11114e0

will-moore added 3 commits August 18, 2026 09:54

Add wrapper.ann_link_name(). Returns e.g. 'ProjectAnnotationLink'

5d092cd

Use wrapper.ann_link_name() instead of %sAnnotationLink

0742f4f

Add missing wrappers to KNOWN_WRAPPERS dict

f5b9b5e

remove LightSourceWrapper from KNOWN_WRAPPERS

0ed10d1

Use global ann_link_name() to handle 'annotation' etc

e0f9d9e

will-moore added 2 commits August 20, 2026 13:57

Fix ann_link_name variable in AnnotationWrapper._getQueryString()

8c32997

Support group.linkAnnotation(tag)

80cdacd

Support group.listAnnotations() and tag.listAnnotations()

1dc5977

will-moore mentioned this pull request Aug 27, 2026

Wrapper improvements for ROIs #459

Open

getAnnotationLinkTableName() uses ann_link_name()

2a6c9c9

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!

conn.getObjects("Annotation")

%sAnnotationLink

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!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

pwalczysko commented Aug 4, 2026

Uh oh!

sbesson commented Aug 4, 2026

Uh oh!

will-moore commented Aug 14, 2026

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

will-moore commented Aug 19, 2026

Uh oh!

pwalczysko commented Aug 20, 2026

Uh oh!

will-moore commented Aug 25, 2026

Uh oh!

snoopycrimecop commented Aug 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

will-moore commented Nov 24, 2025 •

edited

Loading

will-moore commented Jul 30, 2026 •

edited

Loading

sbesson commented Aug 14, 2026 •

edited

Loading

will-moore commented Aug 18, 2026 •

edited

Loading