# PoleDetect2D — PLAN

> 이 문서는 **불변 기준선(baseline)** 이다. 일상 진행 상태는 [PROGRESS.md](PROGRESS.md) 에 기록한다.
> 자세한 배경·근거는 [docs/plan.md](docs/plan.md), [docs/research.md](docs/research.md) 참조.

## Goal

드론 영상(nadir + oblique) 으로부터 **라멘구조 전철주(portal-frame catenary pole)** 를 **2D 이미지상에서 정확히 검출**한다.
출력은 keypoint 좌표 (픽셀) + 신뢰도이며, 3D 좌표 추출은 이 프로젝트 범위 밖이다.

## 핵심 설계 결정 (불변)

1. **Pose/keypoint 모델 (bbox 아님).** 라멘구조 4-keypoint `{foot_L, foot_R, head_L, head_R}` 로 기둥 발목/머리를 구조적으로 구분한다.
2. **라멘구조 전용 스키마.** 두 수직 기둥과 연결 보(beam)를 가진 H-frame / 문형 가구 구조.
3. **Self-training over SfM.** 30장 라벨을 SfM 카메라 포즈 reprojection 으로 5–20× 증식하여 2D pseudo-label 생성.
4. **Zero-shot bootstrap 우선.** Grounding-DINO + SAM2 로 라벨 없이 시작.

## 단일 모듈 구성

- **Module A — Pole Keypoint Detection**
  - 대상: 라멘구조 전철주 (portal-frame, 문형 가구)
  - 모델: RTMPose-m (primary) / ViTPose-Base (fallback)
  - Keypoint: `{foot_L, foot_R, head_L, head_R}` — COCO-keypoints 포맷

## Sprint 분할 (마일스톤)

| Sprint | 목표 | 성공 조건 (contract) |
|---|---|---|
| **S0** Bootstrap | 디렉터리·환경·CI 골격 | `pipeline/run_detect.py --version` 동작, lint/format pass |
| **S1** MVP-Zero | Grounding-DINO+SAM2 zero-label baseline | 30장 pole keypoint 픽셀 오차 baseline 정량화 |
| **S2** Pole-Train | RTMPose-m fine-tune (30장→300장 copy-paste aug) | PCK@5px ≥ S1 baseline + 20% |
| **S3** Self-train | SfM-consistent self-training loop (2D pseudo-label) | 라운드 N+1 PCK > 라운드 N, 3라운드 연속 |
| **S4** Korean-variants | 라멘구조 vs 단주 분류 분기, 다형 keypoint | 두 타입 PCK@5px ≥ 0.85 |

각 sprint 는 시작 시 `/contract <sprint-id>` 로 contract 파일을 생성하고, 완료 시 `/eval A` 로 검증한다.

## 검증 기준 (정량 지표)

- **Module A**: PCK@5px (4 keypoint 전체, 특히 foot_L / foot_R), 30장 holdout
- 기준 파일: `data/eval/pole_pck.json`

## 위험 관리

| 위험 | 대응 |
|---|---|
| 기둥 하단(foot)이 ballast·식생에 가려짐 | SfM pseudo-label 로 다른 뷰의 가시 foot 활용 |
| 라멘구조 외 단주 혼입 | S4 에서 pole_type 분기 처리 |
| 한국 catenary 다양성 (간격·폭 다양) | copy-paste aug 시 scale 범위 확장 |
| Windows MMPose 빌드 | conda-forge wheel, ONNX export fallback |

## 참고 산출물

- [docs/plan.md](docs/plan.md) — 사용자 승인 plan (한국어, 자세한 근거)
- [docs/research.md](docs/research.md) — 초기 기술 조사
- 메모리: `~/.claude/projects/d--MYCLAUDE-PROJECT-detectelectronpole/memory/`