docs: guide acoustic modeling and realtime porting

README.md

@@ -1,6 +1,6 @@
 # micarrsim
 
-192채널 MEMS 마이크 배열의 배치와 자유음장 DAS 음향 영상을 비교하는 로컬 브라우저
+192채널 MEMS 마이크 배열의 배치와 자유음장·저비용 실내 근사에서의 DAS 음향 영상을 비교하는 로컬 브라우저
 시뮬레이터입니다. Dataset Builder에서 녹음 파일·합성 신호와 이동 경로를 포함한 재현 가능한
 음향 장면을 만들고 Acoustic Camera에서 CPU 또는 WebGPU로 배열 응답, acoustic map과 위치 검출
 지표를 계산하거나 이동 장면을 시간축으로 재생합니다.
@@ -46,7 +46,7 @@ powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\scripts\serve.
 1. 시작 화면에서 **Acoustic Camera**를 엽니다.
 2. 기본 192채널 rectangular 배열, single-tone scene과 50×50 experiment가 준비될 때까지
    기다립니다.
-3. **기본 예제 실행**을 누릅니다.
+3. Snapshot 카드의 **▶ Snapshot 실행**을 누릅니다.
 4. 계산이 끝나면 overlay와 평가 지표를 확인하고 **Result JSON**을 누릅니다.
 
 실제 완료 시간은 브라우저와 장치에 따라 다릅니다. CPU fallback에서는 WebGPU보다 오래 걸릴 수
@@ -54,8 +54,8 @@ powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\scripts\serve.
 
 ### 이동 음원 바로 보기
 
-1. Acoustic Camera에서 **이동 예제**를 누릅니다.
-2. **라이브 준비**를 눌러 2 Hz acoustic map을 계산합니다.
+1. Acoustic Camera에서 **이동 예제 열기**를 누릅니다.
+2. Moving 카드의 **Map 준비**를 눌러 2 Hz acoustic map을 계산합니다.
 3. **재생**을 누르거나 시간 slider를 움직여 음원과 heatmap의 이동을 확인합니다.
 
 이 기능은 trajectory가 있는 합성 Scene의 준정적 시간창 재생입니다. 실제 192채널 마이크 장치에서
@@ -118,6 +118,23 @@ WebGPU 경로도 신호 합성과 STFT 일부는 CPU에서 수행합니다. grid
 100×100은 4배, 200×200은 16배입니다. 처음에는 50×50을 사용하고 해상도가 필요할 때만 높이세요.
 실행 시간은 microphone 수, scene 길이, FFT, 대역 폭과 장치에 함께 좌우됩니다.
 
+## 음향 환경과 마이크 응답
+
+Camera의 **고급 설정**에서 자유음장, 흡음된 실내, 일반 실내와 반사 강한 실내를 선택할 수
+있습니다. 실내 preset은 현재 Array·Scene·scan을 감싸는 shoebox room을 만들고 직접음에 다음의
+희소 경로를 추가합니다.
+
+- 여섯 면의 1차 image-source 반사와 결정적 scattering
+- 축 정렬 occluder의 직접음 감쇠와 최단 corner 우회 회절
+- RT60·gain·tap 수로 제한한 deterministic diffuse tail
+
+각 마이크의 Array JSON에는 선택적 `frequencyResponse` 측정 curve를 넣을 수 있습니다.
+합성기는 curve를 수신 채널에 적용하고, 기본 DAS는 알려진 curve를 역보정합니다. **마이크 주파수
+응답 처리**를 보정하지 않음으로 바꾸면 같은 curve를 합성에만 적용해 robustness를 비교합니다.
+응답 notch의 양의 역보정 boost는 기본 24 dB로 제한합니다.
+필드, preset별 경로 예산과 물리적 한계는
+[음향 환경과 마이크 응답 모델](docs/acoustic-model.md)에 정리되어 있습니다.
+
 ## 위치 추정, 빔 분포와 복수 음원
 
 DAS 출력은 각 scan point의 상대 acoustic power map이며 위치 확률분포가 아닙니다. Camera는 map의
@@ -143,13 +160,22 @@ index와 audio asset 재생 위치가 이어지도록 신호를 합성합니다.
 - 모델: 준정적 위치 변화이며 Doppler와 창 내부의 연속 전파 경로 변화는 포함하지 않음
 - 실제 장치: 물리 192채널 capture/stream gateway는 하드웨어 형식이 정해진 뒤 별도 adapter가 필요
 
+Scene 합성 없이 동기식 `Float32Array` 마이크 채널을 바로 처리하는
+`createLocalizationPlan`, `localizeMultichannel`과 `StreamingDasLocalizer`가
+`packages/acoustics-core`에 분리되어 있습니다. 고정 ring buffer, oldest-first drop,
+반복 geometry·steering cache와 `AbortSignal` 취소를 제공하며 실제 capture 장치에는
+channel/clock/transport adapter만 별도로 연결합니다. 실시간 여부는 각 결과의
+`processingTimeMs <= deadlineMs`와 누적 `deadlineMisses`·`droppedSamples`로
+해당 장치에서 확인합니다. 복사할 파일과 운용 계약은
+[실측 다채널 위치추정 코어 포팅](docs/realtime-porting.md)을 참고하세요.
+
 ## Result JSON
 
 Result JSON은 계약 버전 `1.0.0`의 `micarrsim.result` 문서입니다. 주요 내용은 다음과 같습니다.
 
 - 실행한 `experimentId`, `arrayId`, `sceneId`, 실제 `backend`와 생성 시각
 - Array·Scene·Experiment의 canonical SHA-256인 `inputHash`
-- 정규화 전 peak, 적용 scale과 clipping 수를 담은 `signalStats`
+- 정규화 전 peak, 적용 scale, clipping 수와 음향 모델·희소 경로 수를 담은 `signalStats`
 - 전체·신호 생성·beamforming 시간인 `timingMs`
 - 주파수 대역별 선형 power `rawMap`, 표시용 `displayMap`, 검출 `peaks`
 - 위치 오차, precision/recall, truth 반경 내 energy, peak-to-sidelobe, main-lobe 폭을 계산하기
@@ -166,10 +192,12 @@ noise source는 스펙트럼을 미리 알 수 없으므로 모든 band의 groun
 않습니다. 선택한 파일은 브라우저 메모리에서 읽으며 생성한 JSON/WAV는 브라우저 다운로드로만
 저장됩니다.
 
-현재 음향 모델은 직접 경로와 거리 감쇠를 사용하는 자유음장 모델입니다. 반사, 잔향, 회절,
-차폐, 바람, 실제 MEMS 비선형과 장착 구조는 모델링하지 않습니다. Beamformer는 conventional
-DAS이며 UI의 DAMAS와 CLEAN-SC는 아직 사용할 수 없습니다. 따라서 결과는 배열·grid·대역의 상대
-비교와 소프트웨어 검증용이며, 현장 성능 인증이나 안전 판단을 대신하지 않습니다.
+음향 모델은 직접 경로의 자유음장과 1차 반사·scattering·occluder 회절·RT60 tail을 제한된
+경로로 계산하는 shoebox 근사를 제공합니다. 파동 방정식, 고차 반사, 재질별 주파수 의존 흡음,
+복잡한 mesh 회절, 바람, Doppler, 마이크 self-noise·비선형, ADC와 channel clock은 모델링하지
+않습니다. Beamformer는 conventional DAS이며 UI의 DAMAS와 CLEAN-SC는 아직 사용할 수 없습니다.
+따라서 결과는 배열·grid·대역의 상대 비교와 소프트웨어 검증용이며, 현장 성능 인증이나 안전
+판단을 대신하지 않습니다.
 
 ## 배열 예제
 
@@ -200,6 +228,8 @@ test.cmd
 ## 저장 형식과 개발 문서
 
 - [`docs/data-contracts.md`](docs/data-contracts.md): Array·Scene·Experiment·Result 계약
+- [`docs/acoustic-model.md`](docs/acoustic-model.md): 마이크 응답과 자유음장·shoebox 희소 근사
+- [`docs/realtime-porting.md`](docs/realtime-porting.md): 실측 다채널 위치추정 API 포팅
 - [`schemas/README.md`](schemas/README.md): JSON Schema 구성
 - [`docs/execution-plan.md`](docs/execution-plan.md): 구현 단계와 기술 결정
 - [`goal.md`](goal.md): 프로젝트 목표