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="#full-workflow">내 데이터</a>
        <a href="#results">결과 해석</a>
        <a href="#troubleshooting">문제 해결</a>
      </nav>
    </header>

    <main class="guide-shell">
      <section class="guide-hero">
        <p class="eyebrow">Local user guide</p>
        <h1>설치 없이 시작하는<br />음향 카메라 실험</h1>
        <p>
          Windows 10/11과 최신 Chrome 또는 Edge만 있으면 됩니다. 모든 입력과 계산은 이
          컴퓨터의 브라우저 안에서 처리되며 외부 서버로 업로드되지 않습니다.
        </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><strong>▶ 기본 예제 실행</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="full-workflow">
        <div class="section-number">02</div>
        <div>
          <p class="eyebrow">5분 전체 흐름</p>
          <h2>내 장면을 만들고 Camera에서 실행하기</h2>
          <ol class="guide-steps">
            <li>
              <a href="/apps/dataset-builder/">Dataset Builder</a>에서 이미지와 오디오를
              선택하고 음원 위치, gain, 시간, ambient를 설정합니다.
            </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><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">03</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>동일한 자유음장 DAS를 CPU에서 계산</td><td>호환성 확인·기준 비교</td></tr>
              </tbody>
            </table>
          </div>
          <p class="guide-copy">
            먼저 50×50을 권장합니다. 100×100은 4배, 200×200은 16배의 scan point를 계산합니다.
            실행 중에는 취소할 수 있으며, 취소하거나 실패해도 이전 완료 결과는 유지됩니다.
          </p>
        </div>
      </section>

      <section class="guide-section" id="results">
        <div class="section-number">04</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>metrics</dt><dd>energy 비율, precision/recall, sidelobe, main-lobe 폭</dd></div>
            <div><dt>evaluation</dt><dd>검출 threshold, 반경, tolerance 등 지표 계산 조건</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">
            평가는 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">05</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>
        </div>
      </section>

      <section class="guide-section">
        <div class="section-number">06</div>
        <div>
          <p class="eyebrow">Scope & privacy</p>
          <h2>현재 모델의 범위</h2>
          <p class="guide-copy">
            micarrsim 1.0은 점 음원, 구면 감쇠·분수 지연을 쓰는 자유음장 모델과 conventional
            DAS를 제공합니다. 실내 반사·잔향, 실제 마이크 위치 오차와 비선형성, DAMAS,
            CLEAN-SC, DCASE/MIMII 자동 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/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>