OME-Zarr와 OME-TIFF용 형광 현미경 주석

v2.13.0에서 추가

microscopy 주석 스킴은 OME-Zarr 또는 OME-TIFF로 저장된 다채널 현미경 이미지를 보여 주고, 주석자가 이미지에 지정하는 관심 영역과 세포 클래스를 기록합니다. 주석자는 채널을 켜고 끄고, 채널별 색과 대비 한계를 설정하고, z-슬라이스와 시간 지점을 넘겨 보고, 파일 자체의 해상도 피라미드를 따라 확대합니다. 세포생물학자와 이미징 코어는 기존 분할 결과 위에서 세포를 분류하는 데 이 스킴을 사용합니다. 예를 들어 면역형광 패널에서 주석자는 각 핵을 마커 양성 또는 마커 음성으로 판정합니다. 스크리닝 그룹은 같은 스킴으로 고함량 스크리닝 시야의 표현형을 채점하며, 조직 프로젝트는 손상된 부위와 잔해를 영역으로 표시합니다. 여러 주석자가 같은 이미지에 레이블을 달 수 있고, 내보내기는 각 주석자의 영역과 클래스를 따로 보관합니다.

OME-Zarr(OME-NGFF라고도 합니다)는 Open Microscopy Environment의 청크 방식 다중 스케일 이미지 형식입니다. OME-TIFF는 OME-XML 헤더가 채널과 차원을 명시한 TIFF 파일입니다. 레이블 이미지는 정수로 저장된 분할이며, 세포당 ID 하나와 배경 0을 가집니다. Cellpose나 StarDist 같은 분할 도구가 레이블 이미지를 씁니다. Potato는 다른 곳에서 만든 레이블 이미지를 읽을 뿐 어떤 분할 모델도 실행하지 않습니다.

채널 색상과 대비 컨트롤이 세포 보기 옆에 있습니다

• 형식: Potato는 zarr-python으로 OME-Zarr 0.4(Zarr v2)와 0.5(Zarr v3)를 읽으며, 현재 NGFF 개발 명세처럼 coordinateSystems 아래에 축이 나열된 멀티스케일도 포함합니다. Potato는 tifffile로 OME-TIFF를 읽으며, tifffile은 SubIFD로 저장된 피라미드도 읽습니다.
• 축: 이미지는 y와 x에 더해 t, c, z 축을 임의로 가질 수 있습니다. 그 밖의 축이 있는 파일은 메시지와 함께 거부됩니다. 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는 보이는 채널과 채널의 대비 한계로 서버에서 각 타일을 합성합니다. 브라우저는 합성된 JPEG 타일을 OpenSeadragon에 보여 주고, 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를 함께 쓰면 주석자가 세포를 하나 이상 분류할 때까지 다음 버튼이 막혀 있습니다. 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를 고릅니다. label_max_side보다 큰 레이블 이미지는 들어가는 가장 세밀한 피라미드 수준에서 보여 주며, 들어가는 수준이 없으면 몇 픽셀마다 샘플링합니다. 그러면 샘플링 간격보다 좁은 세포는 래스터에서 빠질 수 있습니다. 세포가 50,000개를 넘는 레이블 이미지는 세포 목록에서 거부됩니다.

세포 분류와 영역 그리기

주석자는 드래그로 이동하고 스크롤이나 핀치로 확대합니다. 각 채널 행에는 채널을 표시하거나 숨기는 체크박스, 색 견본, Min 및 Max 대비 슬라이더, 파일 또는 설정의 값을 되돌리는 Reset 버튼이 있습니다. Potato는 한 브라우저 세션 안에서 항목이 바뀌어도 채널 설정을 유지합니다. 이미지에 z-슬라이스나 시간 지점이 둘 이상 있으면 이미지 아래에 해당 슬라이더가 나타납니다.

세포를 분류하려면 주석자는 Pan / select cell(V 키)을 고르고 세포를 클릭합니다. 선택한 세포는 노란색으로 윤곽이 그려지며, 1에서 9까지의 키 또는 클래스 버튼이 그 세포에 클래스를 줍니다. 분류된 세포는 클래스 색으로 채워집니다. 세포의 ID를 입력해서 세포를 선택할 수도 있습니다. 클래스는 모든 z-슬라이스와 시간 지점에서 그 세포의 ID에 적용되며, 저장되는 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로 feature를 걸러 내세요.

레이블 배열은 원본 이미지가 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의 카파 또는 Cohen의 카파를 계산합니다.

전체 슬라이드 병리 이미지

SVS, NDPI, MRXS와 openslide가 읽는 그 밖의 슬라이드 형식의 명시야 전체 슬라이드 스캔에는 wsi 엑스트라와 함께 딥 줌 뷰어의 image_annotation 스킴을 사용하세요. 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

이 예제에는 합성 이미지가 두 개 있습니다. 하나는 채널 세 개, z-슬라이스 세 개, labels/cells 그룹을 가진 OME-Zarr 0.5 저장소이고, 다른 하나는 채널 세 개, 시간 지점 세 개, 별도의 레이블 TIFF를 가진 OME-TIFF입니다. 같은 디렉터리의 generate_data.py가 두 이미지를 씁니다.

코딩 에이전트로 연구 설정하기

potato-skill 1.2.0은 Potato 2.13.1을 대상으로 하며 microscopy를 이름으로 압니다. 이 스킬은 연구 설계 측면을 안내합니다. 주석자에게 무엇을 물을지, 이미지당 몇 명의 주석자가 분류할지, 훈련과 주의 점검, 내보내기가 여기에 포함됩니다. 이 스킬은 아직 OME-Zarr와 OME-TIFF 데이터 형식, 스킴 옵션, microscopy 엑스트라를 문서화하지 않습니다. potato-skill을 설치하고 에이전트에게 연구를 설명한 뒤, 형식과 옵션은 이 페이지의 Markdown 사본을 가리켜 알려 주세요. Markdown 사본은 https://www.potatoannotator.com/docs/annotation-types/microscopy.md에 있습니다.

더 읽을거리

• 이미지 어노테이션 - 일반 이미지의 상자, 다각형, 마스크
• 딥 줌을 이용한 기가픽셀 이미지 어노테이션 - 타일 피라미드와 전체 슬라이드 이미지
• 내보내기 형식 - Potato의 내보내기 형식과 내보내기 명령
• 애너테이터는 몇 명이 필요한가? - 항목당 주석자 수 정하기
• 생명과학 - 생명과학과 바이오큐레이션을 위한 Potato

구현 세부 사항은 소스 문서를 참고하세요.