How to Configure the Face Detection Threshold in Multi-Cam Face Tracker

The Multi-Cam Face Tracker uses two distinct thresholds—detection_threshold (default 0.5) for face region confidence and recognition_threshold (default 0.6) for identity matching—both defined in config/config.yaml and adjustable either statically via the file or dynamically through the built-in UI slider.

The Multi-Cam Face Tracker relies on InsightFace for detection and cosine-similarity scoring for recognition, making threshold tuning critical for balancing false positives against missed detections. Whether you need stricter filtering in high-traffic environments or higher sensitivity for low-light scenarios, the repository provides both static configuration files and runtime UI controls to adjust these parameters. This guide explains the exact file locations, parameter interactions, and code patterns needed to configure the face detection threshold according to your deployment requirements.

Understanding the Two Threshold Types

The system implements a two-stage pipeline with separate thresholds for each phase. Knowing which parameter controls which stage prevents misconfiguration.

• Detection threshold (detection_threshold): Controls the minimum confidence score the underlying InsightFace detector must achieve before accepting a region as a valid face. Defined in config/config.yaml at line 13 with a default value of 0.5.
• Recognition threshold (recognition_threshold): Sets the minimum cosine-similarity score required to label a detected face as a known person rather than "Unknown." Defined in config/config.yaml at line 14 with a default value of 0.6.

The FaceDetector class loads both values during initialization in core/face_detection.py:

# core/face_detection.py – lines 33-35

self.recognition_threshold = config['recognition']['recognition_threshold']
self.detection_threshold   = config['recognition']['detection_threshold']

Static Configuration via config.yaml

For permanent, environment-specific tuning, edit the YAML configuration directly. This method requires an application restart but ensures consistent behavior across sessions.

1. Open config/config.yaml in your editor.

2. Modify the values under the recognition: section. For example, to reduce false detections in bright conditions:

recognition:
  detection_threshold: 0.7   # raise from 0.5 → fewer false positives

  recognition_threshold: 0.8 # raise from 0.6 → require stronger identity match

3. Save the file and restart the application. The FaceDetector class reads these values on instantiation, applying them immediately to the InsightFace model preparation and recognition logic.

Dynamic Runtime Adjustment

For live tuning without restarting, the application exposes the recognition threshold through the UI, while the detection threshold remains static without source modification.

Using the Built-in UI Slider

The Controls tab contains a Recognition Threshold slider that maps integer values (50-100) to floating-point thresholds (0.5-1.0). When moved, it triggers MainWindow.update_threshold():

# ui/main_window.py – lines 81-90

def update_threshold(self, value):
    threshold = value / 100                # convert slider scale to 0.5-1.0

    self.face_detector.recognition_threshold = threshold
    self.threshold_value.setText(f"{threshold:.2f}")

This adjustment takes effect immediately for all subsequent frames, allowing real-time calibration against your specific camera feeds. Note that the UI does not expose detection_threshold; changing this parameter at runtime requires editing the source or restarting after modifying config.yaml.

How Thresholds Affect Processing

Understanding the internal application of these values helps predict the impact of adjustments on precision and recall.

Detection Threshold in Model Preparation

The detection_threshold is passed directly to InsightFace when the model initializes in core/face_detection.py:

# core/face_detection.py – lines 50-52

model.prepare(
    ctx_id=0 if self.device == 'cuda' else -1,
    det_thresh=self.detection_threshold,
    det_size=(640, 640)
)

Lower values (e.g., 0.3) increase recall by accepting marginal detections but introduce noise. Higher values (e.g., 0.8) filter out low-confidence regions, reducing computational overhead and false positives in cluttered backgrounds.

Recognition Threshold in Identity Matching

The recognition_threshold acts as a gatekeeper when comparing face embeddings against the known-face database:

# core/face_detection.py – identity matching logic

if max_similarity > self.recognition_threshold:
    results.append((face, self.known_faces[max_idx], max_similarity))
else:
    results.append((face, None, max_similarity))  # labeled as Unknown

Raising this value reduces false recognitions (incorrectly labeling strangers as known users) but may classify borderline legitimate matches as unknown identities.

Programmatic Configuration Examples

For automated deployment or testing scenarios, modify thresholds programmatically before detector initialization or via external scripts.

Pre-startup Configuration in Python

import yaml
from core.face_detection import FaceDetector

# Load configuration

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

# Adjust thresholds in-memory

cfg['recognition']['detection_threshold'] = 0.65
cfg['recognition']['recognition_threshold'] = 0.85

# Initialize with custom values

detector = FaceDetector(cfg)
print(detector.detection_threshold)      # 0.65

print(detector.recognition_threshold)    # 0.85

Batch Updating config.yaml

import yaml

def set_thresholds(det_thresh: float, rec_thresh: float, path: str = 'config/config.yaml'):
    with open(path) as f:
        cfg = yaml.safe_load(f)
    cfg['recognition']['detection_threshold'] = det_thresh
    cfg['recognition']['recognition_threshold'] = rec_thresh
    with open(path, 'w') as f:
        yaml.safe_dump(cfg, f)

# Deploy stricter settings across environments

set_thresholds(0.7, 0.8)

Summary

• Two thresholds control the pipeline: detection_threshold (InsightFace confidence) and recognition_threshold (cosine-similarity matching), both stored in config/config.yaml.
• Static changes require editing the YAML file and restarting; the FaceDetector class loads these in its __init__ method at lines 33-35 of core/face_detection.py.
• Dynamic adjustments are available only for recognition_threshold via the Controls tab slider, which invokes update_threshold() in ui/main_window.py.
• Higher values reduce false positives and false recognitions but may miss valid faces or label known users as unknown.
• Programmatic access allows threshold modification via the configuration dictionary before instantiating FaceDetector.

Frequently Asked Questions

What is the difference between detection_threshold and recognition_threshold?

The detection_threshold filters raw face candidates from the InsightFace model based on bounding box confidence, while the recognition_threshold determines whether a detected face matches a known identity based on embedding similarity. The former controls whether a face exists in the frame; the latter controls whose face it is.

Why can't I change the detection threshold from the UI?

The UI slider in ui/main_window.py only exposes recognition_threshold because the InsightFace model binds det_thresh during initialization in model.prepare() (lines 50-52 of core/face_detection.py). Changing this value requires reinstantiating the model, so the application restricts runtime adjustment to the recognition phase only.

How do I make the system less sensitive to false detections?

Increase detection_threshold in config/config.yaml from the default 0.5 to 0.7 or higher. This raises the confidence bar for accepting face regions, filtering out shadows, partial faces, and background artifacts that might trigger at lower thresholds.

Will raising the recognition_threshold improve security?

Yes, but with trade-offs. A higher recognition_threshold (e.g., 0.8 instead of 0.6) reduces the risk of false acceptances (impostors labeled as authorized users) by requiring stronger similarity matches. However, it may also reject legitimate users wearing glasses, hats, or exhibiting different lighting conditions, marking them as "Unknown."

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