diff --git a/README.md b/README.md index 601b7a6..6cf257c 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # micarrsim -192채널 MEMS 마이크 배열의 배치와 자유음장·저비용 실내 근사에서 DAS·DAS-PHAT·GCC-PHAT -위치 추정을 비교하는 로컬 브라우저 +192채널 MEMS 마이크 배열의 배치와 자유음장·저비용 실내 근사에서 DAS·DAS-PHAT·GCC-PHAT·MUSIC +위치 추정을 비교하고, 표준 CFAR와 spectral flux로 ADC 대역의 원시 활동 후보를 확인하는 로컬 브라우저 시뮬레이터입니다. Array Builder에서 마이크 배치를 설계하고, Dataset Builder에서 녹음 파일·합성 신호와 이동 경로를 포함한 재현 가능한 음향 장면을 만든 뒤, Acoustic Camera에서 CPU 또는 WebGPU로 배열 응답, acoustic map과 위치 검출 지표를 계산하거나 이동 장면을 시간축으로 재생합니다. @@ -59,6 +59,27 @@ MUSIC을 바로 확인하려면 현재 장면 제목 옆 **MUSIC 빠른 예제** 실제 완료 시간은 브라우저와 장치에 따라 다릅니다. CPU fallback에서는 WebGPU보다 오래 걸릴 수 있습니다. +### 분석 주파수를 모를 때 + +1. Acoustic Camera의 분석 대역 아래에서 **전 대역 활동 검사**를 펼칩니다. +2. 물리 마이크 한 채널과 **OS-CFAR**, **CA-CFAR** 또는 + **Dixon spectral flux**를 고릅니다. +3. **전 대역 검사**를 누르고 frame slider에서 원시 ADC-bin 통계 또는 onset novelty를 봅니다. +4. CFAR candidate의 **아날로그 center 가설**을 직접 입력합니다. 기본값은 관측 ADC + center일 뿐 원 주파수 정답이 아닙니다. +5. **이 가설을 대역으로 추가**한 뒤 위치 추정 알고리즘을 골라 Snapshot을 실행합니다. +6. 감사 가능한 모든 frame/bin 값은 **Activity JSON**으로 저장합니다. + +예를 들어 48 kHz ADC의 1,125 Hz 관측에는 1,125 Hz뿐 아니라 46,875 Hz, +49,125 Hz 같은 서로 다른 아날로그 가설이 대응합니다. Nyquist 초과 값도 막지 않지만, +Camera가 Scene truth로 alias order를 고르지는 않습니다. 각 가설을 별도 band로 넣어 배열의 +spatial alias·grating lobe·실패 양상을 그대로 비교하세요. + +CFAR의 Pfa는 IID exponential 배경 모델의 **tested CUT 하나당 명목값**이며 위치 확률이나 +실측 confidence가 아닙니다. Spectral flux는 지속 신호 검출이 아니라 onset novelty입니다. +세 검출 경로와 위치 map을 자동 합의·평균·maximum fusion하지 않습니다. 수식, 미검사 edge와 +causal latency는 [전 대역 활동 검출 모델](docs/activity-detection.md)에 설명되어 있습니다. + ### 화면 폭 조절 데스크톱에서는 Array Builder와 Acoustic Camera의 왼쪽 설정 패널, Dataset Builder의 오른쪽 설정 @@ -340,6 +361,7 @@ test.cmd ## 저장 형식과 개발 문서 +- [전 대역 활동 검출 모델](docs/activity-detection.md): CA/OS-CFAR, spectral flux와 alias 가설 흐름 - [`docs/data-contracts.md`](docs/data-contracts.md): Array·Scene·Experiment·Result 계약 - [`docs/acoustic-model.md`](docs/acoustic-model.md): 마이크 응답과 자유음장·shoebox 희소 근사 - [`docs/realtime-porting.md`](docs/realtime-porting.md): 실측 다채널 위치추정 API 포팅 diff --git a/apps/acoustic-camera/README.md b/apps/acoustic-camera/README.md index 34ed20b..c91a570 100644 --- a/apps/acoustic-camera/README.md +++ b/apps/acoustic-camera/README.md @@ -1,9 +1,10 @@ # Acoustic Camera -Scene과 마이크 배열로 자유음장 또는 저비용 shoebox microphone signal을 합성하고, STFT와 -DAS·DAS-PHAT·GCC-PHAT 위치추정으로 주파수 대역별 acoustic map과 ground-truth 평가 지표를 -만드는 브라우저 앱입니다. 정지 장면은 Snapshot, trajectory 장면은 Moving 흐름으로 분리되어 -있습니다. +Scene과 마이크 배열로 자유음장 또는 저비용 shoebox microphone signal을 합성하고, 표준 +CA/OS-CFAR·Dixon spectral flux로 ADC 대역 후보를 보거나 STFT와 +DAS·DAS-PHAT·GCC-PHAT·MUSIC 위치추정으로 주파수 대역별 acoustic map과 ground-truth 평가 +지표를 만드는 브라우저 앱입니다. 정지 장면은 Snapshot, trajectory 장면은 Moving 흐름으로 +분리되어 있습니다. ## 열기와 Snapshot @@ -55,6 +56,50 @@ Camera가 SHA-256을 계산해 manifest에 연결합니다. 같은 이름이라 파일은 외부로 업로드되지 않고 브라우저 메모리에서만 처리됩니다. +## 전 대역 활동 후보 찾기 + +분석 주파수를 미리 모를 때는 분석 대역 아래의 **전 대역 활동 검사**를 펼칩니다. +이 흐름은 위치추정 map과 별도이며 다음 순서로 사용합니다. + +1. 실제로 관찰할 물리 마이크 한 채널을 고릅니다. +2. 좁은 spectral outlier에는 OS-CFAR 또는 CA-CFAR, 갑작스러운 onset에는 + Dixon spectral flux를 고릅니다. +3. **전 대역 검사**를 누르고 frame별 원시 결과를 확인합니다. +4. CFAR가 표시한 ADC bin에 대응한다고 가정할 아날로그 center를 직접 입력합니다. +5. **이 가설을 대역으로 추가**한 뒤 DAS·PHAT·GCC-PHAT·MUSIC으로 배열 위치응답을 비교합니다. +6. 모든 complete frame과 모든 tested/untested bin은 **Activity JSON**으로 저장합니다. + +Activity worker는 Scene과 선택한 마이크의 위치·응답으로 물리 수신 신호를 합성하지만, +음원 위치·주파수·개수 정답은 detector 함수에 전달하지 않습니다. 선택하지 않은 마이크는 +합성하거나 평균·투표하지 않습니다. 위치추정 band, algorithm, backend 또는 배경 image 연결이 +잘못돼 Snapshot을 실행할 수 없어도, Scene·선택 마이크·STFT·합성 최소 거리와 필요한 audio +asset이 유효하면 Activity는 실행할 수 있습니다. + +CFAR는 Hann STFT의 각 complete frame을 독립 검사합니다. DC, Nyquist와 좌우 full +reference window가 없는 edge bin은 reference 수를 줄이거나 wrap하지 않고 untested로 남깁니다. +Pfa는 IID exponential square-law 배경을 가정한 tested CUT 하나당 명목 오경보율이며 +위치 확률, confidence, frame 전체 오경보율 또는 실측 보정값이 아닙니다. 화면에는 CUT, +reference, threshold와 ratio를 그대로 표시합니다. + +Dixon spectral flux는 Hamming STFT의 연속 frame 사이에서 증가한 linear magnitude의 +full-DFT L1 합입니다. 지속 activity가 아니라 onset novelty입니다. Böck–Krebs–Schedl +causal peak picker는 기본으로 꺼져 있고, 켤 때도 delta는 확률이 아닌 사용자 보정값입니다. +Frame start는 설명용 시각이며 **available** 시각이 실제 causal 판정 가능 시각입니다. + +Scene의 peak normalization을 선택했다면 선택한 한 채널의 전체 render peak가 detector 전에 +적용됩니다. 이 경우 detector 자체는 입력 이후 causal이어도 spectral-flux 절대값과 delta +event를 포함한 end-to-end 전처리는 미래 sample에 의존하며, UI와 JSON에 이를 표시합니다. +물리 scale을 그대로 비교하려면 Scene normalization을 none으로 두세요. + +검출기가 관찰하는 주파수는 ADC의 0…Fs/2뿐입니다. 예를 들어 Fs=48 kHz에서 ADC 1,125 Hz로 +보인 성분은 1,125 Hz, 46,875 Hz, 49,125 Hz 등 여러 아날로그 carrier와 양립합니다. +Nyquist 초과 가설도 0–1 MHz 검증 범위에서 허용하지만 alias order와 spectral inversion은 +자동 선택하지 않습니다. 각 가설을 FFT-grid center의 별도 band로 추가합니다. CFAR와 flux, +서로 다른 band 또는 위치 map을 합의·평균·maximum으로 자동 결합하지 않습니다. + +수식, 통계 가정, 문헌과 raw output 계약은 +[전 대역 활동 검출 모델](../../docs/activity-detection.md)을 참고하세요. + ## 위치 추정 알고리즘과 Backend **분석 설정 → 위치 추정 알고리즘**에서 다음 네 구현을 선택합니다. diff --git a/docs/activity-detection.md b/docs/activity-detection.md index c38df03..f3a5bfd 100644 --- a/docs/activity-detection.md +++ b/docs/activity-detection.md @@ -4,6 +4,28 @@ 의미와 한계를 정의한다. 검출기는 Scene의 음원 주파수·위치·개수를 입력으로 받지 않으며, 검출 결과를 위치 정답이나 분석 대역으로 자동 변환하지 않는다. +## Camera에서 가장 짧은 사용 순서 + +1. Acoustic Camera의 분석 대역 아래 **전 대역 활동 검사**를 펼친다. +2. 한 물리 마이크와 OS-CFAR, CA-CFAR 또는 Dixon spectral flux를 고른다. +3. **전 대역 검사**를 실행하고 frame의 raw 통계와 실제 판정 가능 시각 + available을 확인한다. +4. CFAR candidate가 있으면 관측 ADC center와 같은 bin으로 접히는 아날로그 + FFT-grid center 가설을 직접 입력한다. +5. **이 가설을 대역으로 추가**하고 원하는 위치추정기를 별도로 실행한다. +6. 모든 complete frame/bin 감사값은 **Activity JSON**으로 저장한다. + +Activity 실행에는 Scene·선택 마이크·STFT·신호 합성용 최소 거리와 참조하는 audio +asset만 필요하다. 위치추정 band, MUSIC source-count, backend, scan 또는 배경 image +연결 오류는 이 검출을 막지 않는다. 반대로 Scene, 선택한 마이크 응답이나 audio +asset이 잘못되면 물리 입력 자체를 만들 수 없으므로 실행하지 않는다. + +예를 들어 (F_s=48,mathrm{kHz})에서 관측한 ADC 1,125 Hz에는 1,125 Hz, +46,875 Hz와 49,125 Hz 등의 아날로그 가설이 대응한다. 기본 입력값 1,125 Hz는 +가장 낮은 가설을 편의상 보여줄 뿐 정답 판정이 아니다. Nyquist 초과 가설도 +0–1 MHz 검증 범위 안에서 별도 band로 추가할 수 있으며, 서로 다른 alias order와 +spectral inversion 가설을 합치지 않는다. + ## 관측 경계 - 입력은 사용자가 고른 **물리 마이크 채널 하나**의 시간 샘플이다. 여러 채널의 @@ -18,6 +40,29 @@ - 정확한 DC와 Nyquist bin은 실수 성분 하나뿐이어서 내부 complex FFT bin과 통계 모델이 다르다. CFAR의 CUT와 reference cell에서 제외한다. +## 시뮬레이터와 detector의 경계 + +Camera는 Scene의 source와 음향 경로로 선택한 물리 마이크 **하나**의 수신 신호를 +먼저 합성한다. 이는 시험 입력을 만드는 forward simulator이므로 source 위치·주파수와 +개수를 사용한다. 그 다음 detector 함수에는 이 한 채널 sample, sample rate, STFT와 +검출 설정만 전달하며 source identity·위치·주파수·개수 정답은 전달하지 않는다. +Activity JSON은 이 경계를 +sceneSourceTruthUsedByPhysicalSimulator: true와 +sceneSourceTruthPassedToDetector: false로 구분한다. + +Report는 source ID와 source별 도착 목록을 내보내지 않지만, 적용한 음향 모델, +종류별 path 수와 최대 지연 같은 집계 physical audit는 남긴다. 이 값은 source에서 +파생된 정보이므로 +sourceDerivedAggregatePhysicalAuditIncluded: true라고 명시한다. +Detector 판정 입력과 사후 감사 metadata를 같은 의미로 부르지 않는다. + +Scene mix가 peak normalization이면 선택한 한 채널의 **전체 render peak**로 먼저 +scale한다. 선택하지 않은 마이크에는 의존하지 않지만 미래 sample에는 의존한다. +따라서 detector는 주어진 sample 이후 causal이어도 raw flux와 절대 delta event를 +포함한 end-to-end 전처리는 causal이 아니다. 이 경우 UI와 JSON의 +futureDependentNormalization이 true가 된다. 물리 amplitude scale을 +비교하려면 Scene normalization을 none으로 둔다. + ## CA-CFAR와 OS-CFAR CFAR는 한 STFT frame 안의 좁은 spectral outlier를 찾는다. frame 또는 마이크 @@ -104,3 +149,9 @@ Spectral flux는 **onset novelty**이지 지속 activity detector가 아니다. 5. 같은 Scene·Array·가설에서 DAS, PHAT, GCC-PHAT, MUSIC의 raw map과 실패 양상을 비교한다. 서로 다른 band의 map은 알려진 별도 wideband 방법을 구현하기 전까지 자동 결합하지 않는다. + +Activity의 독립 preflight는 합성과 detector output 상한을 먼저 계산한다. CFAR는 +complete frame, frame×bin decision과 FFT butterfly hard cap을, spectral flux는 +모든 frame×full-DFT-bin 차이를 보존하는 output byte 상한을 실제 함수와 같은 +estimator로 검사한다. 상한을 넘으면 일부 frame이나 top-K bin만 반환하지 않고 +신호 합성 전에 실패한다. diff --git a/docs/data-contracts.md b/docs/data-contracts.md index 3f13146..8b97007 100644 --- a/docs/data-contracts.md +++ b/docs/data-contracts.md @@ -1,8 +1,9 @@ # 데이터 계약 -micarrsim의 저장 형식은 JSON Schema Draft 2020-12와 추가 관계 검증으로 정의한다. 모든 길이는 m, -시간은 s, 주파수는 Hz다. 배열 중심이 원점이고 `+x`는 오른쪽, `+y`는 위쪽, `+z`는 배열에서 -장면을 향하는 우수 좌표계를 사용한다. +micarrsim의 핵심 Array·Scene·Experiment·Result 형식은 JSON Schema Draft 2020-12와 추가 관계 +검증으로 정의한다. Activity와 비교 기록 같은 편의 감사 export는 이 문서에서 별도 범위를 +명시한다. 모든 길이는 m, 시간은 s, 주파수는 Hz다. 배열 중심이 원점이고 `+x`는 오른쪽, +`+y`는 위쪽, `+z`는 배열에서 장면을 향하는 우수 좌표계를 사용한다. ## 파일 종류 @@ -10,6 +11,8 @@ micarrsim의 저장 형식은 JSON Schema Draft 2020-12와 추가 관계 검증 - `micarrsim.scene`: 음원·ambient recipe, 위치 ground truth와 로컬 asset manifest - `micarrsim.experiment`: scan plane/grid, 주파수 대역, STFT와 위치 추정 설정 - `micarrsim.result`: raw/display acoustic map, 복수 peak와 source 매칭, 평가·성능 정보 +- `micarrsim.activity-report`: 단일 물리 마이크의 raw CFAR 또는 spectral-flux 감사 export. + core schema 검증 대상은 아니며 위치추정 Result를 대신하지 않는다. - `micarrsim.comparison-history`: 세션의 배열별 Result 요약을 모은 편의 export. core schema 검증 대상은 아니며 각 원본 Result JSON을 대신하지 않는다. @@ -202,6 +205,32 @@ Nyquist 위 band의 `aliasOrderResolution`은 `not-attempted`다. MUSIC의 bin이 선택됐을 때 포함한다. noise와 asset source는 모든 band에 포함한다. 녹음 asset의 spectrum을 임의 threshold로 분류하는 미검증 multiband 알고리즘은 사용하지 않는다. +## Activity JSON + +Acoustic Camera의 Activity export는 schemaVersion: "1.0.0", +kind: "micarrsim.activity-report"인 편의 감사 문서다. 최상위에는 실제 실행 +Array·Scene·Experiment ID, 생성 시각과 64자리 SHA-256 inputHash가 있고, +report에는 다음 값이 있다. + +- 사용자가 선택한 원래 microphone index·id·position과 microphone fusion 없음 +- sample rate/count, FFT/hop, ADC 0…Fs/2와 alias order 미결정 상태 +- simulator가 Scene truth로 물리 sample을 만들었다는 사실과 detector에는 truth를 전달하지 + 않았다는 분리 표기 +- 선택 마이크 한 채널의 normalization·clipping·음향 경로 집계와 causal 전처리 여부 +- CFAR의 모든 complete frame×모든 ADC bin 또는 spectral flux의 raw ODF와 모든 + frame×full-DFT-bin 양의 차이 +- 알고리즘 설정·가정·보정 상태, workload와 signal-generation/detector timing + +Source identity와 source별 arrival 목록은 포함하지 않지만 path 수·최대 지연 같은 source-derived +집계 physical audit는 포함하며 이를 명시한다. CFAR의 untested bin과 zero-threshold +ratio 상태도 삭제하지 않는다. Typed array는 JSON 숫자 배열로 변환하고 비유한 수가 생기면 +문자열 Infinity, -Infinity 또는 NaN으로 명시한다. + +Activity inputHash는 검출에 실제로 사용한 선택 마이크, Scene의 음향 입력 +(배경 image와 비audio asset 제외), STFT, 합성 최소 거리와 detector 설정의 canonical +UTF-8 SHA-256이다. 분석 band·scan·위치추정 algorithm/backend는 detector 입력이 아니므로 +hash에 넣지 않는다. Array·Scene·Experiment ID는 provenance label로 별도 보존한다. + ## 재현성 hash `result.inputHash`는 실행에 사용한 `{ array, scene, experiment }`를 객체 key 사전순으로 재귀 diff --git a/docs/execution-plan.md b/docs/execution-plan.md index 54fde78..4281cc4 100644 --- a/docs/execution-plan.md +++ b/docs/execution-plan.md @@ -4,7 +4,8 @@ > > 단계 0–4와 단계 5의 저비용 음향 환경·마이크 응답·다중 알고리즘 portable streaming core까지 완료했다. > 설치 없는 브라우저 앱, CPU/WebGPU DAS·DAS-PHAT와 CPU GCC-PHAT, Builder→Camera asset 재연결, 임의 오디오·이동 -> trajectory, 빔 분포·복수 peak 감도, 라이브 시간축 재생, 배열 비교와 Result 내보내기를 +> trajectory, 표준 단일채널 CA/OS-CFAR·Dixon spectral flux, 빔 분포·복수 peak 감도, +> 라이브 시간축 재생, 배열 비교와 Result 내보내기를 > 전체 자동 테스트로 검증했다. 실제 장치 adapter와 현장 검증은 장치 계약이 필요한 후속 범위다. ## 1. 목표와 성공 기준 @@ -207,6 +208,7 @@ flattening이 모델 타당성을 훼손하는지 청취 및 spectrum 통계로 - [x] 반복 거리·calibration·steering cache, bounded ring과 메모리 hard cap - [x] DAS·DAS-PHAT·reference-pair GCC-PHAT와 알고리즘별 power/score 계약 - [x] CPU 좁은대역 Schmidt MUSIC, fixed K와 Wax–Kailath AIC/MDL, typed unavailable·연산 상한 +- [x] 단일 물리 마이크 CA/OS-CFAR·Dixon spectral flux와 raw frame/bin export - [ ] 라이선스 검토를 통과한 DCASE/MIMII adapter와 batch workflow - [ ] 실제 장치의 channel/clock/sample 형식에 맞춘 capture·transport adapter와 현장 검증 - [ ] 필요 시 센서 self-noise·위치 공차와 DAMAS/CLEAN-SC 후처리 @@ -232,6 +234,9 @@ hardware deadline과 정확도는 장치 adapter가 정해진 뒤 별도 측정 - MUSIC 모호성을 숨김: band당 사용자 지정 analog FFT-grid 가설 하나와 direct-path near-field manifold만 쓰며 Scene truth, diagonal loading, smoothing, multibin/wideband fusion 없이 grating lobe·동률·coherent rank deficiency를 보존한다. +- 자동 주파수 검출의 과장: detector에는 Scene truth를 전달하지 않고 ADC bin만 반환한다. + Nyquist 초과 analog carrier는 사용자가 별도 FFT-grid 가설로 지정하며, CFAR·flux·band·위치 + map을 임의 consensus나 maximum으로 결합하지 않는다. ## 10. 구현 결과와 다음 백로그 @@ -242,6 +247,7 @@ hardware deadline과 정확도는 장치 adapter가 정해진 뒤 별도 측정 - [x] CPU DAS golden implementation - [x] CPU/WebGPU DAS-PHAT와 CPU reference-pair GCC-PHAT 구현·비교 UI - [x] CPU 좁은대역 MUSIC과 fixed/Wax–Kailath source count, q 최소 목적함수·typed unavailable +- [x] 표준 CA/OS-CFAR와 Dixon spectral flux의 독립 전 대역 검사·Activity JSON·alias 가설 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 재연결 왕복 테스트 diff --git a/docs/index.html b/docs/index.html index 75677e4..8ab8c55 100644 --- a/docs/index.html +++ b/docs/index.html @@ -17,6 +17,7 @@