# 알고리즘 경로 두 갈래 (`AlgoMode`)

demo-final 은 팬텀 시연과 임상 계측이 함께 도는 브랜치다. 여기에 신 저장소
(`vesiscan_pre_product/vesiscan_android_user`)가 레퍼런스
(`piezo-phantom-test/vesiscan_test`)와 1:1 로 맞춘 검출·BV 단계들을 옮기되,
**기본 동작은 그대로 두고** dev 패널에서만 켤 수 있게 했다.

- 코드: [`managers/AlgoMode.kt`](../app/src/main/java/com/medithings/vesiscan/managers/AlgoMode.kt)
- UI: 계측 화면 dev 패널 → **알고리즘** 스위치 (기본 꺼짐)
- 상태는 프로세스 수명 동안만 유지된다. 앱을 다시 켜면 기존 경로로 돌아간다.

## "기존" 이 가리키는 것

`ebddc52`(검출·BV 레퍼런스 정합) 와 `20a48ad`(실리콘 cap 억제) 가 들어간 **현재
demo-final HEAD** 다. 2026-09-03 임상이 이 코드 위에서 돌았으므로, 그 값을 움직이는
변경은 기본 경로에 넣지 않는다.

따라서 아래 항목들은 **양쪽 공통**이며 모드와 무관하다:

| 항목 | 값 | 들어간 커밋 |
|---|---|---|
| `d_max` · `inward_walk_win` | 15 · 4 | `ebddc52` |
| prominence 기준 | span 바닥 (`ANT_FLOOR_REF`) | `ebddc52` |
| cap 축 붕괴 폴백 | `CAP_AXIS_RATIO_MAX` 0.85 / `CAP_AXIS_DMAX_MAX` 100 | `ebddc52` |
| `ELLIPSE_CAP_R_MAX` · `TOP_CAP_EDGE_K` | 0.92 · 0.6 | `ebddc52` |
| `cap_d_adaptive` (실리콘) | ("aspect", 80.0, 2.0) | `20a48ad` |
| dps · delay | 프리셋 유도 (v\*=1.936/6.85, r\*=1.897/7.651) | 기존 |

## 스위치를 켜면 바뀌는 것

부분 적용은 없다. 단계들이 서로를 전제하므로 섞으면 어느 쪽도 아닌 값이 나온다.

### 1. 교차채널 보정 (CCC) — 3단계 → 7단계

| | 기존 | 레퍼런스 |
|---|---|---|
| 순서 | `ant_tiebreak` → NTV(Rule A+B) → `inward_post` | ①.9 `envelope_research` → ① `ant_tiebreak` → ①.7 Λ-dip → ①.8 `edge_post_recovery` → ①.95 `lumen_return_recovery` → ② NTV(**Rule A 만**) → ③ `fp_channel_gate` |
| `inward_post` | 있음 | **없음** |
| NTV Rule B | 있음 | 없음 |

레퍼런스 쪽 데이터에서 각 단계가 결과를 바꾼 횟수(파이썬 ablation, 1512 케이스):
`ant_tiebreak` 158 · `edge_post_recovery` 73 · Λ-dip 7 · `fp_gate` 4 · 나머지 0.

### 2. 검출 파이프라인 — 4개 단계 추가

| 단계 | 하는 일 | 왜 |
|---|---|---|
| 2 `scale_recovery` | 검출 **실패** 채널만 SG5 로 재탐색 | window 를 전역으로 바꾸면 모든 벽이 함께 밀려 부피가 통째로 이동한다. 실패 채널만 건드려 커버리지(nch)만 얻는다. |
| 4 `missing_outside` | span 조차 없는 채널 = 진짜 방광 밖 | **CCC 앞**에서 계산해야 한다. CCC 가 복구한 채널은 방광 밖이 아니다. |
| 5b `channel_confidence` | 약한 채널을 CCC **복구 단계에서만** 숨김 | 판정(NTV·FP) 전에 되돌린다. 끝까지 숨기면 CCC 가 그 채널을 FP 로 기각할 기회를 잃어 오히려 살아남는다. |
| 6 `CONF_DEMOTE` | CCC 후 여전히 약한 채널을 단면에서 제외 | 남는 채널이 3 미만이 되면 아무것도 하지 않는다. |

신뢰도는 **비-TGC** `min(ant_amp, post_amp) / lumen_min` 을 trace 최고값으로 나눈 값이다.
TGC 로 재면 원거리 이득이 약한 채널을 정상 채널에 붙여 놓는다(CH1↔CH3 간격 TGC 0.05 vs
비-TGC 0.21).

### 3. BV

- **`si_floor` / `missing_outside`** — 극 cap clamp 의 방향이 관측 증거로 갈린다.
  미검출 채널에 span 이 **없으면** 방광이 그 빔에 없다는 뜻이라 **상한**(종전),
  span 이 **있으면** 방광이 거기까지는 온다는 뜻이라 **하한**이다. 외삽을 관측으로
  바꾸는 것이다. `SI_FLOOR_WALK` 는 span 이 이어지는 가장 바깥 채널까지 걸어간다.
- **bottom cap 제한 신설** — top 만 있고 bottom 은 제약이 전혀 없었다. sitting 에서
  CH3(치골)이 소실될 때 bottom cap 이 과외삽된다.
- **중앙 채널 보간 은행가 반올림** — 레퍼런스는 `int(round((int(prev)+int(next))/2.0))`
  이다. 보간 채널은 subsample 정밀도를 가질 근거가 없다(이웃 둘의 정수 위치뿐).
  실측 f01 tr11: 이 차이로 CH2 단면이 2971.0 vs 2788.2 mm² 로 갈렸다.
- **`adaptive_large_bladder_relax` 제거** — 레퍼런스에서 빠진 완화다. 남아 있는 동안
  `b_si` 를 0.85·`a_ap` 로 바닥 처리해 cap 축 비를 정확히 0.85 로 만들었고, 그래서 바로
  다음의 cap 축 폴백(`< 0.85`)이 **경계에서 발동하지 않았다**.
  실측 PHANTOM mean: Python 160.03 mL vs 완화가 살아 있는 코틀린 232.49 mL.

  폴백 재계산에는 `missing_outside`·`si_floor` 를 **넘기지 않는다** — 레퍼런스
  `runners.estimate_bv` 의 폴백 호출이 그 인자를 빼고 부르기 때문이다.
  실측 f04 cyc20: 넘기면 249.95 mL, 안 넘기면 278.43 mL(= 레퍼런스 값).

## 검증

| 무엇을 | 어떻게 | 결과 |
|---|---|---|
| 기존 경로 무변경 | `LegacyEquivalenceDumpTest` 가 `align_cm{0,1}.csv` 44 cycle × CCC on/off 를 검출→BV 로 돌려 덤프. HEAD 코드와 작업트리 코드의 덤프를 대조. | **88 행 전부 일치** |
| 토글 배선 | `AlgoModeSwitchTest` — 켜면 값이 달라지고 `missing_outside` 가 산출되며, 끄면 기존 값이 정확히 재현되는지 | 44 cycle 중 **39 개가 갈림**, 끈 뒤 완전 복귀 |
| 정렬 판정 | 현행 레퍼런스 `AnchorGuide(ver='v1')` 를 `data123` 3 세션에 돌려 대조 | nch·ch3·hit **전부 일치** (0cm 3/X/2·11, 1cm 4/O/8·11, 3cm 3/O/11·11) |
| 전체 | `:app:testDemoDebugUnitTest` | **30개 전부 통과** |

`LegacyEquivalenceDumpTest` 는 의도적으로 `AlgoMode` 를 참조하지 않는다 — HEAD 에는 그
타입이 없어서, 참조하면 대조 자체가 불가능해진다.

## 이번에 함께 고친 것

- **테스트 픽스처 경로** — 저장소가 갈리면서 `c:/Projects/medilightv2android/data123` 가
  없어졌다. 5개 테스트가 `FileNotFoundException` 으로 조용히 실패하고 있었다.
  `c:/Projects/vesiscan-design-archive/data123` 로 옮겼다.
- **`CenterAlignerValidationTest` 기대값** — 위 픽스처가 깨져 있어 `ebddc52` 이후 이
  테스트가 한 번도 돌지 않았다. 다시 돌리니 hit 7→8 · 10→11 로 어긋났는데, **현행
  레퍼런스를 같은 세션에 돌려 보니 8 · 11 이었다** — 코틀린이 맞고 기대값이 낡은
  것이다(구 `v3_python_reference.py` 기준, 현재 저장소에 없음). 기대값을 현행 레퍼런스
  산출값으로 갱신했다.
  `bv_cv` 는 현행 레퍼런스가 더 이상 내지 않는 값이라 대조할 수단이 없다. "Python 과
  bit-exact" 라던 종전 주석은 근거가 없어져 걷어내고, 성격을 **회귀 고정**으로 바꿔
  적었다.

## 나중에 추가된 3건 (2026-09-03)

`post_tie_lock` · `_sibeam_cap_bounds` · F83 을 마저 옮겼다. 셋 다 레퍼런스 경로에서만
의미가 있다.

| 항목 | 어디 | 기존 경로에 미치는 영향 |
|---|---|---|
| `post_tie_lock` | `walldetect/PostTieLock.kt` | 없음 — 상태기를 **넘길 때만** 동작하고, 넘기는 호출부가 없다 |
| `_sibeam_cap_bounds` | `PiezoBVEstimator.kt` | 없음 — `AlgoMode.reference` 로 막았다 |
| 미러 + F83 | `PiezoBVF83.kt` | 없음 — `mirrorBottomCap` 을 켜는 호출부가 F83 뿐이다 |

`post_tie_lock` 은 후벽 상위 두 후보의 score 가 구조적으로 붙는 구간에서 **직전 trace 의
선택을 유지**한다(방향을 강제하지 않는다 — 그렇게 한 앞선 시도들은 전부 계통 편향을
낳았다). 레퍼런스도 streaming 경로의 strict pass 에서만 걸고 정렬에서는 쓰지 않으므로,
`streaming.py` 를 옮기기 전까지는 클래스와 배선만 자리를 잡아 둔 상태다.

### 좌표계가 두 개다 — 레퍼런스를 그대로 따랐다

레퍼런스 `cross_channel._z` 는 `sample_to_ap_depth(idx, angle)` 를 **인자 없이** 불러
교차채널 좌표가 언제나 모듈 기본값(1.936 / 6.85)으로 떨어진다. 반면 BV 는 프리셋 값을
명시로 넘긴다. abs(v\*)는 두 값이 같아 표가 안 나지만 **실리콘(r\*: 1.897/7.651)에서는
갈린다** — 실측 f06/r1 단일 cycle 에서 CH0 전벽이 8 vs 14 로 갈려 부피가 439.88 vs
416.95 mL 이 됐다. `is_deep` 판정이 34.209 > 34.042 처럼 아슬아슬하게 걸리는 자리라
작은 좌표 차이가 그대로 선택을 뒤집는다.

의도인지 누락인지 **알고리즘팀 확인이 필요하다.** 확인 전까지는 레퍼런스와 같은 값을
내는 쪽을 택했고, **기존 경로는 프리셋 값을 그대로 쓴다** — 오늘 임상이 그 위에서 돌았다.

### 대조 결과

`ThreeFeatureParityTest` 가 모드 ON 상태에서 레퍼런스 산출 기대값과 대조한다.
실데이터는 abs 인체 0~4cm 라 미러·nch=2 에 거의 안 닿아, 그 경로는 합성 입력으로
**레퍼런스 함수를 직접 호출한** 기대값으로 덮었다.

| 대조 | 행 | 실제로 밟은 경로 |
|---|---|---|
| tie lock | 1568 | lock 발동 24 건 |
| 실데이터 BV | 784 | nch=2 6 건 |
| sibeam | 120 | 상한 산출 102 건 |
| 합성 BV | 640 | `mirror sphere` 226 건 |
| F83 blend | 440 | weight 0→1 |
| F83 apply | 12 | sub-window 재검출 |

전부 불일치 0.

## 아직 안 옮긴 것

`streaming.py`(연속 측정 상태기). `post_tie_lock` 의 자연스러운 소비처라 함께 설계해야
한다.

레퍼런스 저장소의 `library/analysis/abdomen.py` 가 커밋되어 있지 않아
`pipeline_dump.py` · `compare.py` 가 그대로는 돌지 않는다. 이번 대조는 스크래치 사본에
호출 시 즉시 실패하는 스텁을 놓아 우회했다(정렬·검출·BV 경로는 이 모듈을 쓰지 않는다).