시스템 개발 매뉴얼 4

FastAPI 기반의 백엔드와 WebSocket을 통한 실시간 통신

핵심 기술 스택

• FastAPI: 비동기 웹 프레임워크
• MediaPipe: 실시간 손 인식
• TensorFlow: 딥러닝 모델 실행
• OpenCV: 이미지 처리
• WebSocket: 실시간 데이터 통신

시스템 아키텍처

1. 백엔드 구조

/
├── models/
│   ├── hand_sign_model.h5
│   └── label_map.json
├── templates/
│   └── index.html
└── main.py

2. 데이터 흐름

1. 웹캠 캡처
2. 프레임 전처리
3. 손 감지 및 랜드마크 추출
4. 모델 예측
5. 결과 시각화 및 전송

주요 컴포넌트 설명

1. 실시간 비디오 처리 시스템

async def generate_frames(websocket: WebSocket = None):
    cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)

• 웹캠 스트림 캡처
• 프레임별 손 감지
• 실시간 예측 수행

• 결과 시각화

• 비동기 처리로 성능 향상
• 프레임 간 지연 추가로 리소스 관리
• 예외 상황 처리

2. WebSocket 통신 시스템

class ConnectionManager:
    def __init__(self):
        self.active_connections = []

• 연결 상태 관리
• 실시간 데이터 브로드캐스트
• 안전한 연결 해제

3. 이미지 처리 파이프라인

def process_landmarks(hand_landmarks):
    landmarks = np.array([[lm.x, lm.y, lm.z] for lm in hand_landmarks.landmark])
    return np.expand_dims(landmarks, axis=0)

1. RGB 변환
2. 랜드마크 추출
3. 좌표 정규화
4. 모델 입력 형태 변환

4. 시각화 시스템

def put_text(img, text, position, font_size=30, font_color=(0, 255, 0)):
    img_pil = Image.fromarray(img)
    draw = ImageDraw.Draw(img_pil)

기능

• 한글 텍스트 렌더링
• 랜드마크 시각화
• 예측 결과 표시

성능 최적화

1. 처리 속도 개선

• 단일 손 감지로 제한
• 비동기 프레임 처리
• 효율적인 메모리 관리

2. 정확도 향상

• 신뢰도 임계값 설정
• 연속 프레임 추적
• 노이즈 필터링

구현 가이드

1. 환경 설정

pip install fastapi uvicorn opencv-python mediapipe tensorflow pillow

2. 실행 방법

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="127.0.0.1", port=8080)

3. 주요 API 엔드포인트

엔드포인트	메소드	설명
/	GET	메인 페이지
/ws	WebSocket	실시간 통신
/video_feed	GET	비디오 스트림

확장 가능성

1. 다중 손 인식
   • max_num_hands 파라미터 조정
   • 처리 로직 확장
2. 성능 모니터링
   • 프레임 처리 시간 측정
   • 메모리 사용량 추적
3. UI 개선
   • 실시간 피드백 시각화
   • 사용자 설정 옵션 추가

주의사항

1. 리소스 관리
   • 카메라 리소스 적절한 해제
   • WebSocket 연결 관리
2. 예외 처리
   • 카메라 연결 실패
   • 모델 로드 오류
   • WebSocket 통신 오류
3. 보안 고려사항
   • WebSocket 연결 검증
   • 사용자 입력 검증
   • 리소스 접근 제한

라즈베리파이 전용 카메라 지원 추가

1. 카메라 시스템 변경

기존 코드

cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)

새 코드

cap = Picamera2()
height = 480
width = 640
middle = (int(width / 2), int(height / 2))
cap.configure(
    cap.create_video_configuration(
        main={
            "format": "RGB888",
            "size": (width, height),
        },
    )
)

• OpenCV 웹캠에서 Raspberry Pi 전용 카메라 시스템으로 전환
• 하드웨어 최적화된 성능 제공
• 더 세밀한 카메라 설정 가능

2. 프레임 처리 방식

항목	기존 코드	새 코드
프레임 획득	cap.read()	cap.capture_array()
프레임 레이트	기본값	120fps로 설정

3. 폰트 시스템 변경

기존 코드

font = ImageFont.truetype("C:/Windows/Fonts/malgun.ttf", font_size)

새 코드

font = ImageFont.truetype("/usr/share/fonts/truetype/nanum/NanumGothic.ttf", font_size)

변경점

• Windows 환경에서 Linux 환경으로 전환
• 나눔고딕 폰트 사용으로 변경

시스템 최적화

1. 성능 개선

• 프레임 레이트 120fps로 고정
• 하드웨어 가속 활용
• 메모리 사용 최적화