docs: guide acoustic modeling and realtime porting

docs/execution-plan.md

@@ -2,15 +2,16 @@
 
 > 구현 상태 · 2026-08-28
 >
-> 단계 0–4는 완료되어 설치 없는 브라우저 앱, CPU/WebGPU DAS, Builder→Camera asset 재연결,
-> 임의 오디오·이동 trajectory, 빔 분포·복수 peak 감도, 라이브 시간축 재생, 배열 비교와
-> Result 내보내기를 71개 자동 테스트로 검증했다. 단계 5는 실제 장치·공간 모델 고도화 범위다.
+> 단계 0–4와 단계 5의 저비용 음향 환경·마이크 응답·portable streaming core까지 완료했다.
+> 설치 없는 브라우저 앱, CPU/WebGPU DAS, Builder→Camera asset 재연결, 임의 오디오·이동
+> trajectory, 빔 분포·복수 peak 감도, 라이브 시간축 재생, 배열 비교와 Result 내보내기를
+> 전체 자동 테스트로 검증했다. 실제 장치 adapter와 현장 검증은 장치 계약이 필요한 후속 범위다.
 
 ## 1. 목표와 성공 기준
 
 이 프로젝트는 정방형 평면에 배치할 192개 MEMS 마이크의 배열을 비교하기 위한 재현 가능한
-시뮬레이터를 만든다. 첫 버전은 자유음장(free field), 점 음원, 구면파 전파를 가정하며 다음 흐름을
-끝까지 수행해야 한다.
+시뮬레이터를 만든다. 기준선은 자유음장(free field), 점 음원과 구면파 전파이며, 같은 입력에서
+마이크 응답과 계산량이 제한된 shoebox multipath를 선택해 다음 흐름을 끝까지 수행한다.
 
 1. 기계음 데이터와 ambient audio를 조합해 장면 및 ground truth를 생성한다.
 2. 배열 JSON과 장면 정보를 사용해 각 마이크에 도달하는 신호를 합성한다.
@@ -42,8 +43,8 @@ CPU 기준 구현과 GPU 결과의 수치 오차가 합의된 허용 범위 안
   seed 고정, 합성 오디오와 ground truth manifest 내보내기
 - `acoustic-camera`: manifest와 배열 JSON 읽기, 마이크 신호 전파 합성, steering vector 생성,
   DAS 실행, overlay·수치 평가·실험 결과 내보내기
-- `acoustics-core`: 두 앱이 공유하는 좌표계, 단위, 구면 감쇠·지연, STFT, 정답 rasterization,
-  지표 및 CPU reference
+- `acoustics-core`: 두 앱이 공유하는 좌표계, 단위, 구면 감쇠·희소 multipath·마이크 응답,
+  STFT, 정답 rasterization, 지표, CPU reference와 실측 channel용 streaming localizer
 - `webgpu-kernels`: steering/DAS 커널, buffer layout, 장치 한도 검사와 benchmark
 
 ## 3. 데이터 계약
@@ -52,43 +53,62 @@ JSON Schema를 먼저 고정하고 모든 길이는 m, 시간은 s, 주파수는
 명시한다.
 
 - `array.schema.json`: schema version, 배열 폭·높이, 192개 마이크의 id와 `[x,y,z]`, 선택적
-  감도·채널 보정값
+  감도·위상·주파수 응답 보정값
 - `scene.schema.json`: 배경 이미지 크기와 실제 평면 변환, 음원별 위치·오디오 참조·시작/종료·
-  gain, ambient 참조, sample rate, seed
+  gain, ambient 참조, sample rate, seed, 선택적 자유음장·shoebox 환경
 - `experiment.schema.json`: 배열/장면 참조, AC-음원 거리, 음속, frequency band 목록과 색,
   STFT window/hop, scan bounds와 해상도, 알고리즘 및 normalization
 - `result.schema.json`: 실행 환경, timing, acoustic map, peak, 평가 지표, 입력 hash
 
 오디오 파일은 manifest 옆의 상대 경로로 참조한다. 브라우저 내 객체 URL은 저장 형식에 포함하지
-않는다. 스키마에는 버전을 두고 향후 잔향 모델과 마이크 지향성을 선택 필드로 추가한다.
+않는다. 스키마에는 버전을 두며, 현재 잔향은 1차 반사·scattering·RT60 tail의 희소 근사로
+계약한다. 마이크 지향성과 더 복잡한 재질·mesh 모델은 후속 선택 필드로 남긴다.
 
 ## 4. 음향 및 연산 모델
 
-첫 모델에서 음원 `s`와 마이크 `m` 사이 거리 `r`에 대해 지연은 `r/c`, 진폭은 기준 거리와
-최소 거리 clamp를 둔 `1/r`로 계산한다. 분수 sample 지연은 주파수 영역의 phase shift로 처리한다.
-복수 음원과 ambient를 선형 합산하되 clipping 전 peak와 최종 normalization을 기록한다.
+기준 자유음장은 음원 `s`와 마이크 `m` 사이 거리 `r`에 대해 지연 `r/c`와 최소 거리
+clamp를 둔 `1/r` 진폭을 사용한다. 선택적 shoebox는 직접음, 여섯 면의 1차 image-source,
+반사 에너지의 deterministic scattering, 축 정렬 occluder의 transmission·최단 corner 우회와
+tap 수가 제한된 RT60 tail만 추가한다. 경로를 source–microphone 전달함수 하나로 합치고 IFFT를
+한 번만 수행하며 위상 recurrence로 bin별 삼각함수 호출을 줄인다.
+
+마이크별 2–64점 `frequencyResponse`는 dB와 wrapped phase를 보간해 수신 channel에 적용한다.
+기본 DAS는 sensitivity/phase와 frequency curve의 알려진 역응답을 적용하되 notch의 양의 boost는
+기본 24 dB로 제한하고, curve 보정만 끈 robustness 비교도 저장 가능하다. 복수 음원과 ambient를
+선형 합산하되 clipping 전 peak, 최종 normalization, 음향 모델과 실제 종류별 경로 수를 기록한다.
 
 DAS는 STFT 후 각 scan point와 마이크 사이 거리로 steering phase를 만들고, 선택된 주파수 bin의
 정렬 합 power를 계산한다. 여러 주파수 구간은 각각 독립 map과 색을 갖는다. CPU reference를 먼저
 작성한 뒤 같은 buffer layout으로 WGSL 결과를 대조한다. DAMAS, CLEAN-SC는 인터페이스만 마련하고
 초기 완료 범위에서는 제외한다.
 
-연산량의 주항은 대략 `O(P × M × F)`다. `M=192`, `P=50²=2,500`일 때 주파수 bin 하나당
+연산량의 주항은 대략 `O(P × M × F × T)`다. `M=192`, `P=50²=2,500`일 때 STFT
+frame·주파수 bin 하나당
 약 48만 개의 복소 steering 누산이 필요하다. 100×100은 50×50보다 4배, 200×200은 16배이므로
 장치별 실제 GPU timing을 UI에 표시하고 목표 frame budget에 맞춰 해상도를 제한한다. 정확한 성능과
 메모리는 대표 GPU에서 benchmark하여 기록하며 이론치만으로 약속하지 않는다.
 
+실측·반복 분석용 CPU 계획은 거리 행렬, bin calibration, 임시 map과 허용되는 steering matrix를
+재사용한다. 192채널·50×50·2 bins를 10회 분석하는 기준에서 거리 계산은 4,800,000회에서
+480,000회, steering pair는 9,600,000회에서 960,000회로 줄어든다. snapshot working set과 계획은
+512 MiB, steering cache는 64 MiB, streaming input은 256 MiB 기본 hard cap을 할당 전에 적용한다.
+Streaming ring은 backlog에서 가장 오래된 sample을 버리고 호출당 결과 수를 제한한다.
+각 portable 분석은 `processingTimeMs`를 기록하고 streaming은 hop 기반
+`deadlineMet`, `deadlineMisses`와 `droppedSamples`로 실제 장치의 지속
+처리 가능 여부를 측정한다. cache 수치만으로 실시간성을 보장하지 않는다.
+
 ## 5. UI 계획
 
-`acoustic-camera`는 폭 600px 이상인 좌측 scene canvas에 기기 이미지, ground-truth hint,
-주파수별 acoustic overlay를 표시한다. 우측에는 배열 geometry를 좌표와 함께 정적 평면도로
-표시하고 그 아래에 제어 패널을 둔다. 작은 화면에서는 두 열을 세로로 쌓는다. 확대·회전 상호작용은
-향후 필요성 검증 뒤 추가한다.
+`acoustic-camera`는 **입력 → 설정 → 실행 → 확인**의 고정 작업 순서를 먼저 보여준다. 실행은
+정지 장면의 Snapshot과 trajectory의 Moving 카드로 나뉘며, 결과 canvas를 주 작업 영역으로 둔다.
+Scene·Array·Experiment·Assets 준비 상태와 실행 가능 여부를 가까이 표시하고, 비교 기록과 저장
+기능은 필요할 때 펼치는 보조 영역으로 내린다. 작은 화면에서는 한 열로 쌓는다.
 
-필수 입력은 음원 수와 위치, AC 거리, 다중 주파수 구간과 색, ambient 파일, scan grid 크기,
-후처리 선택이다. 여기에 sample rate, 음속/온도, STFT window·hop, scan 영역, dynamic range,
-colormap/opacity, 음원별 gain·시작 시간, random seed, 정규화 방법을 추가한다. 잘못된 단위,
-Nyquist 초과 대역, WebGPU buffer 한도는 실행 전에 검증한다.
+일상적으로 바꾸는 backend, grid, 대역과 peak 감도는 설정 단계에 유지한다. 음속, seed, scan
+범위, STFT, 음향 환경 preset과 마이크 응답 보상은 **고급 설정**에 묶는다. 장문의 개발 요구나
+미구현 기능 홍보는 작업 화면에서 제거하고, 물리 모델·데이터 계약·포팅 설명은 문서로 연결한다.
+잘못된 단위, Nyquist 초과 대역, room 포함 관계와 CPU/GPU·신호 working-set 한도는 실행 전에
+검증한다.
 
 ## 6. 평가 방법
 
@@ -158,26 +178,31 @@ flattening이 모델 타당성을 훼손하는지 청취 및 spectrum 통계로
 
 완료 조건: 사용자가 코드 수정 없이 배열 JSON 두 개를 같은 장면에서 비교할 수 있다.
 
-### 단계 5 — 실제 데이터와 고도화 · 향후
+### 단계 5 — 현실성·포팅과 실제 데이터 · 부분 완료
 
-- 라이선스 검토를 통과한 DCASE/MIMII adapter와 batch workflow 추가
-- microphone calibration·noise 모델 검토
-- 실제 192채널 장치의 channel/clock/sample 형식이 정해진 뒤 capture·stream adapter 추가
-- 필요 시 DAMAS/CLEAN-SC를 플러그인형 후처리로 추가
-- image-source method 또는 room impulse response 기반 잔향 모듈 추가
+- [x] 마이크별 gain·phase·frequency-response 합성 및 선택적 DAS 역보정
+- [x] 자유음장을 보존하는 선택형 shoebox 1차 반사·scattering·회절·RT60 tail
+- [x] Scene 합성에서 분리한 block/streaming multichannel 위치추정 API
+- [x] 반복 거리·calibration·steering cache, bounded ring과 메모리 hard cap
+- [ ] 라이선스 검토를 통과한 DCASE/MIMII adapter와 batch workflow
+- [ ] 실제 장치의 channel/clock/sample 형식에 맞춘 capture·transport adapter와 현장 검증
+- [ ] 필요 시 센서 self-noise·위치 공차와 DAMAS/CLEAN-SC 후처리
 
-완료 조건: 자유음장 결과를 훼손하지 않고 propagation model을 선택해 재실행할 수 있다.
+현재 완료 조건은 기존 자유음장 결과를 유지한 채 propagation model과 응답 보상을 선택해
+재실행하고, 같은 CPU DAS를 실측 `Float32Array` channel에 직접 적용하는 것이다. 실제
+hardware deadline과 정확도는 장치 adapter가 정해진 뒤 별도 측정한다.
 
 ## 9. 주요 위험과 대응
 
 - WebGPU 미지원/장치 한도: 시작 시 capability를 표시하고 CPU fallback 및 grid 상한을 둔다.
 - 좌표·phase 부호 오류: analytic tone test와 배열 대칭성 test를 먼저 만든다.
-- 브라우저 메모리: snapshot은 전체 192채널 signal buffer에 512 MiB 한도를 적용하고, 이동
-  미리보기는 최대 48개·2,500 points의 짧은 시간창으로 제한한다. 실제 장시간 capture는 향후
-  chunk/STFT streaming backend로 확장한다.
+- 브라우저 메모리: snapshot signal·최대 sparse delay FFT에 512 MiB 한도를 적용하고, 이동
+  미리보기는 최대 48개·2,500 points의 짧은 시간창으로 제한한다. 장시간 입력은 256 MiB 기본
+  한도의 fixed ring streaming core에서 처리하고 overload의 `droppedSamples`를 감시한다.
 - 데이터셋 부적합/라이선스: 로컬 asset 계약을 유지하고 synthetic fixture를 기본 test 입력으로
   쓴다. 실제 데이터 adapter는 단계 5의 라이선스 검토 뒤 추가한다.
-- 실제 AC와 simulation gap: 감도, 위상, 위치 오차를 이후 calibration/noise model로 주입 가능하게 한다.
+- 실제 AC와 simulation gap: gain·phase·주파수 응답과 희소 실내 환경을 비교 조건으로 제공하되,
+  위치 공차·self-noise·ADC·clock은 실측 adapter와 현장 검증으로 다룬다.
 - post-processing이 기본 결과를 가림: raw DAS map과 후처리 map을 항상 별도로 보존한다.
 
 ## 10. 구현 결과와 다음 백로그
@@ -193,11 +218,16 @@ flattening이 모델 타당성을 훼손하는지 청취 및 spectrum 통계로
 - [x] 이동 trajectory 계약·편집·시간창 합성·Camera 라이브 재생
 - [x] 비확률 beam spread RMS contour와 Result export
 - [x] 복수 음원용 Experiment peak 검출 감도
+- [x] 마이크 주파수 응답 합성·CPU/WebGPU 역보정 비교
+- [x] 자유음장·shoebox 희소 반사/산란/회절/RT60 환경 선택
+- [x] portable block/streaming localizer와 반복 DAS cache·메모리 상한
+- [x] Camera 입력→설정→실행→확인의 Snapshot/Moving UI 재구성
 - [x] `test.cmd` one-command headless browser 검증
 - [ ] DCASE/MIMII 라이선스 검토와 adapter
-- [ ] 실제 192채널 capture/stream adapter
-- [ ] 잔향·calibration·noise model
+- [ ] 실제 192채널 capture/transport adapter와 deadline·정확도 검증
+- [ ] 센서 self-noise·위치 공차·지향성 모델
 - [ ] DAMAS/CLEAN-SC 후처리
 
-정확성 test를 먼저 통과시킨 뒤 UI 또는 최적화를 진행한다는 원칙은 유지한다. 단계 5 기능은
-자유음장 DAS 결과를 바꾸지 않는 선택형 확장으로 추가한다.
+정확성 test를 먼저 통과시킨 뒤 UI 또는 최적화를 진행한다는 원칙은 유지한다. 추가 현실성 모델은
+자유음장 DAS 결과를 바꾸지 않는 선택형 확장으로, 장치 연결은 portable localizer 앞의 adapter로
+추가한다.