YMmim/faster-rcnn-voc-scratch

Faster R-CNN from Scratch (Pascal VOC) — 교육용 구현

torchvision의 완성된 탐지기(fasterrcnn_resnet50_fpn)를 쓰지 않고, Faster R-CNN의 핵심 구성요소를 밑바닥부터 직접 구현하여 원리를 학습하기 위한 저장소입니다. 학습 + 평가(mAP) + 추론 전체 파이프라인을 포함합니다.

⚠️ 성능 경고: 이 저장소의 가중치(frcnn.pth)는 1 에폭만 학습한 데모용입니다. 실사용 목적의 고성능 모델이 아니라, "구현이 올바른가"를 검증하고 학습 원리를 이해하기 위한 교육용 자료입니다. 제대로 된 성능이 필요하면 12 에폭 이상 학습하거나 torchvision 공식 구현을 사용하세요.

무엇을 직접 구현했나

구성요소	파일	내용
데이터 로더	dataset.py	VOC XML 파싱, 리사이즈(박스 동기화), 정규화
박스 연산	box_utils.py	앵커 생성, IoU, 인코딩/디코딩, NMS
모델	model.py	ResNet50 백본 + RPN + RoI Align + RoI Head
손실	losses.py	IoU 기반 타깃 할당 + RPN/RoI 손실
학습·평가	train.py	학습 루프 + VOC mAP@0.5
추론	infer.py	이미지에 박스·라벨·점수 시각화

아키텍처

이미지
  │ ResNet50 (conv1~layer3, stride 16)
  ▼
특징맵
  ├─▶ RPN ── 앵커별 (객체여부 + 박스보정) ── 후보영역(proposal)
  │
  ▼ RoI Align (7x7)
RoI Head ── (클래스 분류 + 클래스별 박스보정) ── 최종 탐지

사용법

1. 준비

pip install torch torchvision pillow

Pascal VOC 2007 다운로드 (torchvision 자동):

import torchvision
torchvision.datasets.VOCDetection(root="./data", year="2007",
                                  image_set="trainval", download=True)

2. 학습

python train.py --voc_root ./data/VOCdevkit/VOC2007 --epochs 12

3. 추론

python infer.py --ckpt frcnn.pth \
  --image ./data/VOCdevkit/VOC2007/JPEGImages/000007.jpg \
  --score_thresh 0.5

결과는 results/ 폴더에 박스가 그려진 이미지로 저장됩니다.

학습 원리 (코드와 대응)

1. 앵커 (box_utils.generate_anchors): 격자마다 9개 기준 박스
2. RPN 타깃 할당 (losses.rpn_loss): IoU≥0.7 객체 / <0.3 배경
3. 후보영역 생성 (model._proposals): RPN 출력 → NMS
4. RoI 타깃 할당 (losses.assign_roi_targets): IoU≥0.5 positive
5. RoI Align (model.RoIHead): 후보영역 → 7×7 고정 특징
6. 손실: 분류(CE/BCE) + 회귀(smooth L1), positive에만 회귀

단순화한 부분 (원논문 대비)

원리 이해에 집중하기 위해 아래를 단순화했습니다. 실전 성능을 높이려면 확장이 필요합니다.

• batch_size=1 고정 (이미지 크기가 제각각)
• RPN objectness를 1-logit(BCE)으로 처리
• RoI Head를 layer4 대신 FC로 구성
• FPN(다중 스케일) 미적용 → 작은 객체에 약함
• 데이터 증강 최소화

학습 곡선 (1 에폭 예시)

밑바닥 구현이 올바른지는 loss가 매끄럽게 감소하는지로 검증합니다.

iter  100 → loss 2.71
iter  800 → loss 1.30
iter 2100 → loss 1.10
iter 4400 → loss 0.98   (계속 감소)

RPN 손실이 0.69 → 0.10 수준으로 떨어지며 "객체 위치 찾기"를 학습하고, RoI 손실은 이미지 난이도에 따라 출렁이지만 누적 평균이 감소합니다.

라이선스

MIT License. 자유롭게 학습·수정·재배포 가능합니다. Pascal VOC 데이터셋은 별도 라이선스를 따르니 공식 사이트를 확인하세요.

면책

이 구현은 교육 목적입니다. 벤치마크 성능이나 프로덕션 배포가 필요하면 torchvision 공식 Faster R-CNN(fasterrcnn_resnet50_fpn)을 권장합니다.