Metadata and Annotations

Annotations may contain participant identifiers, sample names, unpublished results, free text, remote filenames, or attached files. Read and export the minimum fields needed.

Current Annotation Types

The OMERO structured annotation model includes:

• TagAnnotation
• MapAnnotation
• FileAnnotation
• CommentAnnotation
• BooleanAnnotation
• LongAnnotation
• DoubleAnnotation
• TimestampAnnotation
• TermAnnotation
• XmlAnnotation
• annotation hierarchies through annotation-to-annotation links

Current omero.gateway exports corresponding wrappers, including TagAnnotationWrapper, MapAnnotationWrapper, FileAnnotationWrapper, and CommentAnnotationWrapper. Do not import a historical BaseAnnotationWrapper; the current public wrapper is AnnotationWrapper.

Annotations can be linked to multiple objects. Their ownership and the ownership of each link may differ. Deleting an annotation is not the same as deleting one link.

Bounded Read

listAnnotations() supports a namespace filter but not a page-size argument. Cap client iteration and report truncation:

from itertools import islice

image = conn.getObject("Image", image_id)
if image is None:
    raise LookupError("Image unavailable")

max_annotations = 100
items = list(islice(image.listAnnotations(), max_annotations + 1))
truncated = len(items) > max_annotations

for annotation in items[:max_annotations]:
    print(annotation.getId(), type(annotation).__name__, annotation.getNs())

print({"truncated": truncated})

Avoid getValue() when values are outside the export scope. However, listAnnotations() loads linked annotations, including their values, before yielding, and its namespace filter is applied locally. Thus redaction and iteration caps protect output; they do not prevent transfer into client memory or bound the server query. Annotation wrappers inherit OMERO_CLASS=None; use their concrete wrapper class for an annotation type name.

For explicit parent IDs, annotation links can be queried:

image_ids = [101, 102]
for link in islice(
    conn.getAnnotationLinks("Image", parent_ids=image_ids),
    200,
):
    print(link.getParent().getId(), link.getChild().getId())

Keep both the parent-ID list and returned-link count bounded.

Redacted Inventory

A safe default record contains identifiers and type, not values:

def annotation_summary(annotation):
    details = annotation.getDetails()
    owner = details.getOwner() if details is not None else None
    return {
        "id": annotation.getId(),
        "type": type(annotation).__name__.removesuffix("Wrapper"),
        "namespace": annotation.getNs(),
        "owner_id": owner.getId() if owner is not None else None,
        "value_redacted": True,
    }

Owner names, annotation values, file names, descriptions, and link-owner names require separate inclusion decisions.

The bundled exporter defaults to redaction:

python -B scripts/export_image_metadata.py \
  --image-id 101 \
  --max-annotations-per-image 100 \
  --max-rois-per-image 100 \
  --output ./image-101-metadata.json

# Review, then connect. Add inclusion flags only when approved.
python -B scripts/export_image_metadata.py \
  --image-id 101 \
  --max-annotations-per-image 100 \
  --max-rois-per-image 100 \
  --execute \
  --output ./image-101-metadata.json

It never downloads FileAnnotation bytes or pixel data.

Namespaces

Namespaces let tools assign semantics:

for annotation in image.listAnnotations(ns="org.example.analysis.v1"):
    print(annotation.getId())

Use an organization-controlled URI or reverse-domain pattern and document its schema/version. Do not claim a custom namespace is an OME standard.

The current client constant for client map annotations is:

from omero.constants.metadata import NSCLIENTMAPANNOTATION

OME's Python example warns that a client map annotation should be linked to only one object. Create a separate map annotation for each target when using that namespace.

Map Annotations

Read key/value pairs only when approved:

from omero.gateway import MapAnnotationWrapper

for annotation in image.listAnnotations(ns="org.example.analysis.v1"):
    if isinstance(annotation, MapAnnotationWrapper):
        pairs = annotation.getValue()
        for key, value in pairs[:50]:
            print(key, value)

Apply independent limits to annotation count, pair count, key length, and value length. Keys can be sensitive too; a “values redacted” export that leaves participant IDs in keys is not redacted.

Creating and linking is a write:

from omero.constants.metadata import NSCLIENTMAPANNOTATION
from omero.gateway import MapAnnotationWrapper

image = conn.getObject("Image", image_id)
if image is None:
    raise LookupError("Image unavailable")

pairs = [["Analysis version", "2.1"], ["Status", "reviewed"]]
annotation = MapAnnotationWrapper(conn)
annotation.setNs(NSCLIENTMAPANNOTATION)
annotation.setValue(pairs)
annotation.save()
image.linkAnnotation(annotation)

Before running this:

• confirm image ID and group;
• confirm write permission and namespace;
• validate pair count and string lengths;
• decide rollback behavior if save succeeds but link creation fails;
• never create duplicate metadata merely because an earlier query was scoped to the wrong group.

Tags and Comments

Tag creation and linking are separate writes:

from omero.gateway import TagAnnotationWrapper

tag = TagAnnotationWrapper(conn)
tag.setValue("Reviewed")
tag.setDescription("Reviewed under protocol v2")
tag.save()

image = conn.getObject("Image", image_id)
if image is None:
    raise LookupError("Image unavailable")
image.linkAnnotation(tag)

Query for an existing controlled tag before creating another. Check group and owner semantics; do not reuse a same-named tag from an unintended group.

Comments are free text and often the most sensitive annotation type. Do not include them in a general inventory. Never pass untrusted comments into shell, HTML, SQL/HQL, filenames, or dynamic code.

File Annotations

Inspect metadata without downloading bytes:

from omero.gateway import FileAnnotationWrapper

for annotation in image.listAnnotations():
    if isinstance(annotation, FileAnnotationWrapper):
        original = annotation.getFile()
        print(
            {
                "annotation_id": annotation.getId(),
                "original_file_id": original.getId(),
                "size": original.getSize(),
                "mimetype": original.getMimetype(),
                "name_redacted": True,
            }
        )

Remote filenames are untrusted input. Never join them directly to an output directory.

For one explicitly approved file, check size and use a caller-chosen path:

from pathlib import Path

max_bytes = 50 * 1024 * 1024
destination = Path("./approved-result.bin")

original = file_annotation.getFile()
if original.getSize() > max_bytes:
    raise ValueError("File exceeds approved byte limit")
if destination.exists() or destination.is_symlink():
    raise FileExistsError(destination)

written = 0
with destination.open("xb") as handle:
    for chunk in file_annotation.getFileInChunks():
        written += len(chunk)
        if written > max_bytes:
            raise ValueError("Received more than approved byte limit")
        handle.write(chunk)

On failure, delete the partial local file if policy permits. Do not download all file annotations attached to a project/dataset without an explicit list.

Uploading is a mutation:

source = "./approved-analysis.csv"
annotation = conn.createFileAnnfromLocalFile(
    source,
    mimetype="text/csv",
    ns="org.example.analysis.v1",
    desc="Reviewed analysis results",
)
dataset.linkAnnotation(annotation)

Check local file size, type, content classification, target dataset ID/group, and whether upload is permitted before execution.

Numeric and Boolean Values

Wrapper examples:

from omero.gateway import (
    BooleanAnnotationWrapper,
    DoubleAnnotationWrapper,
    LongAnnotationWrapper,
)

Numeric values still need units and semantics in the namespace/schema. Do not infer that DoubleAnnotation values are in micrometers or that a LongAnnotation is a count.

Unlink Versus Delete

• Unlink deletes an object-annotation link but keeps the annotation and other links.
• Delete annotation deletes the annotation and may affect every linked object.

Before either operation:

1. retrieve and display exact link/annotation IDs;
2. count other links;
3. verify ownership and permission;
4. obtain explicit approval for the exact operation;
5. do not use a namespace-only bulk delete without an ID review;
6. wait for and check command completion.

Read-only export utilities must not include delete/unlink modes.

Metadata Export Checklist

• Explicit object type and IDs
• One group context
• Maximum objects, annotations, links, pairs, and string length
• Values redacted by default
• File names and owner names separately gated
• No attachment bytes unless one file and byte cap are approved
• Output path chosen by caller; no remote-derived path
• Atomic write with owner-only permissions
• Connection closed in finally