Spine Annotator 사용 매뉴얼

1. 개요

Spine Annotator는 척추 X-ray(전체 척추, AP/LAT) 이미지를 대상으로 척추체(vertebral body) 25개 클래스(C1–S1)를 폴리곤으로 라벨링하기 위한 웹 도구입니다. 결과는 segmentation 모델 학습용 COCO JSON 형식으로 내보낼 수 있습니다.

• 로컬 폴더 연결 (700+ 이미지도 서버 업로드 없이 작업)
• Konva.js 기반 정밀한 폴리곤 그리기/편집
• Y좌표 기준 라벨 자동 할당 (위→아래)
• 모든 단축키 커스터마이즈 가능, 한/영 IME 무관
• 파일별 자동 저장 (브라우저 LocalStorage)
• COCO 형식 JSON 내보내기

2. 라벨러(작업자) 설정

앱을 처음 열면 라벨러 선택 모달이 자동으로 뜹니다. 본인 이름을 선택하면 헤더 우측에 색상 점과 함께 표시됩니다.

현재 등록된 라벨러

동작 방식

• 라벨 저장 시 마지막 수정자로 기록됨
• 왼쪽 파일 목록의 상태 점이 마지막 수정자 색으로 표시됨
• 다른 라벨러가 수정하면 점 색이 바뀜 (예: 박성배 → 김태준이 수정 → 점이 블루로)
• 점에 마우스 올리면 "박성배(교수님) · 25개 라벨" 식으로 정보 표시

라벨러 변경

헤더 좌측의 ● 박성배 ▾ pill 버튼을 클릭하면 라벨러를 변경할 수 있습니다. (브라우저별로 따로 저장됨)

3. 빠른 시작 (5분)

1. 이미지 열기

   헤더의 폴더 연결 또는 파일 또는 샘플을 누릅니다.

2. 시작 척추 라벨 선택

   왼쪽 사이드바의 시작 라벨 드롭다운에서 이미지 최상단에 보이는 척추(예: C2, T1, L1)를 선택합니다.

3. 그리기 모드 진입

   I를 누르거나 도구 버튼의 그리기를 클릭합니다.

4. 점 찍기 → 완성

   척추체 외곽을 따라 클릭하여 점을 찍습니다. 3개 이상 찍은 후 Q(순서대로 완성) 또는 W(각도순 자동 정렬 완성).

5. 다음 척추로 반복

   완성된 폴리곤은 자동으로 라벨이 할당됩니다(Y좌표 기준). 25개 모두 라벨링되면 라벨이 모두 채워집니다.

6. COCO 내보내기

   헤더 우측의 COCO 미리보기 → 다운로드.

4. 로컬 이미지 폴더 연결

지원 브라우저

• ✅ Chrome / Edge (File System Access API 지원)
• ❌ Firefox / Safari — 단일 파일 업로드만 가능

사용법

1. 헤더의 폴더 연결 클릭
2. X-ray PNG 파일들이 있는 폴더 선택 → 권한 허용
3. 왼쪽 사이드바에 파일 목록이 표시됩니다 (AP/LAT 자동 분류)
4. 파일을 클릭하면 캔버스에 로드됨
5. 다음 세션에서도 자동 복원됩니다 (브라우저에 폴더 핸들 저장)

파일 목록 UI

• AP / LAT — 파일명에서 자동 파싱
• 라벨 없음 / 라벨 있음 (LocalStorage 기준)
• 검색창에 파일명 일부를 입력해서 빠르게 찾기
• 전체 / AP / LAT 필터 버튼으로 보기 조절

5. 폴리곤 그리기

기본 흐름

1. I로 그리기 모드 진입
2. 척추체 외곽을 클릭하여 점 추가 (최소 3점)
3. 완성:
   • Q — 클릭한 순서대로 연결 (점을 시계방향으로 잘 찍은 경우)
   • W — 각도순 자동 정렬로 완성 (점 순서가 뒤죽박죽이어도 볼록 다각형으로 자동 정리)
   • 마지막 점에서 더블클릭으로도 완성 가능
4. E — 마지막 점 한 개 되돌리기 (실수했을 때)
5. Esc — 그리기 전체 취소

6. 편집 모드

O로 편집 모드 진입. 이미 그린 폴리곤을 수정합니다.

점 조작

그리던 폴리곤을 편집 모드에서 마무리

그리기 모드에서 점을 몇 개 찍다가 O로 편집 모드로 전환할 수 있습니다. 이때 찍은 점들은 그대로 유지되며, 드래그로 위치를 미세 조정한 뒤 Q 또는 W로 완성할 수 있습니다.

7. 라벨 자동 할당 / 시작 라벨

폴리곤이 완성될 때마다 모든 폴리곤이 Y좌표(무게중심) 기준 위에서 아래로 정렬되고, 시작 라벨부터 순서대로 자동 할당됩니다.

예시

• 시작 라벨 = T1, 폴리곤 12개 → T1, T2, ..., T12 자동 할당
• 시작 라벨 = L1, 폴리곤 6개 → L1, L2, L3, L4, L5, S1 자동 할당

지원 라벨 시퀀스 (위→아래):

수동 라벨 변경

오른쪽 사이드바의 폴리곤 목록에서 라벨을 클릭하여 직접 변경할 수 있습니다.

8. 뷰 조작

줌 / 팬

• 줌: 마우스 휠 (커서 위치 기준)
• 줌 인/아웃: + / -
• 화면 맞춤: 0
• 팬(이동): Space 누른 채로 드래그

이미지 필터 (오른쪽 사이드바)

• 밝기 / 대비: 슬라이더로 조절
• 색반전: 토글 (X-ray 음영 반전 시 더 잘 보일 때)

사이드바

• 좌/우 사이드바 너비는 경계선 드래그로 조절
• 접기/펼치기 버튼으로 캔버스를 최대화 가능

9. 단축키 전체 목록

모든 단축키는 커스터마이즈 가능합니다. 헤더의 버튼 또는 Ctrl+K.
한/영 입력 상태와 무관하게 물리적 키 위치로 동작합니다 (IME 안전).

도구

그리기

편집

보기

마우스 동작 (변경 불가)

10. COCO 내보내기

헤더의 COCO 미리보기 버튼을 누르면 현재 이미지의 라벨을 COCO segmentation 형식 JSON으로 미리 볼 수 있고 다운로드할 수 있습니다.

출력 형식

{
  "images": [{
    "id": 1,
    "file_name": "patient_001_AP.png",
    "width": 1024,
    "height": 2048
  }],
  "annotations": [{
    "id": 1,
    "image_id": 1,
    "category_id": 8,            // T1 = 8 (C1=1, C2=2, ..., S1=25)
    "segmentation": [[x1,y1,x2,y2,...]],
    "bbox": [x, y, w, h],
    "area": 12345.6,
    "iscrowd": 0
  }, ...],
  "categories": [
    { "id": 1, "name": "C1" }, { "id": 2, "name": "C2" }, ...
    { "id": 25, "name": "S1" }
  ]
}

면적 / bbox 계산

• bbox: 점들의 min/max x,y로 계산
• area: Shoelace 공식 (실제 폴리곤 면적, 픽셀²)

11. 권장 작업 흐름

1. 폴더 연결 — 한 번만 연결하면 다음 세션에도 자동 복원
2. 파일 선택 — AP / LAT 필터로 한 가지 뷰만 먼저 처리하는 것을 권장
3. 시작 라벨 설정 — 이미지 상단에 보이는 척추로 (예: C2 또는 T1)
4. 위에서 아래로 순서대로 폴리곤 그리기
   • 일반적으로 I → 점 4개 클릭 → Q 반복
   • 점 순서가 꼬였으면 W로 자동 정렬
5. 편집 모드로 점들 미세 조정 (O → 드래그)
6. 자동 저장 — 파일 전환 시 자동으로 LocalStorage에 저장됨
7. COCO 내보내기 — 작업 완료 후 JSON 다운로드

12. 자주 묻는 질문 / 트러블슈팅