docs: guide acoustic modeling and realtime porting

docs/data-contracts.md

@@ -18,8 +18,17 @@ scene JSON에는 192채널 원시 sample이나 원본 asset byte를 넣지 않
 `sha256` manifest로 참조한다. 사용자 컴퓨터의 절대 경로, URL, `..` 경로는 저장하지 않는다.
 
 array의 `sensitivityDb`와 `phaseOffsetDeg`는 각 마이크 수신 channel에 적용되는 편차다. 합성기는
-이를 신호에 주입하고, beamformer는 알려진 calibration 값의 역 gain/phase를 적용한다. 따라서
-두 값이 0이 아닌 배열도 오류 없이 조용히 무시되지 않는다.
+이를 신호에 주입하고, beamformer는 알려진 calibration 값의 역 gain/phase를 적용한다. 선택적
+`frequencyResponse`는 2–64개의 `{ frequencyHz, gainDb, phaseDeg? }` 측정점이다.
+주파수는 0–1,000,000 Hz에서 중복 없이 증가해야 하며, dB와 wrapped phase를 구간 선형 보간하고
+측정 범위 밖에서는 가까운 끝점을 사용한다.
+
+Experiment의 선택적 `beamforming.compensateFrequencyResponse`는 기본 `true`다. 합성
+channel에는 curve가 항상 적용되며, `true`이면 CPU/WebGPU DAS가 선택 bin에서 curve의
+역 gain/phase도 적용한다. `false`이면 sensitivity/phase calibration은 유지하고 curve
+역보정만 끈다. 선택적 `beamforming.maxCompensationDb`는 응답 notch의 역보정에서 양의
+gain boost만 제한하는 0–120 dB 값이며 생략 시 24 dB다. 응답 peak를 줄이는 attenuation과
+phase 보상은 이 boost 상한을 그대로 적용하지 않는다.
 
 ## 로컬 asset 재연결
 
@@ -45,6 +54,26 @@ Camera 라이브 미리보기는 sample 경계에 맞춘 시간창 중앙에서
 창으로 Scene 시간을 다시 기준화해도 tone 위상, noise sample index와 audio asset 재생 위치는 원래
 절대 시간에 이어진다. 이는 준정적 근사이며 Doppler를 계약하지 않는다.
 
+## 음향 환경
+
+Scene의 선택적 `acoustics.model`은 `free-field` 또는 `shoebox`다. 필드를
+생략한 문서는 free-field로 해석해 이전 직접음 결과를 유지한다. free-field에는 사용되지 않는
+`room`, `reflections`, `diffuseReverb` 또는 `occluders`를 함께 둘 수 없다.
+
+shoebox에는 `room.min`과 `room.max`가 필요하다. 각 축에서 min은 max보다 작아야 하며
+정적 source와 모든 trajectory keyframe은 room 안에 있어야 한다. `reflections.order`는
+0 또는 1이고, `wallGainDb`와 선택적 면별 `perWallDb`는 -60–0 dB,
+`scattering`은 0–1이다.
+
+`diffuseReverb`는 `enabled`, 0.05–5 s의 `rt60Seconds`, -60–0 dB의
+`gainDb`와 1–32의 `tapCount`를 갖는다. 축 정렬 `occluders`는 최대 8개이며
+room 안의 min/max, 고유 id, -120–0 dB의 `transmissionDb`와
+`diffractionGainDb`를 갖는다.
+
+이 계약은 직접음, 여섯 면의 1차 image-source, 결정적 scattering, 막힌 occluder별 최단 corner
+우회와 제한된 RT60 tail을 위한 것이다. 재질 mesh나 고차 room impulse response 계약은 아니다.
+세부 계산과 preset은 [음향 환경과 마이크 응답 모델](acoustic-model.md)에 설명한다.
+
 ## 오디오와 map 정규화
 
 `scene.mix.normalization`은 마이크 신호 합성 전에 적용할 오디오 mix 정책이다. `none`은 원래
@@ -81,6 +110,11 @@ threshold와 최소 거리, sidelobe 제외 반경, half-power 비율, dynamic r
 버전과 함께 저장한다. `environment`에는 실제 backend, microphone/grid 수, scan bounds와 z,
 가능한 경우 GPU adapter 및 fallback 정보를 기록한다.
 
+`signalStats`는 정규화 전 peak, scale과 clipping 수 외에 선택적으로
+`acousticModel`, 실제 전체 `acousticPathCount`와 `acousticPathCounts`를
+기록한다. 종류별 key는 `direct`, `reflection`, `scattering`,
+`diffraction`과 `diffuse`다.
+
 대역별 ground truth는 tone의 주파수가 band 안에 있을 때 그 tone source를 포함한다. noise와
 asset source는 현재 모든 band의 truth로 간주한다. 즉 녹음 asset의 실제 spectrum energy를
 대역별로 판정하는 계약은 아직 없으며, 이 가정은 실제 데이터 결과를 해석할 때 고려해야 한다.
@@ -100,8 +134,19 @@ SHA-256을 계산해 scene의 해당 asset `sha256` 필드를 채운 상태로 c
 - 중복 id와 array/scene/experiment/result 참조
 - asset 종류와 안전한 상대 경로
 - Nyquist 및 시간·scan 범위
+- 마이크 주파수 응답점의 범위·정렬과 shoebox room/occluder 포함 관계
 - map shape와 source peak 매칭
 - band별 evaluation 파라미터와 허용 metric
-- 현재 비스트리밍 CPU backend의 512 MiB channel-buffer 예산
+- Snapshot channel·최대 sparse delay FFT working set의 512 MiB 예산
 
 지원하지 않는 schemaVersion은 묵시적으로 변환하지 않고 오류로 알린다.
+
+실측 channel을 받는 portable API는 저장 JSON 계약과 별도로 입력 Array를 같은 규칙으로 검사한다.
+CPU 분석 계획은 기본 512 MiB, 반복 steering cache는 64 MiB, streaming ring과 분석창은 기본
+256 MiB hard cap을 할당 전에 적용한다. 채널 순서와 streaming 상태 계약은
+[실측 다채널 위치추정 코어 포팅](realtime-porting.md)을 참고한다.
+
+portable block 결과의 `processingTimeMs`는 DAS와 local-peak 검출 wall time이다. Streaming
+결과는 `deadlineMs`와 `deadlineMet`을 추가하고 상태에는 최근·최대 처리 시간,
+`deadlineMisses`와 `droppedSamples`를 누적한다. 이 runtime telemetry는
+`micarrsim.result` 저장 스키마의 필수 필드가 아니다.