micarrsim/apps/acoustic-camera

Acoustic Camera

Scene과 마이크 배열로 자유음장 또는 저비용 shoebox microphone signal을 합성하고, STFT와 DAS·DAS-PHAT·GCC-PHAT 위치추정으로 주파수 대역별 acoustic map과 ground-truth 평가 지표를 만드는 브라우저 앱입니다. 정지 장면은 Snapshot, trajectory 장면은 Moving 흐름으로 분리되어 있습니다.

열기와 Snapshot

저장소의 start.cmd를 실행한 뒤 시작 화면에서 Acoustic Camera를 선택하거나 http://127.0.0.1:4173/apps/acoustic-camera/을 엽니다. index.html을 직접 열지 마세요.

가장 빠른 확인 방법은 다음과 같습니다.

1. 기본 fixture가 준비될 때까지 기다립니다.
2. 192채널 rectangular 배열, single-tone scene과 50×50 grid를 그대로 둡니다.
3. 상단 작업 순서에서 입력·설정 상태를 확인한 뒤 Snapshot 카드의 ▶ Snapshot 실행을 누릅니다.
4. 완료 후 overlay, 위치 오차와 timing을 확인하고 Result JSON을 저장합니다.

이동 장면을 바로 보려면 Moving 카드에서 이동 예제 열기 → Map 준비 → 재생 순서로 누릅니다. 이동 예제는 24×18 grid와 2 Hz map rate를 사용해 CPU fallback에서도 준비량을 줄였습니다.

사용자 입력 불러오기

문서는 다음 순서로 불러오는 것이 안전합니다.

1. Scene: .scene.json
2. Array: 선택 사항인 .array.json; 또는 비교 배열 preset 사용
3. Experiment: 선택 사항인 .experiment.json
4. Assets: Scene이 참조하는 원본 이미지와 오디오

Scene을 불러오면 현재 Experiment의 sceneId와 scan plane을 Scene에 맞추고 기존 asset 연결을 해제합니다. Array를 불러오면 현재 Experiment의 arrayId를 맞춥니다. 별도 Experiment는 현재 Scene과 Array를 참조해야 하므로 마지막에 불러오세요.

Scene JSON에는 원본 파일 byte가 없습니다. Assets에서 Builder에 사용한 파일을 다시 선택하면 Camera가 SHA-256을 계산해 manifest에 연결합니다. 같은 이름이라도 내용이 바뀌면 거절됩니다. 브라우저를 다시 열거나 Scene을 바꿀 때도 재선택해야 합니다.

• asset 한 파일: 최대 128 MiB
• 연결된 asset 합계: 최대 512 MiB
• decode되어 메모리에 유지되는 오디오 합계: 최대 192 MiB

파일은 외부로 업로드되지 않고 브라우저 메모리에서만 처리됩니다.

위치 추정 알고리즘과 Backend

분석 설정 → 위치 추정 알고리즘에서 다음 세 구현을 선택합니다.

• DAS: 채널 진폭과 위상을 유지해 coherent sum power를 계산하는 기준선입니다. CPU와 WebGPU를 지원하고 rawMap.scale은 power입니다.
• DAS-PHAT: 각 STFT 성분의 크기를 정규화하고 위상을 합산합니다. 채널 gain 차이에 덜 민감한 비교용이며 CPU와 WebGPU를 지원합니다. 결과는 무차원 score입니다.
• GCC-PHAT: 기준 마이크와 나머지 마이크의 PHAT 상관에서 기하학적 TDOA를 평가합니다. 현재 CPU 전용이므로 Auto는 CPU를 선택하고 WebGPU 강제는 선택할 수 없습니다. 각 band가 8개 미만의 FFT bin을 포함하면 협대역 상관이 불안정할 수 있다는 경고가 표시됩니다.

PHAT score는 위치 확률이나 음향 power가 아닙니다. 세 알고리즘 모두 같은 scan grid에 응답 map을 만들지만, 진폭 보존 여부와 실패 양상이 다르므로 같은 Scene·Array·band로 비교하세요. GCC-PHAT raw score는 pair·band coefficient·IFFT 크기를 정규화한 0–1 양의 상관 응답이라 scan 범위나 마이크 수에 따른 단순 scale 변화는 피하지만, 확률이나 다른 알고리즘과 공통인 confidence는 아닙니다.

• Auto (GPU→CPU): 권장. WebGPU를 먼저 시도하고 adapter/device 부재나 지원되는 장치 한계가 있으면 CPU로 계속합니다. 라이브 준비에서는 첫 fallback 뒤 남은 frame이 같은 CPU analysis plan을 재사용하므로 GPU 실패를 매 frame 반복하지 않습니다. GCC-PHAT에서는 **Auto (CPU)**로 표시됩니다.
• WebGPU 강제: DAS와 DAS-PHAT를 GPU에서만 실행하며 운용 오류가 나도 CPU로 fallback하지 않습니다.
• CPU 강제: 선택한 알고리즘의 CPU 수치 기준이나 WebGPU가 없는 환경에서 사용합니다.

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를 넣을 수 있습니다.

{
  "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 위치추정과 DAS/DAS-PHAT WebGPU 경로에서 알려진 gain/phase를 역보정합니다. 측정 curve 적용 + 보정하지 않음은 합성 응답은 유지하고 역보정만 꺼서 영향을 비교합니다. curve가 없는 마이크는 기존 결과를 유지합니다. 응답 notch를 과도하게 증폭하지 않도록 역보정의 양의 gain boost는 기본 24 dB로 제한하며, 사용자 Experiment JSON의 beamforming.maxCompensationDb에서 0–120 dB로 지정할 수 있습니다.

모델 수식, preset 값, Scene/Array/Experiment 예와 제외 범위는 음향 환경과 마이크 응답 모델을 참고하세요.

Grid, STFT와 대역

50×50은 2,500 points입니다. 이를 1로 보면 100×100은 4배, 200×200은 16배 points를 계산합니다. 처음에는 50×50을 권장합니다. 연산량 줄에는 공통 STFT transform 수와 signal path, distance cache를 표시하고 알고리즘별 위치추정 비용을 다음처럼 분리합니다.

• DAS/DAS-PHAT: scan point × microphone × STFT frame × 선택 bin의 complex MAC
• GCC-PHAT: 기준 마이크 pair별 two-pass cross-spectrum, pair × band inverse FFT와 scan point × pair × band correlation lookup

이는 구현 연산 횟수이지 실행 시간 예측값은 아닙니다. scene 길이, microphone 수, FFT/hop, band 수와 폭, grid 및 CPU/GPU에 따라 실제 시간이 달라집니다.

각 band는 id, 최소/최대 Hz와 overlay 색을 가집니다. Nyquist를 넘거나 겹치는 id 등 계약 오류는 실행 전에 표시됩니다. DAMAS와 CLEAN-SC 후처리는 아직 구현하지 않았으며, 실행할 수 없는 비활성 항목은 Camera UI에서 제거했습니다. Result의 processedMaps 계약만 향후 확장을 위해 남아 있습니다.

**Peak 검출 임계값 (%)**은 최강 local peak의 map 값에 대한 상대 임계값이며 Experiment JSON에 저장됩니다. 기본 25%에서 약한 두 번째 음원이 빠지면 10–20%로 낮추세요. 낮은 값은 더 약한 후보를 살리는 대신 sidelobe를 음원으로 잘못 고를 가능성도 높입니다. 같은 대역의 두 음원이 알고리즘의 main lobe 폭보다 가깝다면 grid만 키우거나 threshold를 낮춰도 하나로 합쳐질 수 있습니다.

화면과 배열·알고리즘 비교

• acoustic overlay의 투명도와 표시할 band를 선택할 수 있습니다.
• Ground truth를 켜면 source 위치와 검출 peak를 비교할 수 있습니다.
• 빔 분포는 DAS power의 half-power 또는 PHAT score의 half-maximum 연결 성분을 해당 map 값으로 가중한 공분산으로 계산해 1× RMS 점선과 2× RMS 영역으로 표시합니다. 위치 확률, Gaussian 신뢰구간 또는 측정 불확실성 보정값은 아닙니다.
• 배열 선택에는 채널 수(4·12·48·192·384), aperture 크기(0.12·0.45·1.20 m), rectangular와 Fermat spiral 배치를 분리 비교하는 8개 preset이 있습니다. 같은 scene·scan·STFT에서 연속 실행하면 비교 기록에 배열, 알고리즘, 실제 backend, 위치추정/전체 timing과 평가 요약이 함께 남습니다.
• 입력을 바꾼 뒤 화면에 남은 결과는 이전 실행 snapshot이며 UI가 이전 설정 결과임을 표시합니다.
• Camera에서 거리·음속·seed를 바꾼 Scene과 scan·STFT·band를 바꾼 Experiment는 우측의 각 JSON 저장 버튼으로 보존할 수 있습니다.
• 전체 기록 JSON은 세션에 남은 배열·알고리즘·backend 비교 요약을 micarrsim.comparison-history 문서로 저장합니다.

미저장 Scene·Experiment·Result·비교 기록은 우측 저장 상태에 표시됩니다. 직전 Result를 저장하지 않고 새 실행을 시작하면 교체 여부를 확인하며, 미저장 항목이나 실행 중 계산이 있는 상태에서 페이지를 닫으면 브라우저가 한 번 더 확인합니다.

이동 음원 라이브

Scene source에 두 개 이상의 trajectory keyframe이 있으면 Map 준비가 활성화됩니다. Builder에서는 시간에 따라 음원 이동과 경로 미리보기 slider로 이 데이터를 만들 수 있습니다.

1. 알고리즘, Map rate와 backend를 선택합니다. 처음에는 DAS, 2 Hz와 Auto를 권장합니다.
2. Map 준비를 누릅니다. 현재 입력 snapshot을 최대 48개, map당 최대 2,500 points의 짧은 분석창으로 계산합니다.
3. 재생 또는 시간 slider로 이동합니다. Heatmap은 이웃한 acoustic map 사이를 보간하고 source 위치는 keyframe 사이를 연속 보간합니다.

각 시간창은 sample 경계에 맞추며 tone 위상, 결정적 noise index와 audio asset의 재생 위치를 원래 Scene 시간에 이어 붙입니다. 한 창 안에서는 중앙 시각의 위치를 고정하는 준정적 근사이므로 Doppler, 창 내부 연속 경로 변화와 실제 마이크 스트림은 지원하지 않습니다. 실제 192채널 장치를 연결하려면 장치의 channel 순서, sample 형식, clock와 전송 API에 맞춘 capture adapter가 별도로 필요합니다.

Result JSON

Result JSON은 검증을 통과한 micarrsim.result 문서만 저장합니다.

• experimentId, arrayId, sceneId, createdAt, 실제 algorithm과 backend
• 실행 입력 전체의 canonical SHA-256인 inputHash
• signalStats: 정규화 전 peak, 적용 scale, clipped sample 수, 실제 음향 모델과 sparse path 전체·종류별 수
• timingMs: 전체, signal generation과 localization; 기존 소비자 호환용 beamforming은 같은 위치추정 시간을 담는 alias
• band별 rawMap: DAS는 선형 power, PHAT 계열은 무차원 score; 화면용 displayMap과 검출 peaks
• 각 peak의 비보정 half-power/half-maximum 공분산과 RMS ellipse인 beamSpread
• 평가 설정과 peakToSidelobeDb, energyInsideTruthRatio, precision, recall, mainLobeWidthM

Tone source는 그 주파수가 band 범위 안에 있을 때만 해당 band의 ground truth입니다. Audio asset과 noise source는 스펙트럼을 사전에 판별하지 않으므로 모든 band의 ground truth로 평가합니다. Source z가 scan z와 다르면 평면에 투영한 x/y를 사용하므로 UI 경고와 위치 오차를 함께 해석하세요.

해석 한계

신호 모델은 직접 경로의 자유음장과 선택적인 shoebox 희소 근사입니다. shoebox는 1차 반사, deterministic scattering, 축 정렬 occluder의 직접음 감쇠·최단 corner 우회 회절과 제한된 RT60 tail을 포함합니다. 파동 방정식, 고차 반사, 재질별 주파수 의존 흡음, 복잡한 mesh, 바람, Doppler, 센서 self-noise·비선형, ADC·clock과 장착 구조는 포함하지 않습니다. 배열 JSON의 sensitivity/phase/frequency-response calibration은 적용하지만 결과는 상대 배열 비교와 알고리즘 검증용이며 실측 인증을 대신하지 않습니다.

실제 동기식 microphone Float32Array를 Scene 합성 없이 위치추정하려면 실시간 위치추정 코어 포팅의 createLocalizationPlan, localizeMultichannel 또는 createStreamingLocalizer를 사용하세요. portable config의 algorithm으로 같은 세 위치추정을 선택할 수 있습니다. 실시간성은 장치에서 processingTimeMs <= deadlineMs와 deadlineMisses·droppedSamples를 측정해 판정해야 합니다.

WebGPU 성능을 별도로 측정하려면 서버 실행 후 http://127.0.0.1:4173/benchmarks/webgpu-scaling.html을 여세요.