SEEN — Safety Event Evaluation Network

CCTV/작업현장 영상에서 안전 위반을 자동으로 찾아내고, 위험도 순으로 우선순위를 매기고, 사람이 바로 이해할 수 있는 문장으로 설명해주는 안전관리자용 의사결정 보조 서비스입니다.

문제 정의

현장에 카메라가 많아도 안전관리자는 보통 한두 명입니다. 한 화면을 보는 사이 다른 화면에서 헬멧 없이 크레인 밑을 지나가는 사람이 있어도 놓치고, 결국 사고가 난 뒤에야 CCTV를 되돌려보고 확인하는 일이 반복됩니다. 실시간 탐지 시스템이 있어도 크게 달라지지 않습니다. 크레인 구역에서 헬멧 미착용자가 뜨는 동시에 일반 통로에서 조끼 미착용자도 뜨면, 결국 사람이 둘 중 뭘 먼저 확인할지 판단해야 하기 때문입니다. SEEN은 이벤트를 감지하는 데서 그치지 않고, 위험도 순으로 정리해서 바로 읽을 수 있는 문장으로 요약해줍니다.

핵심 기능

• 실시간 탐지 — 웹캠/CCTV 스트림에서 사람·헬멧·조끼를 매 프레임 탐지하고 화면에 바로 표시
• 위험도 자동 스코어링 — 구역 가중치·지속시간·동시 위반자 수를 반영해 위반 우선순위를 계산
• 자연어 리포트 — 위반 상황을 설명하는 캡션과 조치 권고 문구를 VLM/LLM으로 자동 생성
• 구역 설정 — 캔버스에 클릭만으로 감시 구역을 그리고 구역별 위험 가중치 지정
• 위반 대시보드 — 감지된 위반을 최신순/위험도순으로 필터링·조회·삭제
• 설치 없는 웹 UI — 브라우저만 있으면 별도 클라이언트 없이 바로 사용

핵심 로직

감지되는 이벤트는 두 종류입니다.

• 장비 위반(no_helmet/no_vest) — 구역별 위험 가중치·지속시간·동시 위반자 수를 반영해 위험도를 계산합니다.
  • 위험도 = 기본 심각도 × 구역 가중치 × 지속시간 배수 × 동시 위반자 배수
• 구역 진입 감지(zone_entry) — 사람이 구역에 들어오는 즉시 낮은 위험도로 한 번 기록됩니다. 지속시간 조건은 없습니다.

YOLO 탐지는 매 프레임 실시간으로 돌고, VLM 캡션과 LLM 권고는 새 위반이 뜰 때만 호출합니다.

데이터셋

공개 PPE 데이터셋 3종을 조합해 학습했습니다. 이미지·라벨은 용량 문제로 레포에 포함하지 않습니다.

데이터셋	출처	라이선스	상업적 이용	비고
SFCHD (Safety Clothing & Helmet Detection)	github.com/lijfrank-open/SFCHD-SCALE	공개적으로 사용 가능 확인	공개적으로 사용 가능 확인	12,373장 / 50,558개 객체, 화학공장 작업자 PPE. helmet/no_helmet/vest/no_vest 주력 소스로 채택
Construction Site Safety (Roboflow Universe)	universe.roboflow.com/roboflow-universe-projects/construction-site-safety	CC BY 4.0	가능	717장(raw), 25개 클래스 중 Person/Hardhat/NO-Hardhat/Safety Vest/NO-Safety Vest가 프로젝트 클래스와 거의 1:1 매칭. 건설현장 도메인 다양성 확보용
SHWD (Safety Helmet Wearing Dataset)	github.com/njvisionpower/Safety-Helmet-Wearing-Dataset	MIT License	가능	7,581장 / 약 12만 개 객체, Helmet/Head 2클래스. no_helmet 표본 부족 시 보강용 (head → no_helmet 재해석)

3개 데이터셋의 원본 라벨(YOLO/COCO/VOC 포맷)을 프로젝트 5개 클래스(person/helmet/no_helmet/vest/no_vest)로 매핑해 Superb AI 플랫폼에 임포트했고, Zero 오토라벨링과 수동 라벨링을 정량 비교하는 실험도 진행했습니다. 라벨링 파이프라인과 실험 결과는 data/README.md에 정리되어 있습니다.

모델 성능

YOLOv8n을 파인튜닝한 결과입니다 (검증셋 2,260장). 전체 학습 로그는 training/runs/seen-ppe-v1.md에 있습니다.

클래스	Precision	Recall	mAP50	mAP50-95
전체	0.883	0.765	0.843	0.531
person	0.911	0.811	0.883	0.625
helmet	0.916	0.836	0.896	0.611
no_helmet	0.908	0.849	0.910	0.454
vest	0.864	0.855	0.887	0.578
no_vest	0.814	0.475	0.642	0.387

기술 스택

영역	스택	역할
데이터 · 라벨링		PPE 데이터셋 정제·라벨링, Zero로 1차 라벨 생성 후 검수
모델		사람/헬멧/조끼 실시간 탐지
트래킹		프레임 간 동일 인물 추적, 위반 지속시간 계산
구역 판정		사람 위치가 설정된 구역 폴리곤 안에 있는지 판정 (point-in-polygon)
백엔드		추론 API 서버, 구역·위반 이력 저장
실시간 통신		브라우저 ↔ 서버 프레임 스트리밍 (150ms 간격)
VLM/LLM		위반 상황 캡션 생성, 조치 권고 문구 생성
프론트엔드		구역 편집기, 실시간 탐지 화면, 위반 대시보드

빠른 시작

1. 레포 클론

git clone https://github.com/0euun/SEEN.git
cd SEEN

2. 가상환경 생성 (권장)

python -m venv venv

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

3. 의존성 설치

pip install -r requirements.txt

4. 환경 변수 설정

cp .env.example .env

.env 파일을 열어 아래 값을 채워주세요.

변수	설명
SUPERB_AI_API_KEY	Superb AI VLM/LLM 게이트웨이 API 키. 위반 캡션·조치 권고 문구를 생성하는 데 필요합니다.
SUPERB_AI_TENANT	Superb AI 테넌트 이름. 비워두면 seen이 기본값으로 쓰입니다.
SEEN_WEIGHTS_PATH	파인튜닝한 YOLOv8 가중치 경로. 비워두면 일반 COCO 사전학습 모델(yolov8n.pt)로 대체되며, 이 경우 PPE 클래스(헬멧/조끼)는 감지되지 않습니다.

5. 서버 실행

uvicorn app.main:app --reload

브라우저에서 http://localhost:8000에 접속하면 랜딩 페이지가 뜹니다.

6. 첫 화면 둘러보기

1. 구역 편집기에서 카메라 화면 위에 감시 구역을 그리고 위험 가중치를 지정합니다.
2. 실시간 탐지에서 웹캠을 켜고 탐지 박스와 위반 피드를 확인합니다.
3. 위반 대시보드에서 지금까지 감지된 위반을 최신순/위험도순으로 확인합니다.

화면별 자세한 사용법은 스크린샷과 함께 docs/manual/MANUAL.md에 정리되어 있습니다.

레포 구조

.github/
├─ ISSUE_TEMPLATE/task.md         이슈 템플릿
└─ PULL_REQUEST_TEMPLATE.md       PR 템플릿

app/                              FastAPI 백엔드
├─ main.py                        진입점 — .env 로드, 라우터/정적 파일 마운트
├─ db.py                          SQLite 연결, zones/violations 스키마 생성
├─ api/
│  ├─ detect.py                   WebSocket 탐지 엔드포인트 (YOLO → 트래커 → 구역 → 스코어링 → 리포트 트리거)
│  ├─ zones.py                    구역 CRUD (GET/PUT /api/zones/{camera_id})
│  ├─ violations.py               위반 이력 조회·삭제 (GET/DELETE /api/violations)
│  └─ report.py                   VLM 캡션 + LLM 권고 생성, DB 저장 (중복 병합 포함)
├─ core/
│  ├─ tracker.py                  경량 IoU 기반 트래커 (track_id 부여)
│  ├─ zone.py                     point-in-polygon 판정, bbox 유틸
│  ├─ risk_scoring.py             위험도 스코어링 공식 (순수 함수)
│  └─ vlm_client.py               Superb AI VLM/LLM 게이트웨이 호출 wrapper
└─ models/
   └─ yolo_infer.py                YOLOv8 추론 wrapper

training/                         YOLOv8 학습
├─ train_yolo.py                  파인튜닝 스크립트 (python training/train_yolo.py --epochs ...)
├─ colab_train_yolo.ipynb         Colab에서 학습 돌릴 때 쓰는 노트북
├─ configs/data.yaml              클래스 정의 (person/helmet/no_helmet/vest/no_vest) + 데이터 경로
└─ runs/seen-ppe-v1.md            학습 실험 로그 (에폭별 mAP/precision/recall, 클래스별 최종 지표)

frontend/                         정적 프론트엔드 (순수 HTML/JS)
├─ index.html                     랜딩 페이지
├─ zone_editor.html               구역 편집기 — 캔버스에 폴리곤 그리기
├─ live.html                      실시간 탐지 — 웹캠 스트림 + WebSocket
├─ dashboard.html                 위반 대시보드 — 필터/정렬/삭제
├─ manual.html                    인앱 사용 매뉴얼
└─ manual/                        manual.html용 스크린샷
   ├─ 1_zone_editor.png
   ├─ 2_live.png
   └─ 3_dashboard.png

data/                             데이터셋 관련 (원본 이미지·라벨은 용량 문제로 미포함)
├─ README.md                      라벨링 파이프라인, Zero 오토라벨링 비교 실험 기록
├─ zero_experiment_result.json    위 실험의 원본 결과 (정량 비교 스크립트 출력)
├─ zero_experiment_analysis.ipynb 위 결과를 시각화하는 노트북 (클래스별 precision/recall/F1, 소요시간 비교)
├─ zero_experiment_precision_recall.png / zero_experiment_time_comparison.png  노트북 실행 결과 이미지
├─ raw/                           원본 이미지 (gitignore, 직접 다운로드해서 채워야 함)
└─ superbai_export/               Superb AI 프로젝트에서 export한 YOLO 포맷 라벨 (gitignore)

docs/                             레포 문서 (GitHub에서 바로 보는 문서용)
├─ pipeline.svg                   위 파이프라인 다이어그램
└─ manual/
   ├─ MANUAL.md                   화면별 사용 설명서
   ├─ 1_zone_editor.png
   ├─ 2_live.png
   └─ 3_dashboard.png

scripts/                          Superb AI 연동 스크립트 (데이터 파이프라인 순서대로)
├─ upload_to_superbai.py          1. 로컬 이미지를 Superb AI 데이터셋에 업로드
├─ import_labels_to_superbai.py   2. 3개 소스 데이터셋의 원본 라벨을 5개 클래스로 매핑해 임포트
├─ tag_assets_by_source.py        3. 출처별 태그 부착 (검수 시 필터링용)
├─ zero_vs_manual_experiment.py   4. Zero 오토라벨링 vs 수동 라벨링 정량 비교 실험
├─ create_superbai_project.py     라벨링 프로젝트 생성
└─ export_from_superbai.py        학습 직전, 프로젝트를 버전 고정 후 YOLO 포맷으로 export

weights/                          학습된 YOLOv8 가중치 (best.pt)
snapshots/                        위반 스냅샷 저장 위치 (런타임에 생성, gitignore)
Dockerfile                        Railway 등 배포용 — opencv 런타임 라이브러리 포함
requirements.txt                  Python 의존성
.env.example                      환경 변수 템플릿 (SUPERB_AI_API_KEY 등)
.gitignore
LICENSE                           MIT

향후 개선

• 위반 스냅샷에 얼굴이 그대로 노출됨 — 얼굴 영역 블러링 필요 (헬멧 판정 부위와 겹쳐서 전체 블러는 부적합, 눈 주변만 가리는 방식 검토 필요)
• 구역 진입 감지를 "무단 침입"으로 단정하지 않음 — 카메라만으로는 진입자의 권한 여부를 확인할 수 없기 때문. 신뢰성 있게 판별하려면 배지/ID 태그 같은 출입 인증 시스템 연동 필요
• no_vest recall(0.475)이 다른 클래스(0.81~0.86) 대비 확연히 낮음 — 실제 조끼 미착용 상황의 절반 가까이를 놓칠 수 있다는 뜻. 후속 개선 시 no_vest 샘플 보강이 우선순위