minsung
34a885bcf8
Scripts, prompt JSON tiers, usage docs, and README. Input images (data/) and segmentation outputs (output/) are gitignored.
764 lines
28 KiB
HTML
764 lines
28 KiB
HTML
<!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]>=1.4.1" matplotlib</span>
|
||
|
||
<span class="c"># 4) Windows: sam3 import에 필요</span>
|
||
<span class="cmd">uv pip install "triton-windows>=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/<이미지stem>_<tier>/</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>=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>
|