jaechang-hits/omero-integration

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_ann.setNs("my.analysis.namespace")
tag_ann.save()

image = conn.getObject("Image", 12345)
image.linkAnnotation(tag_ann)
print(f"Tag '{tag_ann.getValue()}' linked to image {image.getId()}")

# Add key-value pairs (MapAnnotation) to an image
map_ann = omero.gateway.MapAnnotationWrapper(conn)
map_ann.setNs("openmicroscopy.org/omero/client/mapAnnotation")
kv_pairs = [
    ["analysis_tool",    "CellProfiler 4.2"],
    ["cell_count",       "342"],
    ["mean_intensity",   "1847.3"],
    ["analysis_date",    "2026-02-18"],
]
map_ann.setValue(kv_pairs)
map_ann.save()
image.linkAnnotation(map_ann)
print(f"Key-value annotation attached to image {image.getId()}")

# Read existing annotations
for ann in image.listAnnotations():
    print(f"  {ann.OMERO_TYPE}: {ann.getValue()}")

Module 5: ROI Access

Read segmentation ROIs (shapes) stored in OMERO for downstream quantification.

from omero.model import RoiI

# Get all ROIs for an image
roi_service = conn.getRoiService()
result = roi_service.findByImage(12345, None)

for roi in result.rois:
    for shape in roi.copyShapes():
        shape_type = shape.__class__.__name__
        print(f"  ROI {roi.id.val}: {shape_type}")
        if shape_type == "RectangleI":
            print(f"    x={shape.x.val:.1f}, y={shape.y.val:.1f}, "
                  f"w={shape.width.val:.1f}, h={shape.height.val:.1f}")
        elif shape_type == "EllipseI":
            print(f"    cx={shape.x.val:.1f}, cy={shape.y.val:.1f}, "
                  f"rx={shape.radiusX.val:.1f}, ry={shape.radiusY.val:.1f}")

# Convert ROI masks to numpy boolean arrays
import numpy as np
from omero.gateway import BlitzGateway

def roi_to_mask(shape, height, width):
    """Convert a rectangle ROI to a boolean numpy mask."""
    mask = np.zeros((height, width), dtype=bool)
    x  = int(shape.x.val)
    y  = int(shape.y.val)
    w  = int(shape.width.val)
    h  = int(shape.height.val)
    mask[y:y+h, x:x+w] = True
    return mask

image  = conn.getObject("Image", 12345)
height = image.getSizeY()
width  = image.getSizeX()

result = conn.getRoiService().findByImage(12345, None)
for roi in result.rois:
    for shape in roi.copyShapes():
        if shape.__class__.__name__ == "RectangleI":
            mask = roi_to_mask(shape, height, width)
            print(f"ROI mask: {mask.sum()} pixels selected")

Key Concepts

OMERO Data Hierarchy

OMERO organizes data as Project → Dataset → Image. Images contain pixel data plus metadata (channels, Z-slices, timepoints). Annotations (tags, key-value pairs, comments) can be attached to any level of the hierarchy.

# Hierarchy navigation
project = conn.getObject("Project", 90)
for dataset in project.listChildren():
    imgs = list(dataset.listChildren())
    print(f"Dataset '{dataset.getName()}': {len(imgs)} images")

Pixel Access Patterns

OMERO stores pixels as (Z, C, T) stacks. getPlane(z, c, t) returns a single 2D numpy array. For large images, use getTiles to download spatial subregions. Pixel type (uint8, uint16, float32) matches the original acquisition format.

image  = conn.getObject("Image", 12345)
pixels = image.getPrimaryPixels()
ptype  = pixels.getPixelsType().getValue()
print(f"Pixel type: {ptype}")  # e.g., "uint16"
print(f"Dimensions: XY={image.getSizeX()}x{image.getSizeY()}, "
      f"Z={image.getSizeZ()}, C={image.getSizeC()}, T={image.getSizeT()}")

Common Workflows

Workflow 1: Batch Download and Analysis

Goal: Download all images from a dataset, apply processing, and store results as key-value annotations.

import numpy as np
from omero.gateway import BlitzGateway, MapAnnotationWrapper

def mean_intensity(plane):
    return float(plane.mean())

conn = BlitzGateway("user", "pass", host="omero.example.org", port=4064)
conn.connect()

dataset = conn.getObject("Dataset", 678)
results = []

for image in dataset.listChildren():
    pixels = image.getPrimaryPixels()
    plane  = pixels.getPlane(0, 0, 0)         # first z, channel 0, t=0
    mi     = mean_intensity(plane)
    results.append((image, mi))

    # Attach mean intensity as key-value annotation
    ann = MapAnnotationWrapper(conn)
    ann.setNs("my.pipeline.v1")
    ann.setValue([["mean_intensity_ch0", f"{mi:.2f}"]])
    ann.save()
    image.linkAnnotation(ann)
    print(f"Image {image.getId()} '{image.getName()}': mean={mi:.2f}")

print(f"\nProcessed {len(results)} images in dataset '{dataset.getName()}'")
conn.close()

Workflow 2: Retrieve Images by Tag and Export

Goal: Find all images tagged "screen_hits", download channel 1 as numpy arrays, and save as TIFF files.

import numpy as np
import tifffile
from omero.gateway import BlitzGateway

conn = BlitzGateway("user", "pass", host="omero.example.org", port=4064)
conn.connect()

# Find images with a specific tag
tag_value = "screen_hits"
tagged_images = []
for ann in conn.getObjects("TagAnnotation", attributes={"textValue": tag_value}):
    for image in ann.listLinkedObjects(["Image"]):
        tagged_images.append(image)

print(f"Found {len(tagged_images)} images tagged '{tag_value}'")

for image in tagged_images:
    pixels = image.getPrimaryPixels()
    # Download DAPI channel (index 0) at z=0, t=0
    plane  = pixels.getPlane(0, 0, 0)
    fname  = f"image_{image.getId()}_DAPI.tif"
    tifffile.imwrite(fname, plane)
    print(f"Saved {fname}: shape={plane.shape}, dtype={plane.dtype}")

conn.close()
print("Export complete")

Key Parameters

| Parameter | Module | Default | Range / Options | Effect | |-----------|--------|---------|-----------------|--------| | host | BlitzGateway | required | hostname or IP | OMERO server address | | port | BlitzGateway | 4064 | 1024–65535 | OMERO server port (4064 = standard) | | secure | BlitzGateway | False | True, False | Use SSL/TLS encrypted connection | | z, c, t | getPlane | 0, 0, 0 | 0 – size-1 | Z-slice, channel, timepoint indices | | tile_coords | getTiles | — | list of (z,c,t,(x,y,w,h)) | Spatial subregion download coordinates | | Ns | annotations | None | any URI string | Namespace for annotation filtering |

Best Practices

1. Always close the connection: Call conn.close() after all operations, or use a context manager. Unclosed connections consume server resources and can cause session timeouts.

2. Use namespaces on annotations: Set a unique Ns (namespace URI) on every annotation you create so your programmatic annotations can be distinguished from manual ones and other tools.

3. Download only the planes you need: For large time-lapse or Z-stack images, use getPlane(z, c, t) with specific indices rather than downloading all planes. For spatial subsets, use getTiles.

4. Batch annotation writes to reduce server round-trips: Collect key-value pairs across multiple images and write them in a loop rather than making individual RPC calls per image per key.

5. Check image dimensions before processing: Always read getSizeX(), getSizeY(), getSizeC(), getSizeZ(), getSizeT() before accessing pixel data to avoid index-out-of-bounds errors on unexpectedly shaped datasets.

Common Recipes

Recipe: List All Tags on an Image

When to use: Inspect existing annotations before adding new ones to avoid duplicates.

image = conn.getObject("Image", 12345)
for ann in image.listAnnotations():
    if ann.OMERO_TYPE == "TagAnnotation":
        print(f"  Tag: '{ann.getValue()}' (ns={ann.getNs()})")
    elif ann.OMERO_TYPE == "MapAnnotation":
        for k, v in ann.getValue():
            print(f"  KV: {k} = {v}")

Recipe: Multi-Channel Max Projection

When to use: Create a maximum intensity projection across all Z-slices for a given channel.

import numpy as np

def max_projection(image, channel=0, timepoint=0):
    pixels = image.getPrimaryPixels()
    planes = [pixels.getPlane(z, channel, timepoint)
              for z in range(image.getSizeZ())]
    stack  = np.stack(planes, axis=0)
    return stack.max(axis=0)

image = conn.getObject("Image", 12345)
proj  = max_projection(image, channel=1)
print(f"Max projection shape: {proj.shape}, max value: {proj.max()}")

Expected Outputs

• NumPy arrays from getPlane(): shape (Y, X), dtype matching acquisition (uint8, uint16, float32)
• Multi-channel stacks: shape (C, Y, X) when stacking planes
• Annotations attached to images visible in OMERO.web and OMERO Insight GUI
• ROI shapes returned as omero.model objects with coordinate attributes

Troubleshooting

| Problem | Cause | Solution | |---------|-------|----------| | Ice.ConnectionRefusedException | Wrong host/port or server down | Verify host and port=4064; confirm server is running | | omero.SecurityViolation | Insufficient permissions on object | Check group membership; ask server admin to grant access | | ImportError: omero | omero-py not installed via conda | Use conda install -c ome -c conda-forge omero-py; pip install is unreliable | | AttributeError: 'NoneType' object | Object ID not found on server | Verify the object exists with conn.getObject(type, id) returns non-None | | Ice.MemoryLimitException | Downloading very large image all at once | Use getTiles() for spatial subsets or getPlane() per slice | | Slow download speed | Downloading many small planes sequentially | Use getTiles() with a list of all coordinates for batch download | | Session timeout mid-run | Long-running analysis exceeds server idle timeout | Call conn.keepAlive() periodically in long loops |

References

• OMERO Python API Documentation — official omero-py docs
• OMERO Developer Documentation — Python client guide
• OMERO GitHub (ome/omero-py) — source code and issue tracker
• Linkert et al. (2010), J Cell Biol — OMERO paper — original OMERO publication