omero-integration

Overview

OMERO is an open-source image data management system widely used in microscopy facilities and core labs. The

omero-py

BlitzGateway

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

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)

getTiles

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

host

port

4064

1024

65535

secure

False

True

False

z, c, t

0, 0, 0

0

tile_coords

(z,c,t,(x,y,w,h))

Ns

None

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

Ice.ConnectionRefusedException

host

port=4064

omero.SecurityViolation

ImportError: omero

conda install -c ome -c conda-forge omero-py

AttributeError: 'NoneType' object

conn.getObject(type, id)

Ice.MemoryLimitException

getTiles()

getPlane()

getTiles()

conn.keepAlive()

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