alterlab-omero

OMERO 集成

概述

OMERO 是一个开源平台，用于管理、可视化和分析显微镜图像及元数据。通过 Python API 访问图像、检索数据集、分析像素、管理 ROI 和注释，适用于高内涵筛选和显微镜工作流。

何时使用此技能

在以下情况下应使用此技能：

• 使用 OMERO Python API（omero-py）访问显微镜数据
• 以编程方式检索图像、数据集、项目或筛选数据
• 分析像素数据并创建衍生图像
• 在显微镜图像上创建或管理 ROI（感兴趣区域）
• 向 OMERO 对象添加注释、标签或元数据
• 在 OMERO 表格中存储测量结果
• 创建用于批处理的服务器端脚本
• 执行高内涵筛选分析

不适用的情况

场景	改用
从 NCI Imaging Data Commons 下载公开的癌症放射学／病理学 DICOM	alterlab-imaging-data-commons
对本地文件中的全切片图像进行切片或预处理	alterlab-histolab
端到端计算病理学模型（分割、图结构、训练）	alterlab-pathml
读取或匿名化临床 DICOM 文件	alterlab-pydicom

核心功能

此技能涵盖八个主要功能领域。每个领域都在 references/ 目录中详细说明：

1. 连接与会话管理

文件：references/connection.md

与 OMERO 服务建立安全连接、管理会话、处理身份验证，并使用组上下文。用于初始设置和连接模式。

常见场景：

• 使用凭据连接到 OMERO 服务
• 使用现有会话 ID
• 在不同组上下文之间切换
• 使用上下文管理器管理连接生命周期

2. 数据访问与检索

文件：references/data_access.md

浏览 OMERO 的分层数据结构（Projects → Datasets → Images）和筛选数据（Screens → Plates → Wells）。检索对象、按属性查询并访问元数据。

常见场景：

• 列出某用户的所有项目和数据集
• 按 ID 或数据集检索图像
• 访问筛选板数据
• 使用筛选条件查询对象

3. 元数据与注释

文件：references/metadata.md

创建和管理注释，包括标签、键值对、文件附件和评论。将注释关联到图像、数据集或其他对象。

常见场景：

• 向图像添加标签
• 将分析结果作为文件附加
• 创建自定义键值元数据
• 按命名空间查询注释

4. 图像处理与渲染

文件：references/image_processing.md

将原始像素数据作为 NumPy 数组访问、调整渲染设置、创建衍生图像并管理物理尺寸。

常见场景：

• 提取像素数据以进行计算分析
• 生成缩略图
• 创建最大强度投影
• 修改通道渲染设置

5. 感兴趣区域（ROI）

文件：references/rois.md

创建、检索和分析各种形状的 ROI（矩形、椭圆、多边形、掩膜、点、线）。提取 ROI 区域的强度统计数据。

常见场景：

• 在图像上绘制矩形 ROI
• 创建用于分割的多边形掩膜
• 分析 ROI 内的像素强度
• 导出 ROI 坐标

6. OMERO 表格

文件：references/tables.md

存储和查询与 OMERO 对象关联的结构化表格数据。适用于分析结果、测量数据和元数据。

常见场景：

• 存储图像的定量测量数据
• 创建包含多种列类型的表格
• 按条件查询表格数据
• 将表格关联到特定图像或数据集

7. 脚本和批量操作

文件：references/scripts.md

创建在服务端运行的 OMERO.scripts，用于批量处理、自动化工作流以及与 OMERO 客户端集成。

常见场景：

• 批量处理多张图像
• 创建自动化分析流水线
• 生成跨数据集的汇总统计信息
• 以自定义格式导出数据

8. 高级功能

文件：references/advanced.md

介绍权限、文件集、跨组查询、删除操作和其他高级功能。

常见场景：

• 处理组权限
• 访问导入的原始文件
• 执行跨组查询
• 使用回调删除对象

安装

# 1. Install a prebuilt ZeroC Ice 3.6 wheel for your Python version and OS first
#    (Glencoe Software builds; links on the OMERO.py page below)
uv pip install /path/to/zeroc_ice-3.6.5-<python>-<platform>.whl
# 2. Then OMERO.py
uv pip install omero-py

要求（截至 2026-09 的当前版本为 omero-py 5.23.x）：

• Python 3.10+ 和 NumPy 2
• ZeroC Ice：omero-py 固定使用 zeroc-ice>=3.6.5,<3.7。PyPI 仅提供适用于 Python 2.7/3.7 的 3.6.5 轮子，因此如果没有预构建轮子，pip 会尝试从源代码编译 Ice；不支持 Ice 3.7/3.8。轮子列表请参阅 https://omero.readthedocs.io/en/stable/developers/Python.html。
• 可访问 OMERO 服务（主机、端口、凭据）；如果使用 omero CLI，请设置 OMERODIR

快速入门

基本连接模式：

from omero.gateway import BlitzGateway

# Connect to OMERO server
conn = BlitzGateway(username, password, host=host, port=port)
connected = conn.connect()

if connected:
    # Perform operations
    for project in conn.listProjects():
        print(project.getName())

    # Always close connection
    conn.close()
else:
    print("Connection failed")

推荐使用上下文管理器的模式：

from omero.gateway import BlitzGateway

with BlitzGateway(username, password, host=host, port=port) as conn:
    # Connection automatically managed
    for project in conn.listProjects():
        print(project.getName())
    # Automatically closed on exit

选择合适的功能

用于数据探索：

• 从 references/connection.md 开始建立连接
• 使用 references/data_access.md 浏览层级结构
• 查看 references/metadata.md 了解注释详情

用于图像分析：

• 使用 references/image_processing.md 访问像素数据
• 使用 references/rois.md 进行基于区域的分析
• 使用 references/tables.md 存储结果

用于自动化：

• 使用 references/scripts.md 进行服务端处理
• 使用 references/data_access.md 批量检索数据

用于高级操作：

• 使用 references/advanced.md 处理权限和删除
• 查看 references/connection.md 了解跨组查询

常见工作流

工作流 1：检索并分析图像

1. 连接到 OMERO 服务（references/connection.md）
2. 浏览至数据集（references/data_access.md）
3. 从数据集检索图像（references/data_access.md）
4. 将像素数据作为 NumPy 数组访问（references/image_processing.md）
5. 执行分析
6. 将结果存储为表格或文件注释（references/tables.md 或 references/metadata.md）

工作流 2：批量 ROI 分析

1. 连接到 OMERO 服务
2. 检索含有现有 ROI 的图像（references/rois.md）
3. 获取每张图像的 ROI 形状
4. 提取 ROI 内的像素强度（references/rois.md）
5. 将测量结果存储在 OMERO 表格中（references/tables.md）

工作流 3：创建分析脚本

1. 设计分析工作流
2. 使用 OMERO.scripts 框架（references/scripts.md）
3. 通过脚本参数访问数据
4. 批量处理图像
5. 生成输出（新图像、表格、文件）

错误处理

始终使用 try-except 块包装 OMERO 操作，并确保正确关闭连接：

from omero.gateway import BlitzGateway
import traceback

conn = None  # bind first so the finally block is safe if the constructor raises
try:
    conn = BlitzGateway(username, password, host=host, port=port)
    if not conn.connect():
        raise Exception("Connection failed")

    # Perform operations

except Exception as e:
    print(f"Error: {e}")
    traceback.print_exc()
finally:
    if conn:
        conn.close()

其他资源

• 官方文档：https://omero.readthedocs.io/en/stable/developers/Python.html
• BlitzGateway API：https://omero.readthedocs.io/en/stable/developers/Python.html#omero-blitzgateway
• OMERO 模型：https://omero.readthedocs.io/en/stable/developers/Model.html
• 社区论坛：https://forum.image.sc/tag/omero

备注

• OMERO 使用基于组的权限（READ-ONLY、READ-ANNOTATE、READ-WRITE）
• OMERO 中的图像按层级组织：Project > Dataset > Image
• 筛选数据使用：Screen > Plate > Well > WellSample > Image
• 始终关闭连接，以释放服务端资源
• 使用上下文管理器自动管理资源
• 像素数据以 NumPy 数组形式返回，用于分析

属于 AlterLab Academic Skills 套件。