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,180 @@
+# samgeo3-lab
+
+독립 SamGeo3 (SAM 3 / SAM 3.1) 세그멘테이션 실험 프로젝트.
+
+- **패키지**: [segment-geospatial](https://github.com/opengeos/segment-geospatial) (`SamGeo3`)
+- **문서**: https://samgeo.gishub.org  
+- **범위**: 설치 검증 + 단일 이미지 텍스트 프롬프트 세그멘테이션
+- **비범위**: railway-client / sam31server 통합, 철도 후처리, REST API
+
+기존 SAM 서버 env/코드와 **공유하지 않습니다**. 이 폴더의 `.venv`만 사용하세요.
+
+## 가정 (이 머신 기준)
+
+| 항목 | 상태 |
+|------|------|
+| GPU | NVIDIA RTX 3060 (드라이버 CUDA 13.x 가능) |
+| conda / pixi | 미설치 → **`uv` + Python 3.12 venv** 사용 |
+| HF 토큰 | `~/.cache/huggingface/token` 존재 |
+| 체크포인트 | `facebook/sam3.1` HF 캐시 이미 존재 (~3.3GB) |
+
+## 폴더 구조
+
+```
+samgeo3-lab/
+  README.md
+  requirements.txt
+  pyproject.toml
+  scripts/
+    check_install.py         # 설치/GPU/import 확인 (+ 옵션: 모델 로드)
+    text_segment.py          # 단일 이미지 텍스트 세그멘테이션
+    multi_prompt_segment.py  # 멀티 프롬프트 일괄 세그 (모델 1회 로드)
+  prompts/
+    dji_20260306_0016.json   # Grok+Gemini 병합 multi-object 프롬프트
+    README.md
+  docs/usage.html
+  data/                      # 입력 이미지
+  output/                    # 마스크/시각화 결과
+  .venv/                     # 로컬 가상환경 (gitignore)
+```
+
+## 설치 (Windows + GPU)
+
+PowerShell, 프로젝트 루트에서:
+
+```powershell
+cd D:\MYCLAUDE_PROJECT\samgeo3-lab
+
+# 1) 독립 venv (Python 3.12)
+uv venv --python 3.12 .venv
+.\.venv\Scripts\Activate.ps1
+
+# 2) CUDA PyTorch 먼저 (CPU wheel 덮어쓰기 방지)
+uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
+
+# 3) SamGeo3 extras only (api / all 설치 금지)
+uv pip install "segment-geospatial[samgeo3]>=1.4.1" matplotlib
+
+# 4) Windows: sam3 import에 필요 (pip extra가 빠질 수 있음)
+uv pip install "triton-windows>=3.3.0.post19"
+
+# 5) (선택) 노트북
+uv pip install ipykernel jupyterlab
+```
+
+### 대안: pixi (공식 권장)
+
+conda/pixi를 쓸 수 있으면 공식 문서 권장 경로가 더 안정적입니다.  
+https://samgeo.gishub.org/installation/#install-with-pixi-recommended
+
+### Hugging Face (SAM 3 / 3.1)
+
+1. https://huggingface.co/facebook/sam3.1 접근 승인  
+2. 인증: `hf auth login` (또는 기존 토큰 파일 유지)  
+3. (선택) 로컬 체크포인트만 쓰려면:
+
+```powershell
+$env:SAM3_CHECKPOINT_PATH = "C:\path\to\sam3.1_multiplex.pt"
+```
+
+## 실행
+
+```powershell
+cd D:\MYCLAUDE_PROJECT\samgeo3-lab
+.\.venv\Scripts\Activate.ps1
+
+# A) 패키지/GPU 확인
+python scripts/check_install.py
+
+# B) 모델 로드까지 확인 (캐시/다운로드)
+python scripts/check_install.py --load-model
+
+# C) 샘플 이미지 텍스트 세그멘테이션
+python scripts/text_segment.py
+# 동의어 (기본 confidence=0.3 — sam3.1 score가 0.5 미만인 경우 많음):
+python scripts/text_segment.py --prompt person --confidence 0.3
+
+# D) 자체 이미지
+python scripts/text_segment.py --image data\my.jpg --prompt building --min-size 100
+
+# E) 멀티 프롬프트 (Grok+Gemini 병합 세트, 모델 1회 로드)
+python scripts/multi_prompt_segment.py --list-only --tier compact
+python scripts/multi_prompt_segment.py --tier compact --confidence 0.3
+python scripts/multi_prompt_segment.py --tier A_high
+python scripts/multi_prompt_segment.py --tier all --confidence 0.25
+# DJI 드론 정사 기본 이미지: data/DJI_20260306100802_0016.JPG
+# 프롬프트 JSON: prompts/dji_20260306_0016.json
+
+# F) 누락 보강 (Gemini gap) — 같은 output 폴더에 추가
+python scripts\multi_prompt_segment.py `
+  --tier gap --confidence 0.25 `
+  --output-dir output\dji_0016_compact
+
+# G) 멀티 결과 한 장으로 합치기 (overlay + grid + HTML)
+python scripts\merge_multi_results.py `
+  --result-dir output\dji_0016_compact `
+  --image data\DJI_20260306100802_0016.JPG
+# → output\dji_0016_compact\merged\index.html  (디스크 마스크 전부 병합)
+
+# H) 예시: DJI_0100 전체 파이프라인 (0044 프롬프트 → compact → gap → gap2_core → merge)
+$img = "data\DJI_20260306101434_0100.JPG"
+$out = "output\dji_0100_compact"
+$json = "prompts\dji_20260306_0044.json"
+
+python scripts\multi_prompt_segment.py --prompts-json $json --list-only --tier compact
+
+python scripts\multi_prompt_segment.py `
+  --prompts-json $json --image $img --tier compact --confidence 0.3 --output-dir $out
+# (선택) gap / gap2_core 보강 — 같은 $out 에 추가
+python scripts\multi_prompt_segment.py `
+  --prompts-json $json --image $img --tier gap --confidence 0.25 --output-dir $out
+python scripts\multi_prompt_segment.py `
+  --prompts-json $json --image $img --tier gap2_core --confidence 0.22 --output-dir $out
+
+python scripts\merge_multi_results.py --result-dir $out --image $img --max-side 2048
+start "$out\merged\index.html"
+```
+
+상세 주석 버전은 `prompts/README.md` §「DJI_0100 전체 파이프라인」을 보세요.
+
+결과 파일은 `output/` 아래에 저장됩니다.
+
+| 파일 | 내용 |
+|------|------|
+| `*_mask.png` | 인스턴스별 unique mask |
+| `*_scores.npy` | 객체별 confidence 점수 |
+| `*_ann.png` | 오버레이 시각화 |
+
+**참고**: 모델 로드 시 `missing_keys` 경고가 날 수 있음 (`sam3` 패키지 vs `sam3.1` 체크포인트 일부 키 불일치). 추론은 동작하나 score가 낮을 수 있어 `--confidence` 튜닝이 필요합니다.
+
+## SamGeo3 빠른 참고
+
+```python
+from samgeo import SamGeo3
+
+sam = SamGeo3(
+    backend="meta",                 # sam3.1 은 meta 전용
+    model_id="facebook/sam3.1",
+    confidence_threshold=0.5,
+    resolution=1008,
+)
+sam.set_image("data/test_image.jpg")
+sam.generate_masks("person")
+sam.save_masks("output/mask.png")
+```
+
+- `backend="meta"`: `facebook/sam3`, `facebook/sam3.1`, 배치·인터랙티브 지원  
+- `backend="transformers"`: `facebook/sam3` 만  
+
+## 검증 순서
+
+1. `check_install.py` — CUDA + imports  
+2. `check_install.py --load-model` — 가중치 로드  
+3. `text_segment.py` — 마스크 저장 확인  
+4. `confidence` / `min_size` 튜닝 후 실데이터 실험  
+
+## 참고
+
+- 업스트림: https://github.com/opengeos/segment-geospatial  
+- API 문서: https://samgeo.gishub.org/samgeo3/  
+- 라이선스(업스트림): MIT