OME-Zarr 與 OME-TIFF 的熒光顯微影像標註

v2.13.0 新增

microscopy 標註方案顯示以 OME-Zarr 或 OME-TIFF 儲存的多通道顯微影像，並記錄標註者在影像上標出的感興趣區域（ROI）和賦予的細胞類別。標註者可以開關通道，設定每個通道的顏色和對比度上下限，逐層瀏覽 z 切片和時間點，並沿檔案自帶的解析度金字塔縮放。細胞生物學研究者和成像核心平臺用這個方案在已有的分割結果上做細胞分類，例如在免疫熒光面板中把每個細胞核判為標記物陽性或標記物陰性。篩選團隊用同一個方案為高內涵篩選視野中的表型評分，組織項目則把受損區域和碎屑標為區域。多名標註者可以標註同一幅影像，匯出時每位標註者的區域和類別分開儲存。

OME-Zarr 是開放顯微環境（Open Microscopy Environment）的分塊、多尺度影像格式，也稱 OME-NGFF；OME-TIFF 是一種 TIFF 檔案，其 OME-XML 頭部給出通道和維度的名稱。標籤影像（label image）是以整數儲存的分割結果，每個細胞一個 id，背景為 0。Cellpose 和 StarDist 等分割工具會輸出標籤影像。Potato 讀取在別處生成的標籤影像，自己不執行任何分割模型。

• 格式： 通過 zarr-python 讀取 OME-Zarr 0.4（Zarr v2）和 0.5（Zarr v3），包括按當前 NGFF 開發版規範把座標軸列在 coordinateSystems 下的多尺度影像。通過 tifffile 讀取 OME-TIFF，金字塔以 SubIFD 形式儲存時也能讀取。
• 座標軸： t、c、z 中的任意幾個，加上 y 和 x。含有其他座標軸的檔案會被拒絕，並給出提示資訊。沒有 C 軸的 RGB TIFF 會把 RGB 取樣當作通道讀取。
• 通道： 名稱、顏色和顯示視窗取自 OME-Zarr 的 omero 塊或 OME-XML 的 Channel 元素。沒有顯示視窗的檔案以最粗金字塔層級的第 0.5 和第 99.8 百分位為初始值，滑塊的上限是能容納資料的最小位深（以 uint16 儲存的 12 位資料為 4095）。沒有顏色的通道依次取藍、綠、紅、品紅、青、黃、白和橙。
• 標籤影像： OME-Zarr 影像的 labels/ 組無需配置即可找到。OME-TIFF 沒有存放標籤影像的標準位置，因此 OME-TIFF 條目要另外指定一個整數標籤 TIFF。
• 離線： 檢視器不從 Potato 伺服器以外載入任何內容。不支援通過 HTTP 或 S3 訪問遠端 OME-Zarr。

Potato 在伺服器上根據可見通道及其對比度上下限合成每個瓦片，瀏覽器在 OpenSeadragon 中顯示合成後的 JPEG 瓦片。伺服器端合成不需要 WebGL，也不向瀏覽器傳送原始通道資料，代價是每次更改通道或對比度設定時，可見瓦片都要往返一次。

讀取器需要 microscopy 可選依賴：

pip install 'potato-annotation[microscopy]'

這個可選依賴在 Python 3.11 及以上版本安裝 zarr-python 3，在更早的 Python 上安裝 zarr-python 2，同時安裝 tifffile。zarr-python 2 無法讀取 OME-Zarr 0.5，因此 OME-Zarr 0.5 儲存需要 Python 3.11 或更高版本。

配置

下面的配置讓三名標註者為每幅影像中的細胞分類，並勾畫受損組織或碎屑。細胞來自影像的標籤影像，區域由標註者手工繪製：

annotation_task_name: "Cell classification"
task_dir: .
media_directory: media
output_annotation_dir: annotation_output
data_files: [data/images.json]
item_properties: {id_key: id, text_key: note}
num_annotators_per_item: 3
 
user_config:
  allow_all_users: true
 
annotation_schemes:
  - annotation_type: microscopy
    name: cells
    description: "Classify the cells, and outline any region that looks damaged."
    image_key: image              # item field naming the OME-Zarr or OME-TIFF
    labels_key: cells             # item field naming a label TIFF (OME-TIFF items)
    tools: [bbox, polygon, landmark]
    labels:                       # classes for regions
      - {name: damaged, color: "#e8590c"}
      - {name: debris, color: "#868e96"}
    cell_labels:                  # classes for cells
      - {name: "marker positive", color: "#f03e3e"}
      - {name: "marker negative", color: "#4dabf7"}
      - {name: dividing, color: "#fab005"}
    channels:                     # overrides of the file's own settings
      - {name: DAPI, label: "DAPI (nuclei)"}
      - {index: 2, contrast: [100, 3000]}
    min_cells: 1
    label_requirement: {required: true}

labels 列出區域類別，cell_labels 列出細胞類別。沒有 cell_labels 時，細胞使用區域類別。第一個 channels 項為檔案中名為 DAPI 的通道重新命名，第二項為第三個通道（從 0 開始計數）設定初始對比度視窗。min_cells 與 label_requirement 同時設定時，標註者至少為一個細胞分類之前，Next 一直不可用。Potato 在伺服器啟動時檢查每個方案值，值有誤時伺服器停止執行，並給出指明該鍵的提示資訊。

只標細胞的任務

篩選中的表型評分通常只需要細胞類別，不需要區域。下面這段部分配置替換上面配置中的 annotation_schemes：

annotation_schemes:
  - annotation_type: microscopy
    name: phenotype
    description: "Give every cell in the field a phenotype."
    tools: []                     # no region tools
    label_image: cells            # entry of the OME-Zarr labels/ group
    labels: [normal, enlarged, multinucleated, apoptotic]
    channels:
      - {index: 0, color: "#0000ff"}
      - {index: 1, visible: false}
    min_cells: 20
    label_requirement: {required: true}

設定 tools: [] 後，區域工具被隱藏，類別列表作用於細胞。OME-Zarr 的 labels/ 組中有多個分割結果（例如細胞核和整個細胞）時，label_image 鍵選擇其中一項。第二個通道初始隱藏，標註者仍然可以把它開啟。

資料格式

每個條目給出相對於 media_directory 的影像路徑：

{"id": "well_A01", "image": "screen/A01.ome.zarr"}
{"id": "tissue_b", "image": "tissue_b.ome.tif", "cells": "tissue_b_cells.tif"}

Potato 先在 media_directory 中查詢該路徑，再在 task_dir 中查詢，並拒絕絕對路徑、URL 以及任何解析後位於兩者之外的路徑。對於 HCS 板或 bioformats2raw 容器，請指定儲存中的某一幅影像，例如 plate.ome.zarr/A/1/0。如果指定的是板的根目錄，Potato 會顯示一條錯誤，並建議使用內部路徑。

標籤 TIFF 包含整數，寬高與影像的全解析度寬高相同，並且只使用影像本身具有的 T、Z、Y 和 X 軸。Potato 拒絕尺寸不同的標籤 TIFF，因為從較小柵格畫出的細胞輪廓會落在影像上錯誤的位置。TIFF 平面整體解碼，超過 max_pixels 的平面會被拒絕。大影像應存為瓦片化的金字塔 OME-TIFF 或 OME-Zarr，這樣讀取器只獲取某個瓦片覆蓋的資料塊。

選項

瀏覽器根據標籤柵格判斷點選落在哪個細胞上，匯出則從同一幅標籤影像讀取細胞 id，因此點選選中的 id 就是匯出中寫出的 id。大於 label_max_side 的標籤影像，取其金字塔中能放得下的最精細層級來顯示；沒有合適的層級時，每隔幾個畫素取樣一次，比取樣步長還窄的細胞可能不會出現在柵格中。細胞數超過 50,000 的標籤影像不能用於細胞列表，會被拒絕。

細胞分類與區域繪製

標註者拖動來平移，滾動或雙指捏合來縮放。每個通道行有一個顯示或隱藏該通道的核取方塊、一個顏色色塊、Min 和 Max 對比度滑塊，以及一個恢復檔案或配置設定的 Reset 按鈕。在同一個瀏覽器會話中，Potato 會在條目之間保留通道設定。影像含有多個 z 切片或多個時間點時，影像下方會出現相應的 z 切片或時間點滑塊。

要為細胞分類，標註者選擇 Pan / select cell（按鍵 V），然後點選一個細胞。選中的細胞以黃色勾邊，按 1 到 9 中的某個鍵或點選類別按鈕即可為它指定類別。已分類的細胞以類別顏色填充。也可以輸入細胞的 id 來選中細胞。類別作用於該細胞 id，覆蓋每個 z 切片和時間點，儲存的 z 和 t 記錄標註者在哪個平面上做出分類。

要繪製區域，標註者選擇 Rectangle（R）、Polygon（P）或 Point（O），並在“Region class”下選擇類別。矩形靠拖動繪製。多邊形每個頂點點選一次，點選第一個頂點、雙擊、按 Enter 或點選“Finish polygon”按鈕即可結束。Escape 取消正在繪製的多邊形，Backspace 刪除最後一個頂點。區域屬於繪製時所在的 z 切片和時間點，也只在那裡顯示。在 Regions 列表中選中一個區域，檢視器會移到該區域所在的平面；列表中的每一項都有類別選單和刪除按鈕。

儲存的答案

每個方案為每個條目儲存一個 JSON 物件：

{"image": {"width": 256, "height": 256},
 "rois": [{"type": "polygon", "label": "damaged", "color": "#e8590c",
           "coordinates": [{"x": 0.58, "y": 0.08}, {"x": 0.86, "y": 0.12}, {"x": 0.78, "y": 0.35}],
           "z": 1, "t": 0}],
 "cells": [{"label_id": 1, "class": "marker positive", "z": 1, "t": 0}],
 "label_image": "cells"}

區域座標是相對於全解析度影像的比例值，形式與 image_annotation 方案相同。bbox 為 {x, y, width, height}，polygon 是一組點，landmark 是一個點。

匯出

microscopy 匯出把每位標註者的答案分開寫入下面命令之後列出的檔案：

python -m potato.export --config config.yaml --format microscopy --output out/

要在 QuPath 中開啟這些區域，先開啟影像，再匯入 microscopy_rois.geojson。GeoJSON 包含所有條目和標註者。多幅影像或多名標註者共用這個檔案時，匯入前先按 item_id 和 user_id 篩選要素。

源影像為 OME-Zarr 0.5 時，標籤陣列寫為 OME-Zarr 0.5，否則寫為 0.4。--option zarr_format=2 或 --option zarr_format=3 可以覆蓋版本，--option label_arrays=false 跳過標籤陣列。每個標籤陣列儲存只有一個 labels/ 組，大多數檢視器無法單獨開啟它。請把 labels/<schema>__<user> 複製到源影像的 labels/ 目錄中，並把這個名稱加入源影像 labels/ 組的 labels 列表。標籤陣列需要 zarr-python，以及位於 media_directory 下的源影像。缺少 zarr-python 或源影像時，匯出只寫出 GeoJSON 和 CSV，並列出一條警告。

Potato 的一致性指標不覆蓋 microscopy 方案。逐細胞的一致性可以在匯出後從 microscopy_cells.csv 計算，做法是按 instance_id、label_image 和 label_id 匹配行，再對匹配上的類別計算 Fleiss' kappa 或 Cohen's kappa。

全切片病理影像

SVS、NDPI、MRXS 以及 openslide 可讀的其他切片格式的明場全切片掃描，使用深度縮放檢視器中的 image_annotation 方案，並需要 wsi 可選依賴。microscopy 方案不能開啟 SVS、NDPI 或 MRXS 檔案。從 Potato 2.13 起，全切片影像上的區域可以用 potato import -i case_01.geojson --image-dir /data/slides -o case-project 從 QuPath GeoJSON 或 ASAP XML 匯入。匯入器會自動檢測格式，也可以用 -f qupath_geojson 或 -f asap_xml 顯式指定。匯入的區域成為預標註。標註者繪製的區域可以用 python -m potato.export -c config.yaml -f qupath_geojson -o out/qupath 以 0 級切片畫素座標匯出回 QuPath GeoJSON，-f asap_xml 則改為寫出 ASAP XML。

示例

python potato/flask_server.py start examples/image/multichannel-microscopy/config.yaml -p 8000

這個示例有兩幅合成影像。一幅是 OME-Zarr 0.5 儲存，含三個通道、三個 z 切片和一個 labels/cells 組；另一幅是 OME-TIFF，含三個通道、三個時間點和一個單獨的標籤 TIFF。同一目錄下的 generate_data.py 會生成這兩幅影像。

用程式設計智慧體搭建研究

potato-skill 1.2.0 面向 Potato 2.13.1，認得 microscopy 這個名稱，並指導研究設計這一側，例如向標註者問什麼、每幅影像由幾名標註者分類、培訓和注意力檢查，以及匯出。這個技能目前還沒有記錄 OME-Zarr 和 OME-TIFF 資料格式、方案選項和 microscopy 可選依賴。安裝 potato-skill，把研究描述給你的智慧體，再讓智慧體參考本頁的 Markdown 副本 https://www.potatoannotator.com/docs/annotation-types/microscopy.md，以瞭解格式和選項。

延伸閱讀

• 影像標註 - 普通影像上的框、多邊形和掩碼
• 基於深度縮放的十億畫素影像標註 - 瓦片金字塔與全切片影像
• 匯出格式 - Potato 的匯出格式和匯出命令
• 你需要多少位標註者？ - 為每個條目選擇標註者人數
• 生命科學 - 用 Potato 做生命科學與生物審編

有關實現細節，請參閱源文件。