Object detection from scratch: Faster R-CNN + YOLO comparison

README.md

@@ -0,0 +1,125 @@
+---
+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를
+정식 라이선스 하에 사용하세요.