Skip to main content

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
  1. 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.

Metadata

Release files for ungyoface 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ungyoface 1.0.0
File Size Uploaded Provenance Actions
ungyoface-1.0.0.tar.gz 17.5 kB Without provenance Details for ungyoface-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ungyoface 1.0.0
File Interpreter ABI Platform Actions
ungyoface-1.0.0-py3-none-any.whl Python 3 none any Details for ungyoface-1.0.0-py3-none-any.whl

Total release size: 36.1 kB

Release files / ungyoface-1.0.0.tar.gz

Download URL ungyoface-1.0.0.tar.gz
Size 17.5 kB
Tags Source
SHA-256 checksum
How to use checksums
13e72017bf4ef8498ba080d7ec5d5da6cad53406500a441751be55c1a8402373
BLAKE2b-256 checksum
How to use checksums
b7c34290573b092c9ef2959ea0ea7c18e5855b2366ad07c443867351981c9377
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.9

Release files / ungyoface-1.0.0-py3-none-any.whl

Download URL ungyoface-1.0.0-py3-none-any.whl
Size 18.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b8b14c253fdf8095d53dbbd5939dfbc717861d249224579ff82a8ec123eddabb
BLAKE2b-256 checksum
How to use checksums
06496d4475cf3c16d08f977c628b88221ce625579dc59d3a9b6a51f8a9133dfb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.9

Security for ungyoface 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page