docs: V3 CenterAligner 2-Pass 이식 반영

- docs/ALGORITHM_COMPARISON.md
  * "V3: CenterAligner 2-Pass BVCV" 신규 서브섹션
  * Python 원본 매핑 · 검증 방식 · commit ID 명시
  * V1 3-stage / V2 6-stage / V3 2-Pass 세 알고리즘 병행 정리
- VesiScan_Android_Pipeline_Summary.md
  * v7 patch 헤더 2026-07-13 → 2026-07-15
  * Alignment 섹션 V3 항목 신규 (piezophantomtest PR #35 링크,
    Pass 1/2 요약, 검증 결과 요약, UI 후속 작업 표기)

기능 변화 없음. V3 라이브러리 이식 (커밋 9387552 / fcdce12) 을 문서에 반영.
This commit is contained in:
2026-07-15 16:04:42 +09:00
parent fcdce12503
commit 909eac9ca3
2 changed files with 61 additions and 3 deletions
+14 -2
View File
@@ -2,7 +2,7 @@
## 작성일: 2026-04-23 ## 작성일: 2026-04-23
## 작성자: dwjang ## 작성자: dwjang
## 마지막 업데이트: 2026-07-13 (v7 patch) — 1.2.0-demo (versionCode 26) ## 마지막 업데이트: 2026-07-15 (v7 patch) — 1.2.0-demo (versionCode 26)
## 권장 펌웨어: **VBTFW0120+** (mim FIFO 지원 필수. VBTFW0121 은 `mls mode 0` handler 취약) ## 권장 펌웨어: **VBTFW0120+** (mim FIFO 지원 필수. VBTFW0121 은 `mls mode 0` handler 취약)
### v7 주요 변경 요약 (2026-07-06 ~ 2026-07-10) ### v7 주요 변경 요약 (2026-07-06 ~ 2026-07-10)
@@ -27,7 +27,19 @@
- **lastBleRxAt 갱신 확대** (커밋 3a41864). `processReceivedData` 진입점에서 - **lastBleRxAt 갱신 확대** (커밋 3a41864). `processReceivedData` 진입점에서
모든 유효 응답에 대해 갱신 → "기기 응답 없음" false-positive 배너 해소. 모든 유효 응답에 대해 갱신 → "기기 응답 없음" false-positive 배너 해소.
**Alignment (V2 6-stage)** **Alignment (V2 6-stage + V3 2-Pass)**
- **V3 CenterAligner 2-Pass BVCV 이식** (커밋 9387552 / fcdce12, 2026-07-15).
piezophantomtest PR #35 (`ffd436b`) 의 `vesiscan_test.alignment.CenterAligner`
를 Kotlin 으로 1:1 이식. Clinical 세션 전용 batch 방식 (실시간 V2 와 병행).
- Pass 1 `scanSelect`: 0~4 cm 각 20 cycle → 11 trace → Rule A + bvcv tie 선택
(ch3 필수 + per-trace ch3 검출률 ≥ 80% + max nch + min bv_cv)
- Pass 2 `guide`: 재측정 위치가 target 기준 (ch3, 검출률, nch, bv_cv × 1.15)
충족 시 STOP, 미충족 시 MOVE_UP
- MethodDRunner (apply_cross false/true 두 모드) + PiezoBVEstimator 재사용
- **검증**: `CenterAlignerValidationTest` — data123 인체 3 세션 대상
Python reference 와 nch/ch3/ch3_hit 완전 일치, bv_cv 오차 <2%,
최종 선택 = cm=3 일치. 상세: [docs/ALGORITHM_COMPARISON.md](docs/ALGORITHM_COMPARISON.md#v3-centeraligner-2-pass-bvcv-alignmentadvisorv3kt-2026-07-15).
- UI 통합 (Pass 1/2 화면) 은 후속 작업.
- **CH3 flicker 무한 대기 방지** (커밋 e808b5b). VERTICAL_CLIMB 진입 조건을 - **CH3 flicker 무한 대기 방지** (커밋 e808b5b). VERTICAL_CLIMB 진입 조건을
"3연속 hit" → "최근 6프레임 중 3회 hit" sliding window majority 로 완화. "3연속 hit" → "최근 6프레임 중 3회 hit" sliding window majority 로 완화.
20 프레임 대기 시 상단 3채널 relaxed mode 진입 (CH3 없이도 정렬 완료). 20 프레임 대기 시 상단 3채널 relaxed mode 진입 (CH3 없이도 정렬 완료).
+47 -1
View File
@@ -1,6 +1,6 @@
# Method A / B / C Algorithm Comparison & Placement Test # Method A / B / C Algorithm Comparison & Placement Test
_마지막 업데이트: 2026-07-13 — V2 6-stage / CH3 flicker 3-Layer 반영._ _마지막 업데이트: 2026-07-15 — V3 CenterAligner 2-Pass BVCV 이식 추가._
## Wall Detection Comparison ## Wall Detection Comparison
@@ -211,6 +211,52 @@ CV 로 정밀 vertical 조정 + CH3 flicker 대응 sliding-window majority.
(CH3 31.8%) 회귀 방지 + Human 1CM (77.3%) 조기 진입 확인, 팬텀 false-positive (CH3 31.8%) 회귀 방지 + Human 1CM (77.3%) 조기 진입 확인, 팬텀 false-positive
없음. 상세 표: `tools/README.md`. 없음. 상세 표: `tools/README.md`.
### V3: CenterAligner 2-Pass BVCV (`AlignmentAdvisorV3.kt`, 2026-07-15)
piezophantomtest [`ffd436b`](https://gitea.medithings.net/medithings-rnd/piezo-phantom-test/commit/32e22a17e8a5733e5a8ea0790d84c3fa9b54ebdb)
(PR #35 "feat: alignment bvcv 규칙 추가") 의 `vesiscan_test.alignment.CenterAligner`
를 Kotlin 으로 이식. 기존 V2 (실시간 sliding 6-stage) 와 병행. Clinical 세션
전용 batch 방식.
**Pass 1 — `scanSelect(cyclesByCm)`**
- 사용자가 치골 위 0/1/2/3/4 cm 각각에서 **20 cycle 씩** 측정.
- 각 위치마다:
- 20 cycle → sliding window 10 → **11 trace**
- `mean_scan` (전체 20 cycle 평균) → `detectMultichannel(applyCross=false)` → `nch`, `ch3`
- `per-trace` → `detectMultichannel(applyCross=true)` → `estimateBladderVolume6ch` → volume_ml 리스트 → `bv_cv = std/mean`
- **Rule A + bvcv tie 로 최적 위치 선택**:
1. ch3 필수 (mean_scan base 검출)
2. per-trace ch3 검출률 ≥ **`CH3_HIT_MIN = 0.80`** (임계 통과 없으면 ch3=O 전체 fallback)
3. max `nch`
4. 동률 → min `bv_cv`
- 선택 위치의 record 를 `target` 으로 저장 (Pass 2 기준값).
**Pass 2 — `guide(cycles, cm)`**
- 재측정한 한 위치 (20 cycle) 가 target 기준 충족 시 `STOP`:
- `ch3='O'`
- per-trace ch3 검출률 ≥ 80%
- `rec.nch ≥ target.nch`
- `rec.bv_cv ≤ target.bv_cv × (1 + bvCvTol)` (기본 `bvCvTol = 0.15`)
- 미충족: `MOVE_UP` (다음 위치로 이동 안내) + 실패 사유 한글 표시.
**Python 1:1 매핑**:
- `_traces(cycles, win=10)` ↔ `buildRecord()` sliding
- `alignment_selection.select_cm(rule='A', tie='bvcv')` ↔ `selectCm()`
- `CenterAligner._fail_reason()` ↔ `failReason()`
- BV 리스트 축적: Python `if bv is not None: bvs.append(volume_ml)` ↔ Kotlin `bv?.let { bvs.add(it.volumeMl) }` (nan/0 필터 없음 — Python 1:1)
**검증** (`app/src/test/java/com/medithings/vesiscan/managers/CenterAlignerValidationTest.kt`,
data123/ 인체 3 세션):
- Python reference 와 `nch / ch3 / ch3_hit` **완전 일치**
- `bv_cv` 오차 <2% (정상 케이스). BV 발산 케이스만 큰 오차 — Rule A 필터링으로 선택 영향 없음
- 최종 선택 위치 = **cm=3 (Python 과 일치)**
주의: unit test 는 `PiezoHW.activePreset = DevicePreset.V1` 명시 설정 필요.
실기기는 `BleManager.autoDetectPreset(deviceName)` 이 자동 처리.
UI 통합 (Pass 1 위치 안내 · 진행바 · Pass 2 판정 화면) 은 후속 작업.
관련 commit: `9387552` (이식) + `fcdce12` (Python 1:1 nan/0 필터 제거).
### Measurement Modes (v6 업데이트) ### Measurement Modes (v6 업데이트)
- **Auto Scan**: **min 600ms gap** (state-based throttle: `!isComplete` + 600ms), 10-sample trimmed mean (max/min removed, 8 avg) - **Auto Scan**: **min 600ms gap** (state-based throttle: `!isComplete` + 600ms), 10-sample trimmed mean (max/min removed, 8 avg)