# PancreaClear3D

**3D islet beta-cell mass & innervation morphometry from tissue-cleared light-sheet pancreas volumes**

- **Domain (도메인):** DM — 당뇨병 (diabetes mellitus)
- **Category (카테고리):** 동물실험 도구 — ex vivo 3D image quantitation
- **Date:** 2026-06-01
- **Status:** MVP, self-contained, offline

> ⚠️ **연구용·참고용 — 임상 진단/의사결정 도구가 아님.**
> Research / reference use only — **NOT** a clinical decision or diagnostic device.
> All figures are illustrative quantitation of the supplied or synthetic volume.

---

## 한 줄 요약 (one-liner)

적출 췌장 투명화(tissue clearing) light-sheet 볼륨에서 islet의 β-cell mass와 islet
혈관·신경 지배를 **3D 체적으로 자동 정량**하는 도구.

From a cleared (tissue-clearing) pancreas light-sheet volume, automatically quantify islet
β-cell mass and islet vascular/neural innervation as 3D volumetrics.

---

## 핵심 기능 (core features)

1. **insulin⁺(β) / glucagon⁺(α) 3D segmentation** → islet 객체 분리·개수·체적·β/α 비율
   - 내분비 신호(β+α)에 Otsu thresholding → 3D connected-component labeling →
     (scipy 가용 시) distance-transform marker-controlled watershed로 맞붙은 islet 분리.
2. **islet 크기 분포 히스토그램 + head/body/tail zonal 분포 맵**
   - islet별 등가직경(equivalent diameter)을 5개 size class로 분류, 장축(Y)을
     head/body/tail 3 구역으로 나눠 개수·체적 분포 출력.
3. **islet별 혈관(CD31) 밀도 · 신경(TH⁺/CGRP⁺) 축삭 근접도 3D 정량**
   - islet voxel 중 CD31⁺ voxel과 임계거리(기본 15 µm) 이내 비율 = 혈관 밀도,
     islet→최근접 신경 voxel 거리(µm) = 신경 근접도 / innervated 여부.
4. **design-based stereology 검증 모드 (2D vs 3D 편향 리포트)**
   - 전체 plane을 쓴 3D ground-truth β-volume 대비, 소수의 무작위 2D 단면에서
     추정·외삽한 값의 편향(typical |bias| 및 worst-case)을 리포트.
     희소 2D sampling이 β-mass를 **수십 % (대략 ±20~40%)** 편향시킴을 시연.
5. **합성 demo 볼륨 (무데이터 체험)**
   - 절차적 islet field 생성: head/body/tail density gradient + 약 4-decade의 크기 분포
     (log-uniform 반경) + α mantle + 혈관/신경 채널. 데이터 없이 즉시 실행.

---

## 기술 스택 (tech stack)

| 구분 | 사용 |
|------|------|
| 필수 | Python 3, **numpy** |
| 선택 | **scipy** (`scipy.ndimage`) — connected-component labeling, distance transform, watershed-style 분리. 없으면 **순수 numpy fallback**(반복 flood-fill labeling + 근사 거리변환)으로 자동 대체되어 `python3 main.py`가 항상 성공 |
| 선택 | **tifffile** — `--input`으로 사용자 TIFF/OME-TIFF stack 로드. 없으면 합성 demo만 사용 |
| **사용 안 함** | napari / cellpose / StarDist / pyclesperanto (무거운 GPU 의존성 — import 강제 안 함) |

> **Production 교체 지점:** 본 MVP의 segmentation 단계(threshold + watershed + label)는
> production에서 **cellpose-3D / StarDist-3D** 등 딥러닝 3D instance segmentation으로
> 교체 가능하도록 `segment_islets()` 한 함수로 분리되어 있다. 입출력 계약(label 볼륨)만
> 유지하면 다운스트림 정량 로직은 그대로 재사용된다.

---

## 데이터 소스 (data sources)

- **합성 demo 볼륨** (기본 내장) — `make_synthetic_volume()`, 외부 데이터 불필요.
- **사용자 light-sheet/confocal TIFF·OME-TIFF** (선택) — `--input PATH`. 다채널 stack을
  `β, α, vessel, nerve` 채널 순으로 해석. tifffile 필요.
- **내장 stereology reference** — `data/stereology_reference.json`
  (Cavalieri 파라미터, islet size class, zonal 구역, 근접 임계값 등 대표 문헌 범위값).

외부 네트워크/API 호출 **없음**. 전부 오프라인·합성 데이터로 시연.

---

## 실행법 (how to run)

```bash
cd "projects/2026-06-01-1-pancreaclear3d"

python3 main.py                  # 합성 demo, 전체 리포트
python3 main.py --summary        # 요약(per-islet 표 생략)
python3 main.py --top 5          # 가장 큰 islet 5개 표시
python3 main.py --n-islets 100   # 합성 islet 개수 조정
python3 main.py --seed 42        # 합성 RNG 시드 변경
python3 main.py --proximity-um 20  # 혈관/신경 근접 임계값(µm) 변경
python3 main.py --json out.json  # 수치 결과를 JSON으로도 저장
python3 main.py --input vol.tif  # 사용자 TIFF stack 로드(tifffile 필요)
python3 main.py --help           # 전체 옵션
```

전역 패키지 설치 불필요. `numpy`만 있으면 동작하고, `scipy`가 있으면 더 정밀한
segmentation을 자동 사용한다.

---

## 출력 구성 (output sections)

- `[1]` islet 개수, β-cell volume(β-mass proxy, µm³), α-cell volume, β:α 비율
- `[2]` size-class 히스토그램 + head/body/tail zonal 분포(개수·체적)
- `[3]` 평균 혈관 밀도, innervated islet 비율, 근접 임계값
- `[4]` 2D 단면 추정 vs 3D ground-truth β-volume 편향 표 (typical |bias|·SD·worst)
- `[5]` 체적 상위 N개 islet 표 (id·체적·직경·zone·class·혈관밀도·신경거리)

---

## 검수 체크리스트 (verification checklist)

- [x] `python3 -c "import ast; ast.parse(open('main.py').read())"` 구문 검증 통과
- [x] `python3 main.py --help` 동작
- [x] `python3 main.py` / `--summary` 실제 실행, 정상 출력 (rc=0)
- [x] numpy/scipy 가용 여부 확인, scipy 미가용 시 **순수 numpy fallback** 동작 확인
- [x] tifffile 미가용 시 `--input`이 안내 후 합성으로 graceful fallback
- [x] β:α 비율이 생리학적 범위(~3-4:1)로 산출됨
- [x] head/body/tail gradient(꼬리 우세) 재현됨
- [x] 2D vs 3D 편향이 명확히(수십 %) 시연됨
- [x] 외부 네트워크 호출 없음

자세한 로그는 [`QA.md`](./QA.md) 참고.

---

## 한계 및 디스클레이머 (limitations & disclaimer)

- 합성 볼륨은 islet 형태/조성/지배를 **단순화**한 절차적 모델로, 실제 조직의 복잡성을
  완전히 대표하지 않는다. reference JSON의 수치는 대표 문헌 범위의 **예시값**이다.
- 순수 numpy fallback은 watershed 분리가 없어 맞붙은 islet을 병합할 수 있다
  (scipy 가용 시 더 정확). β-mass는 voxel 체적 proxy이며 절대 질량(mg)으로의 환산은
  voxel 크기·조직 수축·라벨링 효율 보정이 필요하다.
- **본 도구는 연구용·참고용이며 임상 진단·치료 의사결정에 사용해서는 안 된다.**

---

## 참고 개념 (references / concepts)

- Design-based stereology, Cavalieri principle, physical disector (Smith & Guttman 보정)
- Islet head/body/tail zonal distribution (설측 꼬리가 islet-rich)
- Islet microvasculature (CD31/PECAM-1), 자율·감각 신경 지배 (TH⁺ 교감, CGRP⁺ 감각)
- Tissue clearing + light-sheet 3D islet 정량의 2D 단면 추정 대비 우수성

상세 파라미터: [`data/stereology_reference.json`](./data/stereology_reference.json)