# RailPose3D — PLAN

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

## Goal

드론 영상(nadir + oblique) 으로부터 **전철주(catenary pole)** 와 **레일(rail)** 등 가늘고 긴 구조물을 검출하고, 기존 SfM 카메라 포즈를 활용해 **3D 좌표(EPSG:5186)** 로 추출한다.

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

1. **메시는 버린다.** SfM dense mesh 의 fragmented 출력에 의존하지 않는다. 카메라 포즈 + ground 분류 dense cloud 만 사용.
2. **2D 정확 검출 → 3D 삼각측량.** 가는 물체는 detection-then-triangulate 가 mesh 기반보다 정확.
3. **Pose/keypoint 모델 (bbox 아님).** 4-keypoint `{base, top, L_arm, R_arm}` 로 base/완금 구조적 구분.
4. **Segmentation + skeletonize (lane detector 아님).** 레일은 nadir/oblique view-invariant.
5. **Self-training over SfM.** 30장 라벨을 카메라 포즈로 5–20× 증식.

## 3-모듈 분해

- **Module A — Pole Keypoint Detection** (RTMPose-m, 4-keypoint)
- **Module B — Rail Segmentation** (SegFormer-B2, 3-stage transfer + skeletonize)
- **Module C — 2D→3D Triangulation** (DBSCAN association + pycolmap + pyceres / PDAL CSF + Open3D + scipy splprep)

## Sprint 분할 (마일스톤)

| Sprint | 모듈 | 목표 | 성공 조건 (contract) |
|---|---|---|---|
| **S0** Bootstrap | Infra | 디렉터리·환경·CI 골격 | `pipeline/run_full.py --version` 동작, lint/format pass |
| **S1** MVP-Zero | A+B | Grounding-DINO + SAM2 zero-label baseline | 30장 검증, pole base 픽셀 오차·rail mIoU 정량화 |
| **S2** Pole-A1 | A | RTMPose-m fine-tune (30장 → 300장 copy-paste aug) | PCK@5px ≥ MVP baseline + 20% |
| **S3** Rail-B1 | B | SegFormer 3-stage transfer | rail mIoU ≥ 0.70 on 30 holdout |
| **S4** Triangulate | C | DBSCAN + pycolmap + pyceres pole pipeline | 3D pole point reprojection error < 5 px median |
| **S5** Rail-3D | C | Open3D raycasting + B-spline rail pipeline | 3D rail Hausdorff vs GCP < 10 cm |
| **S6** Self-train | A,B | SfM-consistent self-training loop | 라운드 N+1 PCK > 라운드 N |
| **S7** E2E | All | 100m trial section end-to-end | GeoJSON + DXF export, QGIS 시각화 일치 |
| **S8** Korean catenary 분기 | A | 단주 vs 문형 가구 분류 + 4kpt 변형 | 두 타입에서 PCK@5px ≥ 0.85 |

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

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

- **Module A**: PCK@5px (base keypoint), 30장 holdout
- **Module B**: mIoU (rail mask), Hausdorff (polyline)
- **Module C**: reprojection error (pole), Hausdorff vs GCP (rail), GeoJSON CRS=EPSG:5186 통과

## 위험 관리

| 위험 | 대응 |
|---|---|
| 전철주 base 가림 | self-training 으로 다중뷰 일관성 검증 |
| Windows pycolmap/pyceres 빌드 | conda-forge wheel 우선, 실패 시 WSL2 fallback |
| 좌표계 mismatch | GCP 3점 이상으로 7-param Helmert |
| 한국 catenary 다양성 (단주/문형) | S8에서 분기 처리 |

## 참고 산출물

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