docs: add quick start and user guides
This commit is contained in:
Codex
@@ -1,27 +1,175 @@
|
||||
# micarrsim
|
||||
|
||||
192채널 MEMS 마이크 배열의 배치와 음향 영상 성능을 평가하기 위한 WebGPU 기반 시뮬레이터입니다.
|
||||
192채널 MEMS 마이크 배열의 배치와 자유음장 DAS 음향 영상을 비교하는 로컬 브라우저
|
||||
시뮬레이터입니다. Dataset Builder에서 재현 가능한 음향 장면을 만들고 Acoustic Camera에서
|
||||
CPU 또는 WebGPU로 배열 응답, acoustic map과 위치 검출 지표를 계산합니다.
|
||||
|
||||
현재는 설계 단계입니다. 프로젝트 목표는 [`goal.md`](goal.md), 구현 로드맵과 기술 결정은
|
||||
[`docs/execution-plan.md`](docs/execution-plan.md)를 참고하세요.
|
||||
별도 프로그램이나 패키지를 설치하지 않습니다. 모든 앱과 계산은 이 저장소와 브라우저 안에서
|
||||
실행됩니다.
|
||||
|
||||
## 디렉터리
|
||||
## 실행 환경
|
||||
|
||||
```text
|
||||
apps/
|
||||
dataset-builder/ 음원 합성 및 ground truth 생성 UI
|
||||
acoustic-camera/ 전파, DAC 빔포밍, 평가 및 시각화 UI
|
||||
packages/
|
||||
acoustics-core/ 공통 좌표계, 음향 모델, 평가 로직
|
||||
webgpu-kernels/ WGSL 기반 steering/DAC 연산
|
||||
schemas/ 배열·장면·실험 JSON Schema
|
||||
assets/
|
||||
array-geometries/ 마이크 배열 예제
|
||||
sample-scenes/ 재배포 가능한 소규모 예제 장면
|
||||
tests/
|
||||
unit/ 수치 모델 단위 테스트
|
||||
integration/ 앱 간 데이터 계약과 기준 시나리오 테스트
|
||||
docs/ 설계 및 실행 계획
|
||||
- Windows 10/11
|
||||
- 최신 Microsoft Edge 또는 Google Chrome
|
||||
- 저장소에 포함된 Windows PowerShell과 브라우저 외 추가 런타임 불필요
|
||||
- WebGPU가 없거나 장치를 열 수 없어도 CPU backend로 실행 가능
|
||||
|
||||
## 가장 간단하게 시작하기
|
||||
|
||||
1. 저장소 최상위의 `start.cmd`를 더블클릭합니다.
|
||||
2. 기본 브라우저에서 micarrsim 시작 화면이 열립니다.
|
||||
3. 사용을 마치면 함께 열린 콘솔에서 `Ctrl+C`를 눌러 로컬 서버를 종료합니다.
|
||||
|
||||
브라우저가 자동으로 열리지 않으면 <http://127.0.0.1:4173/>을 직접 여세요. HTML module과
|
||||
Worker를 사용하므로 `index.html` 파일을 탐색기에서 직접 열어서는 안 됩니다.
|
||||
|
||||
다른 포트를 쓰거나 브라우저를 자동으로 열지 않으려면 명령 프롬프트에서 실행합니다.
|
||||
|
||||
```bat
|
||||
start.cmd -Port 4174 -NoBrowser
|
||||
```
|
||||
|
||||
원본 DCASE/MIMII 데이터와 생성된 대용량 결과는 저장소에 커밋하지 않습니다.
|
||||
PowerShell에서 서버를 직접 실행할 수도 있습니다.
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\scripts\serve.ps1 -Port 4174 -NoBrowser
|
||||
```
|
||||
|
||||
이 명령의 `ExecutionPolicy Bypass`는 실행 중인 PowerShell 프로세스에만 적용되며 시스템 정책을
|
||||
영구 변경하지 않습니다. 해당 명령을 사용했다면 <http://127.0.0.1:4174/>을 여세요.
|
||||
|
||||
실행 후 브라우저용 빠른 시작과 문제 해결은 <http://127.0.0.1:4173/docs/>에서도 볼 수 있습니다.
|
||||
|
||||
### 30초 기본 예제
|
||||
|
||||
1. 시작 화면에서 **Acoustic Camera**를 엽니다.
|
||||
2. 기본 192채널 rectangular 배열, single-tone scene과 50×50 experiment가 준비될 때까지
|
||||
기다립니다.
|
||||
3. **기본 예제 실행**을 누릅니다.
|
||||
4. 계산이 끝나면 overlay와 평가 지표를 확인하고 **Result JSON**을 누릅니다.
|
||||
|
||||
실제 완료 시간은 브라우저와 장치에 따라 다릅니다. CPU fallback에서는 WebGPU보다 오래 걸릴 수
|
||||
있습니다.
|
||||
|
||||
## 내 장면으로 전체 흐름 실행하기
|
||||
|
||||
### 1. Dataset Builder에서 Scene 만들기
|
||||
|
||||
1. 시작 화면에서 **Dataset Builder**를 엽니다.
|
||||
2. 선택적으로 배경 이미지와 오디오를 추가합니다.
|
||||
3. 음원을 추가해 canvas 또는 x/y/z 입력으로 위치를 정하고, tone·noise·audio asset과 ambient를
|
||||
설정합니다.
|
||||
4. 상태가 **저장 가능한 장면**이면 **Scene JSON 저장**을 누릅니다.
|
||||
|
||||
**Preview WAV 저장**은 source와 ambient를 공간 정보 없이 하나의 mono channel로 합친 청취
|
||||
확인용 파일입니다. 192채널 마이크 신호나 beamforming 결과가 아닙니다.
|
||||
|
||||
### 2. Acoustic Camera에서 실행하기
|
||||
|
||||
1. 홈으로 돌아가 **Acoustic Camera**를 엽니다.
|
||||
2. 다음 순서로 입력합니다: **Scene → Array → Experiment → Assets**.
|
||||
3. **Scene**에서 Builder가 저장한 `.scene.json`을 선택합니다.
|
||||
4. 기본 배열을 사용하지 않을 때만 **Array**에서 `.array.json`을 선택합니다.
|
||||
5. 별도 실험 문서를 사용할 때만 **Experiment**에서 `.experiment.json`을 선택합니다.
|
||||
6. Scene에 이미지나 audio asset이 있다면 **Assets**에서 Builder에 사용했던 원본 파일을 다시
|
||||
선택합니다. 여러 파일을 한 번에 선택할 수 있습니다.
|
||||
7. 입력 검증이 통과하면 backend와 scan grid를 정하고 실행합니다.
|
||||
8. 완료 후 **Result JSON**을 저장합니다.
|
||||
|
||||
Array와 Scene을 먼저 불러와야 Experiment의 `arrayId`와 `sceneId` 관계를 안전하게 검증할 수
|
||||
있습니다. Scene을 다시 불러오면 이전 asset 연결은 해제됩니다.
|
||||
|
||||
## Scene JSON과 로컬 assets
|
||||
|
||||
Scene JSON에는 원본 이미지나 오디오 byte가 들어가지 않습니다. 대신 asset id, 종류, 파일명과
|
||||
SHA-256 manifest를 저장합니다. 브라우저는 새 페이지나 세션에서 로컬 파일 접근 권한을 유지할 수
|
||||
없으므로 원본 파일을 다시 선택해야 합니다.
|
||||
|
||||
- Camera는 SHA-256으로 선택한 파일을 manifest에 다시 연결합니다.
|
||||
- 같은 이름이라도 내용이 달라 hash가 일치하지 않으면 거절합니다.
|
||||
- 로컬 asset 한 파일은 최대 128 MiB, 연결된 파일 합계는 최대 512 MiB입니다.
|
||||
- 실제 decode되어 메모리에 유지되는 오디오 합계는 최대 192 MiB입니다.
|
||||
- Scene JSON에는 원본 파일명이 기록될 수 있으므로 파일을 외부에 공유하기 전에 확인하세요.
|
||||
|
||||
## Backend와 scan grid
|
||||
|
||||
- **Auto (GPU→CPU)**: 권장값입니다. WebGPU adapter나 device를 사용할 수 없거나 지원되는 장치
|
||||
한계를 넘으면 CPU로 계속합니다.
|
||||
- **WebGPU 강제**: GPU 경로만 사용합니다. 장치를 열 수 없거나 한계를 넘으면 fallback하지 않고
|
||||
오류를 표시합니다.
|
||||
- **CPU 강제**: 비교와 호환성 확인을 위해 CPU DAS만 사용합니다.
|
||||
|
||||
WebGPU 경로도 신호 합성과 STFT 일부는 CPU에서 수행합니다. grid의 point 수는 50×50을 1로 보면
|
||||
100×100은 4배, 200×200은 16배입니다. 처음에는 50×50을 사용하고 해상도가 필요할 때만 높이세요.
|
||||
실행 시간은 microphone 수, scene 길이, FFT, 대역 폭과 장치에 함께 좌우됩니다.
|
||||
|
||||
## Result JSON
|
||||
|
||||
Result JSON은 계약 버전 `1.0.0`의 `micarrsim.result` 문서입니다. 주요 내용은 다음과 같습니다.
|
||||
|
||||
- 실행한 `experimentId`, `arrayId`, `sceneId`, 실제 `backend`와 생성 시각
|
||||
- Array·Scene·Experiment의 canonical SHA-256인 `inputHash`
|
||||
- 정규화 전 peak, 적용 scale과 clipping 수를 담은 `signalStats`
|
||||
- 전체·신호 생성·beamforming 시간인 `timingMs`
|
||||
- 주파수 대역별 선형 power `rawMap`, 표시용 `displayMap`, 검출 `peaks`
|
||||
- 위치 오차, precision/recall, truth 반경 내 energy, peak-to-sidelobe, main-lobe 폭을 계산하기
|
||||
위한 평가 파라미터와 `metrics`
|
||||
|
||||
평가에서 tone source는 tone 주파수가 포함되는 band의 ground truth로만 사용합니다. Audio asset과
|
||||
noise source는 스펙트럼을 미리 알 수 없으므로 모든 band의 ground truth로 취급합니다. 이 가정은
|
||||
결과를 실제 데이터와 해석할 때 고려해야 합니다.
|
||||
|
||||
## 개인정보와 모델의 한계
|
||||
|
||||
서버는 `127.0.0.1` loopback에만 열리고 외부 서비스로 파일을 업로드하거나 telemetry를 보내지
|
||||
않습니다. 선택한 파일은 브라우저 메모리에서 읽으며 생성한 JSON/WAV는 브라우저 다운로드로만
|
||||
저장됩니다.
|
||||
|
||||
현재 음향 모델은 직접 경로와 거리 감쇠를 사용하는 자유음장 모델입니다. 반사, 잔향, 회절,
|
||||
차폐, 바람, 실제 MEMS 비선형과 장착 구조는 모델링하지 않습니다. Beamformer는 conventional
|
||||
DAS이며 UI의 DAMAS와 CLEAN-SC는 아직 사용할 수 없습니다. 따라서 결과는 배열·grid·대역의 상대
|
||||
비교와 소프트웨어 검증용이며, 현장 성능 인증이나 안전 판단을 대신하지 않습니다.
|
||||
|
||||
## 배열 예제
|
||||
|
||||
- `assets/array-geometries/rectangular-16x12.array.json`: 0.45 m 정사각 aperture의 16×12 기준 배열
|
||||
- `assets/array-geometries/fermat-spiral-192.array.json`: 0.45 m 원형 aperture의 192채널 Fermat spiral
|
||||
|
||||
Camera의 **비교 배열** 선택으로 두 fixture를 같은 scene과 experiment에서 연속 실행할 수 있습니다.
|
||||
상세한 생성법은 [`assets/array-geometries/README.md`](assets/array-geometries/README.md)를 참고하세요.
|
||||
|
||||
## 테스트와 benchmark
|
||||
|
||||
서버를 실행한 뒤 다음 주소를 브라우저에서 엽니다.
|
||||
|
||||
- 전체 browser test runner: <http://127.0.0.1:4173/tests/>
|
||||
- WebGPU scaling benchmark: <http://127.0.0.1:4173/benchmarks/webgpu-scaling.html>
|
||||
|
||||
포트를 바꿨다면 URL의 포트도 같은 값으로 바꾸세요. 테스트 범위는
|
||||
[`tests/unit/README.md`](tests/unit/README.md)와
|
||||
[`tests/integration/README.md`](tests/integration/README.md), 기준 실측은
|
||||
[`docs/benchmarks/README.md`](docs/benchmarks/README.md)에 설명되어 있습니다.
|
||||
|
||||
## 저장 형식과 개발 문서
|
||||
|
||||
- [`docs/data-contracts.md`](docs/data-contracts.md): Array·Scene·Experiment·Result 계약
|
||||
- [`schemas/README.md`](schemas/README.md): JSON Schema 구성
|
||||
- [`docs/execution-plan.md`](docs/execution-plan.md): 구현 단계와 기술 결정
|
||||
- [`goal.md`](goal.md): 프로젝트 목표
|
||||
|
||||
원본 DCASE/MIMII 데이터, 사용자가 선택한 assets와 생성된 대용량 결과는 저장소에 커밋하지
|
||||
않습니다.
|
||||
|
||||
## 디렉터리 구조
|
||||
|
||||
```text
|
||||
apps/ Dataset Builder와 Acoustic Camera UI
|
||||
assets/ 192채널 배열과 synthetic Scene/Experiment fixture
|
||||
benchmarks/ 현재 브라우저에서 실행하는 WebGPU scaling 측정
|
||||
docs/ 사용자 안내, 데이터 계약, 실행 계획과 기준 실측
|
||||
packages/ 음향 수치 모델, 계약 검증, UI, WebGPU kernel
|
||||
schemas/ Array·Scene·Experiment·Result JSON Schema
|
||||
scripts/ 무설치 로컬 서버와 fixture 생성기
|
||||
tests/ 브라우저 unit·integration·end-to-end test
|
||||
start.cmd Windows 원클릭 실행 진입점
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user