docs: explain live 3d array analysis

apps/array-builder/README.md

@@ -2,8 +2,8 @@
 
 Array Builder는 `micarrsim.array` JSON을 브라우저에서 만드는 마이크 배열 편집기입니다. aperture
 크기와 생성 경계를 정한 뒤 프리셋으로 시작하거나 마이크를 직접 추가·이동해 Acoustic Camera의
-배열 입력으로 사용할 수 있습니다. 같은 화면에서 현재 좌표의 narrowband far-field 수신 빔 패턴도
-확인할 수 있습니다.
+배열 입력으로 사용할 수 있습니다. 같은 화면에서 배열을 2D로 편집하고 3D로 검사하며, 현재 좌표의
+narrowband far-field 수신 빔 패턴을 XZ·YZ·XY 단면과 3D 보기로 확인할 수 있습니다.
 
 ## 열기
 
@@ -16,9 +16,11 @@ Array Builder는 `micarrsim.array` JSON을 브라우저에서 만드는 마이
 1. **크기와 형상**에서 aperture 너비·높이와 생성 경계를 정합니다.
 2. 프리셋을 고르고 **현재 배열을 프리셋으로 교체**를 누릅니다.
 3. canvas와 마이크 목록에서 좌표와 채널 순서를 다듬습니다.
-4. canvas 아래 **수신 빔 패턴**에서 주파수·절단면·조향각에 따른 main lobe와 동률 응답을 확인합니다.
-5. 상태가 **Array JSON 저장 가능**인지 확인하고 **Array JSON 저장**을 누릅니다.
-6. Acoustic Camera를 열어 **Array** 입력에서 저장한 `.array.json`을 선택합니다.
+4. 3D 배열 보기로 전환해 z 배치와 **+Z FRONT** 방향이 의도와 같은지 회전하며 검사합니다.
+5. canvas 아래 **수신 빔 패턴**에서 로그 주파수 slider를 움직이며 세 polar 단면과 3D 패턴의 main
+   lobe 및 동률 응답을 확인합니다.
+6. 상태가 **Array JSON 저장 가능**인지 확인하고 **Array JSON 저장**을 누릅니다.
+7. Acoustic Camera를 열어 **Array** 입력에서 저장한 `.array.json`을 선택합니다.
 
 ## 크기와 생성 경계
 
@@ -61,6 +63,11 @@ Array JSON을 저장하세요.
 - **실행 취소:** `Ctrl+Z`, 다시 실행은 `Ctrl+Shift+Z`입니다.
 
 확대·축소와 화면 맞춤은 보기만 바꾸며 저장 좌표에는 영향을 주지 않습니다.
+배열 canvas의 2D 모드는 XY 좌표를 배치하는 편집기이고, 3D 모드는 x/y/z 관계와 앞뒤를 회전해 보는
+검사기입니다. 좌표 추가·이동·삭제는 2D canvas나 숫자 필드에서 수행합니다. **+Z FRONT** 표시는
+양의 z 쪽이 배열의 전면이라는 좌표 기준이며, 이상적 무지향성 마이크에 실제 전후 지향성을 추가하지
+않습니다. 3D에서는 drag 또는 방향키로 회전하고 **R**이나 **화면 맞춤**으로 기본 시점을 복원합니다.
+
 터치 화면에서는 마이크 점에서 시작한 제스처만 위치 드래그로 처리하고, 빈 canvas의 세로
 스와이프는 페이지 스크롤로 남겨 둡니다. 추가 도구도 짧은 탭을 놓을 때만 마이크를 만들므로
 스크롤하려는 동작으로 채널이 생기지 않습니다.
@@ -70,25 +77,45 @@ Array JSON을 저장하세요.
 ## 수신 빔 패턴
 
 배열 canvas 아래의 분석 카드는 ideal calibrated omnidirectional point microphone에 conventional
-delay-and-sum을 적용한 geometry-only receive array factor를 표시합니다.
+delay-and-sum을 적용한 geometry-only receive array factor를 표시합니다. 마이크 위치
+<code>r_m</code>, 중심 <code>r_c</code>, 관찰·조향 방향 <code>u</code>·<code>u0</code>에 대해 사용하는
+식은 다음과 같습니다.
+
+<code>B(u)=(1/M)Σ exp[j(2πf/c)(u-u0)·(r_m-r_c)]</code>
+
+<code>u=u0</code>이면 모든 위상이 맞아 <code>B=1</code>입니다. raw power는 <code>|B|²</code>, raw
+dB는 <code>10 log10(|B|²)</code>이며 sampled maximum에 맞춰 결과를 다시 정규화하지 않습니다.
 
 - **아날로그 주파수:** 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가 보는 방향입니다.
+  입력할 수 있으며 sample rate가 없으므로 Nyquist를 넘어도 원래 파장을 사용합니다. 로그 slider의
+  같은 이동 거리는 같은 Hz 차이가 아니라 같은 주파수 비율을 뜻하며, 옆의 출력값으로 실제 Hz를
+  확인합니다. 계산에는 현재 slider 위치의 주파수 하나만 사용됩니다.
+- **세 polar 단면:** XZ는 0°=+Z·90°=+X, YZ는 0°=+Z·90°=+Y, XY는
+  0°=+X·90°=+Y이며 세 plot을 함께 갱신합니다.
+- **3D 패턴:** 같은 물리식을 구면 방향으로 평가해 세 단면 사이의 대각 lobe와 앞뒤 모호성을
+  회전하며 검사합니다. 세 polar 결과를 보간해 만든 가짜 surface가 아닙니다.
+- **조향 방향:** 표시된 좌표 규약에 따라 conventional beamformer가 보는 방향입니다.
 - **각도 샘플:** 자동은 투영 aperture와 파장에 맞춰 최소 720개에서 늘립니다. 고정 sample은
   계산량 비교나 일부러 coarse한 설계 조건을 확인할 때 사용합니다.
-- **표시 하한:** polar dB radius에만 적용됩니다. raw complex·power와 HPBW는 바뀌지 않습니다.
+- **표시 하한:** polar와 3D의 dB 반지름 표시에만 적용됩니다. raw complex·power와 HPBW는 바뀌지
+  않습니다.
 
-마이크를 드래그하는 동안 최대 720-angle preview를 갱신하고 놓으면 선택한 해상도로 다시 계산합니다.
+주파수 slider를 움직이면 그 순간의 단일 narrowband 주파수에서 현재 패턴 보기가 live로 갱신됩니다.
+이는 주파수 대역 적분이나 여러 map의 fusion이 아닙니다. 마이크를 드래그하는 동안에도 가벼운 preview를
+갱신하고 놓으면 선택한 해상도로 다시 계산합니다.
+live preview는 보기 전체에서 최대 240만 microphone-direction 평가, 전체 해상도 계산은 최대
+1,600만 평가로 제한합니다. 세 polar 단면은 이 전체 예산을 동일하게 나눠 쓰므로, 큰 배열·고주파에서
+자동 해상도가 예산을 넘으면 낮은 해상도로 몰래 계산하지 않고 오류를 표시합니다.
 π/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는 포함하지 않습니다.
+않습니다. polar plot은 각각 하나의 great-circle 단면이고, 3D pattern도 이산 구면 표본의
+시각화입니다. 계산은 한 번에 주파수 하나를 보는 narrowband·far-field plane-wave 모델이므로 source
+거리, 구면파, 광대역 결합, near-field, 방·하우징·element directivity와 마이크 frequency response는
+포함하지 않습니다. 3D 모드는 물리 모델의 범위를 늘리는 별도 알고리즘이 아닙니다.
 
 수식, raw 결과 필드, workload 상한과 상태 의미는
 [`../../docs/beam-pattern.md`](../../docs/beam-pattern.md)에 정리되어 있습니다.
@@ -112,8 +139,8 @@ frequency response도 함께 제거됩니다.
 - 채널별 선택적 sensitivity, phase와 frequency-response curve
 
 생성 경계의 사각형/타원 선택, 프리셋 종류, 행·열, random seed·최소 간격·경계 여백, snap과
-zoom, 빔 패턴 주파수·절단면·조향각·표본 수는 편집기 설정입니다. 표준 Array JSON에는 저장되지
-않으며 Camera는 최종 aperture와 실제 마이크 좌표·순서를 사용합니다.
+zoom, 2D/3D 보기, 빔 패턴 주파수·조향 방향·표본 수·표시 모드는 편집기 설정입니다. 표준 Array
+JSON에는 저장되지 않으며 Camera는 최종 aperture와 실제 마이크 좌표·순서를 사용합니다.
 
 ## Camera로 전달하기