K-Dense-AI/scientific-agent-skills / skills/omero-integration
omero-integration
VerifiedInspects and automates microscopy data workflows against OMERO.server with omero-py, BlitzGateway, OMERO CLI, tables, annotations, ROIs, rendering, and documented OMERO.web APIs. Use this skill for scoped OMERO inventory, metadata export, import/export planning, or reviewed write workflows.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.9 KB |
| references/advanced.md | markdown | 10.4 KB |
| references/connection.md | markdown | 10.7 KB |
| references/data_access.md | markdown | 9.9 KB |
| references/image_processing.md | markdown | 7.7 KB |
| references/metadata.md | markdown | 9.1 KB |
| references/rois.md | markdown | 8.9 KB |
| references/scripts.md | markdown | 8.7 KB |
| references/sources.md | markdown | 10.9 KB |
| references/tables.md | markdown | 8.6 KB |
| scripts/export_image_metadata.py | script | 17.1 KB |
| scripts/inventory.py | script | 8.2 KB |
| scripts/omero_common.py | script | 14.2 KB |
| scripts/plan_transfer.py | script | 12.0 KB |
| scripts/validate_config.py | script | 4.0 KB |
references/metadata.md
View on GitHub# 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:
```python
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:
```python
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:
```python
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:
```bash
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:
```python
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:
```python
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:
```python
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:
```python
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:
```python
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:
```python
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:
```python
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:
```python
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:
```python
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`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |