omero-integration

OMERO 集成

使用当前 OME 文档，并将数据范围明确限定为最小范围。OMERO 数据可能包含未发布的图像、标识符、注释、原始文件和派生测量数据。

已验证基线

此技能于 2026-07-23 更新：

• OMERO.server 5.6.18（2026 年 5 月）是当前文档记录的稳定版服务器。
• OME 使用 OMERO.py/omero-py 5.22.1 和 OMERO.web 5.31.0 对其进行了测试。
• omero-py==5.22.1 需要 Python 3.10 或更高版本。OMERO 支持矩阵支持 3.10 和 3.11，推荐 3.12，并仍将 3.13/3.14 标注为“即将推出”。
• OMERO 5.6 使用 IcePy 3.6，文档记录了适用于最高 Python 3.12 版本的 3.6.5 预构建客户端 wheel。

上述固定版本是可复现的技能快照，并不保证每个 OMERO.server 版本都接受该客户端。对于其他服务器版本，请查阅其版本条目，并使用经过该版本测试的 OMERO.py 版本。参见 references/sources.md。

操作约定

1. 从本地验证或试运行开始。只有在用户选定主机、组、对象类型、ID 和结果数量上限后，才能连接。
2. 仅从 frontmatter 中指定的 OMERO_* 变量读取凭据。切勿搜索父目录或加载 .env 文件。
3. 切勿将密码或会话密钥放入命令参数、源代码、输出 JSON、日志、回溯或聊天中。会话密钥是持有者凭据。
4. 默认使用 secure=True。OMERO 默认会加密登录，但此后传输的数据和会话 ID 可能未加密。仅设置 secure=True 并不能保证验证证书主机名。
5. 限制每个列表、页面、ROI、形状、注释、表格行、像素平面和本地文件扫描的范围。未经明确批准，不要将单个对象请求扩展为整个组或跨组导出。
6. 将所有写入操作分别处理：创建注释/链接、保存渲染默认设置、创建图像、导入、上传脚本、写入表格、更改所有权或组，以及删除，都必须指定并审查确切目标。
7. 在 finally 块或文档记录的上下文管理器模式中，关闭 BlitzGateway、表格句柄、原始存储、缩略图存储、渲染引擎、脚本客户端及其他有状态服务。
8. 切勿仅为了“测试”示例而连接真实服务器。

选择接口

• BlitzGateway（omero-py）：用于遍历对象、处理像素、注释、ROI、渲染和服务的主要 Python 客户端。
• OMERO CLI：用于会话、导入扫描/导入、OME-TIFF 或 XML 导出、脚本和管理插件。大多数客户端命令会连接远程服务；导入还需要通过 OMERODIR 提供匹配的服务器端 Java 库。
• OMERO.web api 和 webgateway：官方文档称其为稳定公共 API 的仅有两个 OMERO.web 应用。文档中的 JSON API 会发现版本，且对象覆盖范围有限；这并不能证明每个 webclient URL 都是受支持的 REST 端点。
• OMERO.server 脚本：由服务器基础设施执行的上传插件。它们不同于 scripts/ 中捆绑的本地客户端辅助工具。

安装可复现的客户端

创建 Python 3.12 环境：

uv venv --python 3.12 .venv
source .venv/bin/activate

安装与解释器、操作系统、架构和 wheel 标签匹配的确切 IcePy 3.6.5 wheel，然后安装 OMERO.py：

# Download the matching 3.6.5 wheel from the official OMERO-linked matrix.
uv pip install "/absolute/path/to/zeroc_ice-3.6.5-<matching-tags>.whl"
uv pip install "omero-py==5.22.1"

不要替换为 Ice 3.7：OMERO 5.6 支持矩阵将 Ice 3.6 标记为推荐版本，将 3.7 标记为不受支持。直接安装可能会尝试从源代码编译 IcePy；请优先使用经过审查且匹配的 wheel。上游软件包采用 GPL-2.0-or-later 许可证；此技能自身的文件采用 MIT 许可证。

仅对于导入/管理命令，OMERODIR 必须指向兼容的已解压 OMERO.server 目录。普通远程 BlitzGateway 客户端不需要该服务器目录。在安装或进行身份验证前，请阅读 references/connection.md。

凭据与连接

在调用环境或密钥管理器中设置具名变量。不要将密码放在 omero CLI 命令中：

export OMERO_HOST="omero.example.org"
export OMERO_PORT="4064"
export OMERO_USER="researcher"
export OMERO_SECURE="true"
# Supply OMERO_PASSWORD through the environment/secret manager, or use
# OMERO_SESSION_KEY as an alternative. Do not echo either value.

使用密码进行身份验证且可安全处理异常的读取模式如下：

import os
from omero.gateway import BlitzGateway

conn = None
try:
    conn = BlitzGateway(
        os.environ["OMERO_USER"],
        os.environ["OMERO_PASSWORD"],
        host=os.environ["OMERO_HOST"],
        port=int(os.environ.get("OMERO_PORT", "4064")),
        secure=True,
    )
    if not conn.connect():
        raise RuntimeError("OMERO connection failed")

    images = conn.getObjects(
        "Image",
        opts={"limit": 25, "offset": 0, "order_by": "obj.id"},
    )
    for image in images:
        print(image.getId())  # Do not print names unless requested.
finally:
    if conn is not None:
        conn.close()

有关现有会话和 CLI 提示词模式、证书验证、组上下文及清理的详情，请阅读 references/connection.md。

捆绑的安全辅助工具

所有辅助工具均使用 argparse；即使未安装 OMERO，也可使用 --help。远程 辅助工具默认以试运行模式运行，必须指定 --execute 才会执行。

python -B scripts/validate_config.py --help
python -B scripts/inventory.py --help
python -B scripts/export_image_metadata.py --help
python -B scripts/plan_transfer.py --help

• validate_config.py：仅在本地验证具名端点／身份验证变量； 可选的 DNS 解析仍不会联系 OMERO。
• inventory.py：范围受限、只读的对象清单，支持分页 JSON 输出。
• export_image_metadata.py：导出指定图像的标注／ROI JSON，默认进行脱敏并限制各类别数量；绝不会下载文件字节或像素。
• plan_transfer.py：仅在本地扫描导入内容或为每张图像制定导出计划；绝不会调用 OMERO，也不会输出凭据标志。

使用前请阅读 references/scripts.md。

功能指南

• 连接、会话、组、TLS： references/connection.md
• 层级结构、分页、筛选数据、导入／导出： references/data_access.md
• 标签、地图／文件／评论标注、命名空间： references/metadata.md
• 原始平面、图块、缩略图、渲染： references/image_processing.md
• ROI 模型、形状导出、统计注意事项： references/rois.md
• 范围受限的表创建、分页、查询、关闭： references/tables.md
• 本地辅助工具和 OMERO.server 脚本： references/scripts.md
• 权限、文件集、Web／公开链接、破坏性操作： references/advanced.md

远程操作前的最终检查

• 确认服务器版本及其经过测试的 OMERO.py 配套版本。
• 确认目标主机、SSL 路由器端口、用户／会话，以及一个组。
• 确认对象的确切 ID／类型和硬性限制。
• 确认名称、标注值、文件名、ROI 标签、所有者名称、像素或原始文件是否可以离开服务器。
• 显示拟定的输出路径；除非明确允许，否则拒绝覆盖。
• 执行写入操作时，将变更内容和目标 ID 与任何读取计划分开显示。
• 即使发生部分失败，也要关闭每个连接／服务。

Agent 操作流程

1. 检查环境。 确认仪器或平台型号、API 版本、凭据，以及是否提供模拟器。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。任何会影响结果的值都要询问，不要猜测。
3. 先运行小规模版本。 先模拟该流程，或使用水或虚拟实验室器皿运行，再使用真实样本。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 核对体积、实验台布局和实验室器皿定义；执行前请人工审批该流程。
6. 汇报。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些事项仍不确定。

如果发生这种情况	请这样做
流程在模拟中失败	在模拟中修复；绝不要在未验证的情况下在硬件上运行流程。
这些说明中的函数、标志或端点在已安装的版本中不存在	查看已安装版本自带的文档（help()、--help、官方文档），进行调整并告知用户。绝不要臆造 API。
必需的输入、标识符或参数含糊不清	询问用户，或在运行前明确说明所作假设。

诚信守则

• 绝不捏造结果、参数、标识符、引用或统计数据。如果某项内容无法运行或验证，请如实说明。
• 未经用户明确确认，绝不触发实体操作、下单或扣费。
• 此处与版本相关的细节可能已过时：请对照已安装版本的官方文档进行确认。
• 对于需要付费、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征求同意。

相关技能

• labarchive-integration：安全地与官方 LabArchives 类 REST API 和 Inventory API v1 集成。