micarrsim/docs/data-contracts.md

데이터 계약

micarrsim의 저장 형식은 JSON Schema Draft 2020-12와 추가 관계 검증으로 정의한다. 모든 길이는 m, 시간은 s, 주파수는 Hz다. 배열 중심이 원점이고 +x는 오른쪽, +y는 위쪽, +z는 배열에서 장면을 향하는 우수 좌표계를 사용한다.

파일 종류

• micarrsim.array: aperture와 마이크별 [x, y, z] 좌표
• micarrsim.scene: 음원·ambient recipe, 위치 ground truth와 로컬 asset manifest
• micarrsim.experiment: scan plane/grid, 주파수 대역, STFT와 DAS 설정
• micarrsim.result: raw/display acoustic map, 복수 peak와 source 매칭, 평가·성능 정보

scene JSON에는 192채널 원시 sample을 넣지 않는다. 합성 tone/noise는 seed가 포함된 recipe로 재생성하고, 녹음 파일과 이미지는 manifest 기준의 안전한 상대 경로로 참조한다. 사용자 컴퓨터의 절대 경로, URL, .. 경로는 저장하지 않는다.

오디오와 map 정규화

scene.mix.normalization은 마이크 신호 합성 전에 적용할 오디오 mix 정책이다. none은 원래 gain을 보존하고, peak는 합성 전 peak를 targetPeak에 맞춘다. result의 signalStats에는 정규화 전 peak, 실제 scale, scale 적용 후에도 범위를 넘은 sample 수를 기록한다.

이는 acoustic map 표시 정규화와 별개다. result의 rawMap은 반드시 선형 power이고, displayMap은 peak-normalized 값 또는 dB 값일 수 있다. 후처리 결과는 processedMaps에 넣어 raw DAS map을 덮어쓰지 않는다.

map은 row-major 배열이다. 첫 행은 yMax, 마지막 행은 yMin, 각 행은 xMin에서 xMax 방향이다. values.length는 반드시 rows × columns와 같아야 한다.

재현성 hash

result.inputHash는 실행에 사용한 { array, scene, experiment }를 객체 key 사전순으로 재귀 정렬하고 공백 없이 JSON 직렬화한 UTF-8 byte의 SHA-256 소문자 hex다. 사용한 asset은 실행 전에 SHA-256을 계산해 scene의 해당 asset sha256 필드를 채운 상태로 canonical input을 만든다. 따라서 파일 이름이 같아도 내용이 바뀌면 hash가 달라진다.

버전과 검증

현재 계약 버전은 1.0.0이다. 브라우저는 packages/contracts/schema-validator.js로 저장소의 실제 schema를 실행한 뒤 validation.js에서 다음 관계를 추가 검사한다.

• 중복 id와 array/scene/experiment/result 참조
• asset 종류와 안전한 상대 경로
• Nyquist 및 시간·scan 범위
• map shape와 source peak 매칭
• 현재 비스트리밍 CPU backend의 512 MiB channel-buffer 예산

지원하지 않는 schemaVersion은 묵시적으로 변환하지 않고 오류로 알린다.