micarrsim/apps/array-builder/README.md

# Array Builder

Array Builder는 `micarrsim.array` JSON을 브라우저에서 만드는 마이크 배열 편집기입니다. aperture
크기와 생성 경계를 정한 뒤 프리셋으로 시작하거나 마이크를 직접 추가·이동해 Acoustic Camera의
배열 입력으로 사용할 수 있습니다. 같은 화면에서 배열을 2D로 편집하고 3D로 검사하며, 현재 좌표의
narrowband far-field 수신 빔 패턴을 XZ·YZ·XY 단면과 3D 보기로 확인할 수 있습니다.

## 열기

저장소 루트에서 `start.cmd`를 실행하고 시작 화면의 **Array Builder**를 선택합니다. 서버가 이미
실행 중이면 <http://127.0.0.1:4173/apps/array-builder/>를 직접 열 수 있습니다. HTML module을
사용하므로 파일을 탐색기에서 직접 열지 마세요.

## 가장 짧은 사용 순서

1. **크기와 형상**에서 aperture 너비·높이와 생성 경계를 정합니다.
2. 프리셋을 고르고 **현재 배열을 프리셋으로 교체**를 누릅니다.
3. canvas와 마이크 목록에서 좌표와 채널 순서를 다듬습니다.
4. 3D 배열 보기로 전환해 z 배치와 **+Z FRONT** 방향이 의도와 같은지 회전하며 검사합니다.
5. canvas 아래 **수신 빔 패턴**에서 로그 주파수 slider를 움직이며 세 polar 단면과 3D 패턴의 main
   lobe 및 동률 응답을 확인합니다.
6. 상태가 **Array JSON 저장 가능**인지 확인하고 **Array JSON 저장**을 누릅니다.
7. Acoustic Camera를 열어 **Array** 입력에서 저장한 `.array.json`을 선택합니다.

## 크기와 생성 경계

- **너비·높이:** Array JSON의 `aperture.width`와 `aperture.height`이며 단위는 m입니다.
- **사각형:** 너비와 높이의 직사각형 안에 preset을 배치합니다.
- **타원:** 같은 너비와 높이를 지름으로 하는 타원 안에 preset을 배치합니다.
- **좌표 중앙 정렬:** 현재 마이크의 무게중심을 원점으로 이동합니다.
- **좌표에 크기 맞춤:** 현재 좌표가 들어가도록 aperture를 조절합니다.
- **경계 밖 마이크를 안으로 이동:** 선택한 생성 경계 안으로 좌표를 제한합니다.

aperture 크기를 입력하는 것만으로 기존 좌표가 자동 확대·축소되지는 않습니다. 크기를 줄인 뒤
경계 밖 좌표가 생겼다면 검증 메시지를 보고 크기를 다시 맞추거나 clamp 작업을 사용하세요.

## 프리셋

| 방식 | 설정 | 배치 |
| --- | --- | --- |
| 격자 | 행·열, 경계 여백 | 아래 행부터 위로, 각 행은 왼쪽에서 오른쪽으로 생성 |
| 선형 | 마이크 수, x/y 축 | 선택한 중심축을 따라 일정 간격으로 생성 |
| 원형 링 | 마이크 수 | 경계의 짧은 유효 반지름에 맞춘 실제 내접원 위에 동일 각도 배치 |
| Archimedean 나선 | 마이크 수, 회전 수 | 중심에서 시작해 <code>r∝θ</code>로 커지는 한 줄 곡선형 나선 |
| Fermat 나선 | 마이크 수 | golden angle과 <code>r∝√n</code>을 쓰는 면적 균등 해바라기형 배열 |
| 균일 랜덤 | 마이크 수, seed, 최소 간격 | 경계 내부에 seed로 재현되는 좌표 생성 |

**경계 여백**은 preset 좌표를 aperture 가장자리에서 안쪽으로 띄웁니다. 랜덤 배열은 요청한 최소
간격을 만족하는 배치를 제한된 횟수 안에 찾지 못하면 현재 배열을 바꾸지 않고 오류를 표시합니다.
같은 크기·형상·수·seed·간격을 사용하면 같은 랜덤 좌표가 생성됩니다.
원형과 두 나선은 사각/타원 경계 자체를 변형해 따라가지 않고, 어느 경계에도 들어가는 실제 내접원을
기준으로 만듭니다. 따라서 비정사각 aperture에서도 원이 타원이나 사각 둘레로 바뀌지 않습니다.

프리셋 생성은 현재 마이크 목록 전체를 교체합니다. 필요한 기존 좌표나 채널 보정이 있다면 먼저
Array JSON을 저장하세요.

## 직접 편집

- **선택 도구 (`V`):** 마이크 점을 선택하고 드래그해 x/y를 바꿉니다.
- **추가 도구 (`A`):** 빈 canvas를 클릭해 새 마이크를 만듭니다.
- **좌표 필드:** 선택한 마이크의 ID와 x/y/z를 숫자로 정확히 입력합니다.
- **삭제:** 목록이나 canvas에서 선택한 뒤 **선택 마이크 삭제** 또는 `Delete`를 사용합니다.
- **순서:** **채널 앞으로/뒤로**로 `microphones` 배열의 채널 순서를 바꿉니다.
- **미세 이동:** 방향키로 이동하고 `Shift`를 함께 누르면 10배 거리로 이동합니다.
- **스냅:** 격자 스냅 간격은 화면에서 mm 단위로 입력합니다.
- **실행 취소:** `Ctrl+Z`, 다시 실행은 `Ctrl+Shift+Z`입니다.

확대·축소와 화면 맞춤은 보기만 바꾸며 저장 좌표에는 영향을 주지 않습니다.
배열 canvas의 2D 모드는 XY 좌표를 배치하는 편집기이고, 3D 모드는 x/y/z 관계와 앞뒤를 회전해 보는
검사기입니다. 좌표 추가·이동·삭제는 2D canvas나 숫자 필드에서 수행합니다. **+Z FRONT** 표시는
양의 z 쪽이 배열의 전면이라는 좌표 기준이며, 이상적 무지향성 마이크에 실제 전후 지향성을 추가하지
않습니다. 3D에서는 drag 또는 방향키로 회전하고 **R**이나 **화면 맞춤**으로 기본 시점을 복원합니다.

터치 화면에서는 마이크 점에서 시작한 제스처만 위치 드래그로 처리하고, 빈 canvas의 세로
스와이프는 페이지 스크롤로 남겨 둡니다. 추가 도구도 짧은 탭을 놓을 때만 마이크를 만들므로
스크롤하려는 동작으로 채널이 생기지 않습니다.
`JSON 열기`로 다른 배열을 불러온 직후에도 한 번 실행 취소하면 불러오기 전 문서를 복구할 수
있습니다. 다시 실행하면 불러온 배열로 돌아갑니다.

## 수신 빔 패턴

배열 canvas 아래의 분석 카드는 ideal calibrated omnidirectional point microphone에 conventional
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를 넘어도 원래 파장을 사용합니다. 로그 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와 3D의 dB 반지름 표시에만 적용됩니다. raw complex·power와 HPBW는 바뀌지
  않습니다.

주파수 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로 자동 분류하지
않습니다. 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)에 정리되어 있습니다.

## 보정값 보존

선택한 채널의 `sensitivityDb`와 `phaseOffsetDeg`는 보정값 펼침 영역에서 편집할 수 있습니다. 기존
Array JSON을 불러왔을 때 마이크에 `frequencyResponse`가 있으면 응답점 수를 표시하며, 위치·ID,
채널 순서나 배열 메타데이터를 편집해도 그 curve를 그대로 보존합니다.

프리셋으로 마이크 목록을 교체하면 새 채널이 만들어지므로 이전 채널의 sensitivity, phase와
frequency response도 함께 제거됩니다.

## Array JSON에 저장되는 것

저장 파일은 계약 버전 `1.0.0`의 `micarrsim.array` 문서입니다.

- Array ID, 이름과 선택적 설명
- m 단위 aperture 너비·높이
- 오른손 좌표계와 순서가 있는 마이크 ID·`[x, y, z]`
- 채널별 선택적 sensitivity, phase와 frequency-response curve

생성 경계의 사각형/타원 선택, 프리셋 종류, 행·열, random seed·최소 간격·경계 여백, snap과
zoom, 2D/3D 보기, 빔 패턴 주파수·조향 방향·표본 수·표시 모드는 편집기 설정입니다. 표준 Array
JSON에는 저장되지 않으며 Camera는 최종 aperture와 실제 마이크 좌표·순서를 사용합니다.

## Camera로 전달하기

1. Array Builder에서 **Array JSON 저장**을 누릅니다.
2. 헤더의 **Camera 열기** 또는 홈의 Acoustic Camera를 엽니다.
3. 입력 준비의 **Array**에서 저장한 파일을 선택합니다.
4. 채널 수와 aperture 요약을 확인한 뒤 Scene과 Experiment를 준비해 실행합니다.

Experiment의 `arrayId`는 provenance label이라 불러온 Array의 `id`와 달라도 실행을 막거나
경고하지 않습니다. Camera에서 배열 선택이 **불러온 Array JSON**으로 바뀌고 채널 수·좌표가 의도한
배열인지 직접 확인하세요.

## 검증과 제한

- 마이크는 1개 이상 1,024개 이하입니다.
- Array ID는 영문 소문자나 숫자로 시작하며 소문자·숫자·점·밑줄·하이픈만 허용합니다.
- 마이크 ID는 비어 있을 수 없고 배열 안에서 고유해야 합니다.
- 좌표는 유한한 수여야 합니다. x/y가 현재 생성 경계와 aperture를 벗어나면 저장 가능한 경고로
  표시되므로, 의도한 배치인지 확인하거나 clamp 작업을 사용하세요.
- 마이크 두 개가 같은 x/y/z 좌표를 공유할 수 없습니다.
- 저장되지 않은 변경이 있으면 페이지를 닫을 때 브라우저가 확인합니다.

JSON 구조 자체는 [`../../schemas/array.schema.json`](../../schemas/array.schema.json), 공통 계약은
[`../../docs/data-contracts.md`](../../docs/data-contracts.md), 배열 예제는
[`../../assets/array-geometries/README.md`](../../assets/array-geometries/README.md)를 참고하세요.