samgeo3-lab/README.md

samgeo3-lab

독립 SamGeo3 (SAM 3 / SAM 3.1) 세그멘테이션 실험 프로젝트.

• 패키지: 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, 프로젝트 루트에서:

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. (선택) 로컬 체크포인트만 쓰려면:

$env:SAM3_CHECKPOINT_PATH = "C:\path\to\sam3.1_multiplex.pt"

실행

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 빠른 참고

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