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 までのバージョンに対応した IcePy 3.6.5 のビルド済みクライアントホイールがドキュメントに記載されています。

上記のバージョン固定は再現可能なスキルのスナップショットであり、すべての 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. BlitzGateway、テーブルハンドル、raw ストア、サムネイルストア、レンダリングエンジン、スクリプトクライアント、その他の状態を持つサービスは、finally ブロックまたは文書化されたコンテキストマネージャーパターンで閉じてください。
8. 例を「テスト」するだけの目的で、実サーバーに接続しないでください。

インターフェースを選ぶ

• BlitzGateway (omero-py)：オブジェクトの走査、ピクセル、注釈、ROI、レンダリング、サービスに使用する主要な Python クライアントです。
• OMERO CLI：セッション、インポートのスキャン／インポート、OME-TIFF または XML のエクスポート、スクリプト、管理用プラグインに使用します。ほとんどのクライアントコマンドはリモートで実行されます。インポートには、OMERODIR を介して対応するサーバー側の Java ライブラリも必要です。
• OMERO.web api および webgateway：公式ドキュメントが安定した公開 API としている OMERO.web アプリは、この 2 つだけです。文書化された JSON API はバージョン検出方式で、対応するオブジェクトは限定されています。すべての webclient URL がサポート対象の REST エンドポイントであることを示すものではありません。
• OMERO.server スクリプト：サーバーのインフラストラクチャによって実行される、アップロード済みのプラグインです。scripts/ にある、同梱のローカルクライアント用ヘルパーとは異なります。

再現可能なクライアントをインストールする

Python 3.12 の環境を作成します。

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

インタープリター、OS、アーキテクチャ、ホイールタグに一致する IcePy 3.6.5 のホイールを正確にインストールし、その後 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 のソースからのコンパイルが試みられる場合があります。一致することを確認したホイールを優先してください。上流パッケージのライセンスは 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 ルーターのポート、ユーザー／セッション、およびグループを 1 つ確認してください。
• オブジェクト ID／タイプと厳格な上限を確認してください。
• 名前、注釈の値、ファイル名、ROI ラベル、所有者名、ピクセルデータ、元のファイルをサーバー外に持ち出してよいか確認してください。
• 出力先のパスを示し、明示的に許可されていない限り上書きを拒否してください。
• 書き込みを行う場合は、読み取り計画とは分けて、変更内容と対象 ID を示してください。
• 部分的な失敗の後も、すべての接続／サービスを閉じてください。

エージェントの作業手順

1. 環境を確認します。 機器またはプラットフォームのモデル、API バージョン、認証情報、およびシミュレーターが利用可能かどうかを確認します。
2. 入力を明確にします。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果に影響する値は推測せず、質問してください。
3. まず小規模なバージョンを実行します。 実サンプルを使用する前に、プロトコルをシミュレーションするか、水またはダミーの実験器具を使って実行します。
4. 上記の手順と参照情報を使って、タスク全体を実行します。
5. 結果を検証します。 容量、デッキのレイアウト、実験器具の定義を確認し、実行前に人間によるプロトコルの承認を受けます。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の不確実事項を明記します。

発生した場合	対応
プロトコルがシミュレーションで失敗する	シミュレーションで修正します。検証されていないプロトコルをハードウェア上で実行してはいけません。
これらの手順に記載された関数、フラグ、またはエンドポイントがインストール済みバージョンに存在しない	インストール済みバージョン固有のドキュメント（help()、--help、公式ドキュメント）を確認して適応し、そのことをユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、またはパラメーターが曖昧である	ユーザーに質問するか、実行前に仮定を明示します。

誠実性に関するルール

• 結果、パラメーター、識別子、引用、統計を捏造してはいけません。実行または検証できない場合は、その旨を明確に伝えます。
• ユーザーの明示的な確認なしに、物理的な操作、注文、課金を実行してはいけません。
• ここに記載されたバージョン固有の情報は古い可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントで確認します。
• 金銭がかかる、共有 GPU またはクラウドのクォータを消費する、個人データまたは患者データを扱う、または取り消せない操作を行う前に、ユーザーに確認します。

関連スキル

• labarchive-integration：公式の LabArchives ELN REST ライク API および Inventory API v1 と安全に連携します。