# 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