297 lines
18 KiB
HTML
297 lines
18 KiB
HTML
<!doctype html>
|
||
<html lang="ko">
|
||
<head>
|
||
<meta charset="UTF-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||
<meta
|
||
name="description"
|
||
content="micarrsim 빠른 시작, 전체 데이터 흐름, 결과 해석과 문제 해결"
|
||
/>
|
||
<title>micarrsim 사용 설명서</title>
|
||
<link rel="stylesheet" href="/packages/ui/app-shell.css" />
|
||
<link rel="stylesheet" href="/docs/styles.css" />
|
||
</head>
|
||
<body>
|
||
<header class="guide-header">
|
||
<a class="guide-brand" href="/">← micarrsim 홈</a>
|
||
<nav aria-label="문서 목차">
|
||
<a href="#quick-start">빠른 시작</a>
|
||
<a href="#moving-live">이동 라이브</a>
|
||
<a href="#full-workflow">내 데이터</a>
|
||
<a href="#acoustic-model">환경·실측</a>
|
||
<a href="#results">결과 해석</a>
|
||
<a href="#troubleshooting">문제 해결</a>
|
||
</nav>
|
||
</header>
|
||
|
||
<main class="guide-shell">
|
||
<section class="guide-hero">
|
||
<h1>micarrsim 사용 설명서</h1>
|
||
<p>
|
||
<code>start.cmd</code>로 열고, 장면을 실행하고, 결과를 저장하는 순서만 먼저 확인하세요.
|
||
입력과 계산은 로컬 브라우저에서 처리됩니다.
|
||
</p>
|
||
</section>
|
||
|
||
<section class="guide-section" id="quick-start">
|
||
<div class="section-number">01</div>
|
||
<div>
|
||
<p class="eyebrow">30초 확인</p>
|
||
<h2>기본 결과 하나 저장하기</h2>
|
||
<ol class="guide-steps">
|
||
<li><code>start.cmd</code>를 더블클릭합니다.</li>
|
||
<li>홈에서 <a href="/apps/acoustic-camera/">Acoustic Camera</a>를 엽니다.</li>
|
||
<li>Snapshot 카드의 <strong>▶ Snapshot 실행</strong>을 누릅니다.</li>
|
||
<li>완료되면 <strong>Result JSON</strong>을 눌러 다운로드 폴더에 저장합니다.</li>
|
||
</ol>
|
||
<aside class="callout">
|
||
브라우저가 자동으로 열리지 않으면 서버 콘솔에 표시된 주소(기본
|
||
<code>http://127.0.0.1:4173/</code>)를 입력하거나
|
||
<a href="/">현재 서버의 micarrsim 홈</a>을 여세요. 종료할 때는 서버 콘솔에서
|
||
<kbd>Ctrl</kbd>+<kbd>C</kbd>를 누릅니다.
|
||
</aside>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="guide-section" id="moving-live">
|
||
<div class="section-number">02</div>
|
||
<div>
|
||
<p class="eyebrow">Moving-source demo</p>
|
||
<h2>이동 음원을 바로 재생하기</h2>
|
||
<ol class="guide-steps">
|
||
<li><a href="/apps/acoustic-camera/">Acoustic Camera</a>에서 <strong>이동 예제 열기</strong>를 누릅니다.</li>
|
||
<li>Moving 카드의 <strong>Map 준비</strong>를 눌러 기본 2 Hz map을 계산합니다.</li>
|
||
<li><strong>재생</strong>을 누르거나 시간 slider를 움직입니다.</li>
|
||
</ol>
|
||
<aside class="callout">
|
||
짧은 시간창마다 계산한 heatmap과 trajectory 위치를 보간하는 합성 장면 미리보기입니다.
|
||
실제 192채널 마이크 스트림을 녹음하는 기능은 아닙니다.
|
||
</aside>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="guide-section" id="full-workflow">
|
||
<div class="section-number">03</div>
|
||
<div>
|
||
<p class="eyebrow">5분 전체 흐름</p>
|
||
<h2>내 장면을 만들고 Camera에서 실행하기</h2>
|
||
<ol class="guide-steps">
|
||
<li>
|
||
<a href="/apps/dataset-builder/">Dataset Builder</a>에서 <strong>+ 오디오 파일 음원</strong>
|
||
또는 합성 음원을 추가하고 위치, gain, 시간과 ambient를 설정합니다.
|
||
</li>
|
||
<li>움직이는 source는 <strong>시간에 따라 음원 이동</strong>을 켜고 keyframe을 편집합니다.</li>
|
||
<li><strong>Scene JSON 저장</strong>을 누르고 사용한 원본 파일과 함께 보관합니다.</li>
|
||
<li><strong>Scene 저장 후 Camera 열기</strong>를 누릅니다.</li>
|
||
<li>
|
||
Camera에서 파일을 <strong>Scene → Array → Experiment → Assets</strong> 순서로
|
||
가져옵니다. 내 Array/Experiment가 없다면 내장 기본값을 그대로 둡니다.
|
||
</li>
|
||
<li>
|
||
Assets에서 Builder에 사용한 원본 이미지와 오디오를 한 번에 다시 선택합니다.
|
||
준비 상태가 모두 초록색인지 확인합니다.
|
||
</li>
|
||
<li>Snapshot 또는 Moving을 선택해 <strong>Auto (GPU→CPU)</strong>로 실행한 뒤 Result JSON을 저장합니다.</li>
|
||
</ol>
|
||
|
||
<aside class="callout callout--important" id="asset-reconnect">
|
||
<strong>Scene JSON에는 원본 파일이 들어 있지 않습니다.</strong>
|
||
파일명·종류·SHA-256 manifest만 저장됩니다. 브라우저는 새 페이지에서 로컬 파일
|
||
권한을 유지할 수 없으므로 같은 원본을 다시 선택해야 합니다. 이름이 같아도 내용의
|
||
SHA-256이 다르면 연결되지 않습니다.
|
||
</aside>
|
||
|
||
<div class="limit-grid" aria-label="asset 한도">
|
||
<div><strong>128 MiB</strong><span>원본 파일 하나</span></div>
|
||
<div><strong>512 MiB</strong><span>연결 파일 합계</span></div>
|
||
<div><strong>192 MiB</strong><span>decode된 오디오 합계</span></div>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="guide-section">
|
||
<div class="section-number">04</div>
|
||
<div>
|
||
<p class="eyebrow">Localization & compute</p>
|
||
<h2>알고리즘, 속도와 격자 선택</h2>
|
||
<p class="guide-copy">
|
||
Camera의 <strong>위치 추정 알고리즘</strong>에서 실행할 방법을 고릅니다. 처음에는
|
||
DAS로 전체 흐름을 확인한 뒤 같은 scene·scan·STFT에서 PHAT 계열을 실행해 비교하세요.
|
||
</p>
|
||
<div class="guide-table-wrap">
|
||
<table>
|
||
<thead><tr><th>알고리즘</th><th>raw map</th><th>Backend</th><th>특징</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>DAS</td><td>선형 power</td><td>CPU · WebGPU</td><td>진폭과 위상을 유지하는 기준선</td></tr>
|
||
<tr><td>DAS-PHAT</td><td>무차원 score</td><td>CPU · WebGPU</td><td>STFT 크기를 정규화한 위상 기반 합산</td></tr>
|
||
<tr><td>GCC-PHAT</td><td>무차원 score</td><td>CPU</td><td>기준 마이크 pair의 TDOA 상관</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<div class="guide-table-wrap">
|
||
<table>
|
||
<thead><tr><th>선택</th><th>동작</th><th>권장 상황</th></tr></thead>
|
||
<tbody>
|
||
<tr><td>Auto (GPU→CPU)</td><td>WebGPU를 먼저 시도하고 불가능하면 CPU 사용</td><td>기본 권장</td></tr>
|
||
<tr><td>WebGPU 강제</td><td>DAS/DAS-PHAT를 GPU에서만 실행; 실패하면 fallback 없이 오류</td><td>GPU 비교·측정</td></tr>
|
||
<tr><td>CPU 강제</td><td>선택한 알고리즘을 CPU에서 계산</td><td>호환성 확인·기준 비교</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
<p class="guide-copy">
|
||
GCC-PHAT는 CPU 전용이므로 Auto가 자동으로 CPU를 사용하고 WebGPU 강제는 비활성화됩니다.
|
||
각 band가 8개 미만의 FFT bin을 포함하면 협대역 상관 경고가 나오므로 band 폭이나 FFT
|
||
설정을 확인하세요.
|
||
</p>
|
||
<p class="guide-copy">
|
||
먼저 50×50을 권장합니다. 100×100은 4배, 200×200은 16배의 scan point를 계산합니다.
|
||
연산량 줄은 공통 STFT transform과 함께 DAS/DAS-PHAT의 complex MAC, 또는 GCC-PHAT의
|
||
two-pass cross-spectrum·pair×band inverse FFT·scan correlation lookup을 분리해
|
||
표시합니다. 이는 실행 시간 예측값이 아니며 장치와 입력에 따라 달라집니다. 실행 중에는
|
||
취소할 수 있고, 취소하거나 실패해도 이전 완료 결과는 유지됩니다.
|
||
</p>
|
||
<p class="guide-copy">
|
||
복수 음원에서 약한 peak가 빠지면 <strong>Peak 검출 임계값</strong>을 최강 map 값의
|
||
기본 25%에서 10–20%로 낮춰 보세요. 약한 후보와 함께 sidelobe 오검출도 늘 수 있으며,
|
||
main lobe보다 가까운 같은 대역 음원은 어느 알고리즘에서도 하나로 합쳐질 수 있습니다.
|
||
</p>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="guide-section" id="acoustic-model">
|
||
<div class="section-number">05</div>
|
||
<div>
|
||
<p class="eyebrow">Acoustics & measured input</p>
|
||
<h2>환경과 마이크 응답 선택</h2>
|
||
<p class="guide-copy">
|
||
고급 설정에서 자유음장 또는 흡음·일반·반사 강한 실내 preset을 고릅니다. 실내 모델은
|
||
1차 반사, scattering, occluder 회절과 제한된 RT60 tail을 희소 경로로 근사합니다.
|
||
Array의 마이크 응답 curve는 수신 신호에 적용하며 위치추정 역보정 유무를 비교할 수 있습니다.
|
||
값과 한계는 <a href="/docs/acoustic-model.md">음향 모델 설명</a>에서 확인하세요.
|
||
</p>
|
||
<p class="guide-copy">
|
||
실제 동기식 마이크 채널은 Scene 합성 없이 portable CPU 위치추정 코어에 넣고
|
||
DAS·DAS-PHAT·GCC-PHAT를 선택할 수 있습니다.
|
||
장치별 channel·clock·transport adapter는 별도로 필요하며 실시간 deadline은 해당
|
||
장치에서 <code>processingTimeMs ≤ deadlineMs</code>와 miss·drop 누계로 확인해야
|
||
합니다. <a href="/docs/realtime-porting.md">포팅 설명서</a>에 입력 형식, ring buffer,
|
||
메모리·취소와 backpressure 계약이 있습니다.
|
||
</p>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="guide-section" id="results">
|
||
<div class="section-number">06</div>
|
||
<div>
|
||
<p class="eyebrow">Result JSON</p>
|
||
<h2>무엇이 저장되나요?</h2>
|
||
<dl class="result-list">
|
||
<div><dt>algorithm / backend</dt><dd>실제로 실행한 위치추정과 CPU·WebGPU 경로</dd></div>
|
||
<div><dt>rawMap / displayMap</dt><dd>DAS 선형 power 또는 PHAT 무차원 score와 화면 표시용 map</dd></div>
|
||
<div><dt>peaks</dt><dd>검출 위치, source 매칭, m·pixel 위치 오차</dd></div>
|
||
<div><dt>beamSpread</dt><dd>half-power 또는 half-maximum 응답의 map 값 가중 공분산과 1× RMS ellipse</dd></div>
|
||
<div><dt>metrics</dt><dd>truth concentration, precision/recall, sidelobe, main-lobe 폭</dd></div>
|
||
<div><dt>evaluation</dt><dd>검출 threshold, 반경, tolerance 등 지표 계산 조건</dd></div>
|
||
<div><dt>signalStats</dt><dd>normalization·clipping과 실제 음향 모델·종류별 sparse path 수</dd></div>
|
||
<div><dt>timing / environment</dt><dd>signal generation·localization 시간, backend, grid·scan과 장치 정보</dd></div>
|
||
<div><dt>inputHash</dt><dd>Array·Scene·Experiment 입력을 묶은 SHA-256 재현성 식별자</dd></div>
|
||
<div><dt>comparison-history</dt><dd>배열·알고리즘·실제 backend별 시간·위치 오차·PSR 요약</dd></div>
|
||
</dl>
|
||
<aside class="callout">
|
||
DAS map은 acoustic power 응답이고 PHAT map은 무차원 위치추정 score입니다. score와
|
||
화면의 <strong>빔 분포</strong> 1×/2× RMS contour는 위치 확률, Gaussian 신뢰구간 또는
|
||
보정된 측정 불확실성이 아닙니다. GCC-PHAT의 0–1 raw score도 pair·band·IFFT scale을
|
||
제거한 양의 상관 응답이지 “확률 80%” 같은 의미가 아닙니다.
|
||
</aside>
|
||
<aside class="callout">
|
||
<code>timingMs.localization</code>은 위치추정 시간을 기록합니다. 기존 Result 소비자와의
|
||
호환을 위해 <code>timingMs.beamforming</code>에도 같은 값이 alias로 남습니다.
|
||
</aside>
|
||
<aside class="callout">
|
||
평가는 tone 음원을 해당 주파수 대역이 tone 주파수를 포함할 때만 정답으로 사용합니다.
|
||
noise와 asset 음원은 현재 모든 대역의 정답으로 간주합니다. 녹음 파일의 실제 대역별
|
||
에너지를 자동 판정하는 기능은 아직 없습니다.
|
||
</aside>
|
||
<p class="guide-copy">
|
||
Camera에서 바꾼 Scene과 Experiment는 각각 저장할 수 있습니다. 완료 Result와 비교
|
||
기록도 별도 JSON으로 저장하세요. 저장하지 않은 항목이나 실행 중인 계산이 있으면
|
||
페이지를 닫을 때 브라우저가 확인합니다.
|
||
</p>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="guide-section" id="troubleshooting">
|
||
<div class="section-number">07</div>
|
||
<div>
|
||
<p class="eyebrow">Troubleshooting</p>
|
||
<h2>막혔을 때 확인할 것</h2>
|
||
<details open>
|
||
<summary>화면이 비거나 module/Worker 오류가 납니다.</summary>
|
||
<p><code>index.html</code>을 직접 열지 말고 반드시 <code>start.cmd</code>로 실행하세요.</p>
|
||
</details>
|
||
<details>
|
||
<summary>4173 포트를 사용할 수 없다고 나옵니다.</summary>
|
||
<p><code>start.cmd -Port 4174</code>처럼 다른 포트를 지정하고 <code>http://127.0.0.1:4174/</code>을 여세요.</p>
|
||
</details>
|
||
<details>
|
||
<summary>Experiment를 가져올 수 없습니다.</summary>
|
||
<p>Scene과 Array를 먼저 가져오세요. Experiment의 <code>sceneId</code>와 <code>arrayId</code>가 현재 문서와 같아야 합니다.</p>
|
||
</details>
|
||
<details>
|
||
<summary>Assets가 준비되지 않습니다.</summary>
|
||
<p>Builder에서 사용한 것과 바이트가 같은 원본 파일을 다시 선택하세요. 파일명뿐 아니라 SHA-256도 일치해야 합니다.</p>
|
||
</details>
|
||
<details>
|
||
<summary>WebGPU가 없거나 실행이 너무 느립니다.</summary>
|
||
<p>Backend를 Auto 또는 CPU로 두고 50×50 grid부터 실행하세요. GCC-PHAT는 원래 CPU 전용입니다. DAS/DAS-PHAT WebGPU를 쓴다면 최신 Chrome/Edge와 그래픽 드라이버도 확인하세요.</p>
|
||
</details>
|
||
<details>
|
||
<summary>GCC-PHAT에 8 bins 경고가 나옵니다.</summary>
|
||
<p>각 band가 포함하는 FFT bin이 너무 적으면 PHAT 상관이 협대역 주기성에 민감해집니다. 필요한 신호 대역 안에서 band를 넓히거나 FFT size를 조정하세요.</p>
|
||
</details>
|
||
<details>
|
||
<summary>두 번째 음원을 찾지 못합니다.</summary>
|
||
<p>두 음원이 같은 주파수 대역인지 확인하고 Peak 검출 임계값을 낮추세요. gain 차이, main-lobe 폭보다 짧은 거리, grid 간격과 sidelobe는 threshold만으로 해결되지 않을 수 있습니다.</p>
|
||
</details>
|
||
<details>
|
||
<summary>Map 준비 버튼이 비활성화됩니다.</summary>
|
||
<p>Scene에 시간 순서가 올바른 trajectory keyframe이 두 개 이상 있어야 합니다. Builder에서 시간에 따라 음원 이동을 켜거나 Camera의 이동 예제 열기를 사용하세요.</p>
|
||
</details>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="guide-section">
|
||
<div class="section-number">08</div>
|
||
<div>
|
||
<p class="eyebrow">Scope & privacy</p>
|
||
<h2>현재 모델의 범위</h2>
|
||
<p class="guide-copy">
|
||
micarrsim 1.0은 점 음원의 자유음장과 계산량을 제한한 shoebox 희소 경로, 마이크
|
||
주파수 응답과 DAS·DAS-PHAT·GCC-PHAT를 제공합니다. 파동 방정식·고차 반사·재질별
|
||
흡음, 복잡한 mesh, sensor self-noise·비선형, ADC·clock, DAMAS/CLEAN-SC 후처리와
|
||
자동 장치 capture adapter는 포함하지 않습니다. 실행할 수 없는 DAMAS/CLEAN-SC
|
||
placeholder는 Camera UI에서 제거했습니다. 결과는 장비의 절대 성능 보증이 아니라
|
||
같은 조건에서 배열과 알고리즘을 비교하는 재현 가능한 기준입니다.
|
||
</p>
|
||
<p class="guide-copy">
|
||
원본 asset은 브라우저 메모리에서만 읽고 서버나 외부 네트워크로 보내지 않습니다.
|
||
다만 Scene JSON에는 원본 파일명이 남을 수 있으므로 외부 공유 전 확인하세요.
|
||
</p>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="reference-grid" aria-label="상세 문서">
|
||
<a href="/README.md"><strong>전체 README</strong><span>설치·실행·구조·제약</span></a>
|
||
<a href="/apps/dataset-builder/README.md"><strong>Builder 설명서</strong><span>source·ambient·Preview WAV</span></a>
|
||
<a href="/apps/acoustic-camera/README.md"><strong>Camera 설명서</strong><span>backend·결과·비교</span></a>
|
||
<a href="/docs/acoustic-model.md"><strong>음향 모델</strong><span>마이크 응답·반사·산란·회절</span></a>
|
||
<a href="/docs/realtime-porting.md"><strong>실측 포팅</strong><span>block·streaming 위치추정 API</span></a>
|
||
<a href="/docs/data-contracts.md"><strong>데이터 계약</strong><span>JSON Schema와 재현성</span></a>
|
||
<a href="/docs/execution-plan.md"><strong>실행 계획</strong><span>구현 상태와 향후 단계</span></a>
|
||
<a href="/tests/"><strong>브라우저 테스트</strong><span>단위·통합 테스트 실행</span></a>
|
||
<a href="/benchmarks/webgpu-scaling.html"><strong>WebGPU 측정</strong><span>현재 장치 benchmark</span></a>
|
||
</section>
|
||
</main>
|
||
</body>
|
||
</html>
|