docs: explain localization choices and cost

apps/acoustic-camera/README.md

@@ -1,8 +1,9 @@
 # Acoustic Camera
 
 Scene과 마이크 배열로 자유음장 또는 저비용 shoebox microphone signal을 합성하고, STFT와
-conventional DAS를 통해 주파수 대역별 acoustic map과 ground-truth 평가 지표를 만드는 브라우저
-앱입니다. 정지 장면은 Snapshot, trajectory 장면은 Moving 흐름으로 분리되어 있습니다.
+DAS·DAS-PHAT·GCC-PHAT 위치추정으로 주파수 대역별 acoustic map과 ground-truth 평가 지표를
+만드는 브라우저 앱입니다. 정지 장면은 Snapshot, trajectory 장면은 Moving 흐름으로 분리되어
+있습니다.
 
 ## 열기와 Snapshot
 
@@ -42,12 +43,31 @@ Camera가 SHA-256을 계산해 manifest에 연결합니다. 같은 이름이라
 
 파일은 외부로 업로드되지 않고 브라우저 메모리에서만 처리됩니다.
 
-## Backend 선택
+## 위치 추정 알고리즘과 Backend
+
+**분석 설정 → 위치 추정 알고리즘**에서 다음 세 구현을 선택합니다.
+
+- **DAS**: 채널 진폭과 위상을 유지해 coherent sum power를 계산하는 기준선입니다. CPU와 WebGPU를
+  지원하고 `rawMap.scale`은 `power`입니다.
+- **DAS-PHAT**: 각 STFT 성분의 크기를 정규화하고 위상을 합산합니다. 채널 gain 차이에 덜
+  민감한 비교용이며 CPU와 WebGPU를 지원합니다. 결과는 무차원 `score`입니다.
+- **GCC-PHAT**: 기준 마이크와 나머지 마이크의 PHAT 상관에서 기하학적 TDOA를 평가합니다. 현재
+  CPU 전용이므로 Auto는 CPU를 선택하고 **WebGPU 강제**는 선택할 수 없습니다. 각 band가 8개
+  미만의 FFT bin을 포함하면 협대역 상관이 불안정할 수 있다는 경고가 표시됩니다.
+
+PHAT score는 위치 확률이나 음향 power가 아닙니다. 세 알고리즘 모두 같은 scan grid에 응답 map을
+만들지만, 진폭 보존 여부와 실패 양상이 다르므로 같은 Scene·Array·band로 비교하세요.
+GCC-PHAT raw score는 pair·band coefficient·IFFT 크기를 정규화한 0–1 양의 상관 응답이라 scan
+범위나 마이크 수에 따른 단순 scale 변화는 피하지만, 확률이나 다른 알고리즘과 공통인 confidence는
+아닙니다.
 
 - **Auto (GPU→CPU)**: 권장. WebGPU를 먼저 시도하고 adapter/device 부재나 지원되는 장치 한계가
-  있으면 CPU로 계속합니다.
-- **WebGPU 강제**: GPU만 사용하며 운용 오류가 나도 CPU로 fallback하지 않습니다.
-- **CPU 강제**: CPU 수치 기준이나 WebGPU가 없는 환경에서 사용합니다.
+  있으면 CPU로 계속합니다. 라이브 준비에서는 첫 fallback 뒤 남은 frame이 같은 CPU analysis
+  plan을 재사용하므로 GPU 실패를 매 frame 반복하지 않습니다. GCC-PHAT에서는 **Auto (CPU)**로
+  표시됩니다.
+- **WebGPU 강제**: DAS와 DAS-PHAT를 GPU에서만 실행하며 운용 오류가 나도 CPU로 fallback하지
+  않습니다.
+- **CPU 강제**: 선택한 알고리즘의 CPU 수치 기준이나 WebGPU가 없는 환경에서 사용합니다.
 
 WebGPU가 감지돼도 실제 장치는 실행 시 확인합니다. 계산 중 **계산 취소**를 누르면 Worker를
 종료하며, 이미 완료된 이전 결과가 있으면 그대로 남습니다.
@@ -82,9 +102,10 @@ Array의 각 microphone에는 선택적 `frequencyResponse`를 넣을 수 있습
 ```
 
 curve는 합성 microphone channel에 항상 적용됩니다. **마이크 주파수 응답 처리**의 기본
-**측정 curve 적용 + 위치추정에서 역보정**은 CPU와 WebGPU DAS에서 알려진 gain/phase를
-역보정합니다. **측정 curve 적용 + 보정하지 않음**은 합성 응답은 유지하고 역보정만 꺼서 영향을
-비교합니다. curve가 없는 마이크는 기존 결과를 유지합니다. 응답 notch를 과도하게 증폭하지
+**측정 curve 적용 + 위치추정에서 역보정**은 선택한 CPU 위치추정과 DAS/DAS-PHAT WebGPU
+경로에서 알려진 gain/phase를 역보정합니다. **측정 curve 적용 + 보정하지 않음**은 합성 응답은
+유지하고 역보정만 꺼서 영향을 비교합니다. curve가 없는 마이크는 기존 결과를 유지합니다. 응답 notch를
+과도하게 증폭하지
 않도록 역보정의 양의 gain boost는 기본 24 dB로 제한하며, 사용자 Experiment JSON의
 `beamforming.maxCompensationDb`에서 0–120 dB로 지정할 수 있습니다.
 
@@ -94,32 +115,40 @@ curve는 합성 microphone channel에 항상 적용됩니다. **마이크 주파
 ## Grid, STFT와 대역
 
 50×50은 2,500 points입니다. 이를 1로 보면 100×100은 4배, 200×200은 16배 points를 계산합니다.
-처음에는 50×50을 권장합니다. 실행량은 microphone 수, scene 길이, FFT/hop과 선택 band의 bin
-수에도 비례하므로 실제 시간 배율은 장치마다 다릅니다.
+처음에는 50×50을 권장합니다. 연산량 줄에는 공통 STFT transform 수와 signal path, distance
+cache를 표시하고 알고리즘별 위치추정 비용을 다음처럼 분리합니다.
+
+- DAS/DAS-PHAT: scan point × microphone × STFT frame × 선택 bin의 complex MAC
+- GCC-PHAT: 기준 마이크 pair별 two-pass cross-spectrum, pair × band inverse FFT와
+  scan point × pair × band correlation lookup
+
+이는 구현 연산 횟수이지 실행 시간 예측값은 아닙니다. scene 길이, microphone 수, FFT/hop,
+band 수와 폭, grid 및 CPU/GPU에 따라 실제 시간이 달라집니다.
 
 각 band는 id, 최소/최대 Hz와 overlay 색을 가집니다. Nyquist를 넘거나 겹치는 id 등 계약 오류는
-실행 전에 표시됩니다. 현재 후처리는 raw DAS만 지원하며 DAMAS와 CLEAN-SC 항목은 비활성화되어
-있습니다.
+실행 전에 표시됩니다. DAMAS와 CLEAN-SC 후처리는 아직 구현하지 않았으며, 실행할 수 없는 비활성
+항목은 Camera UI에서 제거했습니다. Result의 `processedMaps` 계약만 향후 확장을 위해 남아 있습니다.
 
-**Peak 검출 임계값 (%)**은 최강 local peak의 power에 대한 상대 임계값이며 Experiment JSON에
+**Peak 검출 임계값 (%)**은 최강 local peak의 map 값에 대한 상대 임계값이며 Experiment JSON에
 저장됩니다. 기본 25%에서 약한 두 번째 음원이 빠지면 10–20%로 낮추세요. 낮은 값은 더 약한 후보를
-살리는 대신 sidelobe를 음원으로 잘못 고를 가능성도 높입니다. 같은 대역의 두 음원이 main lobe
-폭보다 가깝다면 grid만 키우거나 threshold를 낮춰도 conventional DAS map에서 하나로 합쳐질 수
-있습니다.
+살리는 대신 sidelobe를 음원으로 잘못 고를 가능성도 높입니다. 같은 대역의 두 음원이 알고리즘의
+main lobe 폭보다 가깝다면 grid만 키우거나 threshold를 낮춰도 하나로 합쳐질 수 있습니다.
 
-## 화면과 배열 비교
+## 화면과 배열·알고리즘 비교
 
 - acoustic overlay의 투명도와 표시할 band를 선택할 수 있습니다.
 - **Ground truth**를 켜면 source 위치와 검출 peak를 비교할 수 있습니다.
-- **빔 분포**는 peak 주변 half-power lobe의 power 가중 공분산을 1× RMS 점선과 2× RMS 영역으로
-  표시합니다. 위치 확률, Gaussian 신뢰구간 또는 측정 불확실성 보정값은 아닙니다.
+- **빔 분포**는 DAS power의 half-power 또는 PHAT score의 half-maximum 연결 성분을 해당 map
+  값으로 가중한 공분산으로 계산해 1× RMS 점선과 2× RMS 영역으로 표시합니다. 위치 확률,
+  Gaussian 신뢰구간 또는 측정 불확실성 보정값은 아닙니다.
 - **배열 선택**에는 채널 수(4·12·48·192·384), aperture 크기(0.12·0.45·1.20 m), rectangular와
-  Fermat spiral 배치를 분리 비교하는 8개 preset이 있습니다. 같은 Scene/Experiment에서 연속 실행하면
-  **배열 비교 기록**에 backend, timing과 평가 요약이 남습니다.
+  Fermat spiral 배치를 분리 비교하는 8개 preset이 있습니다. 같은 scene·scan·STFT에서 연속
+  실행하면 **비교 기록**에 배열, 알고리즘, 실제 backend, 위치추정/전체 timing과 평가 요약이 함께
+  남습니다.
 - 입력을 바꾼 뒤 화면에 남은 결과는 이전 실행 snapshot이며 UI가 이전 설정 결과임을 표시합니다.
 - Camera에서 거리·음속·seed를 바꾼 Scene과 scan·STFT·band를 바꾼 Experiment는 우측의 각
   **JSON 저장** 버튼으로 보존할 수 있습니다.
-- **전체 기록 JSON**은 세션에 남은 모든 배열 비교 요약을
+- **전체 기록 JSON**은 세션에 남은 배열·알고리즘·backend 비교 요약을
   `micarrsim.comparison-history` 문서로 저장합니다.
 
 미저장 Scene·Experiment·Result·비교 기록은 우측 저장 상태에 표시됩니다. 직전 Result를 저장하지
@@ -131,7 +160,7 @@ curve는 합성 microphone channel에 항상 적용됩니다. **마이크 주파
 Scene source에 두 개 이상의 `trajectory` keyframe이 있으면 **Map 준비**가 활성화됩니다.
 Builder에서는 **시간에 따라 음원 이동**과 경로 미리보기 slider로 이 데이터를 만들 수 있습니다.
 
-1. Map rate와 backend를 선택합니다. 처음에는 2 Hz와 Auto를 권장합니다.
+1. 알고리즘, Map rate와 backend를 선택합니다. 처음에는 DAS, 2 Hz와 Auto를 권장합니다.
 2. **Map 준비**를 누릅니다. 현재 입력 snapshot을 최대 48개, map당 최대 2,500 points의 짧은
    분석창으로 계산합니다.
 3. **재생** 또는 시간 slider로 이동합니다. Heatmap은 이웃한 acoustic map 사이를 보간하고
@@ -146,13 +175,15 @@ Scene 시간에 이어 붙입니다. 한 창 안에서는 중앙 시각의 위
 
 **Result JSON**은 검증을 통과한 `micarrsim.result` 문서만 저장합니다.
 
-- `experimentId`, `arrayId`, `sceneId`, `createdAt`, 실제 `backend`
+- `experimentId`, `arrayId`, `sceneId`, `createdAt`, 실제 `algorithm`과 `backend`
 - 실행 입력 전체의 canonical SHA-256인 `inputHash`
 - `signalStats`: 정규화 전 peak, 적용 scale, clipped sample 수, 실제 음향 모델과 sparse
   path 전체·종류별 수
-- `timingMs`: 전체, signal generation과 beamforming 시간
-- band별 `rawMap` 선형 power, `displayMap`, 검출 `peaks`
-- 각 peak의 비보정 half-power 공분산과 RMS ellipse인 `beamSpread`
+- `timingMs`: 전체, signal generation과 `localization`; 기존 소비자 호환용 `beamforming`은 같은
+  위치추정 시간을 담는 alias
+- band별 `rawMap`: DAS는 선형 `power`, PHAT 계열은 무차원 `score`; 화면용 `displayMap`과 검출
+  `peaks`
+- 각 peak의 비보정 half-power/half-maximum 공분산과 RMS ellipse인 `beamSpread`
 - 평가 설정과 `peakToSidelobeDb`, `energyInsideTruthRatio`, `precision`, `recall`,
   `mainLobeWidthM`
 
@@ -172,7 +203,8 @@ sensitivity/phase/frequency-response calibration은 적용하지만 결과는
 실제 동기식 microphone `Float32Array`를 Scene 합성 없이 위치추정하려면
 [실시간 위치추정 코어 포팅](../../docs/realtime-porting.md)의
 `createLocalizationPlan`, `localizeMultichannel` 또는
-`StreamingDasLocalizer`를 사용하세요. 실시간성은 장치에서
+`createStreamingLocalizer`를 사용하세요. portable config의 `algorithm`으로 같은 세 위치추정을
+선택할 수 있습니다. 실시간성은 장치에서
 `processingTimeMs <= deadlineMs`와 `deadlineMisses`·`droppedSamples`를
 측정해 판정해야 합니다.