skills/omero-integration/references/metadata.md
Annotations may contain participant identifiers, sample names, unpublished results, free text, remote filenames, or attached files. Read and export the minimum fields needed.
The OMERO structured annotation model includes:
TagAnnotationMapAnnotationFileAnnotationCommentAnnotationBooleanAnnotationLongAnnotationDoubleAnnotationTimestampAnnotationTermAnnotationXmlAnnotationCurrent 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.
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(), annotation.OMERO_CLASS, annotation.getNs())
print({"truncated": truncated})
Do not call getValue() when values are outside the approved export scope.
Merely avoiding printing after retrieval is weaker than not retrieving.
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.
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": annotation.OMERO_CLASS,
"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 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.
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:
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.
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.
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.
Before either operation:
Read-only export utilities must not include delete/unlink modes.
finally