OMERO Integration

Use current OME documentation and the smallest explicit data scope. OMERO data may contain unpublished images, identifiers, annotations, original files, and derived measurements.

Verified Baseline

This skill was refreshed on 2026-09-30:

• OMERO.server 5.6.18 (May 2026) is the current documented stable server.
• It was tested by OME with OMERO.py/omero-py 5.22.1 and OMERO.web 5.31.0.
• omero-py==5.22.1 requires Python 3.10 or newer. The OMERO support matrix supports 3.10 and 3.11, recommends 3.12, and still labels 3.13/3.14 “upcoming.”
• OMERO 5.6 uses IcePy 3.6, with 3.6.5 prebuilt client wheels documented for Python versions through 3.12.

Latest client releases: OMERO.py 5.23.0 (2026-07-30) and OMERO.web 5.33.2 are newer than the server history’s tested pairing. The bundled helpers were checked locally with OMERO.py 5.22.1 and 5.23.0, IcePy 3.6.5, and Python 3.12; this did not connect to an OMERO server. Remote snippets in this skill and its references are illustrative, verified against official docs/source, and require adaptation to an authorized server and its object IDs.

The pin above is a reproducible skill snapshot, not a promise that every OMERO.server release accepts that client. For another server version, consult its release entry and use the OMERO.py version tested with it. See references/sources.md.

Operating Contract

1. Start with local validation or a dry run. Do not connect until the user has selected the host, group, object type, IDs, and result limit.
2. Read credentials only from the named OMERO_* variables in the frontmatter. Never search parent directories or load .env files.
3. Never place a password or session key in command arguments, source code, output JSON, logs, tracebacks, or chat. A session key is a bearer credential.
4. Default to secure=True. OMERO encrypts login by default, but post-login data and the session ID may otherwise travel unencrypted. secure=True does not by itself guarantee certificate hostname verification.
5. Bound every list, page, ROI, shape, annotation, table row, pixel plane, and local file scan. Do not turn an object request into a group-wide or cross-group export without explicit approval.
6. Treat all writes separately: annotation/link creation, rendering-default saves, image creation, imports, script uploads, table writes, ownership or group changes, and deletion require an exact reviewed target.
7. Close BlitzGateway, table handles, raw stores, thumbnail stores, rendering engines, script clients, and other stateful services in finally blocks or documented context-manager patterns.
8. Never connect to a real server merely to “test” examples.

Choose the Interface

• BlitzGateway (omero-py): primary Python client for object traversal, pixels, annotations, ROIs, rendering, and services.
• OMERO CLI: sessions, import scanning/import, OME-TIFF or XML export, scripts, and administrative plugins. Most client commands are remote; import also needs the matching server-side Java libraries through OMERODIR.
• OMERO.web api and webgateway: the only OMERO.web apps that official documentation calls stable public APIs. The documented JSON API is version-discovered and has limited object coverage; it is not evidence that every webclient URL is a supported REST endpoint.
• OMERO.server scripts: uploaded plugins executed by server infrastructure. They are different from the bundled local client helpers in scripts/.

Install a Reproducible Client

Create a Python 3.12 environment:

uv venv --python 3.12 .venv
source .venv/bin/activate

Install the exact IcePy 3.6.5 wheel matching the interpreter, OS, architecture, and wheel tags, then OMERO.py:

# Download the matching 3.6.5 wheel from the official OMERO-linked matrix.
uv pip install "/absolute/path/to/zeroc_ice-3.6.5-<matching-tags>.whl"
uv pip install "omero-py==5.22.1"

Do not substitute Ice 3.7: the OMERO 5.6 support matrix marks Ice 3.6 as recommended and 3.7 as unsupported. A plain install may attempt to compile IcePy from source; prefer a reviewed matching wheel. The upstream package is GPL-2.0-or-later; this skill’s own files are MIT.

For import/admin commands only, OMERODIR must point to a compatible extracted OMERO.server directory. A normal remote BlitzGateway client does not require

…