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

> Master PyQt5 face management in Multi-Cam Face Tracker. Add update delete and import faces easily through the intuitive FaceManagerDialog class.

- Repository: [AarambhDevHub/multi-cam-face-tracker](https://github.com/aarambhdevhub/multi-cam-face-tracker)
- Tags: how-to-guide
- Published: 2026-02-23

---

**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](https://github.com/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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/ui/face_manager.py) communicates with the detection backend in [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py).

### MainWindow Integration

The `MainWindow` class in [`ui/main_window.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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:

```python

# 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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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:

```python
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`:

```python
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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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:

```python

# 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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/ui/face_manager.py) | PyQt5 dialog implementation | `FaceManagerDialog` class, `add_face()`, `update_face()`, `delete_face()`, `import_image()` |
| [`ui/main_window.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/ui/main_window.py) | Main application window | `MainWindow` class, menu creation, dialog instantiation |
| [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py) | Face recognition backend | `FaceDetector` class, `add_known_face()`, `load_known_faces()` |
| [`core/utils.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/utils.py) | Image conversion utilities | `numpy_to_pixmap()`, `resize_image()` |
| [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py), ensuring consistency between manual file changes and programmatic updates.
- The utility function `numpy_to_pixmap` in [`core/utils.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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.