README.md

---
license: mit
tags:
  - object-detection
  - faster-rcnn
  - yolo
  - pascal-voc
  - pytorch
  - educational
  - from-scratch
library_name: pytorch
pipeline_tag: object-detection
datasets:
  - pascal-voc-2007
language:
  - en
---

# Object Detection from Scratch — Faster R-CNN vs YOLO

객체탐지를 **밑바닥부터 직접 구현**(Faster R-CNN)하고, 이를 실무 표준인
**YOLO와 비교**하며 학습하는 교육용 저장소입니다.
2-stage 탐지기의 내부 원리를 손으로 구현해보고, 1-stage 탐지기(YOLO)와
결과·철학을 대조합니다.

> ⚠️ **성능 경고**: 이 저장소의 Faster R-CNN 가중치(`frcnn.pth`)는
> **1 에폭만 학습한 데모용**입니다. 실사용 목적이 아니라 "구현이 올바른가"를
> 검증하고 원리를 이해하기 위한 **교육 자료**입니다.

## 두 가지 접근의 대조

| | Faster R-CNN (직접 구현) | YOLOv8 (Ultralytics) |
|---|---|---|
| 방식 | 2-stage (후보영역 → 분류) | 1-stage (한 번에 예측) |
| 속도 | 느림 | 매우 빠름 (실시간) |
| 구현 | 밑바닥부터 (교육적) | 라이브러리 호출 |
| 학습 데이터 | Pascal VOC (20 클래스) | COCO (80 클래스) |
| 이 저장소의 역할 | **원리 학습** | **실무 표준과 비교** |

## 파일 구성

**Faster R-CNN 직접 구현**
| 파일 | 내용 |
|------|------|
| `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` | 추론 + 박스 시각화 |

**YOLO 비교**
| 파일 | 내용 |
|------|------|
| `yolo_infer.py` | YOLOv8(COCO 사전학습) 추론 — 같은 이미지 비교용 |

## 사용법

### Faster R-CNN (직접 구현)

```bash
pip install torch torchvision pillow

# VOC 2007 다운로드 (torchvision 자동)
python -c "import torchvision; torchvision.datasets.VOCDetection(root='./data', year='2007', image_set='trainval', download=True)"

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

# 추론
python infer.py --ckpt frcnn.pth --image ./sample.jpg --score_thresh 0.5
```

### YOLOv8 (비교)

```bash
pip install ultralytics

# 같은 이미지로 추론 (결과를 Faster R-CNN과 비교)
python yolo_infer.py --image ./sample.jpg
```

## 아키텍처 (Faster R-CNN)

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

## 학습 원리 (코드와 대응)

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 미적용 → 작은 객체에 약함

## 라이선스

- **이 저장소의 코드**: MIT License
- **YOLOv8** (`yolo_infer.py`가 사용): Ultralytics YOLO는 **AGPL-3.0**.
  `yolo_infer.py`는 Ultralytics를 *호출*만 하며, YOLO 가중치는 포함하지
  않습니다(사용자가 실행 시 자동 다운로드). 상업적 폐쇄소스 사용 시
  Ultralytics 상용 라이선스가 별도로 필요합니다.
- Pascal VOC 데이터셋은 공식 라이선스를 따릅니다.

## 면책

교육 목적 구현입니다. 프로덕션 배포가 필요하면 torchvision 공식
Faster R-CNN(`fasterrcnn_resnet50_fpn_v2`) 또는 Ultralytics YOLO를
정식 라이선스 하에 사용하세요.