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 매칭, 평가·성능 정보
• micarrsim.comparison-history: 세션의 배열별 Result 요약을 모은 편의 export. core schema 검증 대상은 아니며 각 원본 Result JSON을 대신하지 않는다.

scene JSON에는 192채널 원시 sample이나 원본 asset byte를 넣지 않는다. 합성 tone/noise는 seed가 포함된 recipe로 재생성하고, 녹음 파일과 이미지는 id, kind, fileName, mimeType, sha256 manifest로 참조한다. 사용자 컴퓨터의 절대 경로, URL, .. 경로는 저장하지 않는다.

array의 sensitivityDb와 phaseOffsetDeg는 각 마이크 수신 channel에 적용되는 편차다. 합성기는 이를 신호에 주입하고, beamformer는 알려진 calibration 값의 역 gain/phase를 적용한다. 선택적 frequencyResponse는 2–64개의 { frequencyHz, gainDb, phaseDeg? } 측정점이다. 주파수는 0–1,000,000 Hz에서 중복 없이 증가해야 하며, dB와 wrapped phase를 구간 선형 보간하고 측정 범위 밖에서는 가까운 끝점을 사용한다.

Experiment의 선택적 beamforming.compensateFrequencyResponse는 기본 true다. 합성 channel에는 curve가 항상 적용되며, true이면 CPU/WebGPU DAS가 선택 bin에서 curve의 역 gain/phase도 적용한다. false이면 sensitivity/phase calibration은 유지하고 curve 역보정만 끈다. 선택적 beamforming.maxCompensationDb는 응답 notch의 역보정에서 양의 gain boost만 제한하는 0–120 dB 값이며 생략 시 24 dB다. 응답 peak를 줄이는 attenuation과 phase 보상은 이 boost 상한을 그대로 적용하지 않는다.

로컬 asset 재연결

브라우저 보안상 Scene JSON을 새 페이지에서 열었을 때 이전 로컬 파일 권한은 복원되지 않는다. Camera는 사용자가 다시 선택한 파일을 SHA-256으로 계산해 같은 descriptor에만 연결한다. 이름이 같아도 byte가 다르면 거절하고, 원본은 브라우저 메모리에서만 decode하며 서버에 업로드하지 않는다.

• 파일 하나: 최대 128 MiB
• 한 Scene에 연결된 원본 파일 합계: 최대 512 MiB
• 동시에 유지하는 decode 오디오 channel 합계: 최대 192 MiB

Builder가 내보낸 Scene JSON과 사용한 원본 이미지·오디오는 함께 보관해야 한다. Preview WAV는 scene recipe를 mono로 합친 청취 확인용 파일이며 마이크 배열의 192채널 수신 신호가 아니다.

이동 음원 trajectory

Scene source의 선택적 trajectory는 2–4,096개의 { time, position } keyframe 배열이다. time은 Scene 시작 기준 절대 초이며 0 이상 scene.duration 이하에서 엄격히 증가해야 한다. position은 정적 source와 같은 [x, y, z] m 좌표다. keyframe 사이 위치는 선형 보간하며, 첫 keyframe은 호환용 source.position과 같은 시작 위치로 Builder가 유지한다.

Camera 라이브 미리보기는 sample 경계에 맞춘 시간창 중앙에서 trajectory 위치를 평가한다. 짧은 창으로 Scene 시간을 다시 기준화해도 tone 위상, noise sample index와 audio asset 재생 위치는 원래 절대 시간에 이어진다. 이는 준정적 근사이며 Doppler를 계약하지 않는다.

음향 환경

Scene의 선택적 acoustics.model은 free-field 또는 shoebox다. 필드를 생략한 문서는 free-field로 해석해 이전 직접음 결과를 유지한다. free-field에는 사용되지 않는 room, reflections, diffuseReverb 또는 occluders를 함께 둘 수 없다.

shoebox에는 room.min과 room.max가 필요하다. 각 축에서 min은 max보다 작아야 하며 정적 source와 모든 trajectory keyframe은 room 안에 있어야 한다. reflections.order는 0 또는 1이고, wallGainDb와 선택적 면별 perWallDb는 -60–0 dB, scattering은 0–1이다.

diffuseReverb는 enabled, 0.05–5 s의 rt60Seconds, -60–0 dB의 gainDb와 1–32의 tapCount를 갖는다. 축 정렬 occluders는 최대 8개이며 room 안의 min/max, 고유 id, -120–0 dB의 transmissionDb와 diffractionGainDb를 갖는다.

이 계약은 직접음, 여섯 면의 1차 image-source, 결정적 scattering, 막힌 occluder별 최단 corner 우회와 제한된 RT60 tail을 위한 것이다. 재질 mesh나 고차 room impulse response 계약은 아니다. 세부 계산과 preset은 음향 환경과 마이크 응답 모델에 설명한다.

오디오와 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와 같아야 한다.

Experiment의 선택적 evaluation.detectionThresholdRatio는 최강 local peak power에 대한 검출 임계 비율이며 0 < ratio <= 1이다. 생략된 이전 문서를 Camera에서 열면 기본값 0.25를 적용하며, Experiment JSON을 다시 저장하면 이 값이 명시된다. 값을 낮추면 약한 peak 후보를 포함하지만 sidelobe false positive도 늘 수 있다.

Result 평가 정보

각 band의 peaks는 위치와 power 값, 선택적 sourceId, localizationErrorM, localizationErrorPixels, beamSpread를 저장한다. beamSpread는 선택 peak를 포함하는 연결된 half-power 성분의 power 가중 centroid·공분산과 major/minor RMS 반경·각도다. calibrated는 현재 항상 false이며 확률분포, Gaussian 신뢰구간 또는 통계적 위치 불확실성으로 해석하지 않는다. metrics에는 다음 유한값만 기록한다.

• peakToSidelobeDb
• energyInsideTruthRatio
• precision, recall
• mainLobeWidthM

evaluation은 지표를 다시 해석할 수 있도록 truth 반경, source 매칭 tolerance, peak 검출 threshold와 최소 거리, sidelobe 제외 반경, half-power 비율, dynamic range, 최대 검출 수를 버전과 함께 저장한다. environment에는 실제 backend, microphone/grid 수, scan bounds와 z, 가능한 경우 GPU adapter 및 fallback 정보를 기록한다.

signalStats는 정규화 전 peak, scale과 clipping 수 외에 선택적으로 acousticModel, 실제 전체 acousticPathCount와 acousticPathCounts를 기록한다. 종류별 key는 direct, reflection, scattering, diffraction과 diffuse다.

대역별 ground truth는 tone의 주파수가 band 안에 있을 때 그 tone source를 포함한다. noise와 asset source는 현재 모든 band의 truth로 간주한다. 즉 녹음 asset의 실제 spectrum energy를 대역별로 판정하는 계약은 아직 없으며, 이 가정은 실제 데이터 결과를 해석할 때 고려해야 한다.

재현성 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 범위
• 마이크 주파수 응답점의 범위·정렬과 shoebox room/occluder 포함 관계
• map shape와 source peak 매칭
• band별 evaluation 파라미터와 허용 metric
• Snapshot channel·최대 sparse delay FFT working set의 512 MiB 예산

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

실측 channel을 받는 portable API는 저장 JSON 계약과 별도로 입력 Array를 같은 규칙으로 검사한다. CPU 분석 계획은 기본 512 MiB, 반복 steering cache는 64 MiB, streaming ring과 분석창은 기본 256 MiB hard cap을 할당 전에 적용한다. 채널 순서와 streaming 상태 계약은 실측 다채널 위치추정 코어 포팅을 참고한다.

portable block 결과의 processingTimeMs는 DAS와 local-peak 검출 wall time이다. Streaming 결과는 deadlineMs와 deadlineMet을 추가하고 상태에는 최근·최대 처리 시간, deadlineMisses와 droppedSamples를 누적한다. 이 runtime telemetry는 micarrsim.result 저장 스키마의 필수 필드가 아니다.