142 lines
9.2 KiB
Markdown
142 lines
9.2 KiB
Markdown
# Array Builder
|
||
|
||
Array Builder는 `micarrsim.array` JSON을 브라우저에서 만드는 마이크 배열 편집기입니다. aperture
|
||
크기와 생성 경계를 정한 뒤 프리셋으로 시작하거나 마이크를 직접 추가·이동해 Acoustic Camera의
|
||
배열 입력으로 사용할 수 있습니다. 같은 화면에서 현재 좌표의 narrowband far-field 수신 빔 패턴도
|
||
확인할 수 있습니다.
|
||
|
||
## 열기
|
||
|
||
저장소 루트에서 `start.cmd`를 실행하고 시작 화면의 **Array Builder**를 선택합니다. 서버가 이미
|
||
실행 중이면 <http://127.0.0.1:4173/apps/array-builder/>를 직접 열 수 있습니다. HTML module을
|
||
사용하므로 파일을 탐색기에서 직접 열지 마세요.
|
||
|
||
## 가장 짧은 사용 순서
|
||
|
||
1. **크기와 형상**에서 aperture 너비·높이와 생성 경계를 정합니다.
|
||
2. 프리셋을 고르고 **현재 배열을 프리셋으로 교체**를 누릅니다.
|
||
3. canvas와 마이크 목록에서 좌표와 채널 순서를 다듬습니다.
|
||
4. canvas 아래 **수신 빔 패턴**에서 주파수·절단면·조향각에 따른 main lobe와 동률 응답을 확인합니다.
|
||
5. 상태가 **Array JSON 저장 가능**인지 확인하고 **Array JSON 저장**을 누릅니다.
|
||
6. Acoustic Camera를 열어 **Array** 입력에서 저장한 `.array.json`을 선택합니다.
|
||
|
||
## 크기와 생성 경계
|
||
|
||
- **너비·높이:** Array JSON의 `aperture.width`와 `aperture.height`이며 단위는 m입니다.
|
||
- **사각형:** 너비와 높이의 직사각형 안에 preset을 배치합니다.
|
||
- **타원:** 같은 너비와 높이를 지름으로 하는 타원 안에 preset을 배치합니다.
|
||
- **좌표 중앙 정렬:** 현재 마이크의 무게중심을 원점으로 이동합니다.
|
||
- **좌표에 크기 맞춤:** 현재 좌표가 들어가도록 aperture를 조절합니다.
|
||
- **경계 밖 마이크를 안으로 이동:** 선택한 생성 경계 안으로 좌표를 제한합니다.
|
||
|
||
aperture 크기를 입력하는 것만으로 기존 좌표가 자동 확대·축소되지는 않습니다. 크기를 줄인 뒤
|
||
경계 밖 좌표가 생겼다면 검증 메시지를 보고 크기를 다시 맞추거나 clamp 작업을 사용하세요.
|
||
|
||
## 프리셋
|
||
|
||
| 방식 | 설정 | 배치 |
|
||
| --- | --- | --- |
|
||
| 격자 | 행·열, 경계 여백 | 아래 행부터 위로, 각 행은 왼쪽에서 오른쪽으로 생성 |
|
||
| 선형 | 마이크 수, x/y 축 | 선택한 중심축을 따라 일정 간격으로 생성 |
|
||
| 원형 | 마이크 수 | 사각 경계는 사각 둘레, 타원 경계는 타원 둘레에 균일 배치 |
|
||
| 나선 | 마이크 수 | golden angle을 사용하는 결정론적 Fermat 나선 |
|
||
| 균일 랜덤 | 마이크 수, seed, 최소 간격 | 경계 내부에 seed로 재현되는 좌표 생성 |
|
||
|
||
**경계 여백**은 preset 좌표를 aperture 가장자리에서 안쪽으로 띄웁니다. 랜덤 배열은 요청한 최소
|
||
간격을 만족하는 배치를 제한된 횟수 안에 찾지 못하면 현재 배열을 바꾸지 않고 오류를 표시합니다.
|
||
같은 크기·형상·수·seed·간격을 사용하면 같은 랜덤 좌표가 생성됩니다.
|
||
|
||
프리셋 생성은 현재 마이크 목록 전체를 교체합니다. 필요한 기존 좌표나 채널 보정이 있다면 먼저
|
||
Array JSON을 저장하세요.
|
||
|
||
## 직접 편집
|
||
|
||
- **선택 도구 (`V`):** 마이크 점을 선택하고 드래그해 x/y를 바꿉니다.
|
||
- **추가 도구 (`A`):** 빈 canvas를 클릭해 새 마이크를 만듭니다.
|
||
- **좌표 필드:** 선택한 마이크의 ID와 x/y/z를 숫자로 정확히 입력합니다.
|
||
- **삭제:** 목록이나 canvas에서 선택한 뒤 **선택 마이크 삭제** 또는 `Delete`를 사용합니다.
|
||
- **순서:** **채널 앞으로/뒤로**로 `microphones` 배열의 채널 순서를 바꿉니다.
|
||
- **미세 이동:** 방향키로 이동하고 `Shift`를 함께 누르면 10배 거리로 이동합니다.
|
||
- **스냅:** 격자 스냅 간격은 화면에서 mm 단위로 입력합니다.
|
||
- **실행 취소:** `Ctrl+Z`, 다시 실행은 `Ctrl+Shift+Z`입니다.
|
||
|
||
확대·축소와 화면 맞춤은 보기만 바꾸며 저장 좌표에는 영향을 주지 않습니다.
|
||
터치 화면에서는 마이크 점에서 시작한 제스처만 위치 드래그로 처리하고, 빈 canvas의 세로
|
||
스와이프는 페이지 스크롤로 남겨 둡니다. 추가 도구도 짧은 탭을 놓을 때만 마이크를 만들므로
|
||
스크롤하려는 동작으로 채널이 생기지 않습니다.
|
||
`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`는 보정값 펼침 영역에서 편집할 수 있습니다. 기존
|
||
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, 빔 패턴 주파수·절단면·조향각·표본 수는 편집기 설정입니다. 표준 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)를 참고하세요.
|