# CHANGELOG — PancreaClear3D

## [2026-06-01]

### 수행 내용
- DM(당뇨병) / 동물실험 도구 카테고리의 MVP "PancreaClear3D"를 자기완결적으로 구현.
- 적출 췌장 투명화 light-sheet 볼륨에서 islet β-cell mass·혈관·신경 지배를 3D로
  자동 정량하는 Python CLI(`main.py`) 작성.
- 핵심기능 5종 구현: ① insulin⁺(β)/glucagon⁺(α) 3D segmentation·개수·체적·β/α 비율,
  ② size-class 히스토그램 + head/body/tail zonal 맵, ③ islet별 혈관(CD31) 밀도·신경
  (TH⁺/CGRP⁺) 근접도, ④ 2D 단면 추정 vs 3D ground-truth 편향 리포트, ⑤ 합성 demo 볼륨.
- README.md, QA.md, data/stereology_reference.json 작성 및 검수 완료.

### 주요 결정 사항
- **scikit-image/tifffile 미설치 확인** → segmentation을 scipy.ndimage(threshold +
  distance-transform watershed + label)로 구현하고, scipy마저 없을 때를 대비해 **순수
  numpy fallback**(6-연결 flood-fill labeling + 반복 dilation 근사 거리변환)을 별도 제공.
  덕분에 `python3 main.py`가 numpy만으로도 항상 성공. napari/cellpose/StarDist/
  pyclesperanto는 import 강제하지 않음(README에 production 교체 지점 명시).
- **합성 볼륨 파라미터 튜닝**: α를 alpha_frac 기반 mantle shell로 배치해 β:α≈3.5-3.8:1
  생리학적 비율 달성; 반경 log-uniform(1.3~25 vox)으로 약 4-decade 체적·5개 size class
  분포; head<body<tail density gradient로 꼬리 우세 재현.
- **2D vs 3D 편향 시연 방식**: "전체 plane 3D ground-truth" 대비 "소수 무작위 2D 단면
  외삽" 추정을 60회 반복해 typical |bias|·SD·worst-case를 리포트 → 희소 2D sampling이
  β-mass를 ~9-20%(worst 수십 %) 편향시킴을 결정론적으로 시연.
- 의학 디스클레이머를 README와 CLI 출력 양쪽에 게재.

### 변경된 파일
- `main.py` — CLI 진입점(argparse), 합성 볼륨 생성, 3D segmentation(scipy + numpy
  fallback), islet 정량, 혈관/신경 근접도, stereology 편향, 리포트/JSON 출력.
- `data/stereology_reference.json` — Cavalieri 파라미터, islet size class(5), zonal
  구역(3), 근접 임계값 등 reference 값.
- `README.md` — 목적/도메인/카테고리/핵심기능/실행법/검수 체크리스트/출처/디스클레이머.
- `QA.md` — 검수 로그(10개 항목 + 재시도 기록 + 대표 출력).

### 재현 방법
1. `cd "projects/2026-06-01-1-pancreaclear3d"`
2. `python3 -c "import ast; ast.parse(open('main.py').read())"` — 구문 검증
3. `python3 main.py --help` — 옵션 확인
4. `python3 main.py --summary` — 합성 demo 정량 리포트(seed=7 결정론적)
5. (선택) scipy 차단 fallback 검증, `--json out.json`, `--input vol.tif`(tifffile 필요)
6. 의존성: 표준 라이브러리 + numpy(필수), scipy/tifffile(선택). 전역 설치 불필요.