Array Builder
Array Builder는 micarrsim.array JSON을 브라우저에서 만드는 마이크 배열 편집기입니다. aperture
크기와 생성 경계를 정한 뒤 프리셋으로 시작하거나 마이크를 직접 추가·이동해 Acoustic Camera의
배열 입력으로 사용할 수 있습니다.
열기
저장소 루트에서 start.cmd를 실행하고 시작 화면의 Array Builder를 선택합니다. 서버가 이미
실행 중이면 http://127.0.0.1:4173/apps/array-builder/를 직접 열 수 있습니다. HTML module을
사용하므로 파일을 탐색기에서 직접 열지 마세요.
가장 짧은 사용 순서
- 크기와 형상에서 aperture 너비·높이와 생성 경계를 정합니다.
- 프리셋을 고르고 현재 배열을 프리셋으로 교체를 누릅니다.
- canvas와 마이크 목록에서 좌표와 채널 순서를 다듬습니다.
- 상태가 Array JSON 저장 가능인지 확인하고 Array JSON 저장을 누릅니다.
- 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 열기로 다른 배열을 불러온 직후에도 한 번 실행 취소하면 불러오기 전 문서를 복구할 수
있습니다. 다시 실행하면 불러온 배열로 돌아갑니다.
보정값 보존
선택한 채널의 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로 전달하기
- Array Builder에서 Array JSON 저장을 누릅니다.
- 헤더의 Camera 열기 또는 홈의 Acoustic Camera를 엽니다.
- 입력 준비의 Array에서 저장한 파일을 선택합니다.
- 채널 수와 aperture 요약을 확인한 뒤 Scene과 Experiment를 준비해 실행합니다.
Experiment를 별도 파일로 가져올 때는 그 문서의 arrayId가 방금 불러온 Array ID와 같아야 합니다.
Camera에서 배열 선택이 불러온 Array JSON으로 바뀌고 입력 검증이 통과했는지 확인하세요.
검증과 제한
- 마이크는 1개 이상 1,024개 이하입니다.
- Array ID는 영문 소문자나 숫자로 시작하며 소문자·숫자·점·밑줄·하이픈만 허용합니다.
- 마이크 ID는 비어 있을 수 없고 배열 안에서 고유해야 합니다.
- 좌표는 유한한 수여야 합니다. x/y가 현재 생성 경계와 aperture를 벗어나면 저장 가능한 경고로 표시되므로, 의도한 배치인지 확인하거나 clamp 작업을 사용하세요.
- 마이크 두 개가 같은 x/y/z 좌표를 공유할 수 없습니다.
- 저장되지 않은 변경이 있으면 페이지를 닫을 때 브라우저가 확인합니다.
JSON 구조 자체는 ../../schemas/array.schema.json, 공통 계약은
../../docs/data-contracts.md, 배열 예제는
../../assets/array-geometries/README.md를 참고하세요.