micarrsim/docs/execution-plan.md

# micarrsim 실행 계획

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

## 1. 목표와 성공 기준

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

1. 기계음 데이터와 ambient audio를 조합해 장면 및 ground truth를 생성한다.
2. 배열 JSON과 장면 정보를 사용해 각 마이크에 도달하는 신호를 합성한다.
3. WGSL로 conventional delay-and-sum(DAS) 빔포밍을 수행한다.
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를 추가한다. 이 방식은 초기 복잡도를 줄이면서 확장 경로를
남긴다.

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

- `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, 배열 폭·높이, 192개 마이크의 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 결과를 대조한다. DAMAS, CLEAN-SC는 인터페이스만 마련하고
초기 완료 범위에서는 제외한다.

연산량의 주항은 대략 `O(P × M × F × T)`다. `M=192`, `P=50²=2,500`일 때 STFT
frame·주파수 bin 하나당
약 48만 개의 복소 steering 누산이 필요하다. 100×100은 50×50보다 4배, 200×200은 16배이므로
장치별 실제 GPU timing을 UI에 표시하고 목표 frame budget에 맞춰 해상도를 제한한다. 정확한 성능과
메모리는 대표 GPU에서 benchmark하여 기록하며 이론치만으로 약속하지 않는다.

실측·반복 분석용 CPU 계획은 거리 행렬, bin calibration, 임시 map과 허용되는 steering matrix를
재사용한다. 192채널·50×50·2 bins를 10회 분석하는 기준에서 거리 계산은 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과 마이크 응답 보상은 **고급 설정**에 묶는다. 장문의 개발 요구나
미구현 기능 홍보는 작업 화면에서 제거하고, 물리 모델·데이터 계약·포팅 설명은 문서로 연결한다.
잘못된 단위, Nyquist 초과 대역, room 포함 관계와 CPU/GPU·신호 working-set 한도는 실행 전에
검증한다.

## 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을 통과하고 두 앱이 동일 manifest를 읽는다.

### 단계 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을 다시 열었을 때 음원, 위치, 파형, 정답이 동일하다.

### 단계 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 합성 및 선택적 DAS 역보정
- [x] 자유음장을 보존하는 선택형 shoebox 1차 반사·scattering·회절·RT60 tail
- [x] Scene 합성에서 분리한 block/streaming multichannel 위치추정 API
- [x] 반복 거리·calibration·steering cache, bounded ring과 메모리 hard cap
- [ ] 라이선스 검토를 통과한 DCASE/MIMII adapter와 batch workflow
- [ ] 실제 장치의 channel/clock/sample 형식에 맞춘 capture·transport adapter와 현장 검증
- [ ] 필요 시 센서 self-noise·위치 공차와 DAMAS/CLEAN-SC 후처리

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

## 9. 주요 위험과 대응

- WebGPU 미지원/장치 한도: 시작 시 capability를 표시하고 CPU fallback 및 grid 상한을 둔다.
- 좌표·phase 부호 오류: analytic tone test와 배열 대칭성 test를 먼저 만든다.
- 브라우저 메모리: snapshot signal·최대 sparse delay FFT에 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·주파수 응답과 희소 실내 환경을 비교 조건으로 제공하되,
  위치 공차·self-noise·ADC·clock은 실측 adapter와 현장 검증으로 다룬다.
- post-processing이 기본 결과를 가림: raw DAS map과 후처리 map을 항상 별도로 보존한다.

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

- [x] 설치 없는 ES module workspace와 두 앱 shell
- [x] array/scene/experiment/result schema와 synthetic fixture
- [x] 좌표·거리·구면 감쇠·분수 지연·STFT 단위 테스트
- [x] CPU DAS golden implementation
- [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와 반복 DAS cache·메모리 상한
- [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로
추가한다.