How to Use the PyQt5 User Interface for Face Management in Multi-Cam Face Tracker

The Multi-Cam Face Tracker provides a built-in PyQt5 user interface for face management that allows you to add, update, delete, and import known faces through the FaceManagerDialog class, accessible via the Tools menu or programmatically.

The PyQt5 user interface for face management is a core component of the aarambhdevhub/multi-cam-face-tracker repository. This interface bridges the gap between the computer vision backend and user interaction, enabling non-technical users to manage the face database without editing configuration files directly.

Architecture of the PyQt5 Face Management System

The face management UI follows a modular architecture where the presentation layer in ui/face_manager.py communicates with the detection backend in core/face_detection.py.

MainWindow Integration

The MainWindow class in ui/main_window.py hosts the application and creates the Tools → Face Manager menu entry. When selected, it instantiates FaceManagerDialog with the current FaceDetector instance and the configured known faces directory:

# From ui/main_window.py lines 42-46

dialog = FaceManagerDialog(self.face_detector, self.config['app']['known_faces_dir'])
dialog.exec_()
self.face_detector.load_known_faces(self.config['app']['known_faces_dir'])

FaceManagerDialog Components

The FaceManagerDialog class implements a modal dialog containing:

• A QListWidget displaying registered faces from known_faces_dir
• A preview canvas showing the selected face using numpy_to_pixmap from core/utils.py
• Input fields for name entry
• Action buttons for Add, Update, Delete, and Import operations

FaceDetector Backend

The FaceDetector class in core/face_detection.py provides the data layer methods:

• add_known_face(image, name, save_dir) – Extracts embeddings and saves the image
• load_known_faces(known_faces_dir) – Refreshes the in-memory face database

How to Open the Face Manager Dialog

You can launch the PyQt5 face management interface either through the GUI menu or programmatically from a custom script.

Via the Application Menu

1. Start the application: python main.py
2. Click Tools in the menu bar
3. Select Face Manager

Programmatically from a Script

To open the dialog from external automation or testing scripts:

from ui.face_manager import FaceManagerDialog
from core.face_detection import FaceDetector
import yaml
import pathlib

# Load configuration

with open('config/config.yaml', 'r') as f:
    cfg = yaml.safe_load(f)

# Initialize detector

detector = FaceDetector(cfg)
known_dir = pathlib.Path(cfg['app']['known_faces_dir'])

# Show modal dialog

dialog = FaceManagerDialog(detector, known_dir)
dialog.exec_()

# Refresh after closure

detector.load_known_faces(known_dir)

Managing Known Faces Through the PyQt5 Interface

The FaceManagerDialog provides four primary operations for face database management.

Importing and Adding New Faces

The Import Image button opens a file chooser dialog supporting .jpg, .jpeg, and .png formats. Upon selection:

1. The image loads via OpenCV as a NumPy array
2. numpy_to_pixmap converts it for Qt preview display
3. The filename (without extension) auto-populates the Name field
4. Clicking Add Face calls face_detector.add_known_face() and saves to known_faces_dir

Updating Existing Face Entries

To modify an existing face:

1. Select the entry from the list widget
2. Either import a new image or keep the existing one
3. Edit the Name field if needed
4. Click Update Face to persist changes

The update operation replaces the stored image and re-extracts facial embeddings through the FaceDetector API.

Deleting Faces from the Database

Selecting a face and clicking Delete Face triggers a confirmation dialog. Upon confirmation:

1. The image file removes from known_faces_dir
2. load_known_faces() refreshes the in-memory list
3. The UI list widget updates to reflect the deletion

Programmatic Face Management Without the UI

For batch operations or headless environments, bypass the PyQt5 interface and interact directly with FaceDetector:

import cv2
from core.face_detection import FaceDetector
import yaml
import pathlib

with open('config/config.yaml') as f:
    cfg = yaml.safe_load(f)

detector = FaceDetector(cfg)
known_dir = pathlib.Path(cfg['app']['known_faces_dir'])

# Load image for registration

img = cv2.imread('path/to/person.jpg')
if img is not None:
    success = detector.add_known_face(
        img, 
        name='John Doe', 
        save_dir=known_dir
    )
    if success:
        detector.load_known_faces(known_dir)

This approach uses the same backend methods (add_known_face at lines 75-100 of core/face_detection.py) that the PyQt5 UI calls internally.

Refreshing Face Data After External Changes

If you manually modify files in the known_faces_dir directory (e.g., copying images via command line), refresh the detector's in-memory database:

# Assuming a MainWindow instance named `win`

win.face_detector.load_known_faces(
    win.config['app']['known_faces_dir']
)
win.open_face_manager()  # Optional: reopen UI to verify

The load_known_faces method rescans the directory, re-extracts embeddings for all valid images, and rebuilds the recognition database.

Key Source Files and Functions

File	Purpose	Key Components
ui/face_manager.py	PyQt5 dialog implementation	FaceManagerDialog class, add_face(), update_face(), delete_face(), import_image()
ui/main_window.py	Main application window	MainWindow class, menu creation, dialog instantiation
core/face_detection.py	Face recognition backend	FaceDetector class, add_known_face(), load_known_faces()
core/utils.py	Image conversion utilities	numpy_to_pixmap(), resize_image()
config/config.yaml	Application configuration	app.known_faces_dir setting

Summary

• The PyQt5 user interface for face management centers on the FaceManagerDialog class in ui/face_manager.py, providing modal dialogs for CRUD operations on known faces.
• Access the interface through Tools → Face Manager in the main application, or instantiate FaceManagerDialog programmatically with a FaceDetector instance and the known_faces_dir path.
• All UI operations delegate to FaceDetector.add_known_face() and FaceDetector.load_known_faces() in core/face_detection.py, ensuring consistency between manual file changes and programmatic updates.
• The utility function numpy_to_pixmap in core/utils.py enables OpenCV image arrays to display in Qt widgets for real-time preview.

Frequently Asked Questions

How do I access the PyQt5 face management interface in the application?

Launch the application with python main.py, then click the Tools menu in the menu bar and select Face Manager. This opens the FaceManagerDialog modal window where you can add, update, or delete known faces. The menu entry is created in ui/main_window.py and instantiates the dialog with the current FaceDetector instance and the configured known_faces_dir.

Can I add faces programmatically without opening the PyQt5 GUI?

Yes. Import FaceDetector from core.face_detection, initialize it with your configuration, and call detector.add_known_face(image, name, save_dir) where image is a NumPy array loaded via OpenCV. After adding, call detector.load_known_faces(save_dir) to refresh the in-memory embeddings. This bypasses FaceManagerDialog entirely while using the same backend methods defined in core/face_detection.py.

Where are known faces stored when using the PyQt5 interface?

Known faces are persisted as image files (.jpg, .jpeg, or .png) in the directory specified by app.known_faces_dir in config/config.yaml (default is typically data/known_faces/). When you click Add Face or Update Face in the dialog, FaceDetector.add_known_face() saves the image to this directory and updates the embedding cache. The dialog scans this directory on initialization to populate the face list.

How do I refresh the face detector after making external changes to the known faces folder?

If you manually add, remove, or modify images in the known_faces_dir directory outside the PyQt5 interface (e.g., via command line or file explorer), you must refresh the detector's in-memory database. Call face_detector.load_known_faces(known_faces_dir) to rescan the directory and rebuild the embeddings list. If you have a running MainWindow instance, access the detector via win.face_detector and invoke this method, optionally reopening the face manager dialog to verify the changes visually.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}