Codex
101 lines
5.6 KiB
Markdown
101 lines
5.6 KiB
Markdown
# Acoustic Camera
|
||
|
||
Scene과 마이크 배열로 자유음장 microphone signal을 합성하고, STFT와 conventional DAS를 통해
|
||
주파수 대역별 acoustic map과 ground-truth 평가 지표를 만드는 브라우저 앱입니다.
|
||
|
||
## 열기와 기본 예제
|
||
|
||
저장소의 `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. **기본 예제 실행**을 누릅니다.
|
||
4. 완료 후 overlay, 위치 오차와 timing을 확인하고 **Result JSON**을 저장합니다.
|
||
|
||
## 사용자 입력 불러오기
|
||
|
||
문서는 다음 순서로 불러오는 것이 안전합니다.
|
||
|
||
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 선택
|
||
|
||
- **Auto (GPU→CPU)**: 권장. WebGPU를 먼저 시도하고 adapter/device 부재나 지원되는 장치 한계가
|
||
있으면 CPU로 계속합니다.
|
||
- **WebGPU 강제**: GPU만 사용하며 운용 오류가 나도 CPU로 fallback하지 않습니다.
|
||
- **CPU 강제**: CPU 수치 기준이나 WebGPU가 없는 환경에서 사용합니다.
|
||
|
||
WebGPU가 감지돼도 실제 장치는 실행 시 확인합니다. 계산 중 **계산 취소**를 누르면 Worker를
|
||
종료하며, 이미 완료된 이전 결과가 있으면 그대로 남습니다.
|
||
|
||
## Grid, STFT와 대역
|
||
|
||
50×50은 2,500 points입니다. 이를 1로 보면 100×100은 4배, 200×200은 16배 points를 계산합니다.
|
||
처음에는 50×50을 권장합니다. 실행량은 microphone 수, scene 길이, FFT/hop과 선택 band의 bin
|
||
수에도 비례하므로 실제 시간 배율은 장치마다 다릅니다.
|
||
|
||
각 band는 id, 최소/최대 Hz와 overlay 색을 가집니다. Nyquist를 넘거나 겹치는 id 등 계약 오류는
|
||
실행 전에 표시됩니다. 현재 후처리는 raw DAS만 지원하며 DAMAS와 CLEAN-SC 항목은 비활성화되어
|
||
있습니다.
|
||
|
||
## 화면과 배열 비교
|
||
|
||
- acoustic overlay의 투명도와 표시할 band를 선택할 수 있습니다.
|
||
- **Ground truth**를 켜면 source 위치와 검출 peak를 비교할 수 있습니다.
|
||
- rectangular와 Fermat spiral preset을 같은 Scene/Experiment에서 연속 실행하면 **배열 비교 기록**에
|
||
backend, timing과 평가 요약이 남습니다.
|
||
- 입력을 바꾼 뒤 화면에 남은 결과는 이전 실행 snapshot이며 UI가 이전 설정 결과임을 표시합니다.
|
||
- Camera에서 거리·음속·seed를 바꾼 Scene과 scan·STFT·band를 바꾼 Experiment는 우측의 각
|
||
**JSON 저장** 버튼으로 보존할 수 있습니다.
|
||
- **전체 기록 JSON**은 세션에 남은 모든 배열 비교 요약을
|
||
`micarrsim.comparison-history` 문서로 저장합니다.
|
||
|
||
미저장 Scene·Experiment·Result·비교 기록은 우측 저장 상태에 표시됩니다. 직전 Result를 저장하지
|
||
않고 새 실행을 시작하면 교체 여부를 확인하며, 미저장 항목이나 실행 중 계산이 있는 상태에서
|
||
페이지를 닫으면 브라우저가 한 번 더 확인합니다.
|
||
|
||
## Result JSON
|
||
|
||
**Result JSON**은 검증을 통과한 `micarrsim.result` 문서만 저장합니다.
|
||
|
||
- `experimentId`, `arrayId`, `sceneId`, `createdAt`, 실제 `backend`
|
||
- 실행 입력 전체의 canonical SHA-256인 `inputHash`
|
||
- `signalStats`: 정규화 전 peak, 적용 scale, clipped sample 수
|
||
- `timingMs`: 전체, signal generation과 beamforming 시간
|
||
- band별 `rawMap` 선형 power, `displayMap`, 검출 `peaks`
|
||
- 평가 설정과 `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 경고와 위치 오차를 함께 해석하세요.
|
||
|
||
## 해석 한계
|
||
|
||
신호 모델은 직접 경로와 거리 감쇠를 사용하는 자유음장입니다. 반사, 잔향, 회절, 차폐, 바람,
|
||
센서 비선형과 장착 구조는 포함하지 않습니다. 배열 JSON의 sensitivity/phase calibration은 적용하지만
|
||
결과는 상대 배열 비교와 알고리즘 검증용이며 실측 인증을 대신하지 않습니다.
|
||
|
||
WebGPU 성능을 별도로 측정하려면 서버 실행 후
|
||
<http://127.0.0.1:4173/benchmarks/webgpu-scaling.html>을 여세요.
|