Update README.md

README.md

@@ -1,3 +1,184 @@
----
-license: mit
----
+---
+language:
+  - en
+  - ko
+license: mit
+tags:
+  - vision
+  - object-detection
+  - yolov8
+  - ultralytics
+  - pytorch
+  - safety
+  - ppe
+  - hardhat
+  - mask
+  - construction
+library_name: ultralytics
+pipeline_tag: object-detection
+---
+
+# 🦺 YOLOv8 PPE Detection – End-to-End Safety Vision Model
+
+**Author:** Hansung Cho  
+**Model:** YOLOv8n fine-tuned for PPE (Personal Protective Equipment) detection on construction-like scenes.
+
+이 모델은 건설 현장 등의 이미지/영상에서 **안전모(Hardhat), 마스크, 안전조끼(Safety Vest), 사람(Person)** 등 PPE 착용 여부를 탐지하기 위해 학습된 YOLOv8 기반 객체 탐지 모델입니다.
+
+- Custom PPE dataset 기반 fine-tuning  
+- Web / FastAPI / Webcam까지 연동된 End-to-End 프로젝트의 핵심 모델  
+- Hugging Face Hub에서 바로 다운로드 및 사용 가능
+
+---
+
+## 🧠 Model Description
+
+- **Base model:** YOLOv8n (Ultralytics)  
+- **Task:** Object Detection (Bounding Box)  
+- **Domain:** Construction site & industrial safety PPE detection  
+- **Classes (예시):**
+  - `Person`
+  - `Hardhat`
+  - `No-Hardhat`
+  - `Safety Vest`
+  - `No-Safety Vest`
+  - `Mask`
+  - `No-Mask`
+  - + 기타 PPE 관련 클래스 (총 약 10개)
+
+본 모델은 사람 + PPE 착용 여부를 동시에 탐지하여  
+Web UI / Webcam / FastAPI 서버에서 실시간 경고 시스템 구축에 활용될 수 있습니다.
+
+---
+
+## 📊 Training & Evaluation
+
+### Validation 성능 (YOLOv8n Fine-tuning, Validation Set 기준)
+
+| Metric        | Score  |
+|---------------|--------|
+| **mAP@0.50**  | 0.744  |
+| **mAP@0.50:0.95** | 0.436 |
+| **Precision** | 0.831  |
+| **Recall**    | 0.685  |
+
+---
+
+## 📁 Training Data
+
+- Public PPE / construction-related datasets (Kaggle 등)  
+- RGB 이미지  
+- Bounding box + class label  
+- Hardhat / No-Hardhat / Mask / No-Mask / Safety Vest / No-Safety Vest / Person 등  
+
+> 데이터셋 자체는 포함하지 않으며,  
+> 라이선스는 데이터 제공처를 따릅니다.
+
+---
+
+## ⚙️ How to Use
+
+### Ultralytics YOLO + Hugging Face Hub
+
+```python
+from huggingface_hub import hf_hub_download
+from ultralytics import YOLO
+
+ckpt_path = hf_hub_download(
+    repo_id="Hansung-Cho/yolov8-ppe-detection",
+    filename="best.pt"
+)
+
+model = YOLO(ckpt_path)
+results = model("your_image.jpg")
+results[0].plot()
+```
+
+### Command Line (CLI)
+
+```bash
+yolo task=detect mode=predict \
+    model="https://huggingface.co/Hansung-Cho/yolov8-ppe-detection/resolve/main/best.pt" \
+    source="your_image_or_video.mp4" \
+    conf=0.25
+```
+
+---
+
+## 🎯 Intended Uses & Use Cases
+
+### Intended
+- 건설 현장 CCTV / Webcam 모니터링  
+- PPE 착용 여부 자동 점검  
+- 안전 교육 PoC / 데모  
+- FastAPI + Web UI 실시간 경고 시스템  
+
+### Not Intended
+- 법적 제재/징계의 유일한 근거  
+- 의료/생명 안전의 단독 판단 기준  
+- 완전히 다른 도메인(일상사진/스포츠 등)에서 사용  
+
+---
+
+## ⚠️ Limitations & Ethical Considerations
+
+- **도메인 편향:** 실내·야간·특수복장 환경에서 성능 저하 가능  
+- **Occlusion:** 가려진 경우 오탐/미탐 가능  
+- **Low Resolution:** 멀리 있는 인물 탐지 어려움  
+- **Ethical Use:**  
+  - 보조적 검사 도구로만 사용해야 함  
+  - 인권·개인정보 보호를 반드시 고려해야 함  
+
+---
+
+## 🧪 Evaluation & Reproducibility
+
+- **Framework:** Ultralytics YOLOv8 / PyTorch  
+- **Hardware:** Colab GPU / 단일 GPU  
+- **Notebook:** `training/YOLO_PPE.ipynb`  
+
+### Visualization Assets
+- Training curves (`results.png`)  
+- Confusion matrix (`confusion_matrix.png`)  
+- PR Curve (`BoxPR_curve.png`)  
+- F1 Curve (`BoxF1_curve.png`)  
+- Prediction example (`example.png`)  
+
+---
+
+## 🧩 Integration Example (FastAPI + Web)
+
+### Backend
+- FastAPI server (`backend/app.py`)  
+- `/predict` → 이미지 업로드 후 YOLO 추론  
+- bounding box가 포함된 결과를 base64로 반환  
+
+### Frontend
+- HTML / JavaScript (`index.html`, `webcam.html`)  
+- 이미지 업로드 / 실시간 Webcam 스트림  
+- NO-Hardhat, NO-Mask 등 위험 요소 감지  
+
+### Local
+- `local/webcam_ppe.py` → 로컬 웹캠 실시간 감지  
+
+> 전체 시스템 구현은 GitHub 레포지토리에서 확인할 수 있습니다.
+
+---
+
+## 📚 Citation
+
+```
+Cho, Hansung. "YOLOv8 PPE Detection – End-to-End AI System for Safety Monitoring."
+Hugging Face Model Hub, 2025.
+```
+
+---
+
+## 📬 Contact & References
+
+- **GitHub Project Repository:** https://github.com/Hansung-Cho/YOLO_PPE  
+- **GitHub Profile:** https://github.com/Hansung-Cho  
+- **Model Page:** https://huggingface.co/Hansung-Cho/yolov8-ppe-detection  
+- **Ultralytics YOLOv8 Source:** https://github.com/ultralytics/ultralytics  
+
+Feel free to open an issue or reach out for questions, collaboration, or improvements.