docs: explain full-band activity workflow

docs/activity-detection.md

@@ -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만 반환하지 않고
+신호 합성 전에 실패한다.