Markdown

ungyoface 🎭

A superfast, lightweight, and asynchronous emotion recognition pipeline optimized for Real-Time PC environments. It provides seamless emotion tracking utilizing OpenCV for face localization and DeepFace for deep-learning emotion classification without dropping your main thread's FPS.

✨ Features

• Asynchronous Processing: The heavy deep-learning emotion engine runs entirely on a separate background thread, ensuring the main camera loop stays buttery smooth.
• Interval-based Analysis: Includes a built-in scheduler (ANALYSIS_INTERVAL = 1.0s) to drastically reduce unnecessary CPU/GPU overhead.
• Top 3 Emotion Metrics: Visualizes not just the primary emotion, but also renders a live probability bar chart for the top 3 detected emotions.

🚀 Quick Start

1. Installation

Install the package using the compiled wheel file:

pip install ungyoface-1.0.0-py3-none-any.whl

2. Run Built-in Demo You can immediately trigger the full camera pipeline with a single line of code:

import ungyoface

# Fires up the camera and starts real-time emotion tracking!
ungyoface.run()

🛠️ Advanced Usage (Integration) If you want to integrate the core engine into your own custom multi-modal pipeline (e.g., motion tracking or surveillance safety systems), import the engine class directly:

import cv2
import threading
from ungyoface import UngyoFaceEngine

# Initialize the engine with custom settings
engine = UngyoFaceEngine(input_size=320, analysis_interval=1.0)

cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()
    if not ret: break
    frame = cv2.flip(frame, 1)
    
    # 1. Trigger the background engine non-blockingly
    if not engine.is_analyzing:
        threading.Thread(
            target=engine.emotion_engine,
            args=(frame.copy(),),
            daemon=True
        ).start()
        
    # 2. Safely extract results using the built-in Thread Lock
    with engine.data_lock:
        for item in engine.final_results:
            x, y, w, h = item["box"]
            emotion = item["emotion"]
            scores = item["scores"]
            
            # Draw your custom UI/UX here
            cv2.rectangle(frame, (x, y), (x+w, y+h), (0, 255, 0), 2)
            cv2.putText(frame, emotion.upper(), (x, y - 10), 
                        cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2)

    cv2.imshow('Custom Pipeline', frame)
    if cv2.waitKey(1) & 0xFF == ord('q'): break

cap.release()
cv2.destroyAllWindows()

📊 Technical Specification Face Detector: OpenCV Haar-Cascade (haarcascade_frontalface_default.xml)

Emotion Classifier: DeepFace Framework

Thread Safety: threading.Lock() utilized to eliminate race conditions between the main loop and the background engine.

📝 License Distributed under the MIT License. Created by WoongGyo.