Skip to content

Latest commit

 

History

History
117 lines (100 loc) · 3.65 KB

README.md

File metadata and controls

117 lines (100 loc) · 3.65 KB

SafeView FastAPI Server

실시간 영상 비식별화(얼굴/번호판 모자이크)와 자동 녹화/업로드를 제공하는 FastAPI 기반 서버입니다. WebSocket으로 영상을 받아 모자이크 처리 후 스트리밍하고, 조건에 따라 처리본/원본을 동시에 녹화합니다. 결과는 S3에 업로드되며 완료 시 Spring 서버에 콜백을 보냅니다. 오프라인 영상에 대해 특정 시간 구간의 얼굴을 추출하는 API도 포함됩니다.

자세한 구조와 동작 흐름은 docs/ARCHITECTURE.md 참고.

주요 기능

  • WebSocket 실시간 입력 + 모자이크 스트리밍 (JPEG 전송, FPS 제한, 코얼레싱)
  • 옆모습 지속 모자이크: 머리 추적(IoU+TTL) + HOG 보조
  • 자동 녹화: 처리본/원본 이중 저장, presence 히트 & 부재 타임아웃 기반 시작/중단
  • S3 업로드 및 로컬 폴백, Spring 콜백으로 URL 전달
  • 시간 기반 얼굴 검출 API: 파일 업로드, blob/data URL, http(s), S3 지원

빠른 실행 요약

git clone https://github.com/SafeView/Python_AI.git
cd Python_AI
curl -LsSf https://astral.sh/uv/install.sh | sh  # 또는 brew install uv
uv sync
uv run uvicorn server.app:app --host 0.0.0.0 --port 8000
# 또는
uv run python http_video_server.py

server.app:app 직접 실행 혹은 http_video_server.py 로 진입.

기술 스택

  • Python 3.10 ~ < 3.13
  • FastAPI / Uvicorn
  • OpenCV, MediaPipe, YOLO(ultralytics)
  • aiohttp, boto3
  • uv 패키지/실행 관리

사전 준비

  1. Python 버전 확인 (python --version)
  2. uv 설치 (없다면 위 요약 참조)
  3. (선택) .venv/ 자동 생성 (uv sync 시)

설치 (uv 권장)

uv sync

패키지 추가: uv add 패키지명

(대안) pip

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

실행

uv run python http_video_server.py
# 또는
uv run uvicorn http_video_server:app --host 0.0.0.0 --port 8000

다중 워커 사용 시 전역 상태 공유 불가.

WebSocket 사용 흐름

  1. ws://{host}:{port}/ws/video 연결
  2. JPEG 프레임 전송
  3. 모자이크 처리 후 JPEG 수신
  4. 자동 녹화 이벤트 메시지 수신

자동 녹화 요약

조건 설명
시작 pcnt >= AUTO_RECORD_THRESHOLD AND presence 히트 충족
중단 연속 부재 시간 ≥ AUTO_ZERO_TIMEOUT_SEC
메타 최대 인원 _recording_max_persons 기록

주요 엔드포인트

메소드 경로 설명
GET /health 헬스 체크
WS /ws/video 실시간 스트림
POST /start_recording 수동 녹화 요청
POST /stop_recording 녹화 중단
GET /recording_status 녹화 상태
GET /recordings 녹화 목록
POST /face-detection/upload-video 오프라인 업로드
POST /face-detection/detect-faces 특정 시점 얼굴 추출

디렉토리 개요

server/
  app.py
  websocket_stream.py
  recording.py
  verification.py
  face_time_api.py
  core/state.py
  analytics/person_count.py
AI_processor.py
http_video_server.py
docs/ARCHITECTURE.md

개발 워크플로

uv add some-package
uv run python -c "import requests;print(requests.get('http://localhost:8000/health').json())"

문제 해결

증상 조치
자동 녹화 시작 안 됨 임계/히트 조정, DETECT_EVERY_N=1 테스트
VideoWriter 실패 코덱 지원 확인, MJPG 폴백 로그 확인
S3 업로드 실패 자격/권한 및 구성 점검
사람 수 0 지속 조명/해상도/모델 설정 조정

라이선스

(내부 정책에 따라 지정 예정)

이슈나 개선 요청 환영.