docs: guide acoustic modeling and realtime porting

docs/index.html

@@ -18,6 +18,7 @@
         <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>
@@ -25,11 +26,10 @@
 
     <main class="guide-shell">
       <section class="guide-hero">
-        <p class="eyebrow">Local user guide</p>
-        <h1>설치 없이 시작하는<br />음향 카메라 실험</h1>
+        <h1>micarrsim 사용 설명서</h1>
         <p>
-          Windows 10/11과 최신 Chrome 또는 Edge만 있으면 됩니다. 모든 입력과 계산은 이
-          컴퓨터의 브라우저 안에서 처리되며 외부 서버로 업로드되지 않습니다.
+          <code>start.cmd</code>로 열고, 장면을 실행하고, 결과를 저장하는 순서만 먼저 확인하세요.
+          입력과 계산은 로컬 브라우저에서 처리됩니다.
         </p>
       </section>
 
@@ -41,7 +41,7 @@
           <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>Snapshot 카드의 <strong>▶ Snapshot 실행</strong>을 누릅니다.</li>
             <li>완료되면 <strong>Result JSON</strong>을 눌러 다운로드 폴더에 저장합니다.</li>
           </ol>
           <aside class="callout">
@@ -59,8 +59,8 @@
           <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><strong>라이브 준비</strong>를 눌러 기본 2 Hz map을 계산합니다.</li>
+            <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">
@@ -91,7 +91,7 @@
               Assets에서 Builder에 사용한 원본 이미지와 오디오를 한 번에 다시 선택합니다.
               준비 상태가 모두 초록색인지 확인합니다.
             </li>
-            <li><strong>Auto (GPU→CPU)</strong>로 실행한 뒤 Result JSON을 저장합니다.</li>
+            <li>Snapshot 또는 Moving을 선택해 <strong>Auto (GPU→CPU)</strong>로 실행한 뒤 Result JSON을 저장합니다.</li>
           </ol>
 
           <aside class="callout callout--important" id="asset-reconnect">
@@ -120,7 +120,7 @@
               <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>
+                <tr><td>CPU 강제</td><td>동일한 conventional DAS를 CPU에서 계산</td><td>호환성 확인·기준 비교</td></tr>
               </tbody>
             </table>
           </div>
@@ -136,8 +136,29 @@
         </div>
       </section>
 
-      <section class="guide-section" id="results">
+      <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>
@@ -147,6 +168,7 @@
             <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>
@@ -169,7 +191,7 @@
       </section>
 
       <section class="guide-section" id="troubleshooting">
-        <div class="section-number">06</div>
+        <div class="section-number">07</div>
         <div>
           <p class="eyebrow">Troubleshooting</p>
           <h2>막혔을 때 확인할 것</h2>
@@ -198,22 +220,23 @@
             <p>두 음원이 같은 주파수 대역인지 확인하고 Peak 검출 임계값을 낮추세요. gain 차이, main-lobe 폭보다 짧은 거리, grid 간격과 sidelobe는 threshold만으로 해결되지 않을 수 있습니다.</p>
           </details>
           <details>
-            <summary>라이브 준비 버튼이 비활성화됩니다.</summary>
-            <p>Scene에 시간 순서가 올바른 trajectory keyframe이 두 개 이상 있어야 합니다. Builder에서 시간에 따라 음원 이동을 켜거나 Camera의 이동 예제를 사용하세요.</p>
+            <summary>Map 준비 버튼이 비활성화됩니다.</summary>
+            <p>Scene에 시간 순서가 올바른 trajectory keyframe이 두 개 이상 있어야 합니다. Builder에서 시간에 따라 음원 이동을 켜거나 Camera의 이동 예제 열기를 사용하세요.</p>
           </details>
         </div>
       </section>
 
       <section class="guide-section">
-        <div class="section-number">07</div>
+        <div class="section-number">08</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와 실제 192채널 capture stream은 현재 범위에 포함되지 않습니다. 결과는 실제
-            장비의 절대 성능 보증이 아니라 같은 조건에서 배열을 비교하는 재현 가능한 기준입니다.
+            micarrsim 1.0은 점 음원의 자유음장과 계산량을 제한한 shoebox 희소 경로, 마이크
+            주파수 응답과 conventional DAS를 제공합니다. 파동 방정식·고차 반사·재질별 흡음,
+            복잡한 mesh, sensor self-noise·비선형, ADC·clock, DAMAS/CLEAN-SC와 자동 장치
+            capture adapter는 포함하지 않습니다. 결과는 장비의 절대 성능 보증이 아니라 같은
+            조건에서 배열과 알고리즘을 비교하는 재현 가능한 기준입니다.
           </p>
           <p class="guide-copy">
             원본 asset은 브라우저 메모리에서만 읽고 서버나 외부 네트워크로 보내지 않습니다.
@@ -226,6 +249,8 @@
         <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>