Codex
50 lines
2.7 KiB
Markdown
50 lines
2.7 KiB
Markdown
# 데이터 계약
|
||
|
||
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은 묵시적으로 변환하지 않고 오류로 알린다.
|