samgeo3-lab 사용법

1. 개요 · 범위

프로젝트 경로: D:\MYCLAUDE_PROJECT\samgeo3-lab

2. 폴더 구조

samgeo3-lab/
  README.md
  docs/usage.html          ← 이 문서
  requirements.txt
  pyproject.toml
  scripts/
    check_install.py       # GPU / import / (옵션) 모델 로드 확인
    text_segment.py        # 단일 이미지 텍스트 세그멘테이션
  data/                    # 입력 이미지
  output/                  # 마스크 · 점수 · 오버레이 결과
  .venv/                   # 독립 가상환경

3. 설치 (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에 필요
uv pip install "triton-windows>=3.3.0.post19"

# 5) (선택) 노트북
uv pip install ipykernel jupyterlab

대안: pixi (공식 권장)

conda/pixi 환경이 가능하면 PyTorch·CUDA·SAM3 의존성 해결에 유리합니다.
samgeo.gishub.org — Install with pixi

4. Hugging Face · 체크포인트

1. 모델 접근 승인
   facebook/sam3.1 (및 필요 시 sam3) 폼 제출 후 승인
2. 인증
   hf auth login 또는 기존 토큰 파일 ~/.cache/huggingface/token 유지
3. (선택) 로컬 체크포인트

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

   스크립트에서는 --checkpoint 로도 지정 가능합니다.

5. 실행 커맨드

매번 가상환경을 활성화한 뒤 실행합니다.

cd D:\MYCLAUDE_PROJECT\samgeo3-lab
.\.venv\Scripts\Activate.ps1

# A) 패키지 / GPU / import 확인
python scripts\check_install.py

# B) 모델 로드까지 확인 (HF 캐시 또는 다운로드)
python scripts\check_install.py --load-model

# C) 샘플 이미지 텍스트 세그멘테이션 (기본 prompt=person, confidence=0.3)
python scripts\text_segment.py
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

권장 검증 순서

1. check_install.py — CUDA + imports
2. check_install.py --load-model — 가중치 로드
3. text_segment.py — 마스크 저장 확인
4. --confidence / --min-size 튜닝 후 실데이터 실험

6. text_segment.py 옵션

check_install.py 옵션

python scripts\check_install.py
python scripts\check_install.py --load-model
python scripts\check_install.py --load-model --model-id facebook/sam3.1 --device cuda

6b. 멀티 프롬프트 (Grok + Gemini 병합)

드론 정사 장면 분석 결과를 합친 프롬프트 JSON과 일괄 실행 스크립트입니다. 모델·이미지를 1회만 로드한 뒤 프롬프트를 순차 generate_masks 합니다.

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
python scripts\multi_prompt_segment.py --prompts "railway track,building,solar panel"

tier: compact | gap | gap2 | gap2_core | improved | all | A_high | B_facility | C_detail | D_rail_domain

결과 디렉터리: output/<이미지stem>_<tier>/ — 프롬프트별 mask/ann + summary.json

DJI 정사 — 단일 프롬프트 예시 (실제 경로)

cd D:\MYCLAUDE_PROJECT\samgeo3-lab
.\.venv\Scripts\Activate.ps1

$img = "data\DJI_20260306100802_0016.JPG"
$out = "output\dji_0016_analysis"

python scripts\text_segment.py --image $img --prompt "solar panel" --confidence 0.3 --output-dir $out
python scripts\text_segment.py --image $img --prompt "building" --confidence 0.3 --output-dir $out
python scripts\text_segment.py --image $img --prompt "railway track" --confidence 0.3 --output-dir $out

기대 난이도 (정사 드론)

결과 합치기 (merge)

멀티 프롬프트 실행 후 클래스별 마스크를 한 장 오버레이 + 격자 + HTML로 합칩니다.

python scripts\merge_multi_results.py `
  --result-dir "output\dji_0016_compact" `
  --image "data\DJI_20260306100802_0016.JPG" `
  --max-side 2560

출력: output\dji_0016_compact\merged\

• combined_with_legend.png — 전 클래스 오버레이 + 범례
• per_class_grid.png — 클래스별 썸네일
• index.html — 브라우저 뷰

6c. 예시: DJI_0100 전체 파이프라인

0044 프롬프트 JSON(0016 상속 + 도로/열차 delta)을 DJI_…_0100.JPG에 적용하는 end-to-end 예입니다. 권장 순서: compact → (선택) gap → (선택) gap2_core → merge → HTML.

confidence: compact 0.3 · gap 0.25 · gap2_core 0.22. 같은 출력 폴더에 단계별로 마스크를 쌓은 뒤 merge하면 한 HTML에서 전부 볼 수 있습니다.

cd D:\MYCLAUDE_PROJECT\samgeo3-lab
.\.venv\Scripts\Activate.ps1

$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

# 1) 세그 — compact (0016 상속 + 도로/열차 delta)
python scripts\multi_prompt_segment.py `
  --prompts-json $json `
  --image $img `
  --tier compact `
  --confidence 0.3 `
  --output-dir $out

# 2) (선택) gap 보강
python scripts\multi_prompt_segment.py `
  --prompts-json $json `
  --image $img `
  --tier gap `
  --confidence 0.25 `
  --output-dir $out

# 3) (선택) gap2_core 보강
python scripts\multi_prompt_segment.py `
  --prompts-json $json `
  --image $img `
  --tier gap2_core `
  --confidence 0.22 `
  --output-dir $out

# 4) 합치기 + interactive index.html
python scripts\merge_multi_results.py `
  --result-dir $out `
  --image $img `
  --max-side 2048

# 5) 결과 열기
start "$out\merged\index.html"

7. 출력 파일

결과는 output/ 아래에 저장됩니다. 파일명 패턴: {이미지stem}_{prompt}_*

예: test_image_person_mask.png, test_image_person_ann.png

8. Python API 빠른 참고

from samgeo import SamGeo3

sam = SamGeo3(
    backend="meta",                 # sam3.1 은 meta 전용
    model_id="facebook/sam3.1",
    confidence_threshold=0.3,       # 환경에 맞게 튜닝
    resolution=1008,
    enable_segmentation=True,
    enable_inst_interactivity=False,
)
sam.set_image("data/test_image.jpg")
sam.generate_masks("person")        # 텍스트 프롬프트
sam.save_masks("output/mask.png")
sam.show_anns(output="output/ann.png")

포인트 / 박스 인터랙티브 (참고)

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]),   # 1=foreground, 0=background
)

배치 (meta만)

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")

9. 튜닝 · 트러블슈팅

10. 참고 링크

• 업스트림: opengeos/segment-geospatial
• 문서: samgeo.gishub.org
• SamGeo3 API: samgeo3 문서
• 설치(pixi): Installation
• 라이선스(업스트림): MIT