Initial publish: SamGeo3 multi-prompt segmentation lab.

Scripts, prompt JSON tiers, usage docs, and README. Input images (data/) and segmentation outputs (output/) are gitignored.
2026-07-15 16:11:59 +09:00
commit 34a885bcf8
16 changed files with 4586 additions and 0 deletions
@@ -0,0 +1,763 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>samgeo3-lab 사용법 — SamGeo3 / SAM 3.1</title>
+  <style>
+    :root {
+      --bg: #0f1419;
+      --panel: #1a2332;
+      --panel2: #243044;
+      --text: #e7ecf3;
+      --muted: #9aa8bc;
+      --accent: #3d9cf0;
+      --accent2: #5eead4;
+      --warn: #fbbf24;
+      --ok: #34d399;
+      --border: #2d3a4f;
+      --code-bg: #0b1220;
+      --radius: 10px;
+      --shadow: 0 8px 28px rgba(0,0,0,.35);
+      --font: "Segoe UI", "Malgun Gothic", "Apple SD Gothic Neo", sans-serif;
+      --mono: "Cascadia Code", "Consolas", "Courier New", monospace;
+    }
+
+    * { box-sizing: border-box; }
+    html { scroll-behavior: smooth; }
+    body {
+      margin: 0;
+      font-family: var(--font);
+      background: linear-gradient(160deg, #0b1020 0%, #121a28 40%, #0f1419 100%);
+      color: var(--text);
+      line-height: 1.65;
+      min-height: 100vh;
+    }
+
+    .wrap {
+      max-width: 920px;
+      margin: 0 auto;
+      padding: 2rem 1.25rem 4rem;
+    }
+
+    header.hero {
+      background: linear-gradient(135deg, #1e3a5f 0%, #0f766e 100%);
+      border-radius: 16px;
+      padding: 2rem 1.75rem;
+      box-shadow: var(--shadow);
+      margin-bottom: 1.75rem;
+    }
+    header.hero h1 {
+      margin: 0 0 .4rem;
+      font-size: 1.85rem;
+      letter-spacing: -.02em;
+    }
+    header.hero p {
+      margin: 0;
+      color: rgba(255,255,255,.9);
+      max-width: 40rem;
+    }
+    .badges {
+      display: flex;
+      flex-wrap: wrap;
+      gap: .5rem;
+      margin-top: 1rem;
+    }
+    .badge {
+      display: inline-block;
+      font-size: .75rem;
+      font-weight: 600;
+      padding: .25rem .6rem;
+      border-radius: 999px;
+      background: rgba(255,255,255,.15);
+      border: 1px solid rgba(255,255,255,.2);
+    }
+
+    nav.toc {
+      background: var(--panel);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      padding: 1rem 1.25rem;
+      margin-bottom: 1.75rem;
+    }
+    nav.toc h2 {
+      margin: 0 0 .6rem;
+      font-size: .95rem;
+      color: var(--accent2);
+      text-transform: uppercase;
+      letter-spacing: .06em;
+    }
+    nav.toc ol {
+      margin: 0;
+      padding-left: 1.25rem;
+    }
+    nav.toc a {
+      color: var(--text);
+      text-decoration: none;
+    }
+    nav.toc a:hover { color: var(--accent); text-decoration: underline; }
+
+    section {
+      background: var(--panel);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      padding: 1.35rem 1.4rem 1.5rem;
+      margin-bottom: 1.25rem;
+      box-shadow: 0 2px 12px rgba(0,0,0,.2);
+    }
+    section h2 {
+      margin: 0 0 .85rem;
+      font-size: 1.25rem;
+      border-bottom: 1px solid var(--border);
+      padding-bottom: .55rem;
+      color: #fff;
+    }
+    section h3 {
+      margin: 1.25rem 0 .5rem;
+      font-size: 1.05rem;
+      color: var(--accent2);
+    }
+    p { margin: .55rem 0; color: var(--text); }
+    .muted { color: var(--muted); }
+    ul, ol { margin: .4rem 0 .8rem; padding-left: 1.3rem; }
+    li { margin: .3rem 0; }
+    a { color: var(--accent); }
+
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: .92rem;
+      margin: .75rem 0 1rem;
+    }
+    th, td {
+      border: 1px solid var(--border);
+      padding: .55rem .7rem;
+      text-align: left;
+      vertical-align: top;
+    }
+    th {
+      background: var(--panel2);
+      color: var(--accent2);
+      font-weight: 600;
+    }
+    tr:nth-child(even) td { background: rgba(255,255,255,.02); }
+    code, kbd {
+      font-family: var(--mono);
+      font-size: .86em;
+      background: var(--code-bg);
+      padding: .12em .4em;
+      border-radius: 4px;
+      border: 1px solid var(--border);
+    }
+    pre {
+      background: var(--code-bg);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 1rem 1.1rem;
+      overflow-x: auto;
+      font-family: var(--mono);
+      font-size: .82rem;
+      line-height: 1.55;
+      margin: .7rem 0 1rem;
+      color: #d1e0f5;
+    }
+    pre .c { color: #6b8a9e; } /* comment */
+    pre .cmd { color: #7dd3fc; }
+
+    .callout {
+      border-radius: 8px;
+      padding: .85rem 1rem;
+      margin: .9rem 0;
+      border-left: 4px solid var(--accent);
+      background: rgba(61,156,240,.1);
+    }
+    .callout.warn {
+      border-left-color: var(--warn);
+      background: rgba(251,191,36,.1);
+    }
+    .callout.ok {
+      border-left-color: var(--ok);
+      background: rgba(52,211,153,.1);
+    }
+    .callout strong { display: block; margin-bottom: .25rem; }
+
+    .steps {
+      counter-reset: step;
+      list-style: none;
+      padding: 0;
+    }
+    .steps > li {
+      counter-increment: step;
+      position: relative;
+      padding: .75rem 0 .75rem 3rem;
+      border-bottom: 1px solid var(--border);
+    }
+    .steps > li:last-child { border-bottom: none; }
+    .steps > li::before {
+      content: counter(step);
+      position: absolute;
+      left: 0;
+      top: .85rem;
+      width: 1.85rem;
+      height: 1.85rem;
+      border-radius: 50%;
+      background: var(--accent);
+      color: #041018;
+      font-weight: 700;
+      font-size: .85rem;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+
+    footer {
+      text-align: center;
+      color: var(--muted);
+      font-size: .85rem;
+      margin-top: 2rem;
+    }
+    .path { color: var(--accent2); font-family: var(--mono); font-size: .9em; }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <header class="hero">
+      <h1>samgeo3-lab 사용법</h1>
+      <p>
+        segment-geospatial의 <strong>SamGeo3</strong> 백엔드로
+        SAM 3 / SAM 3.1 텍스트 프롬프트 세그멘테이션을 실험하는
+        <strong>독립 프로젝트</strong> 가이드입니다.
+      </p>
+      <div class="badges">
+        <span class="badge">Python 3.12</span>
+        <span class="badge">CUDA / RTX GPU</span>
+        <span class="badge">backend=meta</span>
+        <span class="badge">facebook/sam3.1</span>
+        <span class="badge">Windows</span>
+      </div>
+    </header>
+
+    <nav class="toc" aria-label="목차">
+      <h2>목차</h2>
+      <ol>
+        <li><a href="#overview">개요 · 범위</a></li>
+        <li><a href="#structure">폴더 구조</a></li>
+        <li><a href="#install">설치</a></li>
+        <li><a href="#hf">Hugging Face · 체크포인트</a></li>
+        <li><a href="#run">실행 커맨드</a></li>
+        <li><a href="#cli">text_segment.py 옵션</a></li>
+        <li><a href="#multi">멀티 프롬프트 (Grok+Gemini)</a></li>
+        <li><a href="#example-0100">예시: DJI_0100 전체 파이프라인</a></li>
+        <li><a href="#output">출력 파일</a></li>
+        <li><a href="#api">Python API 빠른 참고</a></li>
+        <li><a href="#tips">튜닝 · 트러블슈팅</a></li>
+        <li><a href="#links">참고 링크</a></li>
+        <li><a href="dji_gap_fill.html">DJI_0016 갭 필 리포트</a></li>
+        <li><a href="dji_0044_prompts.html">DJI_0044 철로+도로 프롬프트</a></li>
+      </ol>
+    </nav>
+
+    <section id="overview">
+      <h2>1. 개요 · 범위</h2>
+      <p>
+        프로젝트 경로: <span class="path">D:\MYCLAUDE_PROJECT\samgeo3-lab</span>
+      </p>
+      <table>
+        <thead>
+          <tr><th>항목</th><th>내용</th></tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td>패키지</td>
+            <td><code>segment-geospatial</code> (PyPI) — 클래스 <code>SamGeo3</code></td>
+          </tr>
+          <tr>
+            <td>하는 일</td>
+            <td>설치 검증, 단일 이미지 텍스트 세그멘테이션, 마스크/시각화 저장</td>
+          </tr>
+          <tr>
+            <td>하지 않는 일</td>
+            <td>railway-client / sam31server 통합, 철도 후처리, REST API, AnyLabeling/YOLO 파이프라인</td>
+          </tr>
+          <tr>
+            <td>환경 원칙</td>
+            <td>이 폴더의 <code>.venv</code>만 사용. 다른 SAM 서버 env와 <strong>섞지 않음</strong></td>
+          </tr>
+        </tbody>
+      </table>
+      <div class="callout ok">
+        <strong>이미 구성된 경우</strong>
+        설치 단계는 건너뛰고 <a href="#run">§5 실행 커맨드</a>부터 진행하면 됩니다.
+      </div>
+    </section>
+
+    <section id="structure">
+      <h2>2. 폴더 구조</h2>
+      <pre>samgeo3-lab/
+  README.md
+  docs/usage.html          ← 이 문서
+  requirements.txt
+  pyproject.toml
+  scripts/
+    check_install.py       # GPU / import / (옵션) 모델 로드 확인
+    text_segment.py        # 단일 이미지 텍스트 세그멘테이션
+  data/                    # 입력 이미지
+  output/                  # 마스크 · 점수 · 오버레이 결과
+  .venv/                   # 독립 가상환경</pre>
+    </section>
+
+    <section id="install">
+      <h2>3. 설치 (Windows + GPU)</h2>
+      <p class="muted">PowerShell에서 프로젝트 루트로 이동한 뒤 순서대로 실행합니다.</p>
+      <pre><span class="cmd">cd D:\MYCLAUDE_PROJECT\samgeo3-lab</span>
+
+<span class="c"># 1) 독립 venv (Python 3.12)</span>
+<span class="cmd">uv venv --python 3.12 .venv</span>
+<span class="cmd">.\.venv\Scripts\Activate.ps1</span>
+
+<span class="c"># 2) CUDA PyTorch 먼저 (CPU wheel 덮어쓰기 방지)</span>
+<span class="cmd">uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121</span>
+
+<span class="c"># 3) SamGeo3 extras only (api / all 설치 금지)</span>
+<span class="cmd">uv pip install "segment-geospatial[samgeo3]&gt;=1.4.1" matplotlib</span>
+
+<span class="c"># 4) Windows: sam3 import에 필요</span>
+<span class="cmd">uv pip install "triton-windows&gt;=3.3.0.post19"</span>
+
+<span class="c"># 5) (선택) 노트북</span>
+<span class="cmd">uv pip install ipykernel jupyterlab</span></pre>
+
+      <div class="callout warn">
+        <strong>주의</strong>
+        <code>triton-windows</code>가 없으면 <code>import sam3</code> 가 실패합니다.
+        <code>segment-geospatial[samgeo3]</code> 설치 후에도 반드시 확인하세요.
+      </div>
+
+      <h3>대안: pixi (공식 권장)</h3>
+      <p>
+        conda/pixi 환경이 가능하면 PyTorch·CUDA·SAM3 의존성 해결에 유리합니다.<br />
+        <a href="https://samgeo.gishub.org/installation/#install-with-pixi-recommended" target="_blank" rel="noopener">
+          samgeo.gishub.org — Install with pixi
+        </a>
+      </p>
+    </section>
+
+    <section id="hf">
+      <h2>4. Hugging Face · 체크포인트</h2>
+      <ol class="steps">
+        <li>
+          <strong>모델 접근 승인</strong><br />
+          <a href="https://huggingface.co/facebook/sam3.1" target="_blank" rel="noopener">facebook/sam3.1</a>
+          (및 필요 시 <a href="https://huggingface.co/facebook/sam3" target="_blank" rel="noopener">sam3</a>) 폼 제출 후 승인
+        </li>
+        <li>
+          <strong>인증</strong><br />
+          <code>hf auth login</code> 또는 기존 토큰 파일
+          <code>~/.cache/huggingface/token</code> 유지
+        </li>
+        <li>
+          <strong>(선택) 로컬 체크포인트</strong>
+          <pre><span class="cmd">$env:SAM3_CHECKPOINT_PATH = "C:\path\to\sam3.1_multiplex.pt"</span></pre>
+          스크립트에서는 <code>--checkpoint</code> 로도 지정 가능합니다.
+        </li>
+      </ol>
+      <div class="callout">
+        <strong>백엔드 제약</strong>
+        <ul>
+          <li><code>backend="meta"</code> — <code>facebook/sam3</code>, <code>facebook/sam3.1</code> (배치·인터랙티브 풍부)</li>
+          <li><code>backend="transformers"</code> — <code>facebook/sam3</code> 만. <strong>sam3.1은 meta 전용</strong></li>
+        </ul>
+      </div>
+    </section>
+
+    <section id="run">
+      <h2>5. 실행 커맨드</h2>
+      <p>매번 가상환경을 활성화한 뒤 실행합니다.</p>
+      <pre><span class="cmd">cd D:\MYCLAUDE_PROJECT\samgeo3-lab</span>
+<span class="cmd">.\.venv\Scripts\Activate.ps1</span>
+
+<span class="c"># A) 패키지 / GPU / import 확인</span>
+<span class="cmd">python scripts\check_install.py</span>
+
+<span class="c"># B) 모델 로드까지 확인 (HF 캐시 또는 다운로드)</span>
+<span class="cmd">python scripts\check_install.py --load-model</span>
+
+<span class="c"># C) 샘플 이미지 텍스트 세그멘테이션 (기본 prompt=person, confidence=0.3)</span>
+<span class="cmd">python scripts\text_segment.py</span>
+<span class="cmd">python scripts\text_segment.py --prompt person --confidence 0.3</span>
+
+<span class="c"># D) 자체 이미지</span>
+<span class="cmd">python scripts\text_segment.py --image data\my.jpg --prompt building --min-size 100</span></pre>
+
+      <h3>권장 검증 순서</h3>
+      <ol>
+        <li><code>check_install.py</code> — CUDA + imports</li>
+        <li><code>check_install.py --load-model</code> — 가중치 로드</li>
+        <li><code>text_segment.py</code> — 마스크 저장 확인</li>
+        <li><code>--confidence</code> / <code>--min-size</code> 튜닝 후 실데이터 실험</li>
+      </ol>
+    </section>
+
+    <section id="cli">
+      <h2>6. text_segment.py 옵션</h2>
+      <table>
+        <thead>
+          <tr><th>옵션</th><th>기본값</th><th>설명</th></tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><code>--image</code></td>
+            <td><code>data/test_image.jpg</code></td>
+            <td>입력 이미지 경로 (없으면 샘플 자동 다운로드)</td>
+          </tr>
+          <tr>
+            <td><code>--prompt</code></td>
+            <td><code>person</code></td>
+            <td>텍스트 프롬프트 (예: building, tree, car)</td>
+          </tr>
+          <tr>
+            <td><code>--model-id</code></td>
+            <td><code>facebook/sam3.1</code></td>
+            <td>HF 모델 ID</td>
+          </tr>
+          <tr>
+            <td><code>--backend</code></td>
+            <td><code>meta</code></td>
+            <td><code>meta</code> | <code>transformers</code></td>
+          </tr>
+          <tr>
+            <td><code>--confidence</code></td>
+            <td><code>0.3</code></td>
+            <td>confidence threshold. 0.5면 마스크 0개일 수 있음</td>
+          </tr>
+          <tr>
+            <td><code>--mask-threshold</code></td>
+            <td><code>0.5</code></td>
+            <td>transformers 후처리용 마스크 threshold</td>
+          </tr>
+          <tr>
+            <td><code>--resolution</code></td>
+            <td><code>1008</code></td>
+            <td>meta 입력 해상도</td>
+          </tr>
+          <tr>
+            <td><code>--min-size</code> / <code>--max-size</code></td>
+            <td><code>0</code> / 없음</td>
+            <td>마스크 픽셀 면적 필터</td>
+          </tr>
+          <tr>
+            <td><code>--device</code></td>
+            <td>자동</td>
+            <td><code>cuda</code> | <code>cpu</code></td>
+          </tr>
+          <tr>
+            <td><code>--checkpoint</code></td>
+            <td>환경변수 또는 없음</td>
+            <td>로컬 <code>.pt</code> 경로</td>
+          </tr>
+          <tr>
+            <td><code>--output-dir</code></td>
+            <td><code>output/</code></td>
+            <td>결과 저장 디렉터리</td>
+          </tr>
+          <tr>
+            <td><code>--no-viz</code></td>
+            <td>off</td>
+            <td>오버레이 PNG 생략 (마스크는 저장)</td>
+          </tr>
+        </tbody>
+      </table>
+
+      <h3>check_install.py 옵션</h3>
+      <pre><span class="cmd">python scripts\check_install.py</span>
+<span class="cmd">python scripts\check_install.py --load-model</span>
+<span class="cmd">python scripts\check_install.py --load-model --model-id facebook/sam3.1 --device cuda</span></pre>
+    </section>
+
+    <section id="multi">
+      <h2>6b. 멀티 프롬프트 (Grok + Gemini 병합)</h2>
+      <p>
+        드론 정사 장면 분석 결과를 합친 프롬프트 JSON과 일괄 실행 스크립트입니다.
+        모델·이미지를 <strong>1회만</strong> 로드한 뒤 프롬프트를 순차
+        <code>generate_masks</code> 합니다.
+      </p>
+      <table>
+        <thead>
+          <tr><th>경로</th><th>설명</th></tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><code>prompts/dji_20260306_0016.json</code></td>
+            <td>tier A~D + compact, 장면 노트(KO), 권장 confidence</td>
+          </tr>
+          <tr>
+            <td><code>scripts/multi_prompt_segment.py</code></td>
+            <td>멀티 프롬프트 러너 + <code>summary.json</code></td>
+          </tr>
+          <tr>
+            <td><code>data/DJI_20260306100802_0016.JPG</code></td>
+            <td>기본 입력 (없으면 sample 경로 fallback)</td>
+          </tr>
+        </tbody>
+      </table>
+      <pre><span class="cmd">python scripts\multi_prompt_segment.py --list-only --tier compact</span>
+<span class="cmd">python scripts\multi_prompt_segment.py --tier compact --confidence 0.3</span>
+<span class="cmd">python scripts\multi_prompt_segment.py --tier A_high</span>
+<span class="cmd">python scripts\multi_prompt_segment.py --tier all --confidence 0.25</span>
+<span class="cmd">python scripts\multi_prompt_segment.py --prompts "railway track,building,solar panel"</span></pre>
+      <p class="muted">
+        tier: <code>compact</code> | <code>gap</code> | <code>gap2</code> | <code>gap2_core</code> |
+        <code>improved</code> | <code>all</code> | <code>A_high</code> |
+        <code>B_facility</code> | <code>C_detail</code> | <code>D_rail_domain</code>
+      </p>
+      <p>결과 디렉터리: <code>output/&lt;이미지stem&gt;_&lt;tier&gt;/</code> — 프롬프트별 mask/ann + <code>summary.json</code></p>
+
+      <h3>DJI 정사 — 단일 프롬프트 예시 (실제 경로)</h3>
+      <pre><span class="cmd">cd D:\MYCLAUDE_PROJECT\samgeo3-lab</span>
+<span class="cmd">.\.venv\Scripts\Activate.ps1</span>
+
+<span class="cmd">$img = "data\DJI_20260306100802_0016.JPG"</span>
+<span class="cmd">$out = "output\dji_0016_analysis"</span>
+
+<span class="cmd">python scripts\text_segment.py --image $img --prompt "solar panel" --confidence 0.3 --output-dir $out</span>
+<span class="cmd">python scripts\text_segment.py --image $img --prompt "building" --confidence 0.3 --output-dir $out</span>
+<span class="cmd">python scripts\text_segment.py --image $img --prompt "railway track" --confidence 0.3 --output-dir $out</span></pre>
+
+      <h3>기대 난이도 (정사 드론)</h3>
+      <table>
+        <thead>
+          <tr><th>프롬프트</th><th>기대</th><th>튜닝 팁</th></tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><code>building</code>, <code>solar panel</code>, <code>tree</code>, <code>car</code>, <code>truck</code></td>
+            <td>높음</td>
+            <td>기본 객체. 낮은 confidence에서도 비교적 잘 잡힘</td>
+          </tr>
+          <tr>
+            <td><code>railway track</code>, <code>fence</code>, <code>parking lot</code>, <code>blue tarp</code></td>
+            <td>중~높음</td>
+            <td>선형·구획. context에 따라 변동</td>
+          </tr>
+          <tr>
+            <td><code>utility pole</code>, <code>container</code>, <code>material pile</code></td>
+            <td>중</td>
+            <td>작거나 밀집. <code>--min-size</code> 권장</td>
+          </tr>
+          <tr>
+            <td><code>rail</code>, <code>ballast</code>, <code>railroad sleeper</code>, <code>catenary</code></td>
+            <td>낮~중</td>
+            <td>도메인·가는 객체. confidence 튜닝 필수</td>
+          </tr>
+        </tbody>
+      </table>
+      <div class="callout">
+        <strong>권장</strong>
+        confidence <strong>0.25~0.35</strong> 에서 시작. 작은 폴·미세 자재는 <code>--min-size</code>로 노이즈 필터.
+      </div>
+
+      <h3>결과 합치기 (merge)</h3>
+      <p>멀티 프롬프트 실행 후 클래스별 마스크를 <strong>한 장 오버레이 + 격자 + HTML</strong>로 합칩니다.</p>
+      <pre><span class="cmd">python scripts\merge_multi_results.py `
+  --result-dir "output\dji_0016_compact" `
+  --image "data\DJI_20260306100802_0016.JPG" `
+  --max-side 2560</span></pre>
+      <p>출력: <code>output\dji_0016_compact\merged\</code></p>
+      <ul>
+        <li><code>combined_with_legend.png</code> — 전 클래스 오버레이 + 범례</li>
+        <li><code>per_class_grid.png</code> — 클래스별 썸네일</li>
+        <li><code>index.html</code> — 브라우저 뷰</li>
+      </ul>
+    </section>
+
+    <section id="example-0100">
+      <h2>6c. 예시: DJI_0100 전체 파이프라인</h2>
+      <p>
+        0044 프롬프트 JSON(<strong>0016 상속 + 도로/열차 delta</strong>)을
+        <code>DJI_…_0100.JPG</code>에 적용하는 end-to-end 예입니다.
+        권장 순서: <code>compact</code> → (선택) <code>gap</code> → (선택) <code>gap2_core</code> → merge → HTML.
+      </p>
+      <p class="muted">
+        confidence: compact <code>0.3</code> · gap <code>0.25</code> · gap2_core <code>0.22</code>.
+        같은 출력 폴더에 단계별로 마스크를 쌓은 뒤 merge하면 한 HTML에서 전부 볼 수 있습니다.
+      </p>
+      <pre><span class="cmd">cd D:\MYCLAUDE_PROJECT\samgeo3-lab</span>
+<span class="cmd">.\.venv\Scripts\Activate.ps1</span>
+
+<span class="cmd">$img = "data\DJI_20260306101434_0100.JPG"</span>
+<span class="cmd">$out = "output\dji_0100_compact"</span>
+<span class="cmd">$json = "prompts\dji_20260306_0044.json"</span>
+
+<span class="c"># (선택) 프롬프트 목록 확인</span>
+<span class="cmd">python scripts\multi_prompt_segment.py --prompts-json $json --list-only --tier compact</span>
+
+<span class="c"># 1) 세그 — compact (0016 상속 + 도로/열차 delta)</span>
+<span class="cmd">python scripts\multi_prompt_segment.py `
+  --prompts-json $json `
+  --image $img `
+  --tier compact `
+  --confidence 0.3 `
+  --output-dir $out</span>
+
+<span class="c"># 2) (선택) gap 보강</span>
+<span class="cmd">python scripts\multi_prompt_segment.py `
+  --prompts-json $json `
+  --image $img `
+  --tier gap `
+  --confidence 0.25 `
+  --output-dir $out</span>
+
+<span class="c"># 3) (선택) gap2_core 보강</span>
+<span class="cmd">python scripts\multi_prompt_segment.py `
+  --prompts-json $json `
+  --image $img `
+  --tier gap2_core `
+  --confidence 0.22 `
+  --output-dir $out</span>
+
+<span class="c"># 4) 합치기 + interactive index.html</span>
+<span class="cmd">python scripts\merge_multi_results.py `
+  --result-dir $out `
+  --image $img `
+  --max-side 2048</span>
+
+<span class="c"># 5) 결과 열기</span>
+<span class="cmd">start "$out\merged\index.html"</span></pre>
+      <div class="callout ok">
+        <strong>결과</strong>
+        브라우저에서 <code>output\dji_0100_compact\merged\index.html</code> 을 열면
+        오버레이·클래스별 격자·범례를 한눈에 볼 수 있습니다.
+      </div>
+    </section>
+
+    <section id="output">
+      <h2>7. 출력 파일</h2>
+      <p>결과는 <code>output/</code> 아래에 저장됩니다. 파일명 패턴: <code>{이미지stem}_{prompt}_*</code></p>
+      <table>
+        <thead>
+          <tr><th>파일</th><th>내용</th></tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><code>*_mask.png</code></td>
+            <td>인스턴스별 unique mask (객체마다 다른 픽셀 값)</td>
+          </tr>
+          <tr>
+            <td><code>*_scores.npy</code></td>
+            <td>객체별 confidence 점수 (NumPy 배열). float PNG는 저장 불가</td>
+          </tr>
+          <tr>
+            <td><code>*_ann.png</code></td>
+            <td>원본 + 마스크/박스/점수 오버레이 시각화</td>
+          </tr>
+        </tbody>
+      </table>
+      <p class="muted">예: <code>test_image_person_mask.png</code>, <code>test_image_person_ann.png</code></p>
+    </section>
+
+    <section id="api">
+      <h2>8. Python API 빠른 참고</h2>
+      <pre><span class="cmd">from samgeo import SamGeo3</span>
+
+sam = SamGeo3(
+    backend="meta",                 <span class="c"># sam3.1 은 meta 전용</span>
+    model_id="facebook/sam3.1",
+    confidence_threshold=0.3,       <span class="c"># 환경에 맞게 튜닝</span>
+    resolution=1008,
+    enable_segmentation=True,
+    enable_inst_interactivity=False,
+)
+sam.set_image("data/test_image.jpg")
+sam.generate_masks("person")        <span class="c"># 텍스트 프롬프트</span>
+sam.save_masks("output/mask.png")
+sam.show_anns(output="output/ann.png")</pre>
+
+      <h3>포인트 / 박스 인터랙티브 (참고)</h3>
+      <pre>import numpy as np
+from samgeo import SamGeo3
+
+sam = SamGeo3(backend="meta", enable_inst_interactivity=True)
+sam.set_image("image.jpg")
+masks, scores, logits = sam.predict_inst(
+    point_coords=np.array([[520, 375]]),
+    point_labels=np.array([1]),   <span class="c"># 1=foreground, 0=background</span>
+)</pre>
+
+      <h3>배치 (meta만)</h3>
+      <pre>sam = SamGeo3(backend="meta")
+sam.set_image_batch(["a.jpg", "b.jpg"])
+sam.generate_masks_batch("tree")
+sam.save_masks_batch("output/", prefix="tree_mask")</pre>
+    </section>
+
+    <section id="tips">
+      <h2>9. 튜닝 · 트러블슈팅</h2>
+      <table>
+        <thead>
+          <tr><th>증상</th><th>원인 / 대응</th></tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><code>No module named 'triton'</code></td>
+            <td><code>uv pip install "triton-windows&gt;=3.3.0.post19"</code></td>
+          </tr>
+          <tr>
+            <td><code>No objects found</code></td>
+            <td>
+              <code>--confidence</code> 낮추기 (예: 0.3 → 0.2), 프롬프트 변경,
+              명확한 객체가 보이는 이미지 사용
+            </td>
+          </tr>
+          <tr>
+            <td>로드 시 <code>missing_keys</code> 경고</td>
+            <td>
+              sam3 패키지와 sam3.1 체크포인트 일부 키 불일치.
+              추론은 동작할 수 있으나 score가 낮을 수 있음 → confidence 튜닝
+            </td>
+          </tr>
+          <tr>
+            <td><code>CUDA not available</code></td>
+            <td>
+              CUDA torch 재설치, <code>nvidia-smi</code> 확인.
+              SAM3 meta는 GPU 권장 (CPU만으로는 제한)
+            </td>
+          </tr>
+          <tr>
+            <td>HF 접근 거부 / 다운로드 실패</td>
+            <td>모델 게이트 승인 + <code>hf auth login</code></td>
+          </tr>
+          <tr>
+            <td>작은 객체 과다 검출</td>
+            <td><code>--min-size</code> 로 픽셀 면적 필터</td>
+          </tr>
+          <tr>
+            <td>GeoTIFF 멀티밴드</td>
+            <td>API: <code>set_image(path, bands=[4,3,2])</code> (1-based band index)</td>
+          </tr>
+        </tbody>
+      </table>
+      <div class="callout warn">
+        <strong>confidence 기본값 0.3 이유</strong>
+        이 환경에서 sam3.1 meta score가 대략 0.33–0.35 부근으로 나오는 경우가 있어,
+        기본 0.5를 쓰면 마스크가 0개일 수 있습니다. 실데이터에서 점수 분포를 보고 조정하세요.
+      </div>
+    </section>
+
+    <section id="links">
+      <h2>10. 참고 링크</h2>
+      <ul>
+        <li>업스트림: <a href="https://github.com/opengeos/segment-geospatial" target="_blank" rel="noopener">opengeos/segment-geospatial</a></li>
+        <li>문서: <a href="https://samgeo.gishub.org" target="_blank" rel="noopener">samgeo.gishub.org</a></li>
+        <li>SamGeo3 API: <a href="https://samgeo.gishub.org/samgeo3/" target="_blank" rel="noopener">samgeo3 문서</a></li>
+        <li>설치(pixi): <a href="https://samgeo.gishub.org/installation/" target="_blank" rel="noopener">Installation</a></li>
+        <li>라이선스(업스트림): MIT</li>
+      </ul>
+    </section>
+
+    <footer>
+      samgeo3-lab · 독립 SamGeo3 실험 환경 · 생성일 2026-07-15<br />
+      파일 위치: <span class="path">docs/usage.html</span>
+    </footer>
+  </div>
+</body>
+</html>