Compute backend
-Localization & compute
++ Camera의 위치 추정 알고리즘에서 실행할 방법을 고릅니다. 처음에는 + DAS로 전체 흐름을 확인한 뒤 같은 scene·scan·STFT에서 PHAT 계열을 실행해 비교하세요. +
+| 알고리즘 | raw map | Backend | 특징 |
|---|---|---|---|
| DAS | 선형 power | CPU · WebGPU | 진폭과 위상을 유지하는 기준선 |
| DAS-PHAT | 무차원 score | CPU · WebGPU | STFT 크기를 정규화한 위상 기반 합산 |
| GCC-PHAT | 무차원 score | CPU | 기준 마이크 pair의 TDOA 상관 |
| 선택 | 동작 | 권장 상황 |
|---|---|---|
| Auto (GPU→CPU) | WebGPU를 먼저 시도하고 불가능하면 CPU 사용 | 기본 권장 |
| WebGPU 강제 | GPU 장치가 없거나 실패하면 fallback 없이 오류 | GPU 비교·측정 |
| CPU 강제 | 동일한 conventional DAS를 CPU에서 계산 | 호환성 확인·기준 비교 |
| WebGPU 강제 | DAS/DAS-PHAT를 GPU에서만 실행; 실패하면 fallback 없이 오류 | GPU 비교·측정 |
| CPU 강제 | 선택한 알고리즘을 CPU에서 계산 | 호환성 확인·기준 비교 |
- 먼저 50×50을 권장합니다. 100×100은 4배, 200×200은 16배의 scan point를 계산합니다. - 실행 중에는 취소할 수 있으며, 취소하거나 실패해도 이전 완료 결과는 유지됩니다. + GCC-PHAT는 CPU 전용이므로 Auto가 자동으로 CPU를 사용하고 WebGPU 강제는 비활성화됩니다. + 각 band가 8개 미만의 FFT bin을 포함하면 협대역 상관 경고가 나오므로 band 폭이나 FFT + 설정을 확인하세요.
- 복수 음원에서 약한 peak가 빠지면 Peak 검출 임계값을 기본 25%에서 - 10–20%로 낮춰 보세요. 약한 후보와 함께 sidelobe 오검출도 늘 수 있으며, main lobe보다 - 가까운 같은 대역 음원은 conventional DAS에서 하나로 합쳐질 수 있습니다. + 먼저 50×50을 권장합니다. 100×100은 4배, 200×200은 16배의 scan point를 계산합니다. + 연산량 줄은 공통 STFT transform과 함께 DAS/DAS-PHAT의 complex MAC, 또는 GCC-PHAT의 + two-pass cross-spectrum·pair×band inverse FFT·scan correlation lookup을 분리해 + 표시합니다. 이는 실행 시간 예측값이 아니며 장치와 입력에 따라 달라집니다. 실행 중에는 + 취소할 수 있고, 취소하거나 실패해도 이전 완료 결과는 유지됩니다. +
++ 복수 음원에서 약한 peak가 빠지면 Peak 검출 임계값을 최강 map 값의 + 기본 25%에서 10–20%로 낮춰 보세요. 약한 후보와 함께 sidelobe 오검출도 늘 수 있으며, + main lobe보다 가까운 같은 대역 음원은 어느 알고리즘에서도 하나로 합쳐질 수 있습니다.
고급 설정에서 자유음장 또는 흡음·일반·반사 강한 실내 preset을 고릅니다. 실내 모델은 1차 반사, scattering, occluder 회절과 제한된 RT60 tail을 희소 경로로 근사합니다. - Array의 마이크 응답 curve는 수신 신호에 적용하며 DAS 역보정 유무를 비교할 수 있습니다. + Array의 마이크 응답 curve는 수신 신호에 적용하며 위치추정 역보정 유무를 비교할 수 있습니다. 값과 한계는 음향 모델 설명에서 확인하세요.
- 실제 동기식 마이크 채널은 Scene 합성 없이 portable CPU DAS에 넣을 수 있습니다.
+ 실제 동기식 마이크 채널은 Scene 합성 없이 portable CPU 위치추정 코어에 넣고
+ DAS·DAS-PHAT·GCC-PHAT를 선택할 수 있습니다.
장치별 channel·clock·transport adapter는 별도로 필요하며 실시간 deadline은 해당
장치에서 processingTimeMs ≤ deadlineMs와 miss·drop 누계로 확인해야
합니다. 포팅 설명서에 입력 형식, ring buffer,
@@ -163,19 +186,26 @@
Result JSON
- Camera에서 바꾼 Scene과 Experiment는 각각 저장할 수 있습니다. 완료 Result와 배열 비교 + Camera에서 바꾼 Scene과 Experiment는 각각 저장할 수 있습니다. 완료 Result와 비교 기록도 별도 JSON으로 저장하세요. 저장하지 않은 항목이나 실행 중인 계산이 있으면 페이지를 닫을 때 브라우저가 확인합니다.
@@ -213,7 +243,11 @@Backend를 Auto 또는 CPU로 두고 50×50 grid부터 실행하세요. 최신 Chrome/Edge와 그래픽 드라이버도 확인하세요.
+Backend를 Auto 또는 CPU로 두고 50×50 grid부터 실행하세요. GCC-PHAT는 원래 CPU 전용입니다. DAS/DAS-PHAT WebGPU를 쓴다면 최신 Chrome/Edge와 그래픽 드라이버도 확인하세요.
+각 band가 포함하는 FFT bin이 너무 적으면 PHAT 상관이 협대역 주기성에 민감해집니다. 필요한 신호 대역 안에서 band를 넓히거나 FFT size를 조정하세요.
micarrsim 1.0은 점 음원의 자유음장과 계산량을 제한한 shoebox 희소 경로, 마이크 - 주파수 응답과 conventional DAS를 제공합니다. 파동 방정식·고차 반사·재질별 흡음, - 복잡한 mesh, sensor self-noise·비선형, ADC·clock, DAMAS/CLEAN-SC와 자동 장치 - capture adapter는 포함하지 않습니다. 결과는 장비의 절대 성능 보증이 아니라 같은 - 조건에서 배열과 알고리즘을 비교하는 재현 가능한 기준입니다. + 주파수 응답과 DAS·DAS-PHAT·GCC-PHAT를 제공합니다. 파동 방정식·고차 반사·재질별 + 흡음, 복잡한 mesh, sensor self-noise·비선형, ADC·clock, DAMAS/CLEAN-SC 후처리와 + 자동 장치 capture adapter는 포함하지 않습니다. 실행할 수 없는 DAMAS/CLEAN-SC + placeholder는 Camera UI에서 제거했습니다. 결과는 장비의 절대 성능 보증이 아니라 + 같은 조건에서 배열과 알고리즘을 비교하는 재현 가능한 기준입니다.
원본 asset은 브라우저 메모리에서만 읽고 서버나 외부 네트워크로 보내지 않습니다. diff --git a/docs/realtime-porting.md b/docs/realtime-porting.md index e992b1a..9e1c37d 100644 --- a/docs/realtime-porting.md +++ b/docs/realtime-porting.md @@ -1,7 +1,7 @@ # 실측 다채널 위치추정 코어 포팅 `packages/acoustics-core/realtime-localizer.js`는 Scene 생성이나 음향 합성 없이 이미 sampling된 -동기식 마이크 채널을 conventional CPU DAS에 직접 넣는다. 브라우저 DOM과 외부 package에 +동기식 마이크 채널을 CPU DAS·DAS-PHAT·GCC-PHAT 위치 추정에 직접 넣는다. 브라우저 DOM과 외부 package에 의존하지 않는 ES module이므로, 실제 장치 adapter 뒤에 붙이거나 다른 프로젝트로 분리할 수 있다. 이 API는 ADC와 transport를 제어하지 않는다. 입력 channel을 획득·정렬·동기화한 다음 위치 map과 @@ -9,13 +9,16 @@ ## 최소 복사 단위 -직접 경로로 `realtime-localizer.js`를 import한다면 다음 여덟 파일과 상대 경로를 함께 +직접 경로로 `realtime-localizer.js`를 import한다면 다음 열한 파일과 상대 경로를 함께 복사하면 된다. ```text acoustics-core/ realtime-localizer.js + localization.js + localization-algorithms.js das.js + gcc-phat.js stft.js fft.js math.js @@ -24,8 +27,10 @@ acoustics-core/ evaluation.js ``` -`index.js`는 전체 core의 편의 export이므로 최소 포팅에는 필요하지 않다. 현재 portable API는 -CPU 기준 구현이며 Camera의 WebGPU worker나 Scene·propagation 모듈을 요구하지 않는다. +`index.js`는 전체 core의 편의 export이므로 최소 포팅에는 필요하지 않다. Portable API와 +`localization.js`의 analysis plan은 CPU 기준 구현이며 Camera의 WebGPU worker나 Scene·propagation +모듈을 요구하지 않는다. Camera backend 통합은 DAS와 DAS-PHAT에 WebGPU를 제공하지만 GCC-PHAT는 +CPU only다. GCC-PHAT에 명시적 WebGPU를 요청하면 오류가 나며 `auto`는 CPU를 선택한다. ## 입력 계약 @@ -68,6 +73,58 @@ const array = { `beamforming.maxCompensationDb`로 제한하며 기본 24 dB, 허용 범위 0–120 dB다. 응답 peak를 줄이는 attenuation과 phase 보상은 이 boost 상한에 의해 잘리지 않는다. +## 알고리즘 선택과 결과 scale + +Portable plan은 top-level `algorithm`으로 위치 추정기를 선택한다. 이 값을 생략하면 기존 동작과 +결과를 유지하는 `das`다. 기존 구성 형태인 `beamforming.algorithm`도 허용한다. + +| `algorithm` | 핵심 계산 | `rawScale` | portable backend | +| --- | --- | --- | --- | +| `das` | frequency-domain delay-and-sum | `power` | CPU | +| `das-phat` | phase-only spectrum을 steering하는 DAS | `score` | CPU | +| `gcc-phat` | 한 reference mic에 대한 `M-1`개 GCC-PHAT 지연 scan | `score` | CPU only | + +같은 array·scan·band·STFT로 알고리즘을 비교할 때도 알고리즘마다 별도 plan을 만든다. + +```js +const dasPlan = createLocalizationPlan({ + ...commonConfig, + algorithm: "das", +}); + +const dasPhatPlan = createLocalizationPlan({ + ...commonConfig, + algorithm: "das-phat", + phatRelativeFloor: 1e-6, +}); + +const gccPhatPlan = createLocalizationPlan({ + ...commonConfig, + algorithm: "gcc-phat", + phatFloorRatio: 1e-6, +}); +``` + +`phatRelativeFloor`는 DAS-PHAT의 channel spectrum 정규화 floor이고, `phatFloorRatio`는 +GCC-PHAT pair cross spectrum 정규화 floor다. 둘 다 해당 묶음의 최대 magnitude에 대한 0~1 +비율이며 기본값은 `1e-6`이다. GCC-PHAT는 `phatRelativeFloor`도 호환 alias로 받지만 새 코드에서는 +`phatFloorRatio`를 쓰는 편이 의미가 명확하다. 값을 키우면 낮은 magnitude 성분의 기여가 줄어들지만 +너무 크게 두면 유효한 broadband 정보도 약해질 수 있으므로 현장 데이터로 조정한다. + +각 band는 `rawScale`을 반환한다. `rawValue`는 scale에 관계없이 읽을 수 있는 canonical peak +값이다. `rawPower`는 `rawScale === "power"`, `rawScore`는 `rawScale === "score"`인 peak에만 +사용하는 편의 alias이며 두 필드가 항상 함께 있다고 가정하면 안 된다. `score`는 음향 power, +확률 또는 신뢰도가 아니라 동일 알고리즘·설정 안에서 상대 peak를 비교하는 비보정 값이다. +`power`도 capture amplitude와 calibration이 절대 단위로 교정되지 않았다면 W 또는 Pa²가 아니다. +GCC-PHAT의 raw score는 pair 수·band coefficient 수·IFFT 크기로 정규화한 0–1 양의 상관 응답이라 +scan 범위와 microphone 수 자체에 따른 척도 변화는 피하지만, 확률로 보정된 confidence는 아니다. + +GCC-PHAT에는 여러 FFT bin에 에너지가 있는 broadband 입력을 권장한다. Band당 8 bin 미만도 hard +error는 아니지만 단일 tone이나 좁은 band에서는 반복 correlation peak 때문에 위치가 모호할 수 있다. +Plan 생성 시 reference pair와 scan point에서 가능한 최대 절대 기하 지연을 계산하며, 이 값이 +`fftSize / 2` sample을 넘으면 circular alias를 막기 위해 거절한다. 더 큰 `fftSize`를 쓰거나 +배열·scan 기하를 줄여야 하며, 결과의 `maximumLagSamples`로 실제 상한을 기록할 수 있다. + ## 공통 계획 만들기 Array, scan grid, band와 STFT 설정이 바뀌지 않는 동안 계획을 한 번 만들고 재사용한다. @@ -94,6 +151,7 @@ const plan = createLocalizationPlan({ { id: "machine", minHz: 900, maxHz: 1100, color: "#65f2bf" }, ], stft: { fftSize: 512, hopSize: 256 }, + algorithm: "das", // "das" | "das-phat" | "gcc-phat" speedOfSound: 343, normalization: "peak", compensateFrequencyResponse: true, @@ -113,19 +171,63 @@ const plan = createLocalizationPlan({ - scan의 `columns`와 `rows`는 양의 정수 - `speedOfSound`는 양수 - `normalization`은 `peak` 또는 `none` +- `algorithm`은 `das`, `das-phat`, `gcc-phat` 중 하나 +- `phatRelativeFloor`와 `phatFloorRatio`는 지정한 경우 0–1 - `maxCompensationDb`는 0–120 dB - `peakDetection.thresholdRatio`는 0–1, `minimumPeakDistanceM`는 0 이상, `maximumDetections`는 1–128의 정수 -계획은 거리 행렬, bin calibration, 임시 map과 허용되는 경우 steering matrix를 유지하는 -stateful 객체다. 같은 계획으로 두 분석을 동시에 실행하지 말고, worker마다 별도 계획을 만든다. -Array·scan·band·STFT를 바꾸면 새 계획을 만들어야 한다. +계획은 알고리즘별 거리 행렬과 workspace를 유지하는 stateful 객체다. DAS 계열은 bin calibration, +임시 map과 허용되는 경우 steering matrix를 유지하고, GCC-PHAT는 reference mic 선택, +STFT·correlation workspace를 유지한다. 같은 계획으로 두 분석을 동시에 실행하지 말고 worker마다 +별도 계획을 만든다. Array·scan·band·STFT·알고리즘을 바꾸면 새 계획을 만들어야 한다. +Portable plan의 generic cache는 `plan.analysisPlan`이며 기존 호출자를 위해 DAS 계열에는 +`plan.dasPlan`, GCC-PHAT에는 `plan.gccPhatPlan` alias도 제공한다. -portable 계획의 기본 compute batch는 scan point 256개와 STFT transform 128개 단위로 event -loop에 양보한다. `computeOptions.pointBatchSize`와 -`computeOptions.stftTransformBatchSize`로 조정할 수 있지만, 큰 batch는 throughput과 -취소·UI 응답성의 trade-off가 있으므로 장치에서 함께 측정한다. +portable 계획의 기본 scan point batch는 DAS 계열 256개, GCC-PHAT 4,096개이고 STFT transform +batch는 128개다. GCC-PHAT cross-spectrum은 16,384 operation 단위로도 양보한다. 각 batch 경계에서 +event loop에 기회를 주며 `computeOptions.pointBatchSize`, +`computeOptions.stftTransformBatchSize`, `computeOptions.crossSpectrumBatchSize`로 조정할 +수 있다. 큰 batch는 throughput과 취소·UI 응답성의 trade-off가 있으므로 장치에서 함께 측정한다. + +낮은 수준에서 직접 사용할 때는 `localization.js`의 generic plan과 compute 함수를 짝지어 쓴다. +Plan compatibility는 값이 같은 새 객체가 아니라 생성할 때 넘긴 `arrayDefinition`, `scene`, +`experiment`의 정확히 같은 객체를 요구한다. + +```js +import { + computeLocalizationMap, + createLocalizationAnalysisPlan, +} from "./acoustics-core/localization.js"; + +const experiment = { + stft: { fftSize: 512, hopSize: 256, window: "hann" }, + scan, + frequencyBands: bands, + beamforming: { algorithm: "das-phat", normalization: "peak" }, +}; +const scene = { speedOfSound: 343 }; +const analysisPlan = createLocalizationAnalysisPlan({ + sampleRate: 48_000, + arrayDefinition: array, + scene, + experiment, +}); + +for (const channels of capturedBlocks) { + const result = await computeLocalizationMap({ + channels, + sampleRate: 48_000, + arrayDefinition: array, + scene, + experiment, + analysisPlan, + phatRelativeFloor: 1e-6, + }); + consume(result); +} +``` ## 한 블록 분석 @@ -144,22 +246,28 @@ const result = await localizeMultichannel({ }); for (const location of result.locations) { - console.log(location.bandId, location.position, location.rawPower); + console.log( + location.bandId, + location.position, + location.rawScale, + location.rawValue, + ); } ``` `result.locations`는 입력 band별 raw map의 local peak를 flat array로 담는다. 각 band -안에서는 power가 강한 순서이며 항목에는 `bandId`, band 내 `rank`, scan -`index`, `position`과 `rawPower`가 있다. 기본 threshold는 해당 band 최강 -peak의 50%, 최소 peak 간격은 scan cell 대각선, 최대 검출 수는 band당 8개다. 여러 대역을 -사용한다면 `bandId`로 묶어 해석한다. +안에서는 `rawValue`가 큰 순서이며 항목에는 `bandId`, band 내 `rank`, scan `index`, +`position`, `rawValue`, `rawScale`이 있다. DAS의 기존 `rawPower` 필드는 호환 alias로 유지된다. +Score 결과에서는 `rawValue`를 공통 필드로 읽고, `rawScore`가 포함된 peak 객체에서는 같은 값의 +score alias로 사용할 수 있다. 기본 threshold는 해당 band 최강 peak의 50%, 최소 peak 간격은 +scan cell 대각선, 최대 검출 수는 band당 8개다. 여러 대역을 사용한다면 `bandId`로 묶어 해석한다. `peakDetection`은 후처리 위치 목록만 바꾸며 `result.bands[n].rawMap`과 `displayMap`은 그대로 보존한다. 같은 대역의 두 음원이 main lobe보다 가까우면 local peak가 하나로 합쳐질 수 있고, threshold를 낮추면 sidelobe 후보도 늘 수 있다. `sampleCount`와 `duration`도 결과에 함께 반환된다. -Block 결과의 `processingTimeMs`는 DAS 계산과 local-peak 검출에 걸린 monotonic wall +Block 결과의 `processingTimeMs`는 선택한 위치 추정 계산과 local-peak 검출에 걸린 monotonic wall time이다. capture, adapter 변환과 결과 rendering 시간은 포함하지 않으므로 end-to-end latency는 호출자가 별도로 측정한다. @@ -168,13 +276,14 @@ time이다. capture, adapter 변환과 결과 rendering 시간은 포함하지 ## 연속 chunk 처리 -`StreamingDasLocalizer` 또는 같은 factory인 `createStreamingLocalizer`는 고정 용량 -ring buffer와 분석 workspace를 갖는다. +`StreamingLocalizer`는 알고리즘 중립 이름이며 기존 `StreamingDasLocalizer` class의 export alias다. +오래된 이름은 호환을 위해 유지된다. 두 이름과 `createStreamingLocalizer` factory는 모두 선택한 +`algorithm`에 맞는 고정 용량 ring buffer와 분석 workspace를 만든다. ```js -import { createStreamingLocalizer } from "./acoustics-core/realtime-localizer.js"; +import { StreamingLocalizer } from "./acoustics-core/realtime-localizer.js"; -const localizer = createStreamingLocalizer({ +const localizer = new StreamingLocalizer({ sampleRate: 48_000, array, scan: { @@ -190,6 +299,8 @@ const localizer = createStreamingLocalizer({ { id: "machine", minHz: 900, maxHz: 1100, color: "#65f2bf" }, ], stft: { fftSize: 512, hopSize: 256 }, + algorithm: "das-phat", + phatRelativeFloor: 1e-6, analysisWindowSamples: 4_800, analysisHopSamples: 2_400, maximumBufferedSamples: 19_200, @@ -224,6 +335,11 @@ async function analysisLoop(signal) { `deadlineMs = analysisHopSamples / sampleRate × 1000`과 `deadlineMet = processingTimeMs <= deadlineMs`를 반환한다. +`deadlineMet`는 완료된 한 창의 위치 추정 시간이 hop 예산 안이었는지를 나타내는 측정값이지, +해당 구성이 실시간이라는 사전 보장이 아니다. JIT warm-up, GC, 다른 thread의 부하를 포함해 목표 +장치에서 연속 실행을 측정해야 한다. 이 값은 capture·transport·rendering을 포함하지 않으므로 전체 +시스템 deadline은 adapter 경계에서 따로 계측한다. + ## 지연과 backpressure 조정 서로 다른 hop이 두 층에 있다. @@ -268,18 +384,42 @@ async function analysisLoop(signal) { 입력 retained byte는 `채널 수 × (maximumBufferedSamples + analysisWindowSamples) × 4`이며 할당 전에 검사한다. -계획은 거리 행렬, bin calibration, Hann window, Float64 FFT workspace와 임시 map을 재사용한다. -기본 retained data가 `maximumPlanBytes`를 넘으면 계획 생성을 거절한다. 전체 steering -matrix가 64 MiB 또는 계획 전체 한도를 넘으면 선택 bin 앞쪽부터 예산에 들어가는 만큼만 cache하고 -나머지는 고정 microphone workspace에서 필요할 때 계산한다. +모든 계획은 거리 행렬과 STFT workspace를 재사용한다. DAS 계열은 bin calibration, Hann window, +임시 map과 steering cache를, GCC-PHAT는 선택 bin metadata, reference mic와 correlation workspace를 +재사용한다. 기본 retained data가 `maximumPlanBytes`를 넘으면 할당 전에 계획 생성을 거절한다. +Plan 없는 GCC 단발 분석도 거리 행렬 할당 전에 전체 working set을 `maximumWorkingBytes`와 비교한다. +DAS의 전체 steering matrix가 64 MiB 또는 계획 전체 한도를 넘으면 선택 bin 앞쪽부터 예산에 들어가는 +만큼만 cache하고 나머지는 고정 microphone workspace에서 필요할 때 계산한다. -192채널, 50×50 scan, 선택 bin 2개를 같은 계획으로 10회 분석하는 기준에서 구현상 거리 계산은 +기존 DAS 호환 경로에서 192채널, 50×50 scan, 선택 bin 2개를 같은 계획으로 10회 분석하면 거리 계산은 4,800,000회에서 480,000회, steering point–microphone pair는 9,600,000회에서 960,000회로 줄어든다. 17,280,000회의 `sin/cos` 호출을 피하고 약 16.5 MiB를 유지한다. 자동 테스트는 부분 cache와 cache 없음의 raw/display `Float32` map 모든 원소가 bit-exact임을 확인한다. -각 결과의 `analysisCache`에는 cache된 bin capacity와 실제 cached/uncached 사용, -거리·steering pair, STFT transform·FFT butterfly·DAS complex MAC, workspace allocation·reuse -수가 들어가므로 설정별 최적화 효과를 계측할 수 있다. +각 결과의 `analysisCache`에는 공통 거리·STFT 통계와 알고리즘별 작업량이 들어간다. DAS 계열은 +cached/uncached steering pair, FFT butterfly와 complex MAC을, GCC-PHAT는 cross-spectrum +operation, pair별 IFFT, scan lookup과 correlation workspace reuse를 기록한다. + +연산량을 비교할 때 다음 기호를 사용한다. + +- `P`: scan point 수 +- `M`: microphone 수 +- `T`: 한 분석창의 STFT frame 수 +- `F`: 선택한 고유 FFT bin 수 +- `F_b`: band `b`의 bin 수, `B`: band 수 +- `N`: `fftSize` + +DAS와 DAS-PHAT의 지배적인 steering 누산은 대략 `P × M × T × F` complex MAC이다. PHAT +정규화가 추가되지만 scan 차수는 같다. GCC-PHAT는 모든 mic의 forward STFT를 한 번 수행한 뒤 +reference pair `M-1`개에 대해 다음 작업을 수행한다. + +- magnitude 최대값 pass와 PHAT 누산 pass: + `2 × (M-1) × T × ΣF_b` cross-spectrum operation +- 각 pair·band의 길이 `N` correlation IFFT: `(M-1) × B`회 +- 각 scan point의 fractional lag lookup: `P × (M-1) × B`회 + +따라서 GCC-PHAT의 scan lookup은 DAS의 `P × M × T × F`보다 작을 수 있지만 공짜는 아니다. +Forward STFT는 그대로 필요하고, 작은 grid·큰 `N`·많은 band에서는 pair별 IFFT나 2-pass cross +spectrum이 지배할 수 있다. `workload`와 실제 `processingTimeMs`를 함께 비교한다. 실시간 목표를 맞추는 조정 순서는 보통 다음과 같다. @@ -293,15 +433,15 @@ matrix가 64 MiB 또는 계획 전체 한도를 넘으면 선택 bin 앞쪽부 7. capture와 분석을 별도 Worker/thread에 두고 결과만 UI 또는 제어 loop로 전달한다. 캐시 최적화와 위 수치는 반복 계산 감소의 근거이지 192채널·50×50 또는 다른 구성이 실시간이라는 -보장이 아니다. 마이크 수, scan point, 선택 bin, STFT frame에 따른 주연산은 여전히 대략 -`O(P × M × F × T)`다. `deadlineMisses` 또는 `droppedSamples`가 누적되면 -grid·band bin·FFT/분석창 또는 update rate를 줄여야 한다. deadline은 위치추정 처리량 판정이며 -capture와 출력까지 포함하는 시스템 deadline은 adapter에서 별도로 검증한다. +보장이 아니다. `deadlineMisses` 또는 `droppedSamples`가 누적되면 grid·band bin·FFT/분석창 또는 +update rate를 줄여야 한다. 평균 한 번만 재지 말고 목표 장치의 실제 입력으로 warm-up 뒤 충분히 긴 +구간의 최대값과 상위 percentile을 측정한다. Capture와 출력까지 포함하는 시스템 deadline은 +adapter에서 별도로 검증한다. ## 취소와 오류 복구 `localizeMultichannel`과 `analyzeAvailable`에 `AbortSignal`을 전달하면 STFT와 -DAS batch 경계에서 `AbortError`를 발생시키고 계획 lock을 해제한다. +알고리즘별 scan/correlation batch 경계에서 `AbortError`를 발생시키고 계획 lock을 해제한다. Streaming 분석이 취소되거나 실패하면 `failedAnalyses`가 증가하지만 해당 hop을 소비하지 않는다. 실패한 창은 별도 analysis workspace에 보존되며, 다음 @@ -329,4 +469,4 @@ hop을 commit하고 sequence를 증가시킨다. 코어 뒤에서는 `locations`를 제어에 바로 쓰기 전에 현장 데이터로 검출 임계값, false peak, latency와 위치 오차를 검증해야 한다. 현재 `locations`는 통계적 신뢰구간이 아니라 각 band -DAS map에서 threshold와 거리 억제를 통과한 grid local peak 후보들이다. +위치 map에서 threshold와 거리 억제를 통과한 grid local peak 후보들이다. diff --git a/packages/acoustics-core/README.md b/packages/acoustics-core/README.md index c8c53d2..feb37d8 100644 --- a/packages/acoustics-core/README.md +++ b/packages/acoustics-core/README.md @@ -6,7 +6,55 @@ - 자유음장 직접음과 선택적 저비용 shoebox multipath - zero-padded FFT 전달함수 기반 fractional sample delay와 마이크 주파수 응답 - radix-2 FFT, Hann STFT와 선택 bin 추출 -- scan grid 거리 cache 및 conventional frequency-domain DAS +- scan grid 거리 cache 및 DAS·DAS-PHAT·GCC-PHAT 위치 추정 + +## 위치 추정 알고리즘 + +`localization-algorithms.js`의 registry와 `localization.js`의 generic API가 다음 세 경로를 +공통 interface로 제공합니다. + +| `algorithm` | 계산 | raw scale | backend | +| --- | --- | --- | --- | +| `das` | conventional frequency-domain delay-and-sum | `power` | CPU, WebGPU | +| `das-phat` | 채널 spectrum을 phase-only로 만든 DAS | `score` | CPU, WebGPU | +| `gcc-phat` | 하나의 reference mic와 나머지 mic의 GCC-PHAT 지연 scan | `score` | CPU only | + +Portable API에서는 top-level `algorithm`으로 선택합니다. 생략하면 기존과 같은 `das`이며, 낮은 +수준의 generic API는 `experiment.beamforming.algorithm`을 사용합니다. + +```js +import { + createLocalizationPlan, + localizeMultichannel, +} from "./packages/acoustics-core/realtime-localizer.js"; + +const plan = createLocalizationPlan({ + ...commonConfig, // sampleRate, array, scan, bands, stft + algorithm: "gcc-phat", // "das" | "das-phat" | "gcc-phat" + phatFloorRatio: 1e-6, +}); + +// 반복 분석에서도 같은 plan을 재사용합니다. +const result = await localizeMultichannel({ plan, channels }); +``` + +`das-phat`의 `phatRelativeFloor`와 `gcc-phat`의 `phatFloorRatio`는 모두 0~1의 상대 +크기 floor이며 기본값은 `1e-6`입니다. GCC-PHAT는 `phatRelativeFloor`도 호환 alias로 +받지만 새 코드에서는 알고리즘별 이름을 권장합니다. PHAT 경로는 mic gain을 위치 score에 +사용하지 않고 알려진 mic·frequency-response phase만 보정합니다. + +GCC-PHAT는 단일 tone보다 여러 FFT bin에 에너지가 있는 broadband 입력을 권장합니다. 하나의 +band에 선택된 bin이 8개 미만이면 코어는 계산을 허용하지만 주기적 모호성과 ghost peak를 직접 +검증해야 합니다. 또한 reference pair의 scan 전체 최대 절대 기하 지연이 `fftSize / 2` sample을 +넘으면 circular correlation alias를 피하기 위해 plan 생성을 거절합니다. 이때는 `fftSize`를 +늘리거나 배열·scan 기하를 조정합니다. + +각 band의 `rawScale`은 `power` 또는 `score`입니다. `rawValue`가 scale에 무관한 표준 peak +값이며, `rawPower`는 `power`, `rawScore`는 `score`일 때만 쓰는 편의 alias입니다. `score`는 +확률·신뢰도·SPL이 아니고 동일 알고리즘·설정 안에서 상대 peak를 비교하는 비교정 값입니다. +`power`도 입력과 calibration이 절대 단위로 교정되지 않았다면 물리적 W 또는 Pa²로 해석하지 않습니다. +GCC-PHAT score는 pair 수, band coefficient 수와 IFFT 크기로 정규화한 0–1 양의 상관 응답이라 +scan 범위와 마이크 수에 의한 단순 재척도화는 피하지만, 여전히 확률로 보정된 confidence는 아닙니다. ## 실측 다채널 스트림 위치 추정 @@ -15,6 +63,10 @@ 디렉터리를 그대로 복사해 사용할 수 있습니다. 채널 순서는 `array.microphones` 순서와 같아야 하고 각 chunk는 동일 길이의 `Float32Array` 목록이어야 합니다. +`StreamingLocalizer`는 알고리즘 중립 class 이름입니다. 기존 `StreamingDasLocalizer`와 같은 class의 +export alias이므로 오래된 import도 그대로 동작하며, `createStreamingLocalizer()` factory도 세 +알고리즘을 모두 지원합니다. + ```js import { createStreamingLocalizer } from "./packages/acoustics-core/realtime-localizer.js"; @@ -24,6 +76,7 @@ const localizer = createStreamingLocalizer({ scan: { xMin: -1, xMax: 1, yMin: -1, yMax: 1, z: 2, columns: 50, rows: 50 }, bands: [{ id: "machine", minHz: 900, maxHz: 1100, color: "#65f2bf" }], stft: { fftSize: 512, hopSize: 256 }, + algorithm: "das", // 호환 기본값. "das-phat" 또는 "gcc-phat"도 선택할 수 있습니다. maxCompensationDb: 24, peakDetection: { thresholdRatio: 0.5, maximumDetections: 8 }, analysisWindowSamples: 4_800, @@ -38,15 +91,17 @@ localizer.append(channels); // Analysis loop: 호출마다 설정된 상한 이하의 map만 반환합니다. const results = await localizer.analyzeAvailable({ signal: abortController.signal }); for (const result of results) { - const { position, rawPower } = result.locations[0]; - drawMarker(position, rawPower, result.centerTime); + const { position, rawValue, rawScale } = result.locations[0]; + drawMarker(position, rawValue, rawScale, result.centerTime); if (!result.deadlineMet) reportOverload(result.processingTimeMs, result.deadlineMs); } ``` -`locations`는 band 순서, 같은 band 안에서는 raw power 내림차순의 평평한 목록입니다. 각 항목은 -기존 `{ bandId, index, position, rawPower }`에 `rank`를 더하며 같은 band의 여러 local peak를 -포함할 수 있습니다. `peakDetection.thresholdRatio` 기본값은 최강 peak의 0.5배, +`locations`는 band 순서, 같은 band 안에서는 `rawValue` 내림차순의 평평한 목록입니다. 각 항목은 +`{ bandId, rank, index, position, rawValue, rawScale }`이며 같은 band의 여러 local peak를 포함할 +수 있습니다. 기존 DAS 결과의 `rawPower` 별칭은 그대로 유지됩니다. PHAT score는 `rawValue`와 +`rawScale`을 기준으로 읽고, score peak 객체에 포함된 경우 `rawScore`를 같은 값의 별칭으로 씁니다. +`peakDetection.thresholdRatio` 기본값은 최강 peak의 0.5배, `minimumPeakDistanceM` 기본값은 scan cell 대각선, `maximumDetections` 기본값은 8입니다. 기존처럼 `locations[0]`만 읽으면 최강 후보를 그대로 얻습니다. @@ -55,10 +110,13 @@ Streaming 계산이 중단되거나 실패하면 해당 분석창과 sequence를 `onResult` callback의 예외는 `failedAnalyses`에 포함하지 않습니다. 계산 중 capture overflow가 나면 ring의 오래된 sample은 평소와 같이 drop telemetry에 기록됩니다. -한 블록 결과의 `processingTimeMs`는 DAS와 local-peak 검출에 걸린 실제 시간을 기록합니다. Streaming +한 블록 결과의 `processingTimeMs`는 선택한 위치 추정 알고리즘과 local-peak 검출에 걸린 실제 시간을 +기록합니다. Streaming 결과는 `deadlineMs = analysisHopSamples / sampleRate × 1000`과 `deadlineMet`을 더하며, `getState()`는 최근/최대 처리 시간과 `deadlineMisses` 누계를 제공합니다. `deadlineMisses` 또는 `droppedSamples`가 증가하면 grid·대역 bin·분석창·update rate를 장치 성능에 맞게 줄여야 합니다. +이 deadline 비교는 실시간 성능 보장이 아니라 완료된 창의 측정값입니다. 목표 장치에서 warm-up을 거친 +지속 부하를 직접 측정하고, capture·adapter·출력을 포함한 end-to-end deadline은 별도로 검증해야 합니다. 깊은 응답 notch의 역필터가 sensor noise까지 폭증시키지 않도록 inverse response의 양의 boost는 기본 24 dB로 제한합니다. Experiment의 `beamforming.maxCompensationDb` 또는 portable plan의 top-level @@ -71,16 +129,27 @@ cache가 나중에 `maximumPlanBytes`를 넘지 않습니다. buffer byte 수를 돌려주므로 capture adapter가 지연을 감시할 수 있습니다. 실제 장치의 clock, channel framing과 transport는 하드웨어별 adapter 책임이며 이 모듈은 그 다음 단계부터 시작합니다. -반복 CPU 분석 계획은 거리 행렬, bin calibration, Hann window, Float64 FFT workspace, 임시 bin map과 -예산 내의 Float64 steering matrix를 재사용합니다. 예를 들어 192채널·50×50·2 bins를 10회 분석하면 +반복 CPU 분석 계획은 공통 거리 행렬과 STFT workspace를 재사용합니다. DAS 계열은 bin calibration, +Hann window, 임시 bin map과 예산 내의 Float64 steering matrix를, GCC-PHAT는 reference 선택과 +correlation workspace를 추가로 유지합니다. 같은 plan을 동시에 두 분석에 쓰지 말고 설정이나 알고리즘이 +바뀌면 새 plan을 만듭니다. 예를 들어 DAS로 192채널·50×50·2 bins를 10회 분석하면 거리 계산은 4,800,000회에서 480,000회로, steering point/microphone pair는 9,600,000회에서 960,000회로 줄어듭니다(sin/cos 호출 17,280,000회 회피). 이 경우 약 16.5 MiB를 유지합니다. 기본 64 MiB보다 전체 wide-band steering matrix가 크더라도 cache 전체를 끄지 않습니다. 선택 bin 앞쪽부터 예산에 들어가는 만큼만 Float64로 유지하고 나머지는 고정 microphone workspace에서 계산합니다. -`analysisCache`는 cached bin capacity, uncached 사용 횟수·pair 수, STFT transform·FFT butterfly·DAS -complex MAC 수와 실제 workspace allocation/reuse 수를 제공합니다. 자동 테스트는 부분 cache와 -cache 없음 사이 raw/display Float32 map의 전 요소 bit-exact 일치를 고정합니다. +`analysisCache`는 알고리즘별 실제 작업을 제공합니다. DAS 계열은 cached bin capacity, +uncached steering pair, STFT transform·FFT butterfly·complex MAC을, GCC-PHAT는 STFT/IFFT, +2-pass cross-spectrum operation, scan lookup과 correlation workspace reuse를 기록합니다. + +`P`를 scan point 수, `M`을 mic 수, `T`를 STFT frame 수, `F`를 선택한 고유 bin 수, +`B`를 band 수, `N`을 `fftSize`라 하면 DAS의 주 scan 연산은 대략 +`P × M × T × F` complex MAC입니다. GCC-PHAT는 forward STFT에 더해 reference pair `M-1`개마다 +band bin을 두 번 순회하는 cross spectrum, `(M-1) × B`회의 길이 `N` IFFT, +`P × (M-1) × B`회의 fractional correlation lookup을 수행합니다. band별 bin 수를 `F_b`라 하면 +cross-spectrum 항목 수는 구현의 두 pass를 포함해 `2 × (M-1) × T × ΣF_b`입니다. 따라서 GCC가 +scan MAC을 줄여도 작은 grid에서는 forward STFT와 pair별 IFFT가 전체 시간을 지배할 수 있으므로 +두 알고리즘 모두 실제 목표 장치에서 측정해야 합니다. ## 이동 음원과 분석 시간창 @@ -94,25 +163,30 @@ seed 기반 noise index, audio asset 재생 위치와 ambient가 전체 timeline ## Beam spread 의미 -Peak의 `beamSpread`는 half-power 연결 성분을 power 가중한 공간 covariance(`covarianceM2`, m²)와 그 -RMS 주축 ellipse로 요약한 빔 폭입니다. 가우시안 확률 모델, 위치 확률 또는 신뢰구간으로 보정된 값이 -아니며 `calibrated: false`를 유지합니다. +Peak의 `beamSpread`는 raw map의 peak 주변 연결 성분을 가중한 공간 covariance(`covarianceM2`, m²)와 +그 RMS 주축 ellipse로 요약한 폭입니다. `power` map은 half-power/power-weighted, +`score` map은 half-maximum/score-weighted 규칙을 사용합니다. 어느 쪽도 가우시안 확률 모델, +위치 확률 또는 신뢰구간으로 보정된 값이 아니며 `calibrated: false`를 유지합니다. FFT는 `X[k] = Σ x[n] exp(-j2πkn/N)` 규약을 사용합니다. 마이크 신호의 전파 phase `exp(-j2πfr/c)`를 정렬하기 위해 DAS steering은 `exp(+j2πfr/c)`를 곱합니다. 단일 tone의 ground-truth 위치에서 peak가 생기는 회귀 테스트로 이 부호를 고정합니다. -마이크 `sensitivityDb`와 `phaseOffsetDeg`는 수신 channel에 편차로 적용하고, DAS에서는 알려진 -calibration 값의 역 gain/phase로 보정합니다. raw power map과 표시용 normalized map은 서로 다른 -buffer로 보존합니다. bin spectrum은 제한된 batch로 처리합니다. cooperative yield는 지원 환경에서 +마이크 `sensitivityDb`와 `phaseOffsetDeg`는 수신 channel에 편차로 적용합니다. Conventional DAS는 +알려진 calibration의 역 gain/phase를 모두 보정하고, DAS-PHAT와 GCC-PHAT는 amplitude gain을 무시한 +채 알려진 phase만 보정합니다. raw `power`/`score` map과 표시용 normalized map은 서로 다른 buffer로 +보존합니다. bin spectrum은 제한된 batch로 처리합니다. cooperative yield는 지원 환경에서 `scheduler.yield()`, 그 외에는 `MessageChannel`을 사용하고 timer task에도 주기적으로 기회를 주므로 진행 callback과 `AbortSignal` 취소를 유지하면서 연속 `setTimeout(0)` clamp를 피합니다. portable -plan의 기본 batch는 point 256개·STFT transform 128개이며 `computeOptions`로 조정할 수 있습니다. +plan의 기본 point batch는 DAS 계열 256개, GCC-PHAT 4,096개이고 STFT transform batch는 +128개입니다. GCC-PHAT의 두 cross-spectrum pass도 16,384 operation마다 양보합니다. +`pointBatchSize`, `stftTransformBatchSize`, `crossSpectrumBatchSize`를 +`computeOptions`로 조정할 수 있습니다. 마이크별 `frequencyResponse`는 2~64개의 `{ frequencyHz, gainDb, phaseDeg? }` 점으로 정의합니다. `interpolateFrequencyResponse`는 dB와 wrapped phase를 구간 선형 보간하고 측정 범위 밖에서는 가장 -가까운 끝점을 사용합니다. 합성 시 기존 sensitivity/phase 편차에 이 응답을 추가하며, CPU DAS는 -선택 FFT bin의 역응답을 calibration/steering cache에 포함합니다. WebGPU 경로는 GPU 전송 직전의 +가까운 끝점을 사용합니다. 합성 시 기존 sensitivity/phase 편차에 이 응답을 추가하며, CPU 위치 추정은 +선택 FFT bin의 알고리즘별 역응답을 calibration에 포함합니다. WebGPU DAS 계열 경로는 GPU 전송 직전의 packed STFT에 같은 역응답을 적용합니다. `beamforming.compensateFrequencyResponse: false`는 sensitivity/phase 보정은 유지한 채 곡선 보정만 꺼 robustness 비교를 재현합니다. @@ -143,6 +217,9 @@ Scene의 `acoustics`를 생략하거나 `{ "model": "free-field" }`로 두면 snapshot 합성은 전체 signal과 가장 늦은 sparse path를 포함하는 delay FFT working set을 512 MiB로 제한합니다. 실측·장시간 입력은 위 streaming localizer의 bounded ring buffer로 전체 녹음을 메모리에 보관하지 않고 처리할 수 있습니다. CPU analysis plan도 기본 512 MiB -hard cap을 할당 전에 검사하며 steering cache는 별도의 64 MiB 안에서 가능한 bin만 유지합니다. +hard cap을 할당 전에 검사합니다. DAS steering cache는 별도의 64 MiB 안에서 가능한 bin만 유지하고, +GCC-PHAT는 거리·STFT·correlation workspace 전체를 plan 한도 안에서 검사합니다. Plan 없는 단발 +GCC 분석도 거리 행렬을 만들기 전에 spectrum·calibration·output을 포함한 working set을 preflight합니다. -192채널·50×50 fixture는 브라우저 통합 테스트에서 실제 합성부터 DAS peak 검출까지 실행합니다. +192채널·50×50 fixture는 기존 DAS 호환 경로를 실제 합성부터 peak 검출까지 고정하며, 별도의 결정적 +회귀 fixture가 DAS-PHAT와 GCC-PHAT의 score scale·lag 부호·plan 재사용을 검사합니다. diff --git a/tests/integration/README.md b/tests/integration/README.md index dd0ebf9..03efcf5 100644 --- a/tests/integration/README.md +++ b/tests/integration/README.md @@ -17,13 +17,14 @@ Unit과 integration test가 같은 페이지에서 실행됩니다. WebGPU 장 ## 범위 - `cpu-baseline.test.js`: 192채널·50×50 synthetic fixture의 CPU DAS와 위치 기준 -- `webgpu.test.js`: 실제 adapter가 있으면 CPU/GPU map 오차, peak와 강제 bin/point batching; +- `webgpu.test.js`: 실제 adapter가 있으면 DAS·DAS-PHAT CPU/GPU map 오차, peak와 강제 bin/point batching; adapter가 없으면 Auto CPU fallback - `server.test.js`: 숨김 저장소 경로 차단, GET/HEAD 제한과 보안 response headers - `builder-ui.test.js`: 파일 선택 한 번으로 오디오 음원 생성, 이미지·오디오 연결, canvas 편집, trajectory keyframe 편집, Preview WAV/Scene 다운로드, SHA 재연결과 잘못된 import 보존 -- `camera-ui.test.js`: Dedicated Worker CPU/WebGPU 실행, 취소, Result schema, rectangular/Fermat 비교; - 이동 예제 로드, 8×8 CPU·2 Hz live map 준비, 복수 frame, scrub, 재생 시간 증가와 일시정지 +- `camera-ui.test.js`: Dedicated Worker CPU/WebGPU 실행, 취소, Result schema, rectangular/Fermat와 + DAS/DAS-PHAT 비교, GCC-PHAT CPU·협대역 제약; 이동 예제 로드, 8×8 CPU·2 Hz live map의 + Auto→CPU fallback 뒤 공통 analysis plan 재사용, 복수 frame, scrub, 재생 시간 증가와 일시정지 - `workflow-ui.test.js`: Dataset Builder의 Scene JSON과 원본 assets를 Acoustic Camera에 넘겨 Result JSON을 저장하는 end-to-end 흐름 diff --git a/tests/unit/README.md b/tests/unit/README.md index 5648586..7ab6c6c 100644 --- a/tests/unit/README.md +++ b/tests/unit/README.md @@ -17,16 +17,22 @@ Unit과 integration module은 같은 browser runner에서 순서대로 실행됩 ## 범위 -- `contracts.test.js`: Array·Scene·Experiment·Result schema, 관계 검증, 안전한 asset 경로와 이동 fixture +- `contracts.test.js`: Array·Scene·Experiment·Result schema, algorithm·scale·beam-spread 관계 검증, + 안전한 asset 경로와 이동 fixture - `acoustics.test.js`: seed 재현성, 자유음장 전파, trajectory 보간, sample 정렬 시간창과 - tone/noise/asset 절대 시간 연속성, calibration, STFT와 CPU DAS + tone/noise/asset 절대 시간 연속성, calibration, STFT, CPU DAS와 DAS-PHAT +- `gcc-phat.test.js`: reference 선택, near-field lag 부호, 광대역 source peak, alias·메모리 + 선할당 제한, 0–1 score bound·scan 범위 불변성과 geometry/STFT/IFFT workspace 재사용 +- `localization.test.js`: 알고리즘 registry와 generic CPU/backend dispatcher, power/score + 의미, portable GCC-PHAT block·streaming 경로 - `realtime-localizer.test.js`: 기존 CPU DAS와 bit-exact map 동등성, chunk 경계 독립성, bounded ring/result batch, 취소와 geometry·steering cache 연산 절감 - `builder.test.js`: Builder scene model, source/asset·trajectory 조작, 오디오 크기와 WAV 사전 검증 - `evaluation.test.js`: local peak와 검출 감도, truth matching, energy/sidelobe/main-lobe 및 비확률적 beam-spread covariance ellipse - `camera.test.js`: canonical input hash, workload 추정, 이동 timeline 계획·재생 보간, Result schema 검증 -- `webgpu.test.js`: WGSL buffer packing, bin/point batching, 장치 한계와 typed CPU fallback 정책 +- `webgpu.test.js`: WGSL buffer packing, DAS-PHAT phase normalization, bin/point batching, + 장치 한계와 typed CPU fallback 정책 WebGPU unit test 대부분은 실제 GPU 없이 planner와 binary layout을 검증합니다. 실제 GPU 수치 일치는 integration test에서 adapter가 있을 때 수행합니다.