micarrsim/docs/execution-plan.md

# micarrsim 실행 계획

> 구현 상태 · 2026-08-28
>
> 단계 0–4와 단계 5의 저비용 음향 환경·마이크 응답·다중 알고리즘 portable streaming core까지 완료했다.
> 설치 없는 브라우저 앱, CPU/WebGPU DAS·DAS-PHAT와 CPU GCC-PHAT, Builder→Camera asset 재연결, 임의 오디오·이동
> trajectory, 빔 분포·복수 peak 감도, 라이브 시간축 재생, 배열 비교와 Result 내보내기를
> 전체 자동 테스트로 검증했다. 실제 장치 adapter와 현장 검증은 장치 계약이 필요한 후속 범위다.

## 1. 목표와 성공 기준

이 프로젝트는 정방형 평면에 배치할 192개 MEMS 마이크의 배열을 비교하기 위한 재현 가능한
시뮬레이터를 만든다. 기준선은 자유음장(free field), 점 음원과 구면파 전파이며, 같은 입력에서
마이크 응답과 계산량이 제한된 shoebox multipath를 선택해 다음 흐름을 끝까지 수행한다.

1. 기계음 데이터와 ambient audio를 조합해 장면 및 ground truth를 생성한다.
2. 배열 JSON과 장면 정보를 사용해 각 마이크에 도달하는 신호를 합성한다.
3. DAS, DAS-PHAT 또는 GCC-PHAT로 위치 map을 계산하고 같은 입력에서 비교한다.
4. 주파수 구간별 acoustic image를 ground truth 위에 표시하고 정량 평가한다.
5. 배열, 거리, 음원, 주파수, grid 해상도를 바꾼 실험을 저장하고 비교한다.

최소 성공 기준은 192채널, 50×50 scan grid, 단일 및 복수 음원에서 결과를 대화형으로 만들고,
CPU 기준 구현과 GPU 결과의 수치 오차가 합의된 허용 범위 안에 있으며, 동일 seed와 설정으로
실험을 재현할 수 있는 것이다.

## 2. 기술 접근 결정

최종 구현은 빌드 단계와 패키지 설치가 없는 브라우저 네이티브 ES module 2개와 WebGPU/WGSL을
선택했다. 초기 계획의 TypeScript 권고보다 Windows 사용자가 `start.cmd` 하나로 바로 실행하는
목표를 우선한 결정이다. JSON Schema와 브라우저 자동 테스트가 런타임 계약을 보완한다.
브라우저는 배열·장면 편집, 오디오 미리 듣기, 이미지 overlay에 적합하고 WebGPU는
192 × scan point × frequency bin 형태의 병렬 연산에 잘 맞는다. WGSL 커널은 독립 package로
두어 데이터 배치와 수식을 CPU 기준 구현과 대조할 수 있게 했다.

데이터셋 전체를 브라우저에 적재하지 않는다. 사용자가 로컬 파일을 선택해 장면을 만들고,
결과를 manifest와 오디오 파일로 내보내는 방식을 우선 구현한다. 대규모 batch 전처리가 필요해질
때만 동일 스키마를 쓰는 별도 CLI를 추가한다. 이 방식은 초기 복잡도를 줄이면서 확장 경로를
남긴다.

세 앱의 책임은 다음과 같이 분리한다.

- `array-builder`: aperture 크기와 사각/타원 생성 경계, 격자·선형·둘레·Fermat·seed random
  프리셋, 마이크 직접 편집·채널 순서·보정 보존과 표준 Array JSON 내보내기
- `dataset-builder`: 음원 배치, gain/시간 구간/반복 설정, ambient mix, 이미지상의 위치 지정,
  seed 고정, 합성 오디오와 ground truth manifest 내보내기
- `acoustic-camera`: manifest와 배열 JSON 읽기, 마이크 신호 전파 합성, steering vector 생성,
  DAS 실행, overlay·수치 평가·실험 결과 내보내기
- `acoustics-core`: 앱들이 공유하는 좌표계, 단위, 구면 감쇠·희소 multipath·마이크 응답,
  STFT, 정답 rasterization, 지표, CPU reference와 실측 channel용 streaming localizer
- `webgpu-kernels`: steering/DAS 커널, buffer layout, 장치 한도 검사와 benchmark

## 3. 데이터 계약

JSON Schema를 먼저 고정하고 모든 길이는 m, 시간은 s, 주파수는 Hz, 좌표는 우수 좌표계로
명시한다.

- `array.schema.json`: schema version, 배열 폭·높이, 1–1,024개 마이크의 id와 `[x,y,z]`, 선택적
  감도·위상·주파수 응답 보정값
- `scene.schema.json`: 배경 이미지 크기와 실제 평면 변환, 음원별 위치·오디오 참조·시작/종료·
  gain, ambient 참조, sample rate, seed, 선택적 자유음장·shoebox 환경
- `experiment.schema.json`: 배열/장면 참조, AC-음원 거리, 음속, frequency band 목록과 색,
  STFT window/hop, scan bounds와 해상도, 알고리즘 및 normalization
- `result.schema.json`: 실행 환경, timing, acoustic map, peak, 평가 지표, 입력 hash

오디오 파일은 manifest 옆의 상대 경로로 참조한다. 브라우저 내 객체 URL은 저장 형식에 포함하지
않는다. 스키마에는 버전을 두며, 현재 잔향은 1차 반사·scattering·RT60 tail의 희소 근사로
계약한다. 마이크 지향성과 더 복잡한 재질·mesh 모델은 후속 선택 필드로 남긴다.

## 4. 음향 및 연산 모델

기준 자유음장은 음원 `s`와 마이크 `m` 사이 거리 `r`에 대해 지연 `r/c`와 최소 거리
clamp를 둔 `1/r` 진폭을 사용한다. 선택적 shoebox는 직접음, 여섯 면의 1차 image-source,
반사 에너지의 deterministic scattering, 축 정렬 occluder의 transmission·최단 corner 우회와
tap 수가 제한된 RT60 tail만 추가한다. 경로를 source–microphone 전달함수 하나로 합치고 IFFT를
한 번만 수행하며 위상 recurrence로 bin별 삼각함수 호출을 줄인다.

마이크별 2–64점 `frequencyResponse`는 dB와 wrapped phase를 보간해 수신 channel에 적용한다.
기본 DAS는 sensitivity/phase와 frequency curve의 알려진 역응답을 적용하되 notch의 양의 boost는
기본 24 dB로 제한하고, curve 보정만 끈 robustness 비교도 저장 가능하다. 복수 음원과 ambient를
선형 합산하되 clipping 전 peak, 최종 normalization, 음향 모델과 실제 종류별 경로 수를 기록한다.

DAS는 STFT 후 각 scan point와 마이크 사이 거리로 steering phase를 만들고, 선택된 주파수 bin의
정렬 합 power를 계산한다. 여러 주파수 구간은 각각 독립 map과 색을 갖는다. CPU reference를 먼저
작성한 뒤 같은 buffer layout으로 WGSL 결과를 대조한다. DAS-PHAT은 각 frame/bin에서 마이크
spectrum의 진폭을 제거하되 알려진 응답 phase를 보정한다. GCC-PHAT은 한 reference와 나머지
마이크의 band-limited PHAT 상관을 IFFT하고 scan point의 near-field 예상 지연에서 보간한다.
DAMAS, CLEAN-SC는 초기 완료 범위에서 제외한다.

`P` points, `M` microphones, `T__ frames, `F` selected bins에서 DAS 계열 scan은
`O(P × M × T × F)`다. GCC-PHAT은 공통 forward STFT 외에 2-pass cross spectrum
`2(M-1)TΣF_b`, `(M-1)B` inverse FFT와 `P(M-1)B` lookup을 수행한다.
192채널·50×50·46 frames·2 bins의 DAS는 44,160,000 complex MAC이고 같은 한 band
GCC scan은 477,500 lookup이다. 다만 작은 grid에서는 공통 STFT가 지배할 수 있으므로 이 비율을
end-to-end 속도 향상으로 해석하지 않는다. 100×100은 50×50보다 4배, 200×200은 16배 points이며
장치별 실제 timing과 메모리를 기록하고 이론치만으로 실시간성을 약속하지 않는다.

실측·반복 분석용 CPU 계획은 거리 행렬과 workspace를 재사용하고, DAS 계열은 bin calibration과
허용되는 steering matrix도 재사용한다. 192채널·50×50·2 bins를 10회 DAS 분석하는 기준에서 거리 계산은 4,800,000회에서
480,000회, steering pair는 9,600,000회에서 960,000회로 줄어든다. snapshot working set과 계획은
512 MiB, steering cache는 64 MiB, streaming input은 256 MiB 기본 hard cap을 할당 전에 적용한다.
Streaming ring은 backlog에서 가장 오래된 sample을 버리고 호출당 결과 수를 제한한다.
각 portable 분석은 `processingTimeMs`를 기록하고 streaming은 hop 기반
`deadlineMet`, `deadlineMisses`와 `droppedSamples`로 실제 장치의 지속
처리 가능 여부를 측정한다. cache 수치만으로 실시간성을 보장하지 않는다.

## 5. UI 계획

`acoustic-camera`는 **입력 → 설정 → 실행 → 확인**의 고정 작업 순서를 먼저 보여준다. 실행은
정지 장면의 Snapshot과 trajectory의 Moving 카드로 나뉘며, 결과 canvas를 주 작업 영역으로 둔다.
Scene·Array·Experiment·Assets 준비 상태와 실행 가능 여부를 가까이 표시하고, 비교 기록과 저장
기능은 필요할 때 펼치는 보조 영역으로 내린다. 작은 화면에서는 한 열로 쌓는다.

일상적으로 바꾸는 backend, grid, 대역과 peak 감도는 설정 단계에 유지한다. 음속, seed, scan
범위, STFT, 음향 환경 preset과 마이크 응답 보상은 **고급 설정**에 묶는다. 장문의 개발 요구나
미구현 기능 홍보는 작업 화면에서 제거하고, 물리 모델·데이터 계약·포팅 설명은 문서로 연결한다.
잘못된 단위, room 포함 관계와 CPU/GPU·신호 working-set 한도는 실행 전에
검증한다.

Nyquist 초과 tone/band는 배열 설계 실패 양상을 관찰할 수 있도록 허용한다. tone은 analog path
phase와 microphone response를 먼저 적용한 뒤 ideal ADC에서 sampling하고, band는 모든 등가 ADC
bin center로 접는다. 원 carrier를 이용한 숨은 steering이나 결과 선택은 하지 않으며, 연속
Nyquist-zone fold·이산 bin 선택·알고리즘별 localization model·동일 ADC band를 Result 1.1에
기록한다. 0–1 MHz는 Nyquist cutoff가 아니라 현재 수치/마이크 모델의 검증 범위다.

## 6. 평가 방법

점 음원 위치를 image plane으로 투영해 ground-truth heatmap과 위치 목록을 함께 저장한다. 최소
지표는 다음과 같다.

- peak localization error(m 및 pixel)
- 정답 반경 안 에너지 / 전체 에너지
- main-lobe width와 peak-to-sidelobe ratio
- 복수 음원 검출 precision/recall(거리 tolerance 명시)
- 실행 시간, GPU 메모리 추정량, grid 해상도별 scaling

합성 신호의 해석 가능한 단일 tone/단일 음원 case를 golden test로 두고, broadband·복수 음원·
ambient 순으로 난도를 높인다. 배열 비교에는 같은 scene, seed, STFT, scan grid를 사용한다.

## 7. 데이터셋 조사 및 라이선스 관문

DCASE Task 2와 MIMII의 샘플 구조, 녹음 조건, channel 구성, 라이선스와 재배포 조건을 확인한 뒤
채택한다. 초기에는 저장소에 포함할 수 있는 synthetic tone/noise로 전체 pipeline을 검증한다.
실제 데이터는 사용자가 별도로 받아 연결하며 원본이나 파생 대용량 오디오는 Git에서 제외한다.
DCASE/MIMII가 위치별 분리 음원으로 쓰기 어려우면 기계 종류별 clip 추출·정규화 규칙을 문서화하고,
flattening이 모델 타당성을 훼손하는지 청취 및 spectrum 통계로 평가한다.

## 8. 단계별 구현

### 단계 0 — 기반과 계약 · 완료

- 무설치 ES module workspace, browser test runner, WebGPU feature detection 구성
- 네 가지 JSON Schema와 최소 예제 작성
- 좌표계·단위·오디오 normalization 결정 기록
- synthetic single-tone scene과 192채널 기준 배열 작성

완료 조건: 예제 JSON이 schema validation을 통과하고 앱들이 동일 계약을 읽는다.

### 단계 1 — CPU 기준 모델 · 완료

- 자유음장 구면 전파, 분수 지연, STFT, steering, DAS의 CPU reference 구현
- 단일 음원의 지연·감쇠·peak 위치를 analytic result와 비교
- 50×50 기준 정확도와 실행 시간 측정

완료 조건: 자동화된 golden test가 통과하고 sign/좌표 convention이 문서화된다.

### 단계 2 — Dataset Builder · 완료

- 이미지와 음원 파일 불러오기, 위치·시간·gain 편집, ambient mix와 미리 듣기
- 파일 선택 한 번으로 audio asset source 생성, source별 trajectory keyframe 편집·미리보기
- deterministic seed, clipping 경고, Scene JSON과 mono Preview WAV 내보내기
- synthetic tone/noise fixture와 로컬 asset manifest 경계 구현

완료 조건: 만든 scene을 다시 열었을 때 음원, 위치, 파형, 정답이 동일하다.

### 단계 2A — Array Builder · 완료

- aperture 크기와 사각/타원 생성 경계, 5종 결정론적 프리셋 구현
- canvas 추가·선택·drag, 정밀 좌표·ID·채널 순서 편집과 undo/redo
- 가져온 sensitivity·phase·frequency response 보존과 표준 Array JSON 왕복
- 좌표 중복 오류, 경계 초과 경고, clamp·중앙 정렬·aperture 맞춤

완료 조건: 만든 Array가 계약 검증을 통과하고 Acoustic Camera에서 그대로 불러와진다.

### 단계 3 — WebGPU DAS · 완료

- CPU와 동일한 buffer layout 및 WGSL kernel 구현
- frequency band별 map 생성, device limit 대응, CPU fallback
- 50²/100²/200² 및 band/bin 수에 따른 benchmark

완료 조건: CPU/GPU map 오차 기준을 통과하고 192채널 50×50 실행 timing이 기록된다.

### 단계 4 — Acoustic Camera UI와 평가 · 완료

- scene/ground truth/acoustic overlay, 배열 geometry, parameter panel 구현
- 결과 metric, 실행 환경, 입력 hash와 map 내보내기
- 복수 음원·다중 대역 표시와 실험 preset 비교
- peak별 half-power 공분산/RMS 빔 분포와 재현 가능한 검출 임계값
- sample-aligned 준정적 시간창 분석, bounded map 계획과 이동 장면 재생

완료 조건: 사용자가 코드 수정 없이 배열 JSON과 위치 추정 알고리즘을 같은 장면에서 비교할 수 있다.

### 단계 5 — 현실성·포팅과 실제 데이터 · 부분 완료

- [x] 마이크별 gain·phase·frequency-response 합성과 알고리즘별 amplitude/phase 보정
- [x] 자유음장을 보존하는 선택형 shoebox 1차 반사·scattering·회절·RT60 tail
- [x] Scene 합성에서 분리한 block/streaming multichannel 위치추정 API
- [x] 반복 거리·calibration·steering cache, bounded ring과 메모리 hard cap
- [x] DAS·DAS-PHAT·reference-pair GCC-PHAT와 알고리즘별 power/score 계약
- [ ] 라이선스 검토를 통과한 DCASE/MIMII adapter와 batch workflow
- [ ] 실제 장치의 channel/clock/sample 형식에 맞춘 capture·transport adapter와 현장 검증
- [ ] 필요 시 센서 self-noise·위치 공차와 DAMAS/CLEAN-SC 후처리

현재 완료 조건은 기존 자유음장 결과를 유지한 채 propagation model과 응답 보상을 선택해
재실행하고, 선택한 CPU 위치 추정기를 실측 `Float32Array` channel에 직접 적용하는 것이다. 실제
hardware deadline과 정확도는 장치 adapter가 정해진 뒤 별도 측정한다.

## 9. 주요 위험과 대응

- WebGPU 미지원/장치 한도: 시작 시 capability를 표시하고 CPU fallback 및 grid 상한을 둔다.
- 좌표·phase 부호 오류: analytic tone test와 배열 대칭성 test를 먼저 만든다.
- 브라우저 메모리: crop microphone channel과 source별로 순차 처리하는 한 sampled
  signal·spectrum·workspace의 peak typed working set에 512 MiB 한도를 적용하고, 이동
  미리보기는 최대 48개·2,500 points의 짧은 시간창으로 제한한다. 장시간 입력은 256 MiB 기본
  한도의 fixed ring streaming core에서 처리하고 overload의 `droppedSamples`를 감시한다.
- 데이터셋 부적합/라이선스: 로컬 asset 계약을 유지하고 synthetic fixture를 기본 test 입력으로
  쓴다. 실제 데이터 adapter는 단계 5의 라이선스 검토 뒤 추가한다.
- 실제 AC와 simulation gap: gain·phase·주파수 응답, ideal real ADC sampling/alias와 희소 실내
  환경을 비교 조건으로 제공하되, 위치 공차·self-noise·ADC quantization/nonlinearity와
  channel clock jitter/drift는 실측 adapter와 현장 검증으로 다룬다.
- post-processing이 기본 결과를 가림: 알고리즘별 raw power/score map과 후처리 map을 별도로 보존한다.

## 10. 구현 결과와 다음 백로그

- [x] 설치 없는 ES module workspace와 세 앱 shell
- [x] Array Builder 프리셋·직접 편집·검증·Camera 전달
- [x] array/scene/experiment/result schema와 synthetic fixture
- [x] 좌표·거리·구면 감쇠·분수 지연·STFT 단위 테스트
- [x] CPU DAS golden implementation
- [x] CPU/WebGPU DAS-PHAT와 CPU reference-pair GCC-PHAT 구현·비교 UI
- [x] WGSL kernel, CPU/GPU 비교와 50²/100²/200² benchmark
- [x] scene canvas, array view, parameter controls와 Result export
- [x] Builder→Camera SHA-256 asset 재연결 왕복 테스트
- [x] 임의 오디오 source 원클릭 생성과 codec 안내
- [x] 이동 trajectory 계약·편집·시간창 합성·Camera 라이브 재생
- [x] 비확률 beam spread RMS contour와 Result export
- [x] 복수 음원용 Experiment peak 검출 감도
- [x] 마이크 주파수 응답 합성·CPU/WebGPU 역보정 비교
- [x] 자유음장·shoebox 희소 반사/산란/회절/RT60 환경 선택
- [x] portable block/streaming localizer와 알고리즘별 반복 plan·메모리 상한
- [x] Camera 입력→설정→실행→확인의 Snapshot/Moving UI 재구성
- [x] `test.cmd` one-command headless browser 검증
- [ ] DCASE/MIMII 라이선스 검토와 adapter
- [ ] 실제 192채널 capture/transport adapter와 deadline·정확도 검증
- [ ] 센서 self-noise·위치 공차·지향성 모델
- [ ] DAMAS/CLEAN-SC 후처리

정확성 test를 먼저 통과시킨 뒤 UI 또는 최적화를 진행한다는 원칙은 유지한다. 추가 현실성 모델은
자유음장 DAS 기준 결과를 바꾸지 않는 선택형 확장으로, 장치 연결은 portable localizer 앞의 adapter로
추가한다.