# How to Add New Known Faces to the Database Dynamically in Multi-Cam Face Tracker

> Dynamically add new known faces to the multi-cam face tracker database using the Face Manager UI or programmatically with FaceDetector.add_known_face() for seamless updates.

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

---

**You can dynamically add new known faces using the built-in Face Manager UI or programmatically via `FaceDetector.add_known_face()`, which extracts embeddings, saves images to disk, and updates the in-memory registry while optionally persisting to SQLite.**

The multi-cam-face-tracker repository implements a flexible dual-layer architecture for face enrollment that supports real-time updates without application restarts. Whether you need to register new identities through the Qt-based graphical interface or automate enrollment via Python scripts, the system provides distinct pathways for both in-memory recognition and persistent database storage.

## Understanding the Dual-Layer Storage Architecture

The system maintains known faces in two complementary layers to balance real-time performance with data persistence.

### In-Memory Registry for Real-Time Recognition

The `FaceDetector` class maintains an in-memory list called `known_faces` containing `KnownFace` objects. Each object stores the person's name, facial embedding vector, and image path. This registry lives in [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py) and provides the sub-millisecond lookup times required for real-time video processing.

### Persistent SQLite Database

For long-term storage across application restarts, the system optionally uses a SQLite database managed by the `FaceDatabase` class in [`core/database.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/database.py). This stores the same fields plus timestamps, enabling external scripts to enroll faces without launching the full application UI.

## Adding Faces via the Face Manager UI

The primary method for enrolling new faces uses the `FaceManagerDialog` class in [`ui/face_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/ui/face_manager.py), which provides a guided workflow for importing and validating face images.

### Importing and Previewing Images

The enrollment process begins with `FaceManagerDialog.import_image()`, which opens a file chooser dialog and loads the selected image using OpenCV. The method displays a preview within the dialog and pre-fills the name field using the file stem for convenience.

### Validating and Storing the Face

When the user clicks **"Add Face"**, the dialog invokes `FaceManagerDialog.add_face()`, which validates the input and delegates to the detector:

```python

# ui/face_manager.py – add_face()

success = self.face_detector.add_known_face(
    self.current_image, name, self.known_faces_dir)

```

Behind the scenes, `FaceDetector.add_known_face()` in [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py) performs three critical operations:

1. Extracts the facial embedding using the InsightFace model
2. Saves the image to disk with a timestamped filename
3. Appends a new `KnownFace` object to the in-memory registry

```python

# core/face_detection.py – add_known_face()

faces = self.detect_faces(image)                     # get embedding

face_path = save_dir / f"{name}_{timestamp}.jpg"    # store image

cv2.imwrite(str(face_path), image)
self.known_faces.append(KnownFace(name, face.embedding, str(face_path)))

```

The UI immediately refreshes the face list, and the system can recognize the newly enrolled identity without requiring a restart.

## Programmatically Adding Known Faces

For automation scenarios such as batch enrollment or API endpoints, you can bypass the UI and interact directly with the detection and database layers.

### Using FaceDetector for In-Memory Updates

To add a face programmatically without database persistence:

```python
import cv2
from core.face_detection import FaceDetector
from pathlib import Path

# Initialize with the same configuration used by the application

detector = FaceDetector(config)

# Load existing faces to maintain current registry

detector.load_known_faces(Path("known_faces"))

# Read new image as NumPy array

img = cv2.imread("new_person.jpg")

# Add to in-memory registry and save image to disk

detector.add_known_face(img, "Alice", "known_faces")

```

### Persisting to SQLite with FaceDatabase

To ensure the face survives application restarts without re-scanning the image directory, persist the embedding to the SQLite database:

```python
from core.database import FaceDatabase

# Initialize database connection

db = FaceDatabase("data/faces.db")

# Retrieve embedding from the newly added face (last entry in registry)

embedding = detector.known_faces[-1].embedding.tobytes()

# Insert into persistent storage

db.add_known_face(
    name="Alice",
    embedding=embedding,
    image_path="known_faces/Alice_1700001234.jpg"
)

```

## Loading Known Faces on Application Startup

When the application initializes, `FaceDetector.load_known_faces()` in [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py) scans the `known_faces_dir`, recomputes embeddings for each image using the InsightFace model, and repopulates the in-memory registry. This ensures that faces added via either the UI or direct file system manipulation are available for recognition.

```python

# core/face_detection.py – load_known_faces()

for face_file in known_faces_dir.glob('*.*'):
    img = cv2.imread(str(face_file))
    faces = self.model.get(img)
    self.known_faces.append(KnownFace(face_file.stem, faces[0].embedding, str(face_file)))

```

## Summary

- The **multi-cam-face-tracker** uses a dual-layer architecture: an in-memory registry for real-time recognition and an optional SQLite database for persistence.
- **UI-driven enrollment** uses `FaceManagerDialog` in [`ui/face_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/ui/face_manager.py) to import images, validate inputs, and call `FaceDetector.add_known_face()`.
- **Programmatic enrollment** allows direct calls to `FaceDetector.add_known_face()` for immediate in-memory updates, with optional `FaceDatabase.add_known_face()` for SQLite persistence.
- Faces are stored as timestamped images in the `known_faces_dir` and reloaded automatically on startup via `FaceDetector.load_known_faces()`.

## Frequently Asked Questions

### Can I add faces without using the GUI?

Yes. You can programmatically add faces by importing `FaceDetector` from [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py), initializing it with your configuration, and calling `add_known_face(image, name, save_dir)` with a NumPy array image. This bypasses the Qt interface entirely and works for batch processing or API integrations.

### Where are the face images physically stored?

Face images are saved to the directory specified as `known_faces_dir` (typically `known_faces/` in the project root) with timestamped filenames in the format `{name}_{timestamp}.jpg`. The `FaceDetector.add_known_face()` method in [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py) handles the file I/O using OpenCV's `imwrite` function.

### Do I need to restart the application after adding a new face?

No. The system supports dynamic updates without restarts. When you add a face via the UI or programmatically, `FaceDetector.add_known_face()` immediately appends the new `KnownFace` object to the in-memory registry. The recognition pipeline uses this live registry for matching, making the new identity available for detection in subsequent video frames instantly.

### How does the system handle duplicate names?

The current implementation in [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py) does not enforce unique name constraints in the `add_known_face` method. If you add multiple faces with the same name, each creates a separate `KnownFace` entry with a unique timestamped filename. During recognition, the system matches based on embedding similarity rather than name uniqueness, so duplicates will exist as separate entries in the registry. To prevent duplicates, implement a check against `self.known_faces` names before calling `add_known_face`.