docs: explain live 3d array analysis

README.md

@@ -109,11 +109,13 @@ causal latency는 [전 대역 활동 검출 모델](docs/activity-detection.md)
 2. aperture 너비·높이와 프리셋을 배치할 **생성 경계**(사각형 또는 타원)를 정합니다.
 3. **격자**, **선형**, **원형**, **Fermat 나선**, **균일 랜덤** 중 하나로 배치합니다. 랜덤은
    seed로 같은 좌표를 재현하며, 최소 간격과 경계 여백도 지정할 수 있습니다.
-4. **추가** 도구로 canvas에 마이크를 놓고, 선택한 점을 드래그하거나 x/y/z 입력으로 수정합니다.
+4. 2D 편집에서 **추가** 도구로 canvas에 마이크를 놓고, 선택한 점을 드래그하거나 x/y/z 입력으로
+   수정합니다.
    목록에서는 삭제와 채널 순서 변경도 할 수 있습니다.
-5. canvas 아래 **수신 빔 패턴**에서 아날로그 주파수·360° 절단면·조향각을 바꿔 polar 응답과
+5. 3D 배열 검사로 전환해 x/y/z 배치와 **+Z FRONT** 방향을 회전하며 확인합니다.
-   조건부 −3.0103 dB 폭, sampled peak 동률을 확인합니다.
+6. canvas 아래 **수신 빔 패턴**에서 로그 주파수 slider를 live로 움직이며 XZ·YZ·XY 세 360° polar
-6. 상태가 **Array JSON 저장 가능**이면 **Array JSON 저장**을 누릅니다.
+   응답과 3D 패턴, 조건부 −3.0103 dB 폭 및 sampled peak 동률을 확인합니다.
+7. 상태가 **Array JSON 저장 가능**이면 **Array JSON 저장**을 누릅니다.
 
 불러온 Array의 `sensitivityDb`, `phaseOffsetDeg`, `frequencyResponse` 보정 정보는 마이크 위치·ID나
 채널 순서를 편집해도 보존됩니다. 프리셋 생성은 마이크 목록 전체를 새로 만드는 작업이므로 기존
@@ -121,7 +123,9 @@ causal latency는 [전 대역 활동 검출 모델](docs/activity-detection.md)
 
 생성 경계 형상, 프리셋 종류, random seed와 최소 간격은 편집을 돕는 설정이며 표준 Array JSON에
 저장되지 않습니다. 저장되는 것은 aperture 너비·높이와 최종 마이크 좌표·순서 및 채널별 보정값입니다.
-빔 패턴 주파수·절단면·조향각도 preview 설정이므로 Array JSON과 undo/dirty 상태에 들어가지 않습니다.
+2D/3D 보기와 빔 패턴 주파수·조향 방향·표시 모드도 preview 설정이므로 Array JSON과 undo/dirty
+상태에 들어가지 않습니다. **+Z FRONT**는 좌표계의 전면 표식이며 무지향성 마이크에 별도 지향성을
+부여하는 설정이 아닙니다.
 자세한 사용법은 [`apps/array-builder/README.md`](apps/array-builder/README.md)를 참고하세요.
 
 ### 2. Dataset Builder에서 Scene 만들기
@@ -343,9 +347,15 @@ 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°
+Array Builder는 현재 배치의 geometry-only conventional receive array factor
-polar 단면으로 즉시 표시합니다. 이 계산은 ADC sample rate 없이 원 아날로그 파장을 사용하므로
+`B(u)=(1/M)Σ exp[j(2πf/c)(u-u0)·(r_m-r_c)]`를 XZ·YZ·XY 세 360° polar 단면으로 동시에
-Nyquist 초과 조건도 실행하며, 각도 해상도가 부족하면 raw 선을 남긴 채 HPBW·peak 해석을 보류합니다.
+표시하며, 같은 식을 구면 방향에 평가한 3D 패턴도 제공합니다. 로그 slider는 넓은 아날로그 주파수
+범위를 비율 단위로 live 탐색하며 각 위치에서 단일 narrowband 주파수 하나를 계산합니다. ADC sample
+rate 없이 원 아날로그 파장을 사용하므로 Nyquist 초과 조건도 실행합니다. raw power는 `|B|²`, dB는
+`10 log10(|B|²)`이고 표시를 위해 결과를 sampled maximum으로 다시 맞추지 않습니다. 각도 해상도가
+부족하면 raw 응답을 남긴 채 HPBW·peak 해석을 보류합니다. polar plot은 직교 great-circle 단면이고
+3D도 이산 구면 표본의 시각화입니다. 둘 다 far-field·단일 주파수 모델이며 near-field 거리나 광대역
+주파수 결합을 추가하지 않습니다.
 
 ## 테스트와 benchmark
 

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와 동률 응답을 확인합니다.
+4. 3D 배열 보기로 전환해 z 배치와 **+Z FRONT** 방향이 의도와 같은지 회전하며 검사합니다.
-5. 상태가 **Array JSON 저장 가능**인지 확인하고 **Array JSON 저장**을 누릅니다.
+5. canvas 아래 **수신 빔 패턴**에서 로그 주파수 slider를 움직이며 세 polar 단면과 3D 패턴의 main
-6. Acoustic Camera를 열어 **Array** 입력에서 저장한 `.array.json`을 선택합니다.
+   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를 넘어도 원래 파장을 사용합니다.
+  입력할 수 있으며 sample rate가 없으므로 Nyquist를 넘어도 원래 파장을 사용합니다. 로그 slider의
-- **절단면:** XZ는 0°=+Z·90°=+X, YZ는 0°=+Z·90°=+Y, XY는 0°=+X·90°=+Y입니다.
+  같은 이동 거리는 같은 Hz 차이가 아니라 같은 주파수 비율을 뜻하며, 옆의 출력값으로 실제 Hz를
-- **조향각:** 선택한 360° great-circle 단면 안에서 conventional beamformer가 보는 방향입니다.
+  확인합니다. 계산에는 현재 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와
+않습니다. polar plot은 각각 하나의 great-circle 단면이고, 3D pattern도 이산 구면 표본의
-마이크 frequency response는 포함하지 않습니다.
+시각화입니다. 계산은 한 번에 주파수 하나를 보는 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에는 저장되지
+zoom, 2D/3D 보기, 빔 패턴 주파수·조향 방향·표본 수·표시 모드는 편집기 설정입니다. 표준 Array
-않으며 Camera는 최종 aperture와 실제 마이크 좌표·순서를 사용합니다.
+JSON에는 저장되지 않으며 Camera는 최종 aperture와 실제 마이크 좌표·순서를 사용합니다.
 
 ## Camera로 전달하기
 

docs/beam-pattern.md

@@ -1,21 +1,31 @@
 # 마이크 어레이 수신 빔 패턴
 
 Array Builder의 **수신 빔 패턴**은 현재 마이크 좌표에 conventional delay-and-sum을 적용했을 때의
-narrowband far-field array factor를 360° polar 단면으로 보여줍니다. 마이크는 송신원이 아니므로
+narrowband far-field array factor를 보여줍니다. XZ·YZ·XY의 세 360° polar 단면을 동시에 비교하거나
-엄밀히는 방사 패턴이 아니라 **수신 응답**입니다.
+구면 방향 전체를 표본화한 3D 패턴으로 검사할 수 있습니다. 마이크는 송신원이 아니므로 엄밀히는
+방사 패턴이 아니라 **수신 응답**입니다.
 
 ## 가장 짧은 사용법
 
 1. Array Builder에서 마이크 배치를 만들거나 Array JSON을 엽니다.
 2. 배열 canvas 아래의 **수신 빔 패턴**을 펼칩니다.
-3. 실제 음향파의 **아날로그 주파수**와 음속을 입력합니다.
+3. **로그 주파수 slider**를 움직여 실제 음향파의 아날로그 주파수를 live로 훑고 옆의 실제 값을
-4. XZ, YZ 또는 XY 360° 절단면과 조향각을 고릅니다.
+   확인합니다.
-5. 기본 **자동 · 위상 간격 기준**을 사용하고, 계산량 비교가 필요할 때만 고정 표본 수를 고릅니다.
+4. 음속과 조향 방향을 정하고 XZ·YZ·XY 세 단면을 나란히 비교합니다.
-6. polar 선, 조향 응답, 조건부 −3.0103 dB 폭과 sampled local maxima를 함께 읽습니다.
+5. 대각 방향을 포함한 전체 모양이 필요하면 3D 패턴으로 전환해 회전하며 검사합니다.
+6. 기본 **자동 · 위상 간격 기준**을 사용하고, 계산량 비교가 필요할 때만 고정 표본 수를 고릅니다.
+7. 각 보기의 raw 응답과 조건부 −3.0103 dB 폭, sampled local maxima 및 해상도 상태를 함께 읽습니다.
 
-마이크를 드래그하는 동안에는 최대 720개 각도의 가벼운 preview를 표시합니다. 마우스나 pointer를
+로그 slider에서 같은 화면 거리는 같은 Hz 차이가 아니라 같은 **주파수 비율**에 해당합니다. 따라서
-놓으면 선택한 표본 설정으로 다시 계산합니다. 빔 패턴 설정은 배열 좌표가 아니므로 undo history,
+넓은 범위를 저주파에 치우치지 않고 훑을 수 있습니다. 이 mapping은 UI 조작 방식일 뿐입니다. 계산에는
-저장되지 않은 변경 상태와 Array JSON에는 들어가지 않습니다.
+slider 위치가 아니라 현재의 선형 Hz 값 하나가 전달되며, 여러 주파수를 합치거나 보간해 하나의
+패턴으로 만들지 않습니다. slider를 움직이면 그 순간의 한 주파수에서 현재 보기가 live로 갱신됩니다.
+slider 위치 <code>p</code>는 0..6000의 정수이고
+<code>f=10^(p/1000) Hz</code>로 바뀌므로 범위는 1 Hz..1 MHz, 한 칸의 비율은 약 1.002305입니다.
+
+마이크를 드래그하는 동안에는 가벼운 preview를 표시하고, pointer를 놓으면 선택한 표본 설정으로 다시
+계산합니다. 빔 패턴 설정과 2D/3D 보기 상태는 배열 좌표가 아니므로 undo history, 저장되지 않은 변경
+상태와 Array JSON에는 들어가지 않습니다.
 
 ## 물리식과 좌표
 
@@ -25,11 +35,17 @@ narrowband far-field array factor를 360° polar 단면으로 보여줍니다.
 
 <code>B(u) = (1/M) Σ_m exp[j (2πf/c) (u-u0)·(r_m-r_c)]</code>
 
+각 마이크의 지수항은 조향 지연을 적용한 뒤 관찰 방향에 남는 복소 위상입니다. 관찰 방향과 조향
+방향이 같아 <code>u=u0</code>이면 모든 지수항이 1이므로 <code>B(u0)=1</code>입니다.
+<code>r_m-r_c</code>를 사용하므로 배열 전체를 평행 이동해도 패턴은 바뀌지 않고, 마이크 사이의 상대
+배치만 영향을 줍니다.
+
 <code>1/M</code>은 sampled maximum에 맞춘 사후 정규화가 아니라 고정 conventional
-delay-and-sum weight입니다. 따라서 조향 방향은 이상적 모델에서 1이고, 같은 0 dB 응답이 여러
+delay-and-sum weight입니다. 따라서 같은 0 dB 응답이 여러 방향에 있으면 모두 그대로 남습니다.
-방향에 있으면 모두 그대로 남습니다. Array Builder는 <code>|B|²</code>와
+복소 응답의 실수부와 허수부를 <code>Re B</code>, <code>Im B</code>라 하면 raw power는
-<code>10 log10(|B|²)</code>를 계산하며, polar 표시 하한만 별도 clamp합니다. 표시 하한을 바꿔도
+<code>P=|B|²=(Re B)²+(Im B)²</code>이고 raw dB는
-raw complex, power, peak 또는 HPBW 계산은 바뀌지 않습니다.
+<code>10 log10 P = 20 log10 |B|</code>입니다. 2D와 3D 보기의 표시 하한만 별도로 clamp하므로 표시
+하한을 바꿔도 raw complex, power, peak 또는 HPBW 계산은 바뀌지 않습니다.
 
 절단면 각도는 오른손 Array 좌표계에서 다음과 같습니다.
 
@@ -39,21 +55,40 @@ raw complex, power, peak 또는 HPBW 계산은 바뀌지 않습니다.
 | YZ | +Z | +Y | XY 평면 배열의 broadside와 y축 단면 |
 | XY | +X | +Y | 배열 평면 안의 edge 방향 단면 |
 
-polar plot은 0°를 오른쪽, +90°를 위쪽에 그립니다. 각 plot은 구면 전체가 아니라 하나의
+세 polar plot 모두 0°를 오른쪽, +90°를 위쪽에 그립니다. 하나의 각도 값은 각 단면의 위 규약에
-great-circle 단면입니다. 임의 3D 배열을 세 단면만으로 완전히 평가할 수는 없습니다.
+따라 해석되므로 0°가 XZ·YZ에서는 +Z이고 XY에서는 +X입니다. 각 polar plot은 구면 전체가 아니라
+하나의 great-circle 단면입니다. 세 개를 동시에 보더라도 대각 방향의 lobe를 놓칠 수 있으므로 전체
+방향 검사는 3D 패턴을 사용합니다.
+
+배열 편집 canvas는 XY 좌표를 정확히 배치하기 위한 2D 보기이고, 3D 배열 보기는 x/y/z 배치와 앞뒤를
+회전해 검사하는 보기입니다. 좌표를 바꾸려면 2D canvas나 숫자 필드를 사용합니다. **+Z FRONT** 표시는
+배열 좌표계에서 양의 z 쪽을 전면으로 읽으라는 기준이며, 마이크 element가 실제로 단방향이라는 뜻은
+아닙니다. 3D 패턴은 같은 좌표계의 단위구면 방향 <code>u</code>들을 평가하므로 polar 세 단면에 없는
+대각 방향 응답도 드러냅니다.
+
+3D 표면은 구면 격자의 각 표시용 <code>displayDb</code> 표본을
+<code>rho=clamp((displayDb-dbFloor)/(0-dbFloor),0,1)</code> 반지름으로 놓고 인접 격자점을 면으로
+연결합니다. 이는 dB 동적 범위를 읽기 위한 표시 좌표이며 raw power를 바꾸지 않습니다. 격자 사이의
+새 물리 응답을 보간하거나 surface를 평활화하지 않습니다.
 
 ## 모델에 들어가는 것과 빠지는 것
 
 현재 array factor는 다음 조건을 명시적으로 고정합니다.
 
-- analog monochromatic narrowband 가설
+- 한 번에 아날로그 주파수 하나만 보는 monochromatic narrowband 가설
-- 자유장의 far-field plane wave
+- 거리와 곡률이 없는 자유장의 far-field plane wave
 - 위치만 가진, 이상적으로 보정된 무지향성 point microphone
 - uniform conventional delay-and-sum weight
 - meter 좌표와 사용자가 입력한 음속
 
+slider를 움직여 여러 주파수의 모양을 연속해서 볼 수는 있지만, 각 frame은 서로 독립적인 단일
+주파수 계산입니다. 광대역 신호의 spectrum을 적분하거나 서로 다른 주파수의 map을 융합하지 않습니다.
+far-field 가정에는 source 거리 입력이 없으므로 거리 추정, 구면파 곡률, <code>1/r</code> 감쇠도 이
+plot에서 평가할 수 없습니다.
+
 따라서 방 반사·회절·산란, near-field 거리와 구면 감쇠, baffle·housing·상호결합, 마이크의 각도별
-element directivity는 포함하지 않습니다. Array JSON의 <code>sensitivityDb</code>,
+element directivity는 포함하지 않습니다. 이 패턴은 위치 확률분포나 실제 장면의 localization
+정확도도 아닙니다. Array JSON의 <code>sensitivityDb</code>,
 <code>phaseOffsetDeg</code>와 <code>frequencyResponse</code>도 이 geometry-only plot에는
 섞지 않습니다. 이 보정들은 합성 및 위치추정 pipeline에서 별도로 적용됩니다. 주파수 응답은
 주파수별 channel transfer이고, 그 자체가 각도별 element pattern은 아닙니다.
@@ -93,12 +128,21 @@ evaluator로 각 경계를 48회 이분합니다.
 평가 상한을 지킵니다. 상한에서도 기준을 만족하지 못하면 계산을 예쁘게 보이도록 평활화하거나
 peak를 제거하지 않고 미확정 상태를 표시합니다.
 
+portable 함수의 호출별 상한과 별도로 Array Builder는 UI 정지를 줄이기 위해 live preview 전체를
+240만 microphone-direction 평가로, pointer를 놓은 뒤의 전체 해상도 계산을 1,600만 평가로 제한합니다.
+XZ·YZ·XY 동시 보기에서는 이 예산을 세 호출에 동일하게 분배합니다. 필요한 자동 표본이 예산을
+넘으면 coarse 결과로 바꾸지 않고 계산을 거부하므로, 사용자가 고정 표본 수·주파수·채널 수의
+trade-off를 직접 선택할 수 있습니다.
+
 ## portable API
 
 <code>beam-pattern.js</code>는 DOM, Scene, ADC와 외부 package에 의존하지 않는 ES module입니다.
 
 ~~~js
-import { computeReceiveBeamPattern } from "./packages/acoustics-core/beam-pattern.js";
+import {
+  computeReceiveBeamPattern,
+  computeReceiveBeamPatternSphere,
+} from "./packages/acoustics-core/beam-pattern.js";
 
 const pattern = computeReceiveBeamPattern({
   array,
@@ -115,8 +159,32 @@ drawPolar(pattern.anglesDeg, pattern.displayDb);
 if (!pattern.angularSampling.metricResolutionSatisfied) {
   showUnresolved(pattern.angularSampling.maximumAdjacentPhaseStepRadBound);
 }
+
+const sphere = computeReceiveBeamPatternSphere({
+  array,
+  frequencyHz: 49_125,
+  speedOfSound: 343,
+  steeringAzimuthDeg: 0,
+  steeringElevationDeg: 90,
+  azimuthSampleCount: 120,
+  elevationSampleCount: 61,
+  dbFloor: -60,
+});
+
+// elevation-major: index = elevationIndex * azimuthSampleCount + azimuthIndex
+drawSphere(
+  sphere.azimuthAxisDeg,
+  sphere.elevationAxisDeg,
+  sphere.displayDb,
+  sphere.grid.shape,
+);
 ~~~
 
+portable 함수는 명시한 절단면 하나를 계산합니다. Array Builder의 동시 polar 보기는 같은 주파수와
+공통 설정으로 XZ·YZ·XY를 각각 계산해 나란히 표시하는 UI 구성입니다. 3D 보기 역시 같은 물리식의
+관찰 방향 <code>u</code>를 구면 위에서 평가합니다. 세 단면을 평균하거나 maximum으로 합치는 새
+beamforming 알고리즘이 아닙니다.
+
 결과는 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,