Comprehensive OMERO Module

Manage and analyze bioimaging data using OMERO (Open Microscopy Environment Remote Objects), a platform for storing, organizing, viewing, and analyzing microscopy images. This skill covers OMERO.py client operations, image import, metadata management, ROI handling, and automated analysis workflows.

When to Use This Skill

Choose Comprehensive OMERO Module when you need to:

• Store and organize large microscopy datasets in a centralized OMERO server
• Programmatically access image data, metadata, and annotations via OMERO.py
• Build automated image analysis pipelines that read from and write results to OMERO
• Manage ROIs (Regions of Interest), tags, and key-value annotations on images

Consider alternatives when:

• You need standalone image analysis without a server (use scikit-image or Fiji)
• You need cloud-based slide viewing (use commercial digital pathology platforms)
• You need real-time microscope control (use Micro-Manager)

Quick Start

Copy
# Install OMERO Python client
pip install omero-py

Copy
import omero
from omero.gateway import BlitzGateway

# Connect to OMERO server
conn = BlitzGateway("username", "password", host="omero.example.org", port=4064)
conn.connect()

# Browse datasets
for project in conn.listProjects():
    print(f"Project: {project.getName()} (ID: {project.getId()})")
    for dataset in project.listChildren():
        print(f"  Dataset: {dataset.getName()}")
        for image in dataset.listChildren():
            print(f"    Image: {image.getName()} "
                  f"({image.getSizeX()}x{image.getSizeY()})")

conn.close()

Core Concepts

OMERO Data Model

Object	Description	Relationships
Project	Top-level container	Contains Datasets
Dataset	Image collection	Contains Images, belongs to Project
Image	Microscopy image with pixels	Has Channels, ROIs, Annotations
Channel	Single imaging channel	Color, excitation/emission wavelength
ROI	Region of interest	Shapes (rectangle, polygon, line)
Annotation	Metadata attachment	Tags, key-value pairs, files, comments
Plate	Multi-well plate	Contains Wells with Images

Image Data Access and Processing

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

def process_image(conn, image_id):
    """Load and process an OMERO image as NumPy array."""
    image = conn.getObject("Image", image_id)

    # Get image dimensions
    size_x = image.getSizeX()
    size_y = image.getSizeY()
    size_z = image.getSizeZ()
    size_c = image.getSizeC()
    size_t = image.getSizeT()

    print(f"Image: {image.getName()}")
    print(f"Dimensions: X={size_x}, Y={size_y}, Z={size_z}, C={size_c}, T={size_t}")

    # Read a single plane (z=0, c=0, t=0)
    pixels = image.getPrimaryPixels()
    plane = pixels.getPlane(0, 0, 0)  # z, c, t
    print(f"Plane shape: {plane.shape}, dtype: {plane.dtype}")

    # Read all channels of a z-plane
    channels = []
    for c in range(size_c):
        ch_plane = pixels.getPlane(0, c, 0)
        channels.append(ch_plane)

    multichannel = np.stack(channels, axis=0)
    print(f"Multi-channel shape: {multichannel.shape}")

    return multichannel

conn = BlitzGateway("user", "pass", host="omero.example.org", port=4064)
conn.connect()
data = process_image(conn, image_id=12345)
conn.close()

ROI and Annotation Management

Copy
import omero
from omero.gateway import BlitzGateway
from omero.model import RoiI, RectangleI, PolygonI

def add_detection_rois(conn, image_id, detections):
    """Add ROIs from cell detection results to an OMERO image."""
    update_service = conn.getUpdateService()

    for det in detections:
        roi = RoiI()
        roi.setImage(conn.getObject("Image", image_id)._obj)

        rect = RectangleI()
        rect.setX(omero.rtypes.rdouble(det["x"]))
        rect.setY(omero.rtypes.rdouble(det["y"]))
        rect.setWidth(omero.rtypes.rdouble(det["width"]))
        rect.setHeight(omero.rtypes.rdouble(det["height"]))
        rect.setTheZ(omero.rtypes.rint(0))
        rect.setTheT(omero.rtypes.rint(0))
        rect.setTextValue(omero.rtypes.rstring(det.get("label", "cell")))

        roi.addShape(rect)
        update_service.saveObject(roi)

    print(f"Added {len(detections)} ROIs to image {image_id}")

def add_key_value_pairs(conn, image_id, kv_pairs):
    """Add key-value annotation to an image."""
    map_ann = omero.gateway.MapAnnotationWrapper(conn)
    map_ann.setNs("custom.analysis.results")
    map_ann.setValue(list(kv_pairs.items()))
    map_ann.save()

    image = conn.getObject("Image", image_id)
    image.linkAnnotation(map_ann)
    print(f"Added {len(kv_pairs)} key-value pairs to image {image_id}")

# Example: add cell detection results
detections = [
    {"x": 100, "y": 200, "width": 50, "height": 50, "label": "cell_1"},
    {"x": 300, "y": 150, "width": 45, "height": 48, "label": "cell_2"},
]
add_detection_rois(conn, 12345, detections)
add_key_value_pairs(conn, 12345, {"cell_count": "2", "method": "StarDist"})

Configuration

Parameter	Description	Default
host	OMERO server hostname	Required
port	OMERO server port	4064
group	OMERO group for permissions	User's default group
secure	Use SSL/TLS connection	false
block_size	Tile size for large image access	1024
max_plane_size	Maximum plane size to load at once	4096 × 4096

Best Practices

1. Always close connections in a finally block — OMERO connections consume server resources. Use try/finally or context managers to ensure conn.close() is called even when exceptions occur. Leaked connections eventually exhaust the server's connection pool.

2. Use tile-based access for large images — Whole slide images can be tens of gigabytes. Use pixels.getTile() to load small regions instead of getPlane(). Process images tile-by-tile and stitch results rather than loading the entire image into memory.

3. Batch annotations instead of one-at-a-time saves — Creating individual annotations in a loop makes one server round-trip per annotation. Collect all annotations in a list and save them in a single updateService.saveArray() call to reduce network overhead significantly.

4. Use groups and permissions for data sharing — Set the OMERO group context appropriately with conn.setGroupForSession(group_id) before accessing shared data. Permission errors are the most common cause of "object not found" errors when data exists but belongs to a different group.

5. Tag images consistently for retrieval — Establish a tagging convention across your lab (e.g., experiment date, staining protocol, organism). Consistent tags enable efficient searching and bulk operations. Use namespaced key-value annotations for structured metadata.

Common Issues

Connection refused or timeout errors — Verify the OMERO server is running and accessible from your network. Check that port 4064 (or your custom port) is open in the firewall. If connecting remotely, ensure the server's omero.web.public.server_list includes your client IP.

Out of memory loading large images — OMERO images can be multi-gigabyte 5D datasets. Never load all Z-planes and timepoints at once. Use getPlane(z, c, t) to load one plane at a time, or getTile(z, c, t, x, y, width, height) for sub-regions. For whole slide images, always use tiled access.

ROIs not visible in OMERO.web viewer — ROIs created via the API may not appear in the web viewer if they lack the correct Z/T plane assignment. Always set TheZ and TheT on each shape, even for 2D images (set both to 0). Missing Z/T values cause the viewer to filter them out.