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, .. 경로는 저장하지 않는다.

array의 sensitivityDb와 phaseOffsetDeg는 각 마이크 수신 channel에 적용되는 편차다. 합성기는 이를 신호에 주입하고, beamformer는 알려진 calibration 값의 역 gain/phase를 적용한다. 따라서 두 값이 0이 아닌 배열도 오류 없이 조용히 무시되지 않는다.

오디오와 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은 묵시적으로 변환하지 않고 오류로 알린다.