docs: explain localization choices and cost

README.md

@@ -1,6 +1,7 @@
 # micarrsim
 
-192채널 MEMS 마이크 배열의 배치와 자유음장·저비용 실내 근사에서의 DAS 음향 영상을 비교하는 로컬 브라우저
+192채널 MEMS 마이크 배열의 배치와 자유음장·저비용 실내 근사에서 DAS·DAS-PHAT·GCC-PHAT
+위치 추정을 비교하는 로컬 브라우저
 시뮬레이터입니다. Dataset Builder에서 녹음 파일·합성 신호와 이동 경로를 포함한 재현 가능한
 음향 장면을 만들고 Acoustic Camera에서 CPU 또는 WebGPU로 배열 응답, acoustic map과 위치 검출
 지표를 계산하거나 이동 장면을 시간축으로 재생합니다.
@@ -46,9 +47,12 @@ powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\scripts\serve.
 1. 시작 화면에서 **Acoustic Camera**를 엽니다.
 2. 기본 192채널 rectangular 배열, single-tone scene과 50×50 experiment가 준비될 때까지
    기다립니다.
-3. Snapshot 카드의 **▶ Snapshot 실행**을 누릅니다.
+3. 처음에는 **DAS · 기준 power**를 두고 Snapshot 카드의 **▶ Snapshot 실행**을 누릅니다.
 4. 계산이 끝나면 overlay와 평가 지표를 확인하고 **Result JSON**을 누릅니다.
 
+같은 입력에서 **위치 추정 알고리즘**만 DAS-PHAT으로 바꿔 다시 실행하면 아래 비교 기록에 두 결과가
+나란히 남습니다. GCC-PHAT은 광대역 입력에서 비교하세요.
+
 실제 완료 시간은 브라우저와 장치에 따라 다릅니다. CPU fallback에서는 WebGPU보다 오래 걸릴 수
 있습니다.
 
@@ -85,7 +89,7 @@ powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\scripts\serve.
 5. 별도 실험 문서를 사용할 때만 **Experiment**에서 `.experiment.json`을 선택합니다.
 6. Scene에 이미지나 audio asset이 있다면 **Assets**에서 Builder에 사용했던 원본 파일을 다시
    선택합니다. 여러 파일을 한 번에 선택할 수 있습니다.
-7. 입력 검증이 통과하면 backend와 scan grid를 정하고 실행합니다.
+7. 입력 검증이 통과하면 위치 추정 알고리즘, backend와 scan grid를 정하고 실행합니다.
 8. 완료 후 **Result JSON**을 저장합니다.
 
 Array와 Scene을 먼저 불러와야 Experiment의 `arrayId`와 `sceneId` 관계를 안전하게 검증할 수
@@ -106,18 +110,38 @@ SHA-256 manifest를 저장합니다. 브라우저는 새 페이지나 세션에
 - 실제 decode되어 메모리에 유지되는 오디오 합계는 최대 192 MiB입니다.
 - Scene JSON에는 원본 파일명이 기록될 수 있으므로 파일을 외부에 공유하기 전에 확인하세요.
 
-## Backend와 scan grid
+## 알고리즘, Backend와 계산량
+
+| 알고리즘 | 원시 map | backend | 용도와 주의점 |
+| --- | --- | --- | --- |
+| DAS | 상대 acoustic power | CPU, WebGPU | 가장 단순한 기준선. 채널 gain과 알려진 마이크 응답을 보정합니다. |
+| DAS-PHAT | 무차원 score | CPU, WebGPU | 마이크별 진폭을 버리고 위상 정합을 비교해 gain·반사에 더 강건할 수 있습니다. |
+| GCC-PHAT | 무차원 score | CPU | 한 reference와 나머지 마이크의 TDOA 상관을 사용합니다. 광대역이 필요하며 협대역에서는 주기적 모호성이 큽니다. |
 
 - **Auto (GPU→CPU)**: 권장값입니다. WebGPU adapter나 device를 사용할 수 없거나 지원되는 장치
   한계를 넘으면 CPU로 계속합니다.
 - **WebGPU 강제**: GPU 경로만 사용합니다. 장치를 열 수 없거나 한계를 넘으면 fallback하지 않고
   오류를 표시합니다.
-- **CPU 강제**: 비교와 호환성 확인을 위해 CPU DAS만 사용합니다.
+- **CPU 강제**: 비교와 호환성 확인을 위해 선택한 알고리즘의 CPU 구현을 사용합니다.
+
+GCC-PHAT은 현재 CPU 전용이므로 선택하면 Auto 또는 CPU만 사용할 수 있습니다. Camera는 각 band가
+8개 미만의 FFT bin을 포함하면 협대역 경고를 표시합니다.
 
 WebGPU 경로도 신호 합성과 STFT 일부는 CPU에서 수행합니다. grid의 point 수는 50×50을 1로 보면
 100×100은 4배, 200×200은 16배입니다. 처음에는 50×50을 사용하고 해상도가 필요할 때만 높이세요.
 실행 시간은 microphone 수, scene 길이, FFT, 대역 폭과 장치에 함께 좌우됩니다.
 
+DAS 계열의 scan 주항은 `P × M × T × F`입니다. 192채널·50×50·46 frames·2 bins의 기존
+fixture는 44,160,000 complex MAC입니다. GCC-PHAT은 같은 조건에서 forward STFT를 그대로
+수행한 뒤 191 reference pairs에 대해 35,144회의 2-pass cross-spectrum 연산, 191회의 inverse
+FFT와 477,500회의 point/pair lookup을 수행합니다. 따라서 큰 grid·광대역에서는 scan 비용을
+줄이지만 작은 grid에서는 공통 STFT 때문에 전체 시간이 같은 비율로 줄지는 않습니다.
+
+저장된 Intel Gen9 측정에서 DAS 50×50의 GPU wall은 79.2 ms였지만 CPU STFT는 1,669.8 ms,
+signal 합성은 별도 1,200.5 ms였습니다. 즉 현재 기본 fixture의 병목은 단순히 grid scan 하나가
+아닙니다. Camera의 workload 줄은 STFT, DAS MAC 또는 GCC cross-spectrum·inverse FFT·lookup,
+signal path와 distance cache를 따로 표시합니다.
+
 ## 음향 환경과 마이크 응답
 
 Camera의 **고급 설정**에서 자유음장, 흡음된 실내, 일반 실내와 반사 강한 실내를 선택할 수
@@ -137,13 +161,18 @@ Camera의 **고급 설정**에서 자유음장, 흡음된 실내, 일반 실내
 
 ## 위치 추정, 빔 분포와 복수 음원
 
-DAS 출력은 각 scan point의 상대 acoustic power map이며 위치 확률분포가 아닙니다. Camera는 map의
-local peak를 위치 후보로 표시합니다. **빔 분포**를 켜면 각 peak의 연결된 half-power lobe에 대해
-power 가중 공분산을 계산해 1× RMS 점선과 2× RMS 영역을 그립니다. Gaussian의 등고선처럼 보일 수
-있지만 통계적으로 보정된 Gaussian, 신뢰구간 또는 발생 확률은 아닙니다.
+DAS 출력은 각 scan point의 상대 acoustic power, PHAT 계열 출력은 무차원 score이며 어느 쪽도
+위치 확률분포가 아닙니다. Camera는 map의 local peak를 위치 후보로 표시합니다. **빔 분포**를 켜면
+각 peak의 연결된 half-maximum lobe에 대해 map 값 가중 공분산을 계산해 1× RMS 점선과 2× RMS
+영역을 그립니다. Gaussian의 등고선처럼 보일 수 있지만 통계적으로 보정된 Gaussian, 신뢰구간 또는
+발생 확률은 아닙니다.
+
+GCC-PHAT raw score는 pair 수·band coefficient 수·IFFT 크기로 정규화한 0–1 양의 상관 응답입니다.
+scan 범위나 마이크 수 때문에 값이 단순히 커지는 현상은 막지만, 0.8을 “위치 확률 80%”로 읽을 수는
+없고 다른 알고리즘의 score와 절대값을 비교해서도 안 됩니다.
 
 복수 음원은 각각 별도 local peak가 남을 만큼 공간적으로 분리되고 선택 대역에 에너지가 있어야
-검출됩니다. **Peak 검출 임계값 (%)**은 최강 peak 대비 후보의 최소 power입니다. 기본 25%에서 약한
+검출됩니다. **Peak 검출 임계값 (%)**은 최강 peak 대비 후보의 최소 map 값입니다. 기본 25%에서 약한
 두 번째 음원이 빠지면 10–20%로 낮출 수 있지만 sidelobe 오검출도 늘어납니다. 서로 같은 대역에서
 main lobe보다 가깝거나 gain 차이가 큰 음원은 conventional DAS의 물리·알고리즘 한계 때문에
 threshold만으로 분리되지 않을 수 있습니다.
@@ -161,9 +190,9 @@ index와 audio asset 재생 위치가 이어지도록 신호를 합성합니다.
 - 실제 장치: 물리 192채널 capture/stream gateway는 하드웨어 형식이 정해진 뒤 별도 adapter가 필요
 
 Scene 합성 없이 동기식 `Float32Array` 마이크 채널을 바로 처리하는
-`createLocalizationPlan`, `localizeMultichannel`과 `StreamingDasLocalizer`가
+`createLocalizationPlan`, `localizeMultichannel`과 `StreamingLocalizer`가
 `packages/acoustics-core`에 분리되어 있습니다. 고정 ring buffer, oldest-first drop,
-반복 geometry·steering cache와 `AbortSignal` 취소를 제공하며 실제 capture 장치에는
+반복 geometry·workspace cache와 `AbortSignal` 취소를 제공하며 실제 capture 장치에는
 channel/clock/transport adapter만 별도로 연결합니다. 실시간 여부는 각 결과의
 `processingTimeMs <= deadlineMs`와 누적 `deadlineMisses`·`droppedSamples`로
 해당 장치에서 확인합니다. 복사할 파일과 운용 계약은
@@ -173,11 +202,11 @@ channel/clock/transport adapter만 별도로 연결합니다. 실시간 여부
 
 Result JSON은 계약 버전 `1.0.0`의 `micarrsim.result` 문서입니다. 주요 내용은 다음과 같습니다.
 
-- 실행한 `experimentId`, `arrayId`, `sceneId`, 실제 `backend`와 생성 시각
+- 실행한 `experimentId`, `arrayId`, `sceneId`, 실제 `algorithm`·`backend`와 생성 시각
 - Array·Scene·Experiment의 canonical SHA-256인 `inputHash`
 - 정규화 전 peak, 적용 scale, clipping 수와 음향 모델·희소 경로 수를 담은 `signalStats`
-- 전체·신호 생성·beamforming 시간인 `timingMs`
-- 주파수 대역별 선형 power `rawMap`, 표시용 `displayMap`, 검출 `peaks`
+- 전체·신호 생성·위치 추정 시간인 `timingMs.localization`과 기존 reader용 `beamforming` alias
+- 주파수 대역별 power 또는 score `rawMap`, 표시용 `displayMap`, 검출 `peaks`
 - 위치 오차, precision/recall, truth 반경 내 energy, peak-to-sidelobe, main-lobe 폭을 계산하기
   위한 평가 파라미터와 `metrics`
 - peak별 half-power 공분산과 RMS ellipse를 담은 `beamSpread` (`calibrated: false`)
@@ -195,7 +224,8 @@ noise source는 스펙트럼을 미리 알 수 없으므로 모든 band의 groun
 음향 모델은 직접 경로의 자유음장과 1차 반사·scattering·occluder 회절·RT60 tail을 제한된
 경로로 계산하는 shoebox 근사를 제공합니다. 파동 방정식, 고차 반사, 재질별 주파수 의존 흡음,
 복잡한 mesh 회절, 바람, Doppler, 마이크 self-noise·비선형, ADC와 channel clock은 모델링하지
-않습니다. Beamformer는 conventional DAS이며 UI의 DAMAS와 CLEAN-SC는 아직 사용할 수 없습니다.
+않습니다. 위치 추정기는 DAS, DAS-PHAT와 CPU GCC-PHAT를 제공하지만 full-pair SRP-PHAT, MUSIC,
+DAMAS와 CLEAN-SC는 구현하지 않습니다.
 따라서 결과는 배열·grid·대역의 상대 비교와 소프트웨어 검증용이며, 현장 성능 인증이나 안전
 판단을 대신하지 않습니다.