Skip to content

Latest commit

 

History

History
320 lines (226 loc) · 7.64 KB

USER_GUIDE.md

File metadata and controls

320 lines (226 loc) · 7.64 KB

AI-CASA 사용자 가이드

정자 현미경 영상을 업로드하면 AI가 자동으로 분석해주는 시스템


📌 시스템 소개

AI-CASA는 정자 현미경 영상에서 다음 항목을 자동 분석합니다.

  • 운동성 — 전진 / 비전진 / 비운동성 정자 비율
  • 운동 패턴 (CASA 키네마틱) — VCL, VSL, VAP, LIN, STR, WOB, ALH 7가지 지표
  • 형태 — 머리, 첨체, 공포, 꼬리 4부위별 정상/비정상 여부
  • 종합 판정 — WHO 6판 기준에 따른 정상 / 일부 주의 / 전문의 상담 권고

⚠️ 의학적 진단 도구가 아닙니다. 병원 방문 전 참고용 보조 분석 도구입니다.


🚀 시작하기

1단계 — 메인 페이지 접속

브라우저에서 http://localhost:5000 접속

보이는 것:
- 시스템 소개 + 핵심 성과 지표
- 영상 업로드 영역
- 분석 파이프라인 미리보기 (5단계)

2단계 — 영상 업로드

영상을 업로드하는 두 가지 방법:

방법 1: 파일 드래그 앤 드롭
  업로드 영역에 영상 파일을 끌어다 놓기

방법 2: 클릭해서 선택
  업로드 영역 클릭 → 파일 탐색기에서 선택

지원 형식: MP4, AVI, MOV
최대 크기: 500MB

3단계 — 분석 시작

🔬 분석 시작하기 버튼 클릭 → 자동으로 분석 진행 페이지로 이동

4단계 — 분석 진행 확인

표시되는 정보:
- 회전 애니메이션 + 현재 단계 메시지
- 진행률 바 (0~100%)
- 5단계 시각화 (탐지/추적/운동성/형태/보고서)

소요 시간: 평균 30초~3분
  - VISEM 표준 영상: 약 30초
  - 변환이 필요한 영상: 추가로 10~60초

5단계 — 결과 보고서 확인

분석 완료 시 자동으로 결과 페이지로 이동합니다.


📊 결과 화면 사용법

상단: 종합 판정 배너

가장 먼저 보이는 큰 박스. 한눈에 결과를 알 수 있어요.

색상별 의미:
  🟢 전반적 정상     — WHO 기준 정상 범위
  🟡 일부 주의       — 일부 지표가 기준 이하
  🔴 전문의 상담 권고 — 여러 지표가 기준 이하
  🔄 재검사 필요     — 영상 품질 또는 정자 수 부족

모드 토글

[👁️ 일반인용]  [🔬 전문가용]

기본값: 일반인용
- 친절한 설명, 일상 비유, 의미 풀이
- "앞으로 잘 나아가는 정자" 같은 쉬운 용어

전문가용:
- 수치 중심 컴팩트 레이아웃
- WHO 기준값 위주
- 기술 용어 (VCL, STR 등) 그대로 표시

선택 기억됨: 한 번 고르면 다음에도 같은 모드로 시작

AI 신뢰도 박스

일반인용 모드에서만 표시

"이 AI 시스템, 얼마나 믿을 수 있나요?"

3가지 모델의 검증 결과 공개:
- 운동성 분석: ★★★ MAE 6.9%p
- 정자 탐지: ★★★ mAP50 0.677
- 형태 분석: ★★ AUC 0.727 (도메인 한계 있음)

[자세히 보기] 버튼으로 펼치기/접기

분석 신뢰도 카드

표시 정보:
- 종합 점수 (0~100점)
- 등급 (높음/보통/낮음)
- 발견된 품질 이슈

이슈 예시:
- 탐지된 정자 수 부족
- 프레임 간 탐지 약간 불안정

신뢰도가 60점 미만이면 "재촬영 권고" 표시

영상 품질 정보 (조건부)

B등급 이하 또는 큰 변환이 적용된 경우에만 표시

표시 정보:
- 등급 (S/A/B/C)
- 종합 점수
- 원본 사양 (해상도/FPS/길이)
- 적용된 변환 (있는 경우)
- 발견된 이슈

S등급 영상은 이 박스가 표시되지 않습니다.

운동성 분석

시각 요소:
- 도넛 차트 (총 운동성)
- 막대 그래프 3종 (전진/비전진/비운동성)
- WHO 기준 검토 결과

일반인용 추가:
- "운동성이란?" 설명 박스
- 의미 카드 3개 (정자 종류별 의미)
- 결과 요약 박스 (한 문장 요약)

CASA 키네마틱 분석

표시 항목:
- 속도 지표 3종 (VCL, VSL, VAP)
- 운동 패턴 지표 3종 (STR, LIN, WOB)
- 각 항목의 기준값 + 정상/경고 색상 표시

일반인용 추가:
- 각 지표별 친절한 설명
- "왜 이 수치가 중요한지" 풀이

형태 분석

표시 정보:
- 분석 정자 수 / 정상 형태 수
- 정상 형태율 (%)
- 부위별 이상 비율 (머리/첨체/공포/꼬리)

일반인용 추가:
- 4부위 각각 무엇인지 설명
- 도메인 한계 안내
- "WHO 기준 4%란 무엇인지" 설명

종합 판정 근거 (일반인용 전용)

"왜 이런 판정이 나왔나요?"

3가지 평가 항목 (운동성/형태/신뢰도)이
최종 판정에 어떻게 영향을 미쳤는지 시각화

액션 버튼

[🔬 새 영상 분석하기]  메인 페이지로 돌아가기
[🖨️ 보고서 인쇄]      현재 화면 인쇄/PDF 저장

📷 권장 영상 사양

좋은 분석 결과를 위한 영상 조건:

항목 권장 사양
해상도 640×480 이상 (HD 1280×720 권장)
프레임률 30~60 fps
영상 길이 30초 ~ 3분
촬영 환경 위상차 현미경 또는 자가키트
염색 비염색 (살아있는 정자)
안정성 삼각대 등으로 카메라 고정
조명 밝고 균일한 조명
초점 정자에 정확히 초점

자동 변환 정책

시스템이 영상을 받으면 자동으로 판단:

S등급 영상 (VISEM 표준 그대로):
  → 변환 없이 즉시 분석

A/B등급 영상 (길이만 다름):
  → 빠른 컷팅 + 대비 향상 (5~15초)

큰 변환 필요 (해상도/FPS 다름):
  → 풀 정규화 (30~60초)

F등급 영상 (분석 불가):
  → 거부 페이지로 이동, 재촬영 안내

분석 거부되는 경우

다음 조건 중 하나라도 해당되면 분석 거부:

- 영상 길이 < 5초
- 해상도 < 320×240
- 프레임률 < 10 fps
- 프레임 수 < 30 프레임

거부 페이지에서 친절한 안내와 권장 사양을 확인할 수 있습니다.


❓ 자주 묻는 질문

Q1. 분석 시간이 너무 오래 걸려요

정상 소요 시간: 30초~3분

오래 걸리는 경우:
- 영상이 너무 김 (10분 이상) → 자동으로 3분만 사용
- 해상도가 매우 큼 (4K 등) → 정규화 추가 시간
- GPU 메모리 부족 → 다른 프로그램 종료 후 재시도

Q2. "재검사 필요"라고 나왔어요

원인:
- 정자 수가 너무 적게 탐지됨 (10개 미만)
- 영상 품질이 낮아 추적이 불안정

해결 방법:
- 정자 농도가 충분한 시료 사용
- 카메라 고정 + 정확한 초점
- 적절한 조명 환경
- 더 긴 영상 (30초 이상) 촬영

Q3. 형태 분석 수치가 너무 안 좋게 나와요

이유:
- 학습 데이터(MHSMA)는 염색된 정자 표본
- 실제 분석은 비염색 살아있는 정자
- 도메인 차이로 비정상 비율이 과대 측정될 수 있음

→ 형태 수치는 절대값보다 상대 비교용으로 활용
→ 운동성 결과를 함께 보세요

Q4. 결과를 다른 사람에게 공유하려면?

방법 1: 화면 캡처 후 이미지 공유
방법 2: [🖨️ 보고서 인쇄] → PDF로 저장 후 공유
방법 3: URL 공유 (같은 PC에서만 접속 가능)

Q5. 결과가 의학적으로 신뢰할 수 있나요?

✅ 학술적 검증:
- 운동성: 논문 최고 성능(motilitAI) 초과 달성
- 5-Fold 교차검증으로 객관적 평가

⚠️ 한계:
- 의학적 진단 도구가 아님
- 병원 검사 대체 불가
- 참고용 보조 분석 도구

→ 정확한 진단은 반드시 전문 의료기관에서 받으세요

📞 문의

GitHub Issues: https://github.com/MoriochoRadio/sperm-ai/issues