micarrsim

192채널 MEMS 마이크 배열의 배치와 자유음장 DAS 음향 영상을 비교하는 로컬 브라우저 시뮬레이터입니다. Dataset Builder에서 녹음 파일·합성 신호와 이동 경로를 포함한 재현 가능한 음향 장면을 만들고 Acoustic Camera에서 CPU 또는 WebGPU로 배열 응답, acoustic map과 위치 검출 지표를 계산하거나 이동 장면을 시간축으로 재생합니다.

별도 프로그램이나 패키지를 설치하지 않습니다. 모든 앱과 계산은 이 저장소와 브라우저 안에서 실행됩니다.

실행 환경

• Windows 10/11
• 최신 Microsoft Edge 또는 Google Chrome
• 저장소에 포함된 Windows PowerShell과 브라우저 외 추가 런타임 불필요
• WebGPU가 없거나 장치를 열 수 없어도 CPU backend로 실행 가능

가장 간단하게 시작하기

1. 저장소 최상위의 start.cmd를 더블클릭합니다.
2. 기본 브라우저에서 micarrsim 시작 화면이 열립니다.
3. 사용을 마치면 함께 열린 콘솔에서 Ctrl+C를 눌러 로컬 서버를 종료합니다.

브라우저가 자동으로 열리지 않으면 http://127.0.0.1:4173/을 직접 여세요. HTML module과 Worker를 사용하므로 index.html 파일을 탐색기에서 직접 열어서는 안 됩니다.

다른 포트를 쓰거나 브라우저를 자동으로 열지 않으려면 명령 프롬프트에서 실행합니다.

start.cmd -Port 4174 -NoBrowser

PowerShell에서 서버를 직접 실행할 수도 있습니다.

powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\scripts\serve.ps1 -Port 4174 -NoBrowser

이 명령의 ExecutionPolicy Bypass는 실행 중인 PowerShell 프로세스에만 적용되며 시스템 정책을 영구 변경하지 않습니다. 해당 명령을 사용했다면 http://127.0.0.1:4174/을 여세요.

실행 후 브라우저용 빠른 시작과 문제 해결은 http://127.0.0.1:4173/docs/에서도 볼 수 있습니다.

30초 기본 예제

1. 시작 화면에서 Acoustic Camera를 엽니다.
2. 기본 192채널 rectangular 배열, single-tone scene과 50×50 experiment가 준비될 때까지 기다립니다.
3. 기본 예제 실행을 누릅니다.
4. 계산이 끝나면 overlay와 평가 지표를 확인하고 Result JSON을 누릅니다.

실제 완료 시간은 브라우저와 장치에 따라 다릅니다. CPU fallback에서는 WebGPU보다 오래 걸릴 수 있습니다.

이동 음원 바로 보기

1. Acoustic Camera에서 이동 예제를 누릅니다.
2. 라이브 준비를 눌러 2 Hz acoustic map을 계산합니다.
3. 재생을 누르거나 시간 slider를 움직여 음원과 heatmap의 이동을 확인합니다.

이 기능은 trajectory가 있는 합성 Scene의 준정적 시간창 재생입니다. 실제 192채널 마이크 장치에서 들어오는 스트림을 캡처하는 기능은 아닙니다.

내 장면으로 전체 흐름 실행하기

1. Dataset Builder에서 Scene 만들기

1. 시작 화면에서 Dataset Builder를 엽니다.
2. 선택적으로 배경 이미지와 오디오를 추가합니다.
3. 녹음 파일은 + 오디오 파일 음원 한 번으로 asset과 source를 함께 만들 수 있습니다. 합성 음원은 별도 버튼으로 추가합니다.
4. canvas 또는 x/y/z 입력으로 위치를 정하고 tone·noise·audio asset과 ambient를 설정합니다.
5. 움직이는 음원은 시간에 따라 음원 이동을 켜고 keyframe과 경로 미리보기 시간을 편집합니다.
6. 상태가 저장 가능한 장면이면 Scene JSON 저장을 누릅니다.

Preview WAV 저장은 source와 ambient를 공간 정보 없이 하나의 mono channel로 합친 청취 확인용 파일입니다. 192채널 마이크 신호나 beamforming 결과가 아닙니다.

2. Acoustic Camera에서 실행하기

1. 홈으로 돌아가 Acoustic Camera를 엽니다.
2. 다음 순서로 입력합니다: Scene → Array → Experiment → Assets.
3. Scene에서 Builder가 저장한 .scene.json을 선택합니다.
4. 기본 배열을 사용하지 않을 때만 Array에서 .array.json을 선택합니다.
5. 별도 실험 문서를 사용할 때만 Experiment에서 .experiment.json을 선택합니다.
6. Scene에 이미지나 audio asset이 있다면 Assets에서 Builder에 사용했던 원본 파일을 다시 선택합니다. 여러 파일을 한 번에 선택할 수 있습니다.
7. 입력 검증이 통과하면 backend와 scan grid를 정하고 실행합니다.
8. 완료 후 Result JSON을 저장합니다.

Array와 Scene을 먼저 불러와야 Experiment의 arrayId와 sceneId 관계를 안전하게 검증할 수 있습니다. Scene을 다시 불러오면 이전 asset 연결은 해제됩니다.

Camera에서 수정한 Scene·Experiment, 완료 Result와 전체 배열 비교 기록은 각각 JSON으로 저장할 수 있습니다. 저장하지 않은 항목이나 실행 중 계산이 있으면 페이지를 닫을 때 브라우저가 확인합니다.

Scene JSON과 로컬 assets

Scene JSON에는 원본 이미지나 오디오 byte가 들어가지 않습니다. 대신 asset id, 종류, 파일명과 SHA-256 manifest를 저장합니다. 브라우저는 새 페이지나 세션에서 로컬 파일 접근 권한을 유지할 수 없으므로 원본 파일을 다시 선택해야 합니다.

• Camera는 SHA-256으로 선택한 파일을 manifest에 다시 연결합니다.
• 같은 이름이라도 내용이 달라 hash가 일치하지 않으면 거절합니다.
• 로컬 asset 한 파일은 최대 128 MiB, 연결된 파일 합계는 최대 512 MiB입니다.
• 실제 decode되어 메모리에 유지되는 오디오 합계는 최대 192 MiB입니다.
• Scene JSON에는 원본 파일명이 기록될 수 있으므로 파일을 외부에 공유하기 전에 확인하세요.

Backend와 scan grid

• Auto (GPU→CPU): 권장값입니다. WebGPU adapter나 device를 사용할 수 없거나 지원되는 장치 한계를 넘으면 CPU로 계속합니다.
• WebGPU 강제: GPU 경로만 사용합니다. 장치를 열 수 없거나 한계를 넘으면 fallback하지 않고 오류를 표시합니다.
• CPU 강제: 비교와 호환성 확인을 위해 CPU DAS만 사용합니다.

WebGPU 경로도 신호 합성과 STFT 일부는 CPU에서 수행합니다. grid의 point 수는 50×50을 1로 보면 100×100은 4배, 200×200은 16배입니다. 처음에는 50×50을 사용하고 해상도가 필요할 때만 높이세요. 실행 시간은 microphone 수, scene 길이, FFT, 대역 폭과 장치에 함께 좌우됩니다.

위치 추정, 빔 분포와 복수 음원

DAS 출력은 각 scan point의 상대 acoustic power map이며 위치 확률분포가 아닙니다. Camera는 map의 local peak를 위치 후보로 표시합니다. 빔 분포를 켜면 각 peak의 연결된 half-power lobe에 대해 power 가중 공분산을 계산해 1× RMS 점선과 2× RMS 영역을 그립니다. Gaussian의 등고선처럼 보일 수 있지만 통계적으로 보정된 Gaussian, 신뢰구간 또는 발생 확률은 아닙니다.

복수 음원은 각각 별도 local peak가 남을 만큼 공간적으로 분리되고 선택 대역에 에너지가 있어야 검출됩니다. **Peak 검출 임계값 (%)**은 최강 peak 대비 후보의 최소 power입니다. 기본 25%에서 약한 두 번째 음원이 빠지면 10–20%로 낮출 수 있지만 sidelobe 오검출도 늘어납니다. 서로 같은 대역에서 main lobe보다 가깝거나 gain 차이가 큰 음원은 conventional DAS의 물리·알고리즘 한계 때문에 threshold만으로 분리되지 않을 수 있습니다.

이동 음원 라이브의 동작

Builder의 trajectory는 Scene 시작 기준 절대 시간의 keyframe 사이를 직선 보간합니다. Camera는 장면을 sample 경계에 맞춘 짧은 시간창으로 나누고, 각 창 중앙의 음원 위치에서 tone 위상, noise index와 audio asset 재생 위치가 이어지도록 신호를 합성합니다. 계산된 map 사이에서는 heatmap을 보간하고 ground-truth 위치는 연속 보간합니다.

• Map rate: 초당 분석 map 목표 수. 높을수록 움직임이 세밀하지만 준비 시간이 늘 수 있습니다.
• 라이브 미리보기 상한: 48 maps, map당 최대 2,500 scan points
• 모델: 준정적 위치 변화이며 Doppler와 창 내부의 연속 전파 경로 변화는 포함하지 않음
• 실제 장치: 물리 192채널 capture/stream gateway는 하드웨어 형식이 정해진 뒤 별도 adapter가 필요

Result JSON

Result JSON은 계약 버전 1.0.0의 micarrsim.result 문서입니다. 주요 내용은 다음과 같습니다.

• 실행한 experimentId, arrayId, sceneId, 실제 backend와 생성 시각
• Array·Scene·Experiment의 canonical SHA-256인 inputHash
• 정규화 전 peak, 적용 scale과 clipping 수를 담은 signalStats
• 전체·신호 생성·beamforming 시간인 timingMs
• 주파수 대역별 선형 power rawMap, 표시용 displayMap, 검출 peaks
• 위치 오차, precision/recall, truth 반경 내 energy, peak-to-sidelobe, main-lobe 폭을 계산하기 위한 평가 파라미터와 metrics
• peak별 half-power 공분산과 RMS ellipse를 담은 beamSpread (calibrated: false)

평가에서 tone source는 tone 주파수가 포함되는 band의 ground truth로만 사용합니다. Audio asset과 noise source는 스펙트럼을 미리 알 수 없으므로 모든 band의 ground truth로 취급합니다. 이 가정은 결과를 실제 데이터와 해석할 때 고려해야 합니다.

개인정보와 모델의 한계

서버는 127.0.0.1 loopback에만 열리고 외부 서비스로 파일을 업로드하거나 telemetry를 보내지 않습니다. 선택한 파일은 브라우저 메모리에서 읽으며 생성한 JSON/WAV는 브라우저 다운로드로만 저장됩니다.

현재 음향 모델은 직접 경로와 거리 감쇠를 사용하는 자유음장 모델입니다. 반사, 잔향, 회절, 차폐, 바람, 실제 MEMS 비선형과 장착 구조는 모델링하지 않습니다. Beamformer는 conventional DAS이며 UI의 DAMAS와 CLEAN-SC는 아직 사용할 수 없습니다. 따라서 결과는 배열·grid·대역의 상대 비교와 소프트웨어 검증용이며, 현장 성능 인증이나 안전 판단을 대신하지 않습니다.

배열 예제

• assets/array-geometries/rectangular-16x12.array.json: 0.45 m 정사각 aperture의 16×12 기준 배열
• assets/array-geometries/fermat-spiral-192.array.json: 0.45 m 원형 aperture의 192채널 Fermat spiral

Camera의 비교 배열 선택으로 두 fixture를 같은 scene과 experiment에서 연속 실행할 수 있습니다. 상세한 생성법은 assets/array-geometries/README.md를 참고하세요.

테스트와 benchmark

최상위 폴더에서 자동 서버·headless 브라우저·정리까지 한 번에 실행하려면 다음을 사용합니다.

test.cmd

서버를 실행한 뒤 다음 주소를 브라우저에서 엽니다.

• 전체 browser test runner: http://127.0.0.1:4173/tests/
• WebGPU scaling benchmark: http://127.0.0.1:4173/benchmarks/webgpu-scaling.html

포트를 바꿨다면 URL의 포트도 같은 값으로 바꾸세요. 테스트 범위는 tests/unit/README.md와 tests/integration/README.md, 기준 실측은 docs/benchmarks/README.md에 설명되어 있습니다.

저장 형식과 개발 문서

• docs/data-contracts.md: Array·Scene·Experiment·Result 계약
• schemas/README.md: JSON Schema 구성
• docs/execution-plan.md: 구현 단계와 기술 결정
• goal.md: 프로젝트 목표

원본 DCASE/MIMII 데이터, 사용자가 선택한 assets와 생성된 대용량 결과는 저장소에 커밋하지 않습니다.

디렉터리 구조

apps/          Dataset Builder와 Acoustic Camera UI
assets/        192채널 배열과 synthetic Scene/Experiment fixture
benchmarks/    현재 브라우저에서 실행하는 WebGPU scaling 측정
docs/          사용자 안내, 데이터 계약, 실행 계획과 기준 실측
packages/      음향 수치 모델, 계약 검증, UI, WebGPU kernel
schemas/       Array·Scene·Experiment·Result JSON Schema
scripts/       무설치 로컬 서버와 fixture 생성기
tests/         브라우저 unit·integration·end-to-end test
start.cmd      Windows 원클릭 실행 진입점