micarrsim/apps/dataset-builder/README.md

# Dataset Builder

이미지 평면에 source ground truth를 배치하고 tone, noise, 로컬 audio asset과 ambient를 조합해
재현 가능한 `micarrsim.scene` JSON을 만드는 브라우저 앱입니다.

## 열기

저장소의 `start.cmd`를 실행한 뒤 시작 화면에서 **Dataset Builder**를 선택하거나
<http://127.0.0.1:4173/apps/dataset-builder/>을 엽니다. `index.html`을 직접 열면 module과 Worker가
동작하지 않습니다.

## 기본 사용법

1. **배경 이미지**를 선택하거나 이미지 없이 grid를 사용합니다.
2. 녹음 파일을 음원으로 쓸 때는 **+ 오디오 파일 음원**을 누르고 파일을 선택합니다. 파일 asset과
   이를 사용하는 source가 함께 생성되고 새 source가 자동으로 선택됩니다.
3. 합성 신호가 필요하면 **+ 합성 음원**을 누릅니다.
4. 선택된 카드를 확인한 뒤 canvas를 클릭하거나 x/y/z를 입력해 위치를 지정합니다.
5. 필요하면 source 종류를 변경하거나 세부 값을 설정합니다.
   - `Tone`: 주파수와 위상을 갖는 합성 정현파
   - `Noise`: seed로 재현되는 white 또는 pink noise
   - `Audio asset`: 선택한 파일의 channel을 사용하며 짧은 파일은 반복 가능
6. 움직이는 음원은 **시간에 따라 음원 이동**을 켭니다. 현재 위치에서 시작해 Scene 끝까지 이어지는
   기본 두 점 경로가 생성됩니다. 경로점의 절대 시간과 x/y/z를 수정하거나 점을 추가·삭제할 수 있습니다.
7. **경로 미리보기** slider로 시간별 위치를 확인합니다. 번호를 눌러 경로점을 선택한 뒤 canvas를
   클릭하면 선택한 점의 x/y가 바뀝니다. 첫 경로점은 고정 장면 호환용 `source.position`에도 동기화됩니다.
8. 필요하면 ambient 종류와 gain을 설정합니다.
9. 검증 카드가 **저장 가능한 장면**이면 **Scene JSON 저장**을 누릅니다.

오디오 파일은 PCM WAV가 가장 안정적입니다. MP3, FLAC, OGG, M4A 등의 실제 decode 지원 여부는
브라우저와 운영체제 codec에 따라 달라지며, 지원하지 않는 파일은 미리 듣기 시 오류로 표시됩니다.

길이, sample rate, 음속, seed와 mix 정규화도 Scene JSON에 저장됩니다. 이미지가 있으면 표시
평면의 x/y 범위, z와 image pixel 크기가 ground truth 좌표 변환에 사용됩니다.

## 미리 듣기와 Preview WAV

**미리 듣기**는 현재 mix를 브라우저에서 재생합니다. **Preview WAV 저장**은 모든 source와
ambient를 공간 정보 없이 합친 mono PCM16 확인용 파일입니다. 마이크별 전파 지연이 적용된
192채널 녹음이나 acoustic-camera 결과가 아닙니다.

클리핑이 예상되면 저장 전에 경고합니다. 출력이 너무 크면 scene 길이 또는 sample rate를 줄이거나
source gain과 mix 정규화를 조절하세요.

## Scene JSON과 assets

Scene JSON은 오디오·이미지 원본을 포함하지 않고 asset manifest만 기록합니다. 각 descriptor에는
id, 종류, 파일명과 SHA-256이 들어갑니다.

- 파일 한 개는 최대 128 MiB, 연결 파일 합계는 최대 512 MiB입니다.
- decode된 오디오의 합계는 최대 192 MiB입니다.
- Scene을 다시 불러오면 브라우저 권한이 없으므로 **원본 오디오 연결**에서 같은 오디오를 다시
  선택해야 합니다. 이 동작은 새 source를 만들지 않고 manifest의 SHA-256으로 기존 asset을 연결합니다.
- 같은 이름의 파일도 SHA-256이 manifest와 다르면 기존 asset으로 연결되지 않습니다.
- 사용 중인 asset은 먼저 source, ambient 또는 image 참조를 바꾼 뒤 제거할 수 있습니다.

원본 파일은 외부로 업로드되지 않고 브라우저 메모리에서만 처리됩니다. 단, JSON에는 파일명이
남을 수 있으므로 공유 전에 확인하세요.

## Acoustic Camera로 넘기기

1. Scene JSON과 사용한 원본 assets를 함께 보관합니다.
2. Acoustic Camera에서 **Scene**으로 JSON을 선택합니다.
3. 사용자 문서가 있다면 **Array**, **Experiment** 순서로 선택합니다.
4. **Assets**에서 원본 이미지와 오디오를 다시 선택해 SHA-256 연결 상태를 확인합니다.
5. 검증이 통과하면 시뮬레이션을 실행합니다.

안전한 전체 import 순서는 **Scene → Array → Experiment → Assets**입니다. 자세한 계산과 Result
설명은 [`../acoustic-camera/README.md`](../acoustic-camera/README.md)를 참고하세요.

## 모델 범위

Builder의 mix는 재현 가능한 source recipe와 위치 ground truth를 만드는 단계입니다. 자유음장 전파,
마이크 calibration과 DAS는 Acoustic Camera에서 수행합니다. 실제 방의 반사·잔향·차폐를 Builder가
추정하지 않습니다.

이동 경로는 Scene 시작 기준의 keyframe을 직선 보간합니다. Builder의 mono 미리 듣기는 공간 위치를
소리로 표현하지 않으므로, 움직임은 canvas에서 확인하고 실제 시간창별 위치 추정은 Acoustic Camera에서
실행합니다. 경로점 사이의 Doppler 효과나 연속적인 전파 시간 변화는 현재 모델 범위에 포함되지 않습니다.