VesiscanClinicalAndroid/docs/ALGO_BRANCH_COMPARISON.md

demo-final vs feature/cloud-mvp 알고리즘 브랜치 비교

마지막 업데이트: 2026-08-11 · 대상: Alignment · Detection · BV Estimation

배경

VesiScan-Basic Android 앱은 두 개의 활성 브랜치로 관리됨.

브랜치	용도	대상 방광	상태
demo-final	시연/데모 전용 · 안정판	phantom (구 모형 방광)	동결 시연
feature/cloud-mvp	실사용/개발 · 인체 임상	실제 인체 (타원 방광)	활성 개발

핵심 원칙: 두 브랜치 알고리즘 결과가 서로 다른 것이 정상 설계. phantom (구) 과 인체 (비대칭 타원) 은 기하가 근본 다르므로 · 같은 코드로 두 상황 모두 정확 계산 불가.

• demo-final = 데모 시 팬텀에서 300ml 근처 값이 안정적으로 나오는 것이 목표. 구 공식 (V = 4/3πr³) 사용.
• cloud-mvp = 인체 정확도 (Halir-Flusser + adaptive_large_bladder_relax + b_si_floor 등 Python parity).

또한 cloud-mvp 는 패키지 domain-driven 재배치를 완료: managers/* → piezo/* · alignment/* · common/util/*. 두 브랜치 동일 파일이 경로만 다르고 로직은 대부분 동일한 경우가 많음.

---

1. Alignment (정렬 · placement guide)

1-1. 기본 설정값

항목	demo-final	feature/cloud-mvp
alignmentAlgo (default)	V1	V1
placementGuideMode (default)	SIMPLE (표시명 "Gradient")	SIMPLE
V2 진입 조건	clinical alignment session 만	clinical alignment session 만
verticalHitRequired (V2)	3	3
VERTICAL_HIT_WINDOW / _MAJORITY	6 / 3	6 / 3
STABILIZE_LOST_WINDOW / _MAJORITY	4 / 3	4 / 3
V3 CenterAligner (2-Pass batch)	✅ 있음	❌ 없음

1-2. 로직 차이

• V1/V2 state machine 은 두 브랜치 100% 동일 (phase 진입 · hysteresis · CV 계산 · MOVE_UP/DOWN 방향 판정).
• RollingAligner의 detectMultichannel 호출부:
  • demo-final: applyCross = false (piezophantomtest ea3f15c 이식 · 2026-07-06) → 정렬 위치 선택은 base 검출로만 수행 · 교차채널 보정이 nch 를 흔들지 못하게 격리 · BV 산출은 별도 경로에서 applyCross=true.
  • cloud-mvp: applyCross 파라미터 자체 제거 → 정렬 위치 판정에도 cross-channel 보정 결과 사용.
• V3 CenterAligner (demo-final 전용): Pass 1 = 5 위치 각 20 cycle 스캔 → Rule A (ch3 필수 · 검출률 ≥ 80% · max nch · min bv_cv) 로 최적 위치 선택. Pass 2 = 재측정 검증. cloud-mvp 는 이 배치 알고리즘 자체가 없음.

1-3. 관련 파일

파일	demo-final	cloud-mvp
PlacementGuideView	ui/views/monitoring/PlacementGuideView.kt (2317 L)	alignment/ui/PlacementGuideView.kt (2187 L)
AlignmentAdvisorV2 (+ RollingAligner)	managers/AlignmentAdvisorV2.kt:677 (applyCross=false)	alignment/AlignmentAdvisorV2.kt:680 (파라미터 제거)
AlignmentAdvisorV3	managers/AlignmentAdvisorV3.kt (신규)	—
ImuAnalysis / ImuPostureClassifier	managers/	alignment/

---

2. Detection (벽 검출)

2-1. 기본 설정값

항목	demo-final	feature/cloud-mvp
detectionMethod (default)	METHOD_C (V4.1 SphereFit walls)	METHOD_D (Python for_app_share 1:1)
MethodDParams.otsuRatio	0.88	0.88
MethodDParams.oscfarWin	9	9
MethodDParams.promGamma / shoulderPromGamma	1.5 / 1.5	1.5 / 1.5
MethodDParams.minWallLumenRatio	1.16	1.16
MethodDParams.minPostRawRatio	1.08	1.08
MethodDParams.antDMax / dMax	18 / 10	18 / 10
Cross-channel stage 순서	①→②→③ (3-stage)	①→①.5→②→③ (4-stage)
VDIP_POST_RECOVERY	❌ 없음	✅ true (DIP_TOL=8.0mm · REACH_MARGIN=15.0mm)
NEIGHBOR_TOP_VALIDATE / INWARD_POST_SEARCH	true / true	true / true
applyCross 파라미터	✅ 있음 (default true)	❌ 제거 (항상 적용)
topRecoverWallRatio 파라미터	❌ 없음	✅ 있음 (streaming relaxed pass 용)

2-2. 로직 차이

• MethodDParams 는 모든 필드 100% 동일 (임계값 · 필터 파라미터 전부).

• MethodDRunner 는 105 lines 차이 (443L vs 548L). 실질 로직 차이 3가지:

  1. applyVdipPostRecovery (cloud-mvp only · stage ①.5)
     • V-dip 심부후벽 복구. 중간 center 채널 후벽 z 가 양 이웃 모두보다 VDIP_DIP_TOL=8.0mm 얕고, 두 이웃이 서로 8.0mm 이내 일치 (=under-detected 심부후벽) 이면 consensus 깊이로 재탐색.
     • Gate (wall/lumen ratio + post_raw_ratio) 통과한 심부 peak 만 채택.
     • 원본: piezophantomtest c800f5d (2026-08-06).
  2. applyCross 파라미터
     • demo-final: detectMultichannel(..., applyCross: Boolean = true) 유지 → 정렬 / BV 경로 분리 가능.
     • cloud-mvp: 제거됨 → 두 경로 모두 cross-channel 적용된 결과 사용.
  3. topRecoverWallRatio 파라미터 (cloud-mvp only)
     • applyNeighborTopValidate Rule A (FN 복원) 재탐색 시 minWallLumenRatio gate override.
     • StreamingBladderEstimator relaxed pass (게이트 1.16 → 1.13) 용 hook.

• detection default 가 다른 것 자체가 브랜치 성격의 표현: demo-final = phantom-검증된 V4.1 (안정 · 시연 유효), cloud-mvp = 임상용 METHOD_D (Python for_app_share 1:1).

2-3. 관련 파일

파일	demo-final	cloud-mvp
MethodDRunner	walldetect/MethodDRunner.kt (443 L)	piezo/walldetect/MethodDRunner.kt (548 L)
MethodDParams	walldetect/algo/methodd/MethodDParams.kt	piezo/walldetect/algo/methodd/MethodDParams.kt (동일)
VDIP 신설 함수	—	MethodDRunner.kt:214-306 (vdipDeepCandidate + applyVdipPostRecovery)

---

3. BV Estimation (부피 계산)

3-1. 기본 설정값

항목	demo-final	feature/cloud-mvp
bvMethod (default)	METHOD_D_PHANTOM (2026-08-11 신설 · 구 공식)	METHOD_D (Halir + adaptive)
BvMethod enum	{FRUSTUM, V41, METHOD_D, METHOD_D_PHANTOM} (4개)	{FRUSTUM, V41, METHOD_D} (3개)
distancePerSample (dps)	1.968 mm/sample (2026-08-11 phantom rollback)	1.936 mm/sample (Python config_6ch.py:90)
lrRatioOverride (default)	1.0	1.0
lrRatioMin / lrRatioMax clip	❌ 없음	✅ 0.5 / 1.5 (해부학적 clip)
estimateBv(walls, adaptive=true) 구현	✅ 있음 (동일)	✅ 있음 (동일)
estimateBvPhantomSphere(walls)	✅ 있음 (신규 · 구 공식)	❌ 없음
Halíř–Flusser (EllipseFitSpecific)	✅ 있음 (로직 완전 동일)	✅ 있음
adaptive_large_bladder_relax (low_wide_endpoint)	✅ 있음 (동일)	✅ 있음
b_si_floor_ratio / _edge_min	✅ 있음 (동일)	✅ 있음
Subsample refined (Double ant/post)	✅ 있음	✅ 있음
StreamingBladderEstimator	❌ 없음	✅ 있음 (age-based strict/relaxed 병합)
useStreamingBv dev toggle	❌ 없음	✅ 있음

3-2. 로직 차이

• estimateBv(walls) 본체는 두 브랜치 100% 동일
  • evalOnce() → applyLumenInsetOne(0.15) → estimateBladderVolume6ch → Halíř–Flusser 타원 fit → 결과 검사 (capFrac < 0.20 && edge ≥ 0.48 && (edge ≥ 0.70 && hRel < 0.42)) → low_wide_endpoint 이면 urineInsetFrac=0.05 + bSiFloorRatio=0.85 로 재계산.
  • Python runners.estimate_bv 1:1.
• estimateBvPhantomSphere(walls) — demo-final 전용 (2026-08-11 신설)
  • 위치: PiezoBVEstimator.kt:600
  • 로직: center CH0~3 각 채널의 (post − ant) × dps 를 지름으로 보고 평균 → V = 4/3·π·r³ (r = D/2). Halíř · adaptive · b_si_floor · lr_ratio 전부 우회.
  • 검증: D = 42 samples × 1.968 dps = 82.7 mm → r = 41.35 mm → V ≈ 296 ml (300 ml phantom 시연에서 재현 성공).
  • 인체 방광 (비대칭 타원) 에는 부적합 · phantom 전용.
• distancePerSample 편차 (1.968 vs 1.936)
  • 두 브랜치 계산 결과가 다른 결정적 원인 중 하나.
  • dps 는 WdConfig.DPS_DEFAULT 도 함께 동기화 (V41 · Geometry · AnatomicalGate 모두 이 상수 사용) → 한 값만 바꾸면 두 경로 (6ch estimate vs V41/gate) dps 불일치 방지.
• StreamingBladderEstimator (cloud-mvp only)
  • 파일: piezo/StreamingBladderEstimator.kt (신규).
  • 각 채널별 age (마지막 strict 검출 이후 trace 수) 유지 → strict 실패 채널을 최근 K trace 내 strict 이력 있으면 relaxed (게이트 1.13) 로만 복구 · 이력 없으면 완화 안 함 → 게이트 경계 flicker 억제.
  • MethodDRunner.detectMultichannel(topRecoverWallRatio=…) 로 게이트 override.
  • PiezoMonitoringView:406 에서 dev toggle 로 라우팅. 배뇨/탈착 시 reset().
• lrRatioMin/Max clip [0.5, 1.5]
  • cloud-mvp 만 도입 (PiezoHW:164-165 · computeLrRatio 반환값 clip).
  • demo-final 은 computed lr 그대로 (실제로는 lrRatioOverride=1.0 강제 사용해서 clip 무의미).

3-3. 관련 파일

파일	demo-final	cloud-mvp
PiezoBVEstimator	managers/PiezoBVEstimator.kt (1174 L)	piezo/PiezoBVEstimator.kt (1124 L)
EllipseFitSpecific	managers/EllipseFitSpecific.kt	piezo/EllipseFitSpecific.kt (package 다름)
GreenZoneConstants	managers/GreenZoneConstants.kt:38, :59	common/util/GreenZoneConstants.kt:38, :69
BV 신설 함수 (sphere)	PiezoBVEstimator.kt:600 estimateBvPhantomSphere	—
Streaming BV	—	piezo/StreamingBladderEstimator.kt (신규)
BV 분기점	ui/views/monitoring/PiezoMonitoringView.kt:487-491 (METHOD_D_PHANTOM → estimateBvPhantomSphere)	piezo/ui/PiezoMonitoringView.kt:406-418 (useStreamingBv → streamingBv.update(signals))

---

4. 브랜치 전용 파일/기능 요약

demo-final only

• managers/AlignmentAdvisorV3.kt (CenterAligner · Rule A + bvcv batch scan-select)
• BvMethod.METHOD_D_PHANTOM enum value
• fun estimateBvPhantomSphere(walls) (구 공식 · phantom 시연 전용)
• MethodDRunner.detectMultichannel(..., applyCross = false) API 보존

cloud-mvp only

• piezo/StreamingBladderEstimator.kt (age-based strict/relaxed 병합)
• GreenZoneConstants.useStreamingBv dev toggle + custom-setter audit logging
• PiezoHW.lrRatioMin / lrRatioMax clip + coerceIn in computeLrRatio
• MethodDRunner.applyVdipPostRecovery + vdipDeepCandidate (V-dip 심부후벽 복구)
• MethodDRunner.detectMultichannel(..., topRecoverWallRatio: Double?) API
• PiezoHW.autoDetectPreset PhiRedactor 마스킹 (cybersecurity DC-02)
• Custom-setter audit-logger wrappers on _detectionMethod / _bvMethod / _lrRatioOverride / _placementGuideMode / _alignmentAlgo / _useStreamingBv (cybersecurity UC-04)
• piezo/ui/PiezoPersonalizationView.kt streaming BV dev toggle UI

공통 (구현 동일 · 위치만 다름)

• Halíř–Flusser EllipseFitSpecific · estimateBv(walls) 본체 · adaptive_large_bladder_relax · b_si_floor · subsample refined · MethodDParams 전 필드 · V1/V2 alignment state machine 임계

---

5. 브랜치 default 조합 종합

축	demo-final	cloud-mvp
정렬	V1 · Gradient (SIMPLE)	V1 · Gradient (SIMPLE)
검출	METHOD_C (V4.1 SphereFit walls)	METHOD_D (Python for_app_share)
BV	METHOD_D_PHANTOM (구 공식 · V=4/3πr³)	METHOD_D (Halir + adaptive)
dps	1.968 mm/sample	1.936 mm/sample
Streaming BV	—	dev toggle
Audit logging	—	활성

6. 브랜치별 의사결정 기록 (핵심 커밋)

커밋	날짜	브랜치	변경
bcbc7b4	2026-07-02	demo-final	패키지 통일 (com.example → com.medithings) · BV 로직 안정판
d732150	2026-07-20	demo-final	Halíř-Flusser ellipse fit 이식 (BV Δ 43→13mL)
3152783	2026-07-20	demo-final	estimateBv wrapper + adaptive_large_bladder_relax + b_si_floor
430d9ad	2026-07-30	demo-final	feature-folder refactor (147 파일 이동)
1c3748b	2026-08-07	demo-final	vdip_post_recovery 이식 (MethodDRunner)
8cab1d0	2026-08-10	demo-final	rollback 후 재조정 · detection=C + bv=METHOD_D
d054b3b	2026-08-11	demo-final	dps 1.936 → 1.968 (phantom 스케일 재현)
d1d17f8	2026-08-11	demo-final	METHOD_D_PHANTOM (구 공식) 신설 · demo default
6dfe5e6	2026-08-11	demo-final	BleManager.disconnect() 즉시 UI 반영 fix

7. 향후 유지 원칙

1. cloud-mvp 의 알고리즘 개선을 demo-final 로 무분별 이식하지 않기
   • Halir · adaptive 등은 인체 정확도 개선이지만 phantom 에서는 오히려 값 왜곡.
2. demo-final 은 phantom 시연 재현성 최우선
   • 알고리즘 변경 시 300 ml phantom 결과가 296 ml 근처를 유지하는지 확인.
3. 동시 이식이 필요한 fix (예: BLE 안정성 · UI 버그) 는 두 브랜치 각각 별도 커밋
   • cherry-pick 대신 각 브랜치에서 명시적으로 적용 후 커밋 메시지에 "demo-final 이식" / "cloud-mvp 이식" 명시.