/omero-integration

name: "omero-integration"
description: "Open-source bio-image data management. Use the omero-py client to connect to an OMERO server, retrieve images as numpy arrays, annotate with tags and key-value pairs, manage ROIs, and feed image data into Python analysis pipelines — programmatically, no GUI."
license: "GPL-2.0"

omero-integration

Overview

OMERO is an open-source image data management system widely used in microscopy facilities and core labs. The `omero-py` library provides a Python client (`BlitzGateway`) that connects to an OMERO server, allowing programmatic access to images, datasets, projects, tags, annotations, and ROIs. Use it to build automated analysis workflows that pull images from OMERO, process them in Python, and write results back as annotations.

When to Use

• **Programmatic image retrieval from OMERO**: Downloading microscopy images as numpy arrays for downstream analysis without using the OMERO Insight GUI.
• **Bulk annotation and tagging**: Applying tags, key-value pair annotations, or comments to large numbers of images/datasets based on analysis results.
• **ROI access and management**: Reading segmentation ROIs (shapes) stored in OMERO for downstream quantification or export.
• **Integrating OMERO into Python analysis pipelines**: Connecting OMERO image data to scikit-image, OpenCV, CellPose, or other image analysis tools.
• **Automated QC workflows**: Querying images by metadata (channel, acquisition date, experimenter) and flagging those that fail quality criteria.
• **Data provenance tracking**: Attaching analysis provenance (parameters, tool versions) as structured key-value annotations to images.
• For local image analysis without an OMERO server, use `tifffile`, `aicsimageio`, or `imageio` directly.

Prerequisites

• **Python packages**: `omero-py`, `numpy`, `Pillow`
• **System**: Java 8+ (required by `omero-py` internals), Ice 3.6 (installed automatically via conda)
• **Data requirements**: Access credentials to a running OMERO server (host, port, username, password)
• **Environment**: Conda is strongly recommended; `omero-py` has complex dependencies

conda create -n omero python=3.9
conda activate omero
conda install -c ome -c conda-forge omero-py
pip install numpy Pillow

Quick Start

import omero
from omero.gateway import BlitzGateway

# Connect to OMERO server
conn = BlitzGateway("username", "password", host="omero.example.org", port=4064)
conn.connect()
print(f"Connected: {conn.isConnected()}, user: {conn.getUser().getName()}")

# Get an image by ID and download as numpy array
image = conn.getObject("Image", 12345)
pixels = image.getPrimaryPixels()
plane = pixels.getPlane(0, 0, 0)   # z=0, c=0, t=0
print(f"Image shape: {plane.shape}, dtype: {plane.dtype}")

conn.close()

Core API

Module 1: BlitzGateway — Connection Management

`BlitzGateway` is the main entry point for all server interactions.

from omero.gateway import BlitzGateway

# Establish connection
conn = BlitzGateway(
    username="user",
    passwd="password",
    host="omero.example.org",
    port=4064,
    secure=True,
)
success = conn.connect()
print(f"Connected: {success}")
print(f"Server version: {conn.getServerVersion()}")
print(f"Current group: {conn.getGroupFromContext().getName()}")

# Always close when done
conn.close()

# Context manager pattern for automatic cleanup
class OmeroConnection:
    def __init__(self, **kwargs):
        self.conn = BlitzGateway(**kwargs)
    def __enter__(self):
        self.conn.connect()
        return self.conn
    def __exit__(self, *args):
        self.conn.close()

with OmeroConnection(username="user", passwd="pass",
                     host="omero.example.org", port=4064) as conn:
    print(f"Connected as: {conn.getUser().getFullName()}")

Module 2: Project, Dataset, and Image Queries

Traverse the OMERO data hierarchy (Project → Dataset → Image).

# List all projects for the current user
for project in conn.listProjects():
    print(f"Project {project.getId()}: {project.getName()}")
    for dataset in project.listChildren():
        print(f"  Dataset {dataset.getId()}: {dataset.getName()}")
        for image in dataset.listChildren():
            print(f"    Image {image.getId()}: {image.getName()}")

# Search for images by name
results = conn.searchObjects(["Image"], "GFP_control")
for img in results:
    print(f"  Found: {img.getId()} - {img.getName()}")

# Get a specific object by ID
image   = conn.getObject("Image",   12345)
dataset = conn.getObject("Dataset", 678)
project = conn.getObject("Project", 90)
print(f"Image: {image.getName()}, size: {image.getSizeX()}x{image.getSizeY()}")
print(f"Channels: {image.getSizeC()}, Z-slices: {image.getSizeZ()}, timepoints: {image.getSizeT()}")

Module 3: Image Download as NumPy Arrays

Retrieve pixel data as numpy arrays for processing.

import numpy as np

image  = conn.getObject("Image", 12345)
pixels = image.getPrimaryPixels()

# Get a single 2D plane: getPlane(z_index, channel_index, time_index)
plane = pixels.getPlane(0, 0, 0)
print(f"Plane shape: {plane.shape}, dtype: {plane.dtype}")

# Get all channels at z=0, t=0
planes = [pixels.getPlane(0, c, 0) for c in range(image.getSizeC())]
stack  = np.stack(planes, axis=0)   # shape: (C, Y, X)
print(f"Multi-channel stack: {stack.shape}")

# Efficient bulk download using getTiles (for large images)
image  = conn.getObject("Image", 12345)
pixels = image.getPrimaryPixels()

tile_coords = [(0, 0, 0, (0, 0, 512, 512))]  # (z, c, t, (x, y, w, h))
for tile in pixels.getTiles(tile_coords):
    print(f"Tile shape: {tile.shape}")  # (512, 512) numpy array

Module 4: Tag and Annotation Management

Add, retrieve, and update tags and key-value pair annotations on OMERO objects.

import omero

# Add a tag to an image
tag_ann = omero.gateway.TagAnnotationWrapper(conn)
tag_ann.setValue("passed_QC")
tag_a