Create README.md

README.md

@@ -0,0 +1,138 @@
+---
+license: agpl-3.0
+base_model: ultralytics/yolov8n
+tags:
+- yolov8
+- object-detection
+- onnx
+- onnxruntime
+- raspberry-pi5
+- edge-ai
+- fire-detection
+pipeline_tag: object-detection
+---
+
+# Edge Fire Detection AI (화재 감시 온점 시스템)
+
+라즈베리파이 5 등 임베디드 엣지 디바이스 환경에서 실시간으로 불꽃(Flame)과 연기(Smoke)를 감지하고 바운딩 박스를 추적하는 경량 객체 탐지(Object Detection) 모델입니다. `YOLOv8n(Nano)` 아키텍처를 기반으로 파인튜닝되었으며, 엣지 환경에서의 실시간성 확보를 위해 `ONNX` 포맷 고속 최적화 런타임을 지원합니다.
+
+## 1. 학습 데이터 (Training Data)
+* **데이터 출처:** AI Hub 화재 감지 영상 데이터셋 및 자체 수집 화재 전처리 이미지
+* **클래스 구성:** 총 2개 클래스 정렬 (`flame`: 불꽃 / `smoke`: 연기)
+* **데이터 정제 및 증강 (Data Augmentation):** * 저조도 가혹 환경 및 카메라 노이즈 환경에서의 오작동(False Positive)을 방지하기 위해 밝기 변형, 흐림(Blur), 모자이크 증강 기법 적용
+  * 라즈베리파이 5 I/O 버스 전송량 과부하 방지를 위해 입력 해상도를 320x240 및 640x480 스케일러로 가공 정렬 (v2)
+
+## 2. 모델 성능 (Evaluation)
+
+| 평가 지표 | 파이토치 (.pt) 규격 | ONNX 경량 가속 규격 | 비고 (라즈베리파이 5 CPU 기준) |
+| :--- | :---: | :---: | :--- |
+| **mAP50 (전체 정확도)** | 84.5% | 83.9% | 포맷 변환에 따른 정확도 손실 최소화 |
+| **mAP50-95** | 0.521 | 0.518 | - |
+| **추론 속도 (Latency)** | 약 350ms | **약 45ms** | ONNX 가속 시 실시간성(20 FPS 이상) 달성 |
+
+## 3. 학습 설정 (Hyperparameters)
+
+| 항목 | 설정값 | 비고 |
+| :--- | :---: | :--- |
+| **기반 아키텍처 (Model)** | YOLOv8n | 3.2M 경량 파라미터 구조 |
+| **입력 해상도 (imgsz)** | 320 / 640 | 가변 하향 레이어 매핑 |
+| **Epochs** | 50 | - |
+| **Batch Size** | 32 | - |
+| **Optimizer** | AdamW | - |
+| **Augmentation** | Mosaic (1.0), Blur (0.2) | 임베디드 환경 오작동 차단용 |
+
+## 4. 사용 방법 (Inference Code)
+
+라즈베리파이 5 환경에서 `onnxruntime` 백엔드를 활용하여 하드웨어 병목 없이 고속 추론을 수행하는 주피터 노트북 최적화 마스터 스크립트입니다.
+
+```python
+import cv2
+import numpy as np
+from ultralytics import YOLO
+from IPython.display import display
+import ipywidgets as widgets
+import time
+
+def main():
+    # 1. 고속 가속 ONNX 모델 로드 (task='detect' 명시 필수)
+    model_path = "best.onnx"
+    model = YOLO(model_path, task='detect')
+
+    # 2. V4L2 리눅스 표준 비디오 입력 소켓 연결 (물리 0번 채널)
+    cap = cv2.VideoCapture(0, cv2.CAP_V4L2)
+    
+    # 3. 하드웨어 대역폭 과부하 방지를 위한 해상도 및 버퍼 제어
+    cap.set(cv2.CAP_PROP_FRAME_WIDTH, 320)
+    cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 240)
+    cap.set(cv2.CAP_PROP_BUFFERSIZE, 1)
+
+    time.sleep(1) # 회로 동기화 안정화 지연
+    if not cap.isOpened():
+        print("[오류] 카메라 장치를 활성화할 수 없습니다.")
+        return
+
+    # 주피터 노트북 인라인 출력을 위한 이미지 위젯 선언
+    image_widget = widgets.Image(format='jpeg', width=320, height=240)
+    display(image_widget)
+
+    try:
+        while cap.isOpened():
+            success, frame = cap.read()
+            if not success or frame is None:
+                continue
+
+            # 4. YOLOv8 ONNX 가속 추론 구동
+            results = model(frame, imgsz=320, stream=True)
+            for r in results:
+                annotated_frame = r.plot()
+
+            # 5. JPEG 압축 인코딩 후 주피터 렌더링 파이프라인 전송
+            ret, jpeg = cv2.imencode('.jpg', annotated_frame)
+            if ret:
+                image_widget.value = jpeg.tobytes()
+            
+            # 주피터 웹 소켓 과부하(ZMQ 에러) 차단용 미세 지연
+            time.sleep(0.04) 
+            
+    except KeyboardInterrupt:
+        print("\n사용자에 의해 시스템 가동이 중단되었습니다.")
+    finally:
+        cap.release()
+        cv2.destroyAllWindows()
+        print("하드웨어 자원 회수 완료.")
+
+if __name__ == '__main__':
+    main()
+```
+
+
+## 5. 입출력 형식 (Input / Output Format)
+Plaintext
+
+입력(Input): 실시간 카메라 비디오 프레임 (320x240 또는 640x480 RGB 이미지)
+출력(Output): 
+  - 예측 객체 바운딩 박스 투사 (Bounding Box 좌표 정보)
+  - 클래스 레이블 매핑: [flame, smoke]
+  - 신뢰도 수치 출력 (Confidence Score: 0.0 ~ 1.0)
+
+## 6. 라즈베리파이 임베디드 배포 가이드
+환경 구축 및 서버 가동
+Bash
+
+# 가상환경 진입 상태 확인 후 필요 라이브러리 적재
+conda activate myenv
+pip install notebook ultralytics ipywidgets opencv-python onnxruntime
+
+# 라즈베리파이 5 최신 OS의 미��어 자원 독점 잠금(Lock) 우회 옵션을 탑재하여 주피터 실행
+LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libv4l/v4l1compat.so jupyter notebook --ip=0.0.0.0 --no-browser --port=8888
+
+웹캠 하드웨어 실시간 트러블슈팅 세션
+
+    select() timeout 경고 발생 시: 라즈베리파이 5의 전력 공급 문제이거나 커널 락 상태입니다. 터미널에서 sudo reboot를 수행하여 장치 락을 강제 초기화한 뒤 재가동하십시오.
+
+    화면 깨짐 및 error dequeuing buf 발생 시: USB 버스 전송 대역폭 한계치 초과 현상입니다. 카메라 연결 선을 검은색 포트에서 전송 전력이 높은 파란색 USB 3.0 포트로 물리적으로 이동 정렬하고 코드 내 해상도를 320x240으로 유지하십시오.
+
+## 7. 로컬 동기화 가중치 다운로드 CLI
+Bash
+
+huggingface-cli download Onjeom/fire_detection_yolov8n --local-dir ./model