Files
micarrsim/docs/index.html
T

365 lines
24 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!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="#activity">전 대역 검사</a>
<a href="#array-builder">배열 만들기</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="activity">
<div class="section-number">03</div>
<div>
<p class="eyebrow">Unknown-frequency activity</p>
<h2>분석 주파수를 모를 때</h2>
<ol class="guide-steps">
<li><a href="/apps/acoustic-camera/">Acoustic Camera</a>의 분석 대역 아래 <strong>전 대역 활동 검사</strong>를 펼칩니다.</li>
<li>한 물리 마이크와 OS-CFAR·CA-CFAR 또는 Dixon spectral flux를 고르고 <strong>전 대역 검사</strong>를 누릅니다.</li>
<li>CFAR candidate의 ADC bin과 raw CUT/reference/threshold를 확인합니다. Spectral flux는 onset novelty만 봅니다.</li>
<li>아날로그 center 가설을 직접 입력해 별도 band로 추가한 뒤 Snapshot 위치추정을 실행합니다.</li>
<li>모든 complete frame/bin은 <strong>Activity JSON</strong>으로 저장합니다.</li>
</ol>
<aside class="callout callout--important">
Nyquist 초과 가설도 허용하지만 Scene truth로 원 주파수를 고르지 않습니다.
CFAR Pfa는 tested CUT 하나당 명목값이고 spectral flux는 확률이 아닙니다.
검출기·band·위치 map의 자동 fusion도 하지 않습니다.
<a href="/docs/activity-detection.md">수식과 물리적 한계</a>를 함께 확인하세요.
</aside>
</div>
</section>
<section class="guide-section" id="array-builder">
<div class="section-number">04</div>
<div>
<p class="eyebrow">Microphone geometry</p>
<h2>내 마이크 배열 만들기</h2>
<ol class="guide-steps">
<li><a href="/apps/array-builder/">Array Builder</a>에서 aperture 너비·높이와 사각형 또는 타원 생성 경계를 정합니다.</li>
<li>격자·선형·원형 링·Archimedean 나선·Fermat 나선·균일 랜덤 중 하나를 고릅니다. 랜덤은 seed와 최소 간격으로 재현성과 채널 간 거리를 제어합니다.</li>
<li>canvas의 <strong>추가</strong> 도구로 마이크를 놓고, 점을 드래그하거나 x/y/z 필드로 좌표를 수정합니다.</li>
<li>3D 검사에서 등각 또는 ±X/±Y/±Z 축에서 원점을 보는 시점으로 배치와 +Z FRONT를 확인합니다.</li>
<li>canvas 아래 <strong>수신 빔 패턴</strong>에서 아날로그 주파수·XZ/YZ/XY 절단면·조향각에 따른 polar 응답을 확인하고, 3D 패턴도 같은 축 시점으로 정렬합니다.</li>
<li>목록에서 마이크를 삭제하거나 채널 순서를 바꾸고, 상태가 <strong>Array JSON 저장 가능</strong>이면 저장합니다.</li>
<li><a href="/apps/acoustic-camera/">Acoustic Camera</a>의 <strong>Array</strong> 입력에서 저장한 파일을 선택합니다.</li>
</ol>
<aside class="callout">
가져온 채널의 sensitivity, phase와 frequency-response 보정은 위치·순서 편집 중 보존됩니다.
다만 프리셋으로 마이크 목록을 교체하면 기존 채널별 보정도 교체됩니다.
</aside>
<aside class="callout callout--important">
생성 경계 형상, 프리셋 종류, seed와 최소 간격은 편집기 설정이라 표준 Array JSON에
저장되지 않습니다. Camera가 사용하는 것은 저장된 aperture와 최종 마이크 좌표·순서입니다.
</aside>
<aside class="callout">
빔 패턴은 이상적으로 보정된 무지향성 point microphone의 narrowband far-field
geometry-only 수신 단면입니다. Nyquist 초과 주파수도 원 파장으로 계산하며, angular
phase-step 기준이 부족하면 raw polar 선만 남기고 HPBW·peak 해석을 보류합니다.
<a href="/docs/beam-pattern.md">수식과 제한 보기</a>
</aside>
</div>
</section>
<section class="guide-section" id="full-workflow">
<div class="section-number">05</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> 순서로
가져오는 것을 권장합니다. Experiment는 어느 시점에 열어도 분석 대역을 보존하고
<code>sceneId</code>와 <code>arrayId</code> provenance label도 덮어쓰지 않습니다.
실행에는 현재 열린 Scene·Array를 사용하고 Result에 실제 입력 ID와 hash를 기록합니다.
Array Builder에서 저장한 파일이 있다면 Array
단계에서 선택하고, 내 Array/Experiment가 없다면 내장 기본값을 그대로 둡니다.
</li>
<li>
Assets에서 Builder에 사용한 원본 이미지와 오디오를 한 번에 다시 선택합니다.
준비 상태가 모두 초록색인지 확인합니다.
</li>
<li>Snapshot 또는 Moving을 선택해 <strong>Auto (GPU→CPU)</strong>로 실행한 뒤 Result JSON을 저장합니다.</li>
</ol>
<aside class="callout">
데스크톱에서는 설정과 작업 영역 사이의 선을 드래그하거나 방향키로 패널 폭을 조절할
수 있습니다. <kbd>Enter</kbd> 또는 더블클릭하면 기본 폭으로 돌아갑니다. 폭은 각 Builder와
Camera별로 이 브라우저에 저장되며, 좁은 화면에서는 두 영역이 자동으로 위아래로
배치됩니다.
</aside>
<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">06</div>
<div>
<p class="eyebrow">Localization &amp; 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">07</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">08</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">09</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>참조 ID는 provenance label이라 현재 Scene·Array와 달라도 보존되며 실행을 막지 않습니다. Nyquist 위 tone·band는 ideal ADC alias로 실행되고 원/관측 주파수가 함께 표시됩니다. 실행할 수 없다면 검증 카드에서 scan 범위나 asset처럼 실제 입력 오류를 확인하세요.</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">10</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/array-builder/README.md"><strong>Array Builder 설명서</strong><span>마이크 배치·프리셋·JSON</span></a>
<a href="/apps/dataset-builder/README.md"><strong>Dataset 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/activity-detection.md"><strong>전 대역 활동 검출</strong><span>CFAR·spectral flux·alias 가설</span></a>
<a href="/docs/beam-pattern.md"><strong>수신 빔 패턴</strong><span>array factor·HPBW·해상도</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>