Update README.md

README.md

@@ -14,36 +14,57 @@ pipeline_tag: object-detection
 
 # Edge Fire Detection AI (화재 감시 온점 시스템)
 
-라즈베리파이 5 등 임베디드 엣지 디바이스 환경에서 실시간으로 불꽃(Flame)과 연기(Smoke)를 감지하고 바운딩 박스를 추적하는 경량 객체 탐지(Object Detection) 모델입니다. `YOLOv8n(Nano)` 아키텍처를 기반으로 파인튜닝되었으며, 엣지 환경에서의 실시간성 확보를 위해 `ONNX` 포맷 고속 최적화 런타임을 지원합니다.
+라즈베리파이 5(Raspberry Pi 5) 임베디드 엣지 디바이스 환경에서 실시간으로 불꽃(Flame)과 연기(Smoke)를 감지하고 바운딩 박스를 추적하는 경량 객체 탐지(Object Detection) 모델입니다. `YOLOv8n(Nano)` 아키텍처를 기반으로 전이 학습(Transfer Learning)을 진행했으며, 하드웨어 연산 부하를 최소화하기 위해 `ONNX` 포맷 고속 런타임 최적화를 적용했습니다.
 
 ## 1. 학습 데이터 (Training Data)
-* **데이터 출처:** AI Hub 화재 감지 영상 데이터셋 및 자체 수집 화재 전처리 이미지
-* **클래스 구성:** 총 2개 클래스 정렬 (`flame`: 불꽃 / `smoke`: 연기)
-* **데이터 정제 및 증강 (Data Augmentation):** * 저조도 가혹 환경 및 카메라 노이즈 환경에서의 오작동(False Positive)을 방지하기 위해 밝기 변형, 흐림(Blur), 모자이크 증강 기법 적용
-  * 라즈베리파이 5 I/O 버스 전송량 과부하 방지를 위해 입력 해상도를 320x240 및 640x480 스케일러로 가공 정렬 (v2)
+* **데이터 출처:** AI Hub 화재 감지 영상 데이터셋 및 자체 수집 화재 이미지 셋
+* **클래스 정의:** 총 2개 클래스 (`flame`: 불꽃 / `smoke`: 연기)
+* **데이터 정제 및 증강 (Data Augmentation):**
+  * 야간 및 오지 등 저조도 상황에서의 오작동(False Positive)을 차단하기 위해 밝기 변형, 흐림(Blur), 모자이크(Mosaic) 증강 기법을 적용하여 모델의 강건성(Robustness) 확보
+  * 엣지 디바이스의 I/O 버스 대역폭 부하를 경감하기 위해 입력 해상도를 320x240 및 640x480 투 트랙 규격으로 스케일링 전처리 수행
 
-## 2. 모델 성능 (Evaluation)
+## 2. 모델 성능 (Evaluation Metrics)
 
-| 평가 지표 | 파이토치 (.pt) 규격 | ONNX 경량 가속 규격 | 비고 (라즈베리파이 5 CPU 기준) |
+| 평가 지표 | 파이토치 (.pt) 원본 | ONNX 경량 가속 규격 | 비고 (라즈베리파이 5 CPU 기준) |
 | :--- | :---: | :---: | :--- |
-| **mAP50 (전체 정확도)** | 84.5% | 83.9% | 포맷 변환에 따른 정확도 손실 최소화 |
+| **mAP50 (전체 정확도)** | 84.5% | 83.9% | 포맷 변환에 따른 정확도 손실 0.6% 미만 방어 |
 | **mAP50-95** | 0.521 | 0.518 | - |
-| **추론 속도 (Latency)** | 약 350ms | **약 45ms** | ONNX 가속 시 실시간성(20 FPS 이상) 달성 |
+| **추론 속도 (Latency)** | 약 350ms | **약 45ms** | ONNX 변환 후 실시간성(20 FPS 이상) 수렴 |
 
-## 3. 학습 설정 (Hyperparameters)
+## 3. 모델 학습 과정 (Model Training Process)
+* **학습 인프라:** 고성능 외장 GPU(RTX 5070 Ti, 32GB RAM) 환경 기반 로컬 가속 빌드 구동
+* **기반 아키텍처:** 3.2M 가벼운 파라미터 구조를 가진 `YOLOv8n`을 백본(Backbone)으로 채택하여 임베디드 CPU 가동 대역폭 사전 확보
+* **하이퍼파라미터 설정:**
 
 | 항목 | 설정값 | 비고 |
 | :--- | :---: | :--- |
-| **기반 아키텍처 (Model)** | YOLOv8n | 3.2M 경량 파라미터 구조 |
-| **입력 해상도 (imgsz)** | 320 / 640 | 가변 하향 레이어 매핑 |
 | **Epochs** | 50 | - |
-| **Batch Size** | 32 | - |
+| **Batch Size** | 32 | 하드웨어 VRAM 최적화 크기 |
 | **Optimizer** | AdamW | - |
-| **Augmentation** | Mosaic (1.0), Blur (0.2) | 임베디드 환경 오작동 차단용 |
+| **Learning Rate** | 1e-3 | 초기 학습률 지정 |
+| **Augmentation** | Mosaic (1.0), Blur (0.2) | 가혹 환경 오작동 차단용 |
 
-## 4. 사용 방법 (Inference Code)
+## 4. 개발 시행착오 및 트러블슈팅 (Trials & Errors)
 
-라즈베리파이 5 환경에서 `onnxruntime` 백엔드를 활용하여 하드웨어 병목 없이 고속 추론을 수행하는 주피터 노트북 최적화 마스터 스크립트입니다.
+임베디드 엣지 AI 시스템 구현 중 발생한 물리/소프트웨어 레이어의 병목 현상과 해결 리포트입니다.
+
+### ① PyTorch 원시 모델(.pt) 구동 시 레이턴시 저하
+* **문제 상황:** 학습 완료된 `best.pt` 가중치를 라즈베리파이 5 CPU 단독 환경에서 추론했을 때 프레임 지연이 약 350ms(3 FPS 미만)까지 늘어나 실시간 화재 탐지가 불가능한 병목 직면.
+* **해결 조치:** 정적 연산 그래프 구조를 가진 `ONNX` 포맷으로 모델을 익스포트(`format=onnx`, `imgsz=320`)하고, 파이썬 백엔드에 `onnxruntime` 가속 플러그인을 결합하여 추론 레이턴시를 45ms(22 FPS 이상) 수준으로 비약적으로 단축함.
+
+### ② Linux V4L2 장치 채널 타임아웃 (`select() timeout`)
+* **문제 상황:** 최신 라즈베리파이 OS(Bookworm) 커널에서 OpenCV로 웹캠을 호출할 때 미디어 컨트롤러 가속 스택이 `/dev/video0` 자원을 독점 점유(Lock)하여 `select() timeout`과 함께 하드웨어 좀비 락 현상 발생.
+* **해결 조치:** OpenCV 카메라 개시 코드단에 V4L2 백엔드를 명시적으로 지정(`cv2.VideoCapture(0, cv2.CAP_V4L2)`)하고, 주피터 서버 구동 시 리눅스 에뮬레이션 호환 레이어 환경 변수인 `LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libv4l/v4l1compat.so`를 프리로드 래핑하여 커널 점유 충돌을 우회함.
+
+### ③ USB 버스 대역폭 초과 및 픽셀 오염 (`error dequeuing buf`)
+* **문제 상황:** 압축 코덱 기능이 없는 일반 웹캠의 원시 데이터(Raw YUYV)를 640x480 해상도로 수신 시, 라즈베리파이 USB 대역폭 한계로 프레임 버퍼가 누수되어 화면이 지질거리거나 검은색(Black Screen)으로 죽는 현상 발생.
+* **해결 조치:** 웹캠을 전력 및 전송 효율이 높은 **파란색 USB 3.0 포트**로 물리적 이동 정렬을 수행한 후, 코드 레벨에서 입력 해상도를 `320x240`으로 대폭 낮추고 고속 압축 스트리밍 포맷(`MJPG`) 코덱 지정을 강제화하여 데이터 버스 통로를 복구함.
+
+### ④ 주피터 네트워크 웹 소켓 붕괴 크래시 (`ZMQError`)
+* **문제 상황:** 추론 `while` 루프가 초당 수십 장의 이미지를 지연 없이 주피터 인라인 위젯(`ipywidgets`) 화면으로 밀어 넣으면서 통신 버퍼 오버플로우로 인해 주피터 커널이 정지하고 소켓이 터지는 현상 발생.
+* **해결 조치:** 이미지 변환 및 전송 루틴 직후 미세 유휴 연산 타임인 `time.sleep(0.04)` 지연 버퍼 로직을 안착시켜 초당 전송률을 20~25프레임 수준으로 안정화함으로써 연속 구동 안전성을 확보함.
+
+## 5. 사용 방법 (Inference Code)
 
 ```python
 import cv2
@@ -54,24 +75,20 @@ 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번 채널)
+    # V4L2 가속 백엔드 매핑
     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) # 회로 동기화 안정화 지연
+    time.sleep(1) # 하드웨어 안정화 대기
     if not cap.isOpened():
         print("[오류] 카메라 장치를 활성화할 수 없습니다.")
         return
 
-    # 주피터 노트북 인라인 출력을 위한 이미지 위젯 선언
     image_widget = widgets.Image(format='jpeg', width=320, height=240)
     display(image_widget)
 
@@ -81,17 +98,17 @@ def main():
             if not success or frame is None:
                 continue
 
-            # 4. YOLOv8 ONNX 가속 추론 구동
+            # ONNX 가속 추론 구동 (imgsz 일치)
             results = model(frame, imgsz=320, stream=True)
             for r in results:
                 annotated_frame = r.plot()
 
-            # 5. JPEG 압축 인코딩 후 주피터 렌더링 파이프라인 전송
+            # JPEG 압축 후 주피터 렌더링 영역 업데이트
             ret, jpeg = cv2.imencode('.jpg', annotated_frame)
             if ret:
                 image_widget.value = jpeg.tobytes()
             
-            # 주피터 웹 소켓 과부하(ZMQ 에러) 차단용 미세 지연
+            # ZMQ 과부하 방지용 micro-delay
             time.sleep(0.04) 
             
     except KeyboardInterrupt:
@@ -105,34 +122,18 @@ if __name__ == '__main__':
     main()
 ```
 
+## 6. 입출력 형식 (Input / Output Format)
 
-## 5. 입출력 형식 (Input / Output Format)
-Plaintext
-
-입력(Input): 실시간 카메라 비디오 프레임 (320x240 또는 640x480 RGB 이미지)
+``` Plaintext
+입력(Input): 실시간 임베디드 카메라 비디오 프레임 (320x240 RGB Image)
 출력(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으로 유지하십시오.
+  - 불꽃 및 연기 영역 바운딩 박스(Bounding Box) 시각화 투사
+  - 탐지 클래스 레이블 매핑: [flame, smoke]
+  - 객체별 추론 신뢰도 수치 출력 (Confidence Score: 0.0 ~ 1.0)
+```
 
 ## 7. 로컬 동기화 가중치 다운로드 CLI
-Bash
 
-huggingface-cli download Onjeom/fire_detection_yolov8n --local-dir ./model
+``` Bash
+huggingface-cli download firedetection/fire_detection_yolov8n --local-dir ./model
+```