Railway Client 사용 가이드

드론 항공 이미지 기반 철도 시설물 자동 검출 파이프라인

🔴 라멘형(門) 전철주 검출 파이프라인

드론 사선 촬영 이미지에서 門자형 라멘 구조 전철주를 검출한다. SAM3.1로 폴리곤을 추출한 후 소실점(Vanishing Point) 기반 기하학 분석으로 C(기둥)/B(빔)를 분류, 라멘 그룹을 판정한다.

Step 1 — 전철주 폴리곤 추출

cd D:\MYCLAUDE_PROJECT\railway-client

.venv\Scripts\python.exe tools/detect_all_objects.py `
  --input "data/역사구간/1.회덕역/DJI_20260306100900_0034.JPG" `
  --categories configs/railway_zone.json `
  --tiles all `
  --cols 4 --rows 3 --overlap 0.10 --workers 2

출력: output/detect/DJI_20260306100900_0034.json — X-AnyLabeling 호환 annotation

Step 2 — 라멘 구조 분석

.venv\Scripts\python.exe tools/detect_raamen.py `
  --image "data/역사구간/1.회덕역/DJI_20260306100900_0034.JPG" `
  --label "output/detect/DJI_20260306100900_0034.json" `
  --output "output/raamen/DJI_20260306100900_0034_raamen.png"

출력: 이미지 위에 C/B 라벨 + 라멘 그룹 번호 오버레이

4단계 내부 처리 흐름

Everything 탐색 모드 (Discovery Sweep)

새 지역·새 구간을 처음 분석할 때 사용. SAM3.1 텍스트 grounding 방식이므로 완전 무프롬프트는 불가 — 대신 광범위한 Discovery Prompt로 이미지에 존재하는 모든 객체를 일괄 검출하고 라벨 빈도를 집계한다.

cd D:\MYCLAUDE_PROJECT\railway-client

# 기본 (8×6 타일)
.venv\Scripts\python.exe tools/sam3_everything_explore.py `
  --input "data/역사구간/1.회덕역/DJI_20260306100900_0034.JPG"

# 타일 수 조정 (고해상도 드론 이미지)
.venv\Scripts\python.exe tools/sam3_everything_explore.py `
  --input "data/역사구간/..." `
  --cols 8 --rows 6 --conf 0.10 --workers 4

# 특정 영역(ROI)만 탐색
.venv\Scripts\python.exe tools/sam3_everything_explore.py `
  --input "..." `
  --zone 1000 500 3000 2500

# Discovery Prompt에 추가 키워드 삽입
.venv\Scripts\python.exe tools/sam3_everything_explore.py `
  --input "..." `
  --prompt-extra "signal box, relay cabinet"

파라미터

railroad track, railway rail,
catenary pole, overhead line pole, electric pole,
overhead wire, catenary wire, power line cable,
railway sleeper, concrete tie,
guardrail, highway barrier, road fence,
bridge, viaduct, overpass,
vegetation, tree, bush, grass,
building, structure, roof, wall,
vehicle, car, truck,
road, asphalt, pavement,
slope, embankment, retaining wall,
noise barrier, sound wall,
signal, sign board,
small dark object on ballast, small square metal box on ground,
control box on ballast, gray square lid on gravel,
flat metal cover on ground, bright square object on gravel

output/everything/
└── DJI_20260306100900_0034_everything.jpg   ← 모든 segment 오버레이

콘솔 출력 (라벨 빈도 집계):
  catenary pole         : 47
  railway rail          : 31
  overhead wire         : 28
  concrete tie          : 19
  control box on ballast:  8
  ...

서버 설정 (sam31server)

시스템 아키텍처

┌─────────────────────────────────┐
│        sam31server              │
│  FastAPI  app/main.py :8000     │
│  GET  /health                   │
│  POST /v1/predict               │
│  Model: SAM 3.1 Multiplex (CUDA)│
└──────────────┬──────────────────┘
               │ HTTP localhost:8000
┌──────────────▼──────────────────┐
│       railway-client tools      │
│  detect_all_objects.py          │  ─┐
│  detect_raamen.py       ◀────────┘  │ 라멘 파이프라인
│  sam3_everything_explore.py     │
│  sam3_autolabel.py  ...         │
└─────────────────────────────────┘

요구사항

디렉토리 구조

sam31server/
├── sam3/                    ← SAM 3.1 모델 라이브러리
├── app/
│   ├── main.py              ← FastAPI 진입점
│   ├── api/predict.py       ← POST /v1/predict
│   ├── api/health.py        ← GET /health
│   ├── models/segment_anything_3.py
│   ├── core/registry.py
│   └── tasks/inference.py
├── configs/
│   ├── server.yaml          ← 포트·동시성
│   ├── models.yaml          ← enabled: segment_anything_3
│   └── auto_labeling/segment_anything_3.yaml
├── bpe_simple_vocab_16e6.txt.gz
└── start_server.bat

서버 시작

cd D:\MYCLAUDE_PROJECT\sam31server

# 배치파일
start_server.bat

# 또는 직접
.venv\Scripts\python.exe -m app.main

# 또는 uvicorn 직접 (Windows 이벤트루프 이슈 우회)
.venv\Scripts\python.exe -m uvicorn app.main:app --host 0.0.0.0 --port 8000

INFO | Loading [segment_anything_3] (Segment Anything 3.1)...
INFO | SAM3 model loaded successfully
INFO | Uvicorn running on http://0.0.0.0:8000

API 엔드포인트

POST /v1/predict

{
  "model": "segment_anything_3",
  "image": "<base64 JPEG>",
  "params": {
    "text_prompt": "catenary pole, overhead line pole",
    "conf_threshold": 0.25,
    "show_masks": true,
    "show_boxes": false
  }
}

응답:

{
  "data": {
    "shapes": [
      { "label": "catenary pole", "shape_type": "polygon",
        "points": [[x,y], ...], "score": 0.87 }
    ]
  }
}

클라이언트 도구 전체 목록

detect_all_objects.py

.venv\Scripts\python.exe tools/detect_all_objects.py `
  --input  "data/역사구간/..." `
  --categories configs/railway_zone.json `
  --tiles  all `
  --cols 4 --rows 3 --overlap 0.10 --workers 2

출력: output/detect/이미지명_detected.png + .json

sam3_autolabel.py

.venv\Scripts\python.exe tools/sam3_autolabel.py `
  --input data/역사구간/1.회덕역/ `
  --output output/labels/

sam3_batch_label.py

.venv\Scripts\python.exe tools/sam3_batch_label.py `
  --input data/역사구간/ `
  --prompt "railway catenary pole" `
  --output output/batch_labels/ `
  --workers 8

yoloworld_sam3_pipeline.py

.venv\Scripts\python.exe tools/yoloworld_sam3_pipeline.py `
  --input data/역사구간/ `
  --output output/labeled/

video_sam3_segment.py

.venv\Scripts\python.exe tools/video_sam3_segment.py

스크립트 상단에서 영상 경로·프롬프트·프레임 추출 간격 직접 수정.

렌더링 도구

# 라벨별 색상 렌더링
.venv\Scripts\python.exe tools/render_everything_by_label.py `
  --input output/labels/image.json --image data/.../image.JPG

# polygon 오버레이
.venv\Scripts\python.exe tools/render_label_polygons.py `
  --input output/labels/ --image data/.../

카테고리 설정 — railway_zone.json

경로: configs/railway_zone.json

프롬프트 파일

일부 도구는 prompts/ 폴더의 텍스트 파일을 사용:

prompts/
├── pole.txt      ← 전철주 검출용 프롬프트
├── rail.txt      ← 레일 검출용 프롬프트
├── bracket.txt   ← 브라켓 검출용
└── sleeper.txt   ← 침목 검출용

빠른 시작 — 단일 이미지 전체 파이프라인

cd D:\MYCLAUDE_PROJECT\sam31server
.venv\Scripts\python.exe -m app.main

cd D:\MYCLAUDE_PROJECT\railway-client
.venv\Scripts\python.exe tools/sam3_everything_explore.py `
  --input "data/역사구간/1.회덕역/.../DJI_20260306100900_0034.JPG" `
  --cols 4 --rows 3

.venv\Scripts\python.exe tools/detect_all_objects.py `
  --input "data/역사구간/1.회덕역/.../DJI_20260306100900_0034.JPG" `
  --categories configs/railway_zone.json `
  --tiles all --cols 4 --rows 3 --overlap 0.10 --workers 2

.venv\Scripts\python.exe tools/detect_raamen.py `
  --image "data/역사구간/1.회덕역/.../DJI_20260306100900_0034.JPG" `
  --label "output/detect/DJI_20260306100900_0034.json" `
  --output "output/raamen/DJI_20260306100900_0034_raamen.png"

트러블슈팅

Railway Client Guide · SAM 3.1 + FastAPI · 2026-06