docs: guide acoustic modeling and realtime porting

apps/acoustic-camera/README.md

@@ -1,9 +1,10 @@
 # Acoustic Camera
 
-Scene과 마이크 배열로 자유음장 microphone signal을 합성하고, STFT와 conventional DAS를 통해
-주파수 대역별 acoustic map과 ground-truth 평가 지표를 만드는 브라우저 앱입니다.
+Scene과 마이크 배열로 자유음장 또는 저비용 shoebox microphone signal을 합성하고, STFT와
+conventional DAS를 통해 주파수 대역별 acoustic map과 ground-truth 평가 지표를 만드는 브라우저
+앱입니다. 정지 장면은 Snapshot, trajectory 장면은 Moving 흐름으로 분리되어 있습니다.
 
-## 열기와 기본 예제
+## 열기와 Snapshot
 
 저장소의 `start.cmd`를 실행한 뒤 시작 화면에서 **Acoustic Camera**를 선택하거나
 <http://127.0.0.1:4173/apps/acoustic-camera/>을 엽니다. `index.html`을 직접 열지 마세요.
@@ -12,11 +13,11 @@ Scene과 마이크 배열로 자유음장 microphone signal을 합성하고, STF
 
 1. 기본 fixture가 준비될 때까지 기다립니다.
 2. 192채널 rectangular 배열, single-tone scene과 50×50 grid를 그대로 둡니다.
-3. **기본 예제 실행**을 누릅니다.
+3. 상단 작업 순서에서 입력·설정 상태를 확인한 뒤 Snapshot 카드의 **▶ Snapshot 실행**을 누릅니다.
 4. 완료 후 overlay, 위치 오차와 timing을 확인하고 **Result JSON**을 저장합니다.
 
-이동 장면을 바로 보려면 **이동 예제 → 라이브 준비 → 재생** 순서로 누릅니다. 기본 예제는
-24×18 grid와 2 Hz map rate를 사용해 CPU fallback에서도 준비량을 줄였습니다.
+이동 장면을 바로 보려면 Moving 카드에서 **이동 예제 열기 → Map 준비 → 재생** 순서로 누릅니다.
+이동 예제는 24×18 grid와 2 Hz map rate를 사용해 CPU fallback에서도 준비량을 줄였습니다.
 
 ## 사용자 입력 불러오기
 
@@ -51,6 +52,45 @@ Camera가 SHA-256을 계산해 manifest에 연결합니다. 같은 이름이라
 WebGPU가 감지돼도 실제 장치는 실행 시 확인합니다. 계산 중 **계산 취소**를 누르면 Worker를
 종료하며, 이미 완료된 이전 결과가 있으면 그대로 남습니다.
 
+## 음향 환경과 마이크 주파수 응답
+
+**고급 설정 → 음향 환경**에서 다음 preset을 선택합니다.
+
+- **자유음장 · 직접음만**: 거리 지연과 `1/r` 감쇠의 기준선
+- **흡음된 실내 · 짧은 잔향**: 수신점당 최대 17개 sparse path
+- **일반 실내 · 균형**: 수신점당 최대 19개 sparse path
+- **반사 강한 실내**: 수신점당 최대 23개 sparse path
+
+실내 preset은 현재 마이크, 정적·trajectory source와 scan corner를 포함하도록 직육면체 room을
+자동 추론합니다. 직접음에 여섯 면의 1차 image-source 반사, 결정적 scattering과 tap 수가 제한된
+RT60 diffuse tail을 추가합니다. Scene JSON에 사용자 `shoebox`와 축 정렬
+`occluders`를 넣으면 직접음 감쇠와 최단 corner 우회 회절도 계산합니다. 사용자 설정은
+dropdown에 **Scene 사용자 설정**으로 표시되고 preset 값으로 덮어쓰기 전까지 유지됩니다.
+
+Array의 각 microphone에는 선택적 `frequencyResponse`를 넣을 수 있습니다.
+
+```json
+{
+  "id": "mic-001",
+  "position": [-0.225, 0.225, 0],
+  "frequencyResponse": [
+    { "frequencyHz": 100, "gainDb": -8, "phaseDeg": -12 },
+    { "frequencyHz": 1000, "gainDb": -0.7, "phaseDeg": -2 },
+    { "frequencyHz": 10000, "gainDb": 1.2, "phaseDeg": 8 }
+  ]
+}
+```
+
+curve는 합성 microphone channel에 항상 적용됩니다. **마이크 주파수 응답 처리**의 기본
+**측정 curve 적용 + 위치추정에서 역보정**은 CPU와 WebGPU DAS에서 알려진 gain/phase를
+역보정합니다. **측정 curve 적용 + 보정하지 않음**은 합성 응답은 유지하고 역보정만 꺼서 영향을
+비교합니다. curve가 없는 마이크는 기존 결과를 유지합니다. 응답 notch를 과도하게 증폭하지
+않도록 역보정의 양의 gain boost는 기본 24 dB로 제한하며, 사용자 Experiment JSON의
+`beamforming.maxCompensationDb`에서 0–120 dB로 지정할 수 있습니다.
+
+모델 수식, preset 값, Scene/Array/Experiment 예와 제외 범위는
+[음향 환경과 마이크 응답 모델](../../docs/acoustic-model.md)을 참고하세요.
+
 ## Grid, STFT와 대역
 
 50×50은 2,500 points입니다. 이를 1로 보면 100×100은 4배, 200×200은 16배 points를 계산합니다.
@@ -87,11 +127,11 @@ WebGPU가 감지돼도 실제 장치는 실행 시 확인합니다. 계산 중 *
 
 ## 이동 음원 라이브
 
-Scene source에 두 개 이상의 `trajectory` keyframe이 있으면 **라이브 준비**가 활성화됩니다.
+Scene source에 두 개 이상의 `trajectory` keyframe이 있으면 **Map 준비**가 활성화됩니다.
 Builder에서는 **시간에 따라 음원 이동**과 경로 미리보기 slider로 이 데이터를 만들 수 있습니다.
 
 1. Map rate와 backend를 선택합니다. 처음에는 2 Hz와 Auto를 권장합니다.
-2. **라이브 준비**를 누릅니다. 현재 입력 snapshot을 최대 48개, map당 최대 2,500 points의 짧은
+2. **Map 준비**를 누릅니다. 현재 입력 snapshot을 최대 48개, map당 최대 2,500 points의 짧은
    분석창으로 계산합니다.
 3. **재생** 또는 시간 slider로 이동합니다. Heatmap은 이웃한 acoustic map 사이를 보간하고
    source 위치는 keyframe 사이를 연속 보간합니다.
@@ -107,7 +147,8 @@ Scene 시간에 이어 붙입니다. 한 창 안에서는 중앙 시각의 위
 
 - `experimentId`, `arrayId`, `sceneId`, `createdAt`, 실제 `backend`
 - 실행 입력 전체의 canonical SHA-256인 `inputHash`
-- `signalStats`: 정규화 전 peak, 적용 scale, clipped sample 수
+- `signalStats`: 정규화 전 peak, 적용 scale, clipped sample 수, 실제 음향 모델과 sparse
+  path 전체·종류별 수
 - `timingMs`: 전체, signal generation과 beamforming 시간
 - band별 `rawMap` 선형 power, `displayMap`, 검출 `peaks`
 - 각 peak의 비보정 half-power 공분산과 RMS ellipse인 `beamSpread`
@@ -120,9 +161,19 @@ z가 scan z와 다르면 평면에 투영한 x/y를 사용하므로 UI 경고와
 
 ## 해석 한계
 
-신호 모델은 직접 경로와 거리 감쇠를 사용하는 자유음장입니다. 반사, 잔향, 회절, 차폐, 바람,
-센서 비선형과 장착 구조는 포함하지 않습니다. 배열 JSON의 sensitivity/phase calibration은 적용하지만
-결과는 상대 배열 비교와 알고리즘 검증용이며 실측 인증을 대신하지 않습니다.
+신호 모델은 직접 경로의 자유음장과 선택적인 shoebox 희소 근사입니다. shoebox는 1차 반사,
+deterministic scattering, 축 정렬 occluder의 직접음 감쇠·최단 corner 우회 회절과 제한된 RT60
+tail을 포함합니다. 파동 방정식, 고차 반사, 재질별 주파수 의존 흡음, 복잡한 mesh, 바람, Doppler,
+센서 self-noise·비선형, ADC·clock과 장착 구조는 포함하지 않습니다. 배열 JSON의
+sensitivity/phase/frequency-response calibration은 적용하지만 결과는 상대 배열 비교와 알고리즘
+검증용이며 실측 인증을 대신하지 않습니다.
+
+실제 동기식 microphone `Float32Array`를 Scene 합성 없이 위치추정하려면
+[실시간 위치추정 코어 포팅](../../docs/realtime-porting.md)의
+`createLocalizationPlan`, `localizeMultichannel` 또는
+`StreamingDasLocalizer`를 사용하세요. 실시간성은 장치에서
+`processingTimeMs <= deadlineMs`와 `deadlineMisses`·`droppedSamples`를
+측정해 판정해야 합니다.
 
 WebGPU 성능을 별도로 측정하려면 서버 실행 후
 <http://127.0.0.1:4173/benchmarks/webgpu-scaling.html>을 여세요.