ungyoface 0.1.0

Ultimate Fast Face Recognition System with ungyoseries Integration

Markdown

ungyoface

Ultimate Fast Face Recognition System powered by DeepFace and optimized with ungyoseries Core Framework.

🚀 Features

• Zero Box Delay: Real-time face tracking using OpenCV Haar Cascades aligned perfectly with the camera FPS.
• Asynchronous Processing: Background DeepFace embedding and emotion recognition to eliminate main thread freezing.
• RAM Caching: Pre-computed VGG-Face embeddings for lightning-fast matching.

---

🛠️ Installation

1. Create a directory to store reference images (Default path: ./my_faces/) and add your face photos.

   • The filename will be used as the recognition identity (e.g., ungyo.jpg -> displayed as ungyo on screen).

2. Install the package in editable (development) mode from the root directory:

   pip install -e .
   

💻 Usage

1. Run Directly via Terminal Command Once installed, you can launch the real-time face acceleration radar system from anywhere in your terminal using a single command:

Bash ungyoface 2. Import as a Module in Python Scripts You can import and control the core pipeline of the ungyoface package directly within other Python projects:

from ungyoface import main_pipeline

if __name__ == "__main__":
    # Start the main pipeline integrated with hardware booster and real-time detection stream
    main_pipeline()

⚙️ Core API Reference Below is the specification of the core functions operating inside the ungyoface package. Refer to this when custom extensions are required.

pre_compute_db_embeddings()
Description: Extracts VGG-Face feature vectors from all image files inside the specified directory (./my_faces) at startup and caches them into RAM.

Key Detail: Minimizes initial file injection overhead by warming up the DeepFace model structure in memory exactly once.

detect_faces_cv2(frame)
Description: Swiftly extracts face bounding box coordinates from the input frame using the OpenCV Haar Cascade algorithm.

Returns: A list of dictionaries in the format of [{'box': (x, y, w, h)}, ...].

async_analysis_worker(face_crops_with_id)
Description: A background worker thread completely isolated from the main rendering thread. It receives cropped face images, processes heavy deep learning computations (DeepFace.analyze for emotion and scipy.spatial.distance.cosine for verification) asynchronously, and updates the global tracking table in real time.

main_pipeline()

Description: The top-level main loop of the system running under the @ungyoseries.boost() hardware acceleration. It opens an ultra-fast video stream and outputs the final frame by seamlessly combining the synchronous real-time tracking box rendering with the asynchronous feature identification layer.