docs: explain receive beam pattern workflow

README.md

@@ -111,7 +111,9 @@ causal latency는 [전 대역 활동 검출 모델](docs/activity-detection.md)
    seed로 같은 좌표를 재현하며, 최소 간격과 경계 여백도 지정할 수 있습니다.
 4. **추가** 도구로 canvas에 마이크를 놓고, 선택한 점을 드래그하거나 x/y/z 입력으로 수정합니다.
    목록에서는 삭제와 채널 순서 변경도 할 수 있습니다.
-5. 상태가 **Array JSON 저장 가능**이면 **Array JSON 저장**을 누릅니다.
+5. canvas 아래 **수신 빔 패턴**에서 아날로그 주파수·360° 절단면·조향각을 바꿔 polar 응답과
+   조건부 −3.0103 dB 폭, sampled peak 동률을 확인합니다.
+6. 상태가 **Array JSON 저장 가능**이면 **Array JSON 저장**을 누릅니다.
 
 불러온 Array의 `sensitivityDb`, `phaseOffsetDeg`, `frequencyResponse` 보정 정보는 마이크 위치·ID나
 채널 순서를 편집해도 보존됩니다. 프리셋 생성은 마이크 목록 전체를 새로 만드는 작업이므로 기존
@@ -119,6 +121,7 @@ causal latency는 [전 대역 활동 검출 모델](docs/activity-detection.md)
 
 생성 경계 형상, 프리셋 종류, random seed와 최소 간격은 편집을 돕는 설정이며 표준 Array JSON에
 저장되지 않습니다. 저장되는 것은 aperture 너비·높이와 최종 마이크 좌표·순서 및 채널별 보정값입니다.
+빔 패턴 주파수·절단면·조향각도 preview 설정이므로 Array JSON과 undo/dirty 상태에 들어가지 않습니다.
 자세한 사용법은 [`apps/array-builder/README.md`](apps/array-builder/README.md)를 참고하세요.
 
 ### 2. Dataset Builder에서 Scene 만들기
@@ -340,6 +343,9 @@ Camera의 **배열 선택**에서 8개 fixture를 바로 불러와 같은 Scene/
 의도된 예제 특성입니다.
 새 배치를 직접 만들려면 [Array Builder](apps/array-builder/README.md)를 사용하세요. 저장소 fixture의
 상세한 생성법은 [`assets/array-geometries/README.md`](assets/array-geometries/README.md)를 참고하세요.
+Array Builder는 현재 배치의 geometry-only conventional receive array factor를 XZ·YZ·XY 360°
+polar 단면으로 즉시 표시합니다. 이 계산은 ADC sample rate 없이 원 아날로그 파장을 사용하므로
+Nyquist 초과 조건도 실행하며, 각도 해상도가 부족하면 raw 선을 남긴 채 HPBW·peak 해석을 보류합니다.
 
 ## 테스트와 benchmark
 
@@ -362,6 +368,7 @@ test.cmd
 ## 저장 형식과 개발 문서
 
 - [전 대역 활동 검출 모델](docs/activity-detection.md): CA/OS-CFAR, spectral flux와 alias 가설 흐름
+- [수신 빔 패턴 모델](docs/beam-pattern.md): array factor 수식, polar 단면, HPBW와 해상도 기준
 - [`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 포팅

apps/array-builder/README.md

@@ -2,7 +2,8 @@
 
 Array Builder는 `micarrsim.array` JSON을 브라우저에서 만드는 마이크 배열 편집기입니다. aperture
 크기와 생성 경계를 정한 뒤 프리셋으로 시작하거나 마이크를 직접 추가·이동해 Acoustic Camera의
-배열 입력으로 사용할 수 있습니다.
+배열 입력으로 사용할 수 있습니다. 같은 화면에서 현재 좌표의 narrowband far-field 수신 빔 패턴도
+확인할 수 있습니다.
 
 ## 열기
 
@@ -15,8 +16,9 @@ Array Builder는 `micarrsim.array` JSON을 브라우저에서 만드는 마이
 1. **크기와 형상**에서 aperture 너비·높이와 생성 경계를 정합니다.
 2. 프리셋을 고르고 **현재 배열을 프리셋으로 교체**를 누릅니다.
 3. canvas와 마이크 목록에서 좌표와 채널 순서를 다듬습니다.
-4. 상태가 **Array JSON 저장 가능**인지 확인하고 **Array JSON 저장**을 누릅니다.
+4. canvas 아래 **수신 빔 패턴**에서 주파수·절단면·조향각에 따른 main lobe와 동률 응답을 확인합니다.
-5. Acoustic Camera를 열어 **Array** 입력에서 저장한 `.array.json`을 선택합니다.
+5. 상태가 **Array JSON 저장 가능**인지 확인하고 **Array JSON 저장**을 누릅니다.
+6. Acoustic Camera를 열어 **Array** 입력에서 저장한 `.array.json`을 선택합니다.
 
 ## 크기와 생성 경계
 
@@ -65,6 +67,32 @@ Array JSON을 저장하세요.
 `JSON 열기`로 다른 배열을 불러온 직후에도 한 번 실행 취소하면 불러오기 전 문서를 복구할 수
 있습니다. 다시 실행하면 불러온 배열로 돌아갑니다.
 
+## 수신 빔 패턴
+
+배열 canvas 아래의 분석 카드는 ideal calibrated omnidirectional point microphone에 conventional
+delay-and-sum을 적용한 geometry-only receive array factor를 표시합니다.
+
+- **아날로그 주파수:** ADC bin이나 alias 주파수가 아닌 실제 음향 주파수입니다. 1 MHz까지
+  입력할 수 있으며 sample rate가 없으므로 Nyquist를 넘어도 원래 파장을 사용합니다.
+- **절단면:** XZ는 0°=+Z·90°=+X, YZ는 0°=+Z·90°=+Y, XY는 0°=+X·90°=+Y입니다.
+- **조향각:** 선택한 360° great-circle 단면 안에서 conventional beamformer가 보는 방향입니다.
+- **각도 샘플:** 자동은 투영 aperture와 파장에 맞춰 최소 720개에서 늘립니다. 고정 sample은
+  계산량 비교나 일부러 coarse한 설계 조건을 확인할 때 사용합니다.
+- **표시 하한:** polar dB radius에만 적용됩니다. raw complex·power와 HPBW는 바뀌지 않습니다.
+
+마이크를 드래그하는 동안 최대 720-angle preview를 갱신하고 놓으면 선택한 해상도로 다시 계산합니다.
+π/8 인접 pair phase-step 기준을 넘으면 raw polar 선은 유지하되 HPBW와 peak 해석을 **해상도
+부족**으로 보류합니다. 기준을 만족한다는 것은 공개된 sampling 정책을 통과했다는 뜻이며 모든 연속
+lobe 검출을 보장하지 않습니다.
+
+−3.0103 dB 폭은 조향 lobe의 sampled bracket을 찾은 경우에만 표시합니다. sampled local maximum은
+모두 나열하고 0 dB 동률을 임의로 하나 고르지 않지만, 이를 grating lobe나 sidelobe로 자동 분류하지
+않습니다. plot은 3D 전체가 아니라 선택한 단면이고 near-field, 방·하우징·element directivity와
+마이크 frequency response는 포함하지 않습니다.
+
+수식, raw 결과 필드, workload 상한과 상태 의미는
+[`../../docs/beam-pattern.md`](../../docs/beam-pattern.md)에 정리되어 있습니다.
+
 ## 보정값 보존
 
 선택한 채널의 `sensitivityDb`와 `phaseOffsetDeg`는 보정값 펼침 영역에서 편집할 수 있습니다. 기존
@@ -84,8 +112,8 @@ frequency response도 함께 제거됩니다.
 - 채널별 선택적 sensitivity, phase와 frequency-response curve
 
 생성 경계의 사각형/타원 선택, 프리셋 종류, 행·열, random seed·최소 간격·경계 여백, snap과
-zoom은 편집기 설정입니다. 표준 Array JSON에는 저장되지 않으며 Camera는 최종 aperture와 실제
+zoom, 빔 패턴 주파수·절단면·조향각·표본 수는 편집기 설정입니다. 표준 Array JSON에는 저장되지
-마이크 좌표·순서를 사용합니다.
+않으며 Camera는 최종 aperture와 실제 마이크 좌표·순서를 사용합니다.
 
 ## Camera로 전달하기
 
@@ -94,8 +122,9 @@ zoom은 편집기 설정입니다. 표준 Array JSON에는 저장되지 않으
 3. 입력 준비의 **Array**에서 저장한 파일을 선택합니다.
 4. 채널 수와 aperture 요약을 확인한 뒤 Scene과 Experiment를 준비해 실행합니다.
 
-Experiment를 별도 파일로 가져올 때는 그 문서의 `arrayId`가 방금 불러온 Array ID와 같아야 합니다.
+Experiment의 `arrayId`는 provenance label이라 불러온 Array의 `id`와 달라도 실행을 막거나
-Camera에서 배열 선택이 **불러온 Array JSON**으로 바뀌고 입력 검증이 통과했는지 확인하세요.
+경고하지 않습니다. Camera에서 배열 선택이 **불러온 Array JSON**으로 바뀌고 채널 수·좌표가 의도한
+배열인지 직접 확인하세요.
 
 ## 검증과 제한
 

docs/beam-pattern.md

@@ -0,0 +1,130 @@
+# 마이크 어레이 수신 빔 패턴
+
+Array Builder의 **수신 빔 패턴**은 현재 마이크 좌표에 conventional delay-and-sum을 적용했을 때의
+narrowband far-field array factor를 360° polar 단면으로 보여줍니다. 마이크는 송신원이 아니므로
+엄밀히는 방사 패턴이 아니라 **수신 응답**입니다.
+
+## 가장 짧은 사용법
+
+1. Array Builder에서 마이크 배치를 만들거나 Array JSON을 엽니다.
+2. 배열 canvas 아래의 **수신 빔 패턴**을 펼칩니다.
+3. 실제 음향파의 **아날로그 주파수**와 음속을 입력합니다.
+4. XZ, YZ 또는 XY 360° 절단면과 조향각을 고릅니다.
+5. 기본 **자동 · 위상 간격 기준**을 사용하고, 계산량 비교가 필요할 때만 고정 표본 수를 고릅니다.
+6. polar 선, 조향 응답, 조건부 −3.0103 dB 폭과 sampled local maxima를 함께 읽습니다.
+
+마이크를 드래그하는 동안에는 최대 720개 각도의 가벼운 preview를 표시합니다. 마우스나 pointer를
+놓으면 선택한 표본 설정으로 다시 계산합니다. 빔 패턴 설정은 배열 좌표가 아니므로 undo history,
+저장되지 않은 변경 상태와 Array JSON에는 들어가지 않습니다.
+
+## 물리식과 좌표
+
+마이크 위치 <code>r_m</code>, 배열 중심 <code>r_c</code>, array→source 방향 단위벡터
+<code>u</code>, 조향 방향 <code>u0</code>, 아날로그 주파수 <code>f</code>, 음속
+<code>c</code>에 대해 표시하는 complex receive array factor는 다음입니다.
+
+<code>B(u) = (1/M) Σ_m exp[j (2πf/c) (u-u0)·(r_m-r_c)]</code>
+
+<code>1/M</code>은 sampled maximum에 맞춘 사후 정규화가 아니라 고정 conventional
+delay-and-sum weight입니다. 따라서 조향 방향은 이상적 모델에서 1이고, 같은 0 dB 응답이 여러
+방향에 있으면 모두 그대로 남습니다. Array Builder는 <code>|B|²</code>와
+<code>10 log10(|B|²)</code>를 계산하며, polar 표시 하한만 별도 clamp합니다. 표시 하한을 바꿔도
+raw complex, power, peak 또는 HPBW 계산은 바뀌지 않습니다.
+
+절단면 각도는 오른손 Array 좌표계에서 다음과 같습니다.
+
+| 절단면 | 0° | +90° | 의미 |
+| --- | --- | --- | --- |
+| XZ | +Z | +X | 기본. XY 평면 배열의 broadside와 x축 단면 |
+| YZ | +Z | +Y | XY 평면 배열의 broadside와 y축 단면 |
+| XY | +X | +Y | 배열 평면 안의 edge 방향 단면 |
+
+polar plot은 0°를 오른쪽, +90°를 위쪽에 그립니다. 각 plot은 구면 전체가 아니라 하나의
+great-circle 단면입니다. 임의 3D 배열을 세 단면만으로 완전히 평가할 수는 없습니다.
+
+## 모델에 들어가는 것과 빠지는 것
+
+현재 array factor는 다음 조건을 명시적으로 고정합니다.
+
+- analog monochromatic narrowband 가설
+- 자유장의 far-field plane wave
+- 위치만 가진, 이상적으로 보정된 무지향성 point microphone
+- uniform conventional delay-and-sum weight
+- meter 좌표와 사용자가 입력한 음속
+
+따라서 방 반사·회절·산란, near-field 거리와 구면 감쇠, baffle·housing·상호결합, 마이크의 각도별
+element directivity는 포함하지 않습니다. Array JSON의 <code>sensitivityDb</code>,
+<code>phaseOffsetDeg</code>와 <code>frequencyResponse</code>도 이 geometry-only plot에는
+섞지 않습니다. 이 보정들은 합성 및 위치추정 pipeline에서 별도로 적용됩니다. 주파수 응답은
+주파수별 channel transfer이고, 그 자체가 각도별 element pattern은 아닙니다.
+
+## Nyquist와 공간 alias
+
+이 계산에는 ADC sample rate 입력이 없습니다. 파수는 항상 원래 아날로그 주파수로
+<code>k=2πf/c</code>를 계산하며, 48 kHz ADC를 가정했을 때 Nyquist를 넘는 49,125 Hz 같은 값도
+1,125 Hz로 접지 않습니다. 이는 배열 설계에서 실제 파장과 grating/ambiguity를 관찰하기 위한
+의도된 동작입니다.
+
+ADC의 temporal alias, anti-alias filter와 signed alias orientation은 sampling 단계의 문제입니다.
+마이크 간격·파장·조향이 만드는 spatial alias와는 별개입니다. 이 plot은 sampled local maximum을
+보여줄 수 있지만, 그것을 자동으로 grating lobe나 sidelobe로 분류하지 않습니다. planar 배열의
+앞·뒤 0 dB 동률처럼 서로 다른 원인도 같은 단면 응답으로 나타날 수 있기 때문입니다.
+
+## HPBW와 각도 해상도
+
+HPBW는 조향 방향을 포함하는 연결 lobe에서 raw power가 정확히 0.5, 즉 −3.010299956… dB가 되는
+양쪽 crossing을 찾았을 때만 표시합니다. 표본 두 점이 crossing을 bracket하면 raw analytic
+evaluator로 각 경계를 48회 이분합니다.
+
+고주파·큰 aperture에서는 고정 각도 grid가 매우 좁은 lobe나 dip을 건너뛸 수 있습니다. 이를 숨기지
+않기 위해 투영된 최대 microphone baseline <code>D</code>, 각도 간격
+<code>Δ=2π/N</code>에 대한 인접 방향 pair phase 변화 상한
+<code>2 k D sin(Δ/2)</code>를 계산합니다. 현재 metric 해석 기준은 이 상한이
+<code>π/8</code> 이하인 경우입니다.
+
+이 기준은 공개된 수치 해상도 정책이지, 모든 연속 lobe와 half-power excursion을 검출한다는
+수학적 증명이 아닙니다. 기준을 넘으면 raw polar 표본은 그대로 표시하되 HPBW와 peak 해석을
+<code>resolution-unresolved</code>로 보류합니다. 기준을 만족해도 half-power crossing을 표본에서
+찾지 못한 비상수 패턴은 360° HPBW라고 만들지 않고
+<code>no-sampled-half-power-crossing</code>으로 남깁니다. 단일 또는 절단면 투영 좌표가 모두 같은
+배열만 analytic constant로 판정하고 폭을 <code>null</code>로 반환합니다.
+
+자동 표본은 최소 720개에서 시작해 이 phase-step 기준에 맞게 늘어나며 최대 14,400개와 전체 phasor
+평가 상한을 지킵니다. 상한에서도 기준을 만족하지 못하면 계산을 예쁘게 보이도록 평활화하거나
+peak를 제거하지 않고 미확정 상태를 표시합니다.
+
+## portable API
+
+<code>beam-pattern.js</code>는 DOM, Scene, ADC와 외부 package에 의존하지 않는 ES module입니다.
+
+~~~js
+import { computeReceiveBeamPattern } from "./packages/acoustics-core/beam-pattern.js";
+
+const pattern = computeReceiveBeamPattern({
+  array,
+  frequencyHz: 49_125,
+  speedOfSound: 343,
+  cut: "xz",
+  steeringAngleDeg: 0,
+  sampleCount: "auto",
+  dbFloor: -60,
+});
+
+drawPolar(pattern.anglesDeg, pattern.displayDb);
+
+if (!pattern.angularSampling.metricResolutionSatisfied) {
+  showUnresolved(pattern.angularSampling.maximumAdjacentPhaseStepRadBound);
+}
+~~~
+
+결과는 normalized raw <code>responseReal</code>, <code>responseImaginary</code>,
+<code>responsePower</code>, <code>responseLinear</code>, unclamped <code>responseDb</code>와
+표시용 <code>displayDb</code>를 각각 보존합니다. workload에는 baseline pair 비교, sampled phasor,
+HPBW용 최대·실제 평가 수가 따로 기록됩니다. 1,024채널, 0–1 MHz, 각도·phasor·baseline 상한은
+할당과 큰 반복 전에 검사합니다.
+
+far-field steering vector와 beamformer response를 구현한 독립 참고 구현은
+[Pyroomacoustics 공식 beamforming source](https://github.com/LCAV/pyroomacoustics/blob/master/pyroomacoustics/beamforming.py)에서
+확인할 수 있습니다. array factor와 element pattern의 구분은
+[MathWorks 공식 설명](https://www.mathworks.com/help/phased/ug/element-and-array-radiation-patterns-and-responses.html)을
+함께 참고하세요.

docs/data-contracts.md

@@ -28,7 +28,8 @@ array의 `sensitivityDb`와 `phaseOffsetDeg`는 각 마이크 수신 channel에
 측정 범위 밖에서는 가까운 끝점을 사용한다.
 
 Array Builder의 사각형/타원 생성 경계, 프리셋 종류, 행·열, random seed·최소 간격·경계 여백,
-snap과 zoom은 편집기 상태이며 `micarrsim.array` 계약에 포함되지 않는다. 저장 파일에는
+snap·zoom과 수신 빔 패턴의 주파수·음속·절단면·조향각·angular sample·display floor는 편집기
+preview 상태이며 `micarrsim.array` 계약에 포함되지 않는다. 저장 파일에는
 `aperture.width/height`와 최종 `microphones` 좌표·순서만 들어간다. 따라서 다른 도구는
 형상 이름을 추론하지 않고 실제 좌표를 배열 geometry의 기준으로 사용해야 한다.
 

docs/execution-plan.md

@@ -41,13 +41,15 @@ CPU 기준 구현과 GPU 결과의 수치 오차가 합의된 허용 범위 안
 세 앱의 책임은 다음과 같이 분리한다.
 
 - `array-builder`: aperture 크기와 사각/타원 생성 경계, 격자·선형·둘레·Fermat·seed random
-  프리셋, 마이크 직접 편집·채널 순서·보정 보존과 표준 Array JSON 내보내기
+  프리셋, 마이크 직접 편집·채널 순서·보정 보존, receive array-factor polar 분석과 표준 Array
+  JSON 내보내기
 - `dataset-builder`: 음원 배치, gain/시간 구간/반복 설정, ambient mix, 이미지상의 위치 지정,
   seed 고정, 합성 오디오와 ground truth manifest 내보내기
 - `acoustic-camera`: manifest와 배열 JSON 읽기, 마이크 신호 전파 합성, steering vector 생성,
   DAS 실행, overlay·수치 평가·실험 결과 내보내기
 - `acoustics-core`: 앱들이 공유하는 좌표계, 단위, 구면 감쇠·희소 multipath·마이크 응답,
-  STFT, 정답 rasterization, 지표, CPU reference와 실측 channel용 streaming localizer
+  STFT, far-field receive array factor, 정답 rasterization, 지표, CPU reference와 실측
+  channel용 streaming localizer
 - `webgpu-kernels`: steering/DAS 커널, buffer layout, 장치 한도 검사와 benchmark
 
 ## 3. 데이터 계약
@@ -179,6 +181,8 @@ flattening이 모델 타당성을 훼손하는지 청취 및 spectrum 통계로
 - canvas 추가·선택·drag, 정밀 좌표·ID·채널 순서 편집과 undo/redo
 - 가져온 sensitivity·phase·frequency response 보존과 표준 Array JSON 왕복
 - 좌표 중복 오류, 경계 초과 경고, clamp·중앙 정렬·aperture 맞춤
+- analog frequency·XZ/YZ/XY 조향의 360° conventional receive array-factor polar plot
+- raw complex/power 보존, 조건부 HPBW·sampled peak tie와 phase-step 해상도 미확정 상태
 
 완료 조건: 만든 Array가 계약 검증을 통과하고 Acoustic Camera에서 그대로 불러와진다.
 
@@ -242,6 +246,7 @@ hardware deadline과 정확도는 장치 adapter가 정해진 뒤 별도 측정
 
 - [x] 설치 없는 ES module workspace와 세 앱 shell
 - [x] Array Builder 프리셋·직접 편집·검증·Camera 전달
+- [x] Array Builder receive array-factor polar 단면·HPBW·Nyquist 초과 설계 조건
 - [x] array/scene/experiment/result schema와 synthetic fixture
 - [x] 좌표·거리·구면 감쇠·분수 지연·STFT 단위 테스트
 - [x] CPU DAS golden implementation

docs/index.html

@@ -102,6 +102,7 @@
             <li><a href="/apps/array-builder/">Array Builder</a>에서 aperture 너비·높이와 사각형 또는 타원 생성 경계를 정합니다.</li>
             <li>격자·선형·원형·Fermat 나선·균일 랜덤 중 하나를 고릅니다. 랜덤은 seed와 최소 간격으로 재현성과 채널 간 거리를 제어합니다.</li>
             <li>canvas의 <strong>추가</strong> 도구로 마이크를 놓고, 점을 드래그하거나 x/y/z 필드로 좌표를 수정합니다.</li>
+            <li>canvas 아래 <strong>수신 빔 패턴</strong>에서 아날로그 주파수·XZ/YZ/XY 절단면·조향각에 따른 polar 응답을 확인합니다.</li>
             <li>목록에서 마이크를 삭제하거나 채널 순서를 바꾸고, 상태가 <strong>Array JSON 저장 가능</strong>이면 저장합니다.</li>
             <li><a href="/apps/acoustic-camera/">Acoustic Camera</a>의 <strong>Array</strong> 입력에서 저장한 파일을 선택합니다.</li>
           </ol>
@@ -113,6 +114,12 @@
             생성 경계 형상, 프리셋 종류, seed와 최소 간격은 편집기 설정이라 표준 Array JSON에
             저장되지 않습니다. Camera가 사용하는 것은 저장된 aperture와 최종 마이크 좌표·순서입니다.
           </aside>
+          <aside class="callout">
+            빔 패턴은 이상적으로 보정된 무지향성 point microphone의 narrowband far-field
+            geometry-only 수신 단면입니다. Nyquist 초과 주파수도 원 파장으로 계산하며, angular
+            phase-step 기준이 부족하면 raw polar 선만 남기고 HPBW·peak 해석을 보류합니다.
+            <a href="/docs/beam-pattern.md">수식과 제한 보기</a>
+          </aside>
         </div>
       </section>
 
@@ -343,6 +350,7 @@
         <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/beam-pattern.md"><strong>수신 빔 패턴</strong><span>array factor·HPBW·해상도</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>

packages/acoustics-core/README.md

@@ -76,6 +76,41 @@ Tone과 band의 검증 범위는 0–1 MHz다. 이는 Nyquist cutoff가 아니
 마이크 응답과 희소 경로 모델의 명시적 정밀도 범위다. public sampling helper는 비정상적으로
 작은 sample rate에서도 최대 513개 fold segment를 넘기 전에 거부한다.
 
+## 수신 빔 패턴 API
+
+`beam-pattern.js`의 `computeReceiveBeamPattern()`은 Scene과 ADC 없이 microphone geometry의
+narrowband far-field conventional delay-and-sum receive array factor를 계산합니다.
+
+~~~js
+import { computeReceiveBeamPattern } from "./packages/acoustics-core/beam-pattern.js";
+
+const pattern = computeReceiveBeamPattern({
+  array,
+  frequencyHz: 49_125,
+  speedOfSound: 343,
+  cut: "xz",
+  steeringAngleDeg: 0,
+  sampleCount: "auto",
+  dbFloor: -60,
+});
+~~~
+
+파수는 `2π frequencyHz / speedOfSound`이며 `frequencyHz`를 temporal ADC alias로 접지 않습니다.
+결과는 `1/M` weight의 raw normalized complex·power·dB와 별도의 display-floor buffer를 보존합니다.
+이상적으로 보정된 무지향성 point microphone의 geometry-only 응답이므로
+`sensitivityDb`, `phaseOffsetDeg`, `frequencyResponse`, element directivity, 방과 near-field는
+포함하지 않습니다.
+
+XZ는 0°=+Z/90°=+X, YZ는 0°=+Z/90°=+Y, XY는 0°=+X/90°=+Y인 great-circle 단면입니다.
+투영 maximum baseline `D`와 angle 수 `N`에서
+`2 k D sin(π/N) ≤ π/8` phase-step criterion을 검사합니다. 이는 모든 lobe 검출 보장이 아니라
+metric sampling 정책입니다. 미충족 시 raw samples만 반환하고 HPBW와 sampled peak 해석을
+`resolution-unresolved`로 남깁니다. HPBW도 sampled half-power bracket이 있을 때만 raw analytic
+response를 48회 이분하며, 비상수 all-above grid를 360° 폭으로 만들지 않습니다.
+
+마이크 수·baseline pair·angular sample·phasor evaluation은 큰 반복과 할당 전에 상한을 검사합니다.
+portable 결과 계약과 상태별 의미는 [수신 빔 패턴 문서](../../docs/beam-pattern.md)를 참고하세요.
+
 ## 위치 추정 알고리즘
 
 `localization-algorithms.js`의 registry와 `localization.js`의 generic API가 다음 네 경로를

tests/integration/README.md

@@ -23,7 +23,8 @@ Unit과 integration test가 같은 페이지에서 실행됩니다. WebGPU 장
 - `builder-ui.test.js`: 파일 선택 한 번으로 오디오 음원 생성, 이미지·오디오 연결, canvas 편집,
   trajectory keyframe 편집, Preview WAV/Scene 다운로드, SHA 재연결과 잘못된 import 보존
 - `array-builder-ui.test.js`: 프리셋·직접 추가·좌표·보정·채널 편집, undo/redo,
-  중복 좌표 차단, 표준 Array JSON 저장·재가져오기와 390px layout
+  중복 좌표 차단, 표준 Array JSON 저장·재가져오기, receive polar plot·고주파 auto sampling,
+  coarse-grid 미확정·drag 갱신·preview/export 독립성과 390px layout
 - `camera-ui.test.js`: Dedicated Worker CPU/WebGPU 실행, 취소, Result schema, rectangular/Fermat와
   DAS/DAS-PHAT 비교, GCC-PHAT CPU·협대역 제약, Builder 새 탭과 Experiment 선로드·Scene
   재import의 다중 band 보존; 독립 OS-CFAR·raw spectral-flux Activity, 모든 frame/bin JSON,

tests/unit/README.md

@@ -38,6 +38,9 @@ Unit과 integration module은 같은 browser runner에서 순서대로 실행됩
   최소 간격, 직접 채널 편집, calibration 보존과 geometry 진단
 - `array-builder-canvas.test.js`: 동일 축척 좌표 왕복, y-up 변환, pointer clamp, hit test,
   1/2/5 grid와 keyboard nudge
+- `beam-pattern.test.js`: conventional receive array-factor 부호·raw complex/power, XY/XZ/YZ
+  좌표, analog Nyquist 초과 파장, front/back 동률, 조건부 HPBW, angular phase-step 해상도와
+  exact workload cap
 - `evaluation.test.js`: local maximum·8-connected component·marker watershed peak 묶기,
   검출 감도, truth matching, energy/sidelobe/main-lobe 및 비확률적 beam-spread covariance ellipse
 - `camera.test.js`: canonical input hash, workload 추정, Scene 정렬의 분석 band 보존,