docs: explain full-band activity workflow

2026-08-29 14:03:38 +09:00
parent 51e346a477
commit 764cf28cf8
9 changed files with 252 additions and 19 deletions
@@ -4,6 +4,28 @@
 의미와 한계를 정의한다. 검출기는 Scene의 음원 주파수·위치·개수를 입력으로 받지
 않으며, 검출 결과를 위치 정답이나 분석 대역으로 자동 변환하지 않는다.

+## Camera에서 가장 짧은 사용 순서
+
+1. Acoustic Camera의 분석 대역 아래 **전 대역 활동 검사**를 펼친다.
+2. 한 물리 마이크와 OS-CFAR, CA-CFAR 또는 Dixon spectral flux를 고른다.
+3. **전 대역 검사**를 실행하고 frame의 raw 통계와 실제 판정 가능 시각
+   <code>available</code>을 확인한다.
+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은 이 경계를
+<code>sceneSourceTruthUsedByPhysicalSimulator: true</code>와
+<code>sceneSourceTruthPassedToDetector: false</code>로 구분한다.
+
+Report는 source ID와 source별 도착 목록을 내보내지 않지만, 적용한 음향 모델,
+종류별 path 수와 최대 지연 같은 집계 physical audit는 남긴다. 이 값은 source에서
+파생된 정보이므로
+<code>sourceDerivedAggregatePhysicalAuditIncluded: true</code>라고 명시한다.
+Detector 판정 입력과 사후 감사 metadata를 같은 의미로 부르지 않는다.
+
+Scene mix가 peak normalization이면 선택한 한 채널의 **전체 render peak**로 먼저
+scale한다. 선택하지 않은 마이크에는 의존하지 않지만 미래 sample에는 의존한다.
+따라서 detector는 주어진 sample 이후 causal이어도 raw flux와 절대 delta event를
+포함한 end-to-end 전처리는 causal이 아니다. 이 경우 UI와 JSON의
+<code>futureDependentNormalization</code>이 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만 반환하지 않고
+신호 합성 전에 실패한다.
@@ -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는 <code>schemaVersion: "1.0.0"</code>,
+<code>kind: "micarrsim.activity-report"</code>인 편의 감사 문서다. 최상위에는 실제 실행
+Array·Scene·Experiment ID, 생성 시각과 64자리 SHA-256 <code>inputHash</code>가 있고,
+<code>report</code>에는 다음 값이 있다.
+
+- 사용자가 선택한 원래 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의 <code>untested</code> bin과 zero-threshold
+ratio 상태도 삭제하지 않는다. Typed array는 JSON 숫자 배열로 변환하고 비유한 수가 생기면
+문자열 <code>Infinity</code>, <code>-Infinity</code> 또는 <code>NaN</code>으로 명시한다.
+
+Activity <code>inputHash</code>는 검출에 실제로 사용한 선택 마이크, 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 사전순으로 재귀
@@ -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 재연결 왕복 테스트
@@ -17,6 +17,7 @@
      <nav aria-label="문서 목차">
        <a href="#quick-start">빠른 시작</a>
        <a href="#moving-live">이동 라이브</a>
+        <a href="#activity">전 대역 검사</a>
        <a href="#array-builder">배열 만들기</a>
        <a href="#full-workflow">내 데이터</a>
        <a href="#acoustic-model">환경·실측</a>
@@ -71,8 +72,29 @@
        </div>
      </section>

-      <section class="guide-section" id="array-builder">
+      <section class="guide-section" id="activity">
        <div class="section-number">03</div>
+        <div>
+          <p class="eyebrow">Unknown-frequency activity</p>
+          <h2>분석 주파수를 모를 때</h2>
+          <ol class="guide-steps">
+            <li><a href="/apps/acoustic-camera/">Acoustic Camera</a>의 분석 대역 아래 <strong>전 대역 활동 검사</strong>를 펼칩니다.</li>
+            <li>한 물리 마이크와 OS-CFAR·CA-CFAR 또는 Dixon spectral flux를 고르고 <strong>전 대역 검사</strong>를 누릅니다.</li>
+            <li>CFAR candidate의 ADC bin과 raw CUT/reference/threshold를 확인합니다. Spectral flux는 onset novelty만 봅니다.</li>
+            <li>아날로그 center 가설을 직접 입력해 별도 band로 추가한 뒤 Snapshot 위치추정을 실행합니다.</li>
+            <li>모든 complete frame/bin은 <strong>Activity JSON</strong>으로 저장합니다.</li>
+          </ol>
+          <aside class="callout callout--important">
+            Nyquist 초과 가설도 허용하지만 Scene truth로 원 주파수를 고르지 않습니다.
+            CFAR Pfa는 tested CUT 하나당 명목값이고 spectral flux는 확률이 아닙니다.
+            검출기·band·위치 map의 자동 fusion도 하지 않습니다.
+            <a href="/docs/activity-detection.md">수식과 물리적 한계</a>를 함께 확인하세요.
+          </aside>
+        </div>
+      </section>
+
+      <section class="guide-section" id="array-builder">
+        <div class="section-number">04</div>
        <div>
          <p class="eyebrow">Microphone geometry</p>
          <h2>내 마이크 배열 만들기</h2>
@@ -95,7 +117,7 @@
      </section>

      <section class="guide-section" id="full-workflow">
-        <div class="section-number">04</div>
+        <div class="section-number">05</div>
        <div>
          <p class="eyebrow">5분 전체 흐름</p>
          <h2>내 장면을 만들고 Camera에서 실행하기</h2>
@@ -145,7 +167,7 @@
      </section>

      <section class="guide-section">
-        <div class="section-number">05</div>
+        <div class="section-number">06</div>
        <div>
          <p class="eyebrow">Localization &amp; compute</p>
          <h2>알고리즘, 속도와 격자 선택</h2>
@@ -194,7 +216,7 @@
      </section>

      <section class="guide-section" id="acoustic-model">
-        <div class="section-number">06</div>
+        <div class="section-number">07</div>
        <div>
          <p class="eyebrow">Acoustics & measured input</p>
          <h2>환경과 마이크 응답 선택</h2>
@@ -216,7 +238,7 @@
      </section>

      <section class="guide-section" id="results">
-        <div class="section-number">07</div>
+        <div class="section-number">08</div>
        <div>
          <p class="eyebrow">Result JSON</p>
          <h2>무엇이 저장되나요?</h2>
@@ -256,7 +278,7 @@
      </section>

      <section class="guide-section" id="troubleshooting">
-        <div class="section-number">08</div>
+        <div class="section-number">09</div>
        <div>
          <p class="eyebrow">Troubleshooting</p>
          <h2>막혔을 때 확인할 것</h2>
@@ -296,7 +318,7 @@
      </section>

      <section class="guide-section">
-        <div class="section-number">09</div>
+        <div class="section-number">10</div>
        <div>
          <p class="eyebrow">Scope & privacy</p>
          <h2>현재 모델의 범위</h2>
@@ -320,6 +342,7 @@
        <a href="/apps/array-builder/README.md"><strong>Array Builder 설명서</strong><span>마이크 배치·프리셋·JSON</span></a>
        <a href="/apps/dataset-builder/README.md"><strong>Dataset Builder 설명서</strong><span>source·ambient·Preview WAV</span></a>
        <a href="/apps/acoustic-camera/README.md"><strong>Camera 설명서</strong><span>backend·결과·비교</span></a>
+        <a href="/docs/activity-detection.md"><strong>전 대역 활동 검출</strong><span>CFAR·spectral flux·alias 가설</span></a>
        <a href="/docs/acoustic-model.md"><strong>음향 모델</strong><span>마이크 응답·반사·산란·회절</span></a>
        <a href="/docs/realtime-porting.md"><strong>실측 포팅</strong><span>block·streaming 위치추정 API</span></a>
        <a href="/docs/data-contracts.md"><strong>데이터 계약</strong><span>JSON Schema와 재현성</span></a>