micarrsim/docs/index.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">Compute backend</p>
          <h2>속도와 격자 선택</h2>
          <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>GPU 장치가 없거나 실패하면 fallback 없이 오류</td><td>GPU 비교·측정</td></tr>
                <tr><td>CPU 강제</td><td>동일한 conventional DAS를 CPU에서 계산</td><td>호환성 확인·기준 비교</td></tr>
              </tbody>
            </table>
          </div>
          <p class="guide-copy">
            먼저 50×50을 권장합니다. 100×100은 4배, 200×200은 16배의 scan point를 계산합니다.
            실행 중에는 취소할 수 있으며, 취소하거나 실패해도 이전 완료 결과는 유지됩니다.
          </p>
          <p class="guide-copy">
            복수 음원에서 약한 peak가 빠지면 <strong>Peak 검출 임계값</strong>을 기본 25%에서
            10–20%로 낮춰 보세요. 약한 후보와 함께 sidelobe 오검출도 늘 수 있으며, main lobe보다
            가까운 같은 대역 음원은 conventional DAS에서 하나로 합쳐질 수 있습니다.
          </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는 수신 신호에 적용하며 DAS 역보정 유무를 비교할 수 있습니다.
            값과 한계는 <a href="/docs/acoustic-model.md">음향 모델 설명</a>에서 확인하세요.
          </p>
          <p class="guide-copy">
            실제 동기식 마이크 채널은 Scene 합성 없이 portable CPU DAS에 넣을 수 있습니다.
            장치별 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>rawMap / displayMap</dt><dd>선형 power 원본과 화면 표시용 acoustic map</dd></div>
            <div><dt>peaks</dt><dd>검출 위치, source 매칭, m·pixel 위치 오차</dd></div>
            <div><dt>beamSpread</dt><dd>half-power lobe의 power 가중 공분산과 1× RMS ellipse</dd></div>
            <div><dt>metrics</dt><dd>energy 비율, 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>backend, grid·scan 범위, 장치 정보와 구간별 시간</dd></div>
            <div><dt>inputHash</dt><dd>Array·Scene·Experiment 입력을 묶은 SHA-256 재현성 식별자</dd></div>
            <div><dt>comparison-history</dt><dd>세션의 배열별 시간·위치 오차·PSR 요약을 한 번에 저장</dd></div>
          </dl>
          <aside class="callout">
            화면의 <strong>빔 분포</strong> 1×/2× RMS contour는 acoustic power lobe의 모양입니다.
            위치 확률, Gaussian 신뢰구간 또는 보정된 측정 불확실성이 아닙니다.
          </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부터 실행하세요. 최신 Chrome/Edge와 그래픽 드라이버도 확인하세요.</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 희소 경로, 마이크
            주파수 응답과 conventional DAS를 제공합니다. 파동 방정식·고차 반사·재질별 흡음,
            복잡한 mesh, sensor self-noise·비선형, ADC·clock, DAMAS/CLEAN-SC와 자동 장치
            capture adapter는 포함하지 않습니다. 결과는 장비의 절대 성능 보증이 아니라 같은
            조건에서 배열과 알고리즘을 비교하는 재현 가능한 기준입니다.
          </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>