docs: connect the array builder workflow

2026-08-28 22:21:32 +09:00
parent 0f9b4f8942
commit 3714146df9
9 changed files with 214 additions and 27 deletions
@@ -0,0 +1,107 @@
+# 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을
+사용하므로 파일을 탐색기에서 직접 열지 마세요.
+
+## 가장 짧은 사용 순서
+
+1. **크기와 형상**에서 aperture 너비·높이와 생성 경계를 정합니다.
+2. 프리셋을 고르고 **현재 배열을 프리셋으로 교체**를 누릅니다.
+3. canvas와 마이크 목록에서 좌표와 채널 순서를 다듬습니다.
+4. 상태가 **Array JSON 저장 가능**인지 확인하고 **Array JSON 저장**을 누릅니다.
+5. 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`입니다.
+
+확대·축소와 화면 맞춤은 보기만 바꾸며 저장 좌표에는 영향을 주지 않습니다.
+
+## 보정값 보존
+
+선택한 채널의 `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`가 방금 불러온 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)를 참고하세요.