# 실사 인물 모자이크 파이프라인

## 개요

이미지 및 영상에서 실사 인물을 탐지하여 신체 윤곽 기준으로 전신 모자이크를 적용하는 파이프라인.

## 처리 대상

| 입력 타입 | 설명 |
|-----------|------|
| 실사 사진 | 인물이 포함된 정지 이미지 |
| 실사 영상 | 인물이 포함된 동영상 |
| 애니메이션/일러스트 | 추후 확장 고려 (현재 범위外) |

## 모델 선정: YOLO11

### 선정 이유

- **Ultralytics YOLO11** (2024년 9월 출시)
- COCO 데이터셋에 person 클래스(class ID 0)가 포함되어 있어 별도 학습 불필요
- YOLOv8 대비 정확도 +2.1%, 속도 +22%, 파라미터 -16% 향상
- 동일 패키지(`ultralytics`) 내에서 트래킹(BoT-SORT/ByteTrack) 기본 지원
- ONNX / TensorRT / CoreML export 가능

### 모델별 성능 (RTX 3090, 640px 입력)

| 모델 | mAP50-95 | FPS | 용도 |
|------|:--------:|:---:|------|
| yolo11n | 39.5 | ~1100 | 초경량, 실시간 |
| **yolo11s** | **47.0** | **~730** | **추천 (밸런스 최적)** |
| yolo11m | 51.5 | ~370 | 정밀도 우선 |
| yolo11x | 54.7 | ~150 | 최고 정밀도 |

### M1 Max (맥북 로컬) 성능

| 모델 | FPS (GPU/MPS) |
|------|:-------------:|
| yolo11n | ~47 |
| yolo11s | ~43 |
| yolo11m | ~29 |
| yolo11x | ~18 |

MPS(Metal Performance Shaders) 백엔드는 FP16 미지원, CUDA 대비 최적화 덜 됨.
1080p 기준 풀파이프라인 약 30 FPS로 실시간 처리 가능.

## 파이프라인 구조

```
입력 (영상/이미지)
  │
  ├─ 프레임 추출 (OpenCV VideoCapture)
  │
  ├─ 사람 탐지 (YOLO11, class=[0])
  │   └─ model.track(frame, persist=True, classes=[0], conf=0.5)
  │   └─ 반환: 바운딩 박스 (xyxy) + 트래킹 ID
  │
  ├─ 모자이크 적용 (OpenCV)
  │   └─ ROI 추출 → downscale (1/10) → upscale (INTER_NEAREST)
  │   └─ 필요시 GaussianBlur 대체 가능
  │
  └─ 출력 (처리된 영상/이미지)
```

### 핵심 코드

```python
from ultralytics import YOLO
import cv2

model = YOLO('yolo11s.pt')
cap = cv2.VideoCapture('input.mp4')

while cap.isOpened():
    ret, frame = cap.read()
    if not ret:
        break
    
    # 사람 탐지 + 트래킹
    results = model.track(frame, persist=True, classes=[0], conf=0.5)
    
    # 모자이크 적용
    if results[0].boxes.id is not None:
        for box in results[0].boxes.xyxy:
            x1, y1, x2, y2 = map(int, box)
            roi = frame[y1:y2, x1:x2]
            h, w = roi.shape[:2]
            small = cv2.resize(roi, (w // 10, h // 10))
            mosaic = cv2.resize(small, (w, h), interpolation=cv2.INTER_NEAREST)
            frame[y1:y2, x1:x2] = mosaic
    
    out.write(frame)
```

## 기술 스택

| 항목 | 선택 |
|------|------|
| 탐지 모델 | YOLO11 (yolo11s.pt) |
| 라이브러리 | ultralytics, opencv-python |
| 트래커 | BoT-SORT (기본) 또는 ByteTrack |
| 추론 백엔드 | PyTorch (dev1), MPS (M1 Max) |
| 최적화 | TensorRT FP16 (dev1 선택사항) |
| 설치 | `pip install ultralytics opencv-python` |

## 처리 속도 예상

### dev1 (RTX 3090)
| 영상 길이 | 처리 시간 | 비고 |
|:---------:|:---------:|:----:|
| 10초 | < 1초 | |
| 1분 | ~0.3초 | |
| 10분 | ~3초 | |
| 1시간 | ~18초 | |

### 로컬 (M1 Max)
| 영상 길이 | 처리 시간 | 비고 |
|:---------:|:---------:|:----:|
| 10초 | ~1초 | |
| 1분 | ~2초 | |
| 10분 | ~20초 | |
| 1시간 | ~2분 | |

## 참고 자료

- Ultralytics YOLO11 공식 문서: https://docs.ultralytics.com/models/yolo11/
- Multi-Object Tracking: https://docs.ultralytics.com/modes/track/
- Person Tracking 튜토리얼: https://aaron.de/en/posts/personentracking-mit-ultralytics-yolo11/
- YOLO11 vs YOLOv8 비교 리뷰: https://www.labellerr.com/blog/yolo11-vs-yolov8-model-comparison/