DEV Community: Yakhyokhuja Valikhujaev

Changing a Face Recognition Model Also Changes Your Threshold

Yakhyokhuja Valikhujaev — Fri, 16 Oct 2026 09:34:28 +0000

Replacing a face recognition model can leave the Python code almost unchanged while changing the meaning of every stored embedding and similarity score.

UniFace exposes AdaFace, ArcFace, EdgeFace, MobileFace, and SphereFace through a common recognizer interface. That makes it convenient to compare implementations. It does not make their embedding spaces or decision thresholds interchangeable.

This article develops that distinction from my original recognition model comparison. The focus here is what needs to change in a pipeline when the recognizer changes.

The interface stays stable; the representation changes

The recognition path starts with an image and five alignment landmarks. The landmarks define a standardized face crop, and the recognizer maps that crop to an embedding. UniFace can return an L2-normalized vector for cosine similarity.

Two models can both produce 512 values without assigning the same meaning to those coordinates. Comparing an AdaFace vector with an ArcFace vector is not a supported identity comparison. Even switching weights within a model family should be treated as a representation change unless compatibility has been established.

For a stored gallery, replacing the recognizer therefore requires regenerating its embeddings and rebuilding the corresponding search index. A migration that changes only the model constructor can produce plausible-looking scores from incompatible vectors.

Compute a score before assigning a decision

The following example uses an explicit ArcFace variant and requires one face in each input. It prints a similarity score without attaching an uncalibrated match label.

Install the CPU runtime with pip install "uniface[cpu]", then supply two portrait images:

import cv2
from uniface import ArcFace, RetinaFace, compute_similarity
from uniface.constants import ArcFaceWeights

detector = RetinaFace()
recognizer = ArcFace(model_name=ArcFaceWeights.MNET)

def embed(path):
    image = cv2.imread(path)
    if image is None:
        raise FileNotFoundError(f'Could not read {path}')
    faces = detector.detect(image)
    if len(faces) != 1:
        raise ValueError(f'Expected one face in {path}, found {len(faces)}')
    return recognizer.get_normalized_embedding(image, faces[0].landmarks)

score = compute_similarity(
    embed('portrait_a.jpg'),
    embed('portrait_b.jpg'),
    normalized=True,
)
print(f'Cosine similarity: {score:.3f}')

The score is a similarity measurement, not the probability that the images show the same person. A decision threshold is a separate part of the application.

Selecting the highest-confidence detection would not resolve an ambiguous multi-person image: detector confidence measures detection confidence, not which subject the caller intended. Requiring exactly one face makes this example's assumption explicit.

What a small comparison can tell you

The original post compared six model configurations on five archival portraits, producing two same-person pairs and eight different-person pairs. That exercise showed how the scores changed between models while the input images stayed fixed.

It did not establish a general accuracy ranking, a false-match rate for deployment, or a recommendation for a particular device. Ten pairs are too few to characterize errors across lighting, pose, age, camera quality, and population differences. The illustration above comes from a separate demo run and should not be treated as the numerical record of the comparison.

A small test can check that a pipeline runs and reveal obvious score changes. Choosing a deployment threshold requires a larger, representative evaluation.

Calibrate the complete pipeline

Collect labeled same-person and different-person examples that reflect the intended inputs. Separate threshold selection from final evaluation so the reported result is not simply a fit to the calibration examples.

For a rule that accepts a pair when its score is at least a threshold, increasing that threshold generally reduces false matches while increasing missed matches. Evaluate both errors and choose an operating point based on the application's requirements. A value copied from a demo or another model has no such justification.

The detector and preprocessing belong in that evaluation. Different landmarks change alignment; crop geometry, color conventions, and image quality can also affect embeddings. Keep the detector, alignment method, recognizer weights, and preprocessing fixed when comparing scores.

For one-to-many search, evaluate the search workflow with a gallery of representative size as well. A pairwise threshold study alone does not describe the chance of an incorrect identification across many candidates.

Plan model changes as data migrations

Record the recognizer variant, weight checksum, and preprocessing configuration alongside the embedding collection. Build the replacement gallery separately, recalibrate its decision rule, and validate it before switching the application to the new index.

Runtime measurements need the same care. Weight-file size describes storage, not latency. Measure preprocessing, alignment, inference, and search on the intended hardware and execution provider. The laptop timings in the original post are observations from that setup, not performance promises for another device.

A shared API reduces the code needed to compare recognizers. The data migration and evaluation remain part of the change.

See UniFace's recognition documentation, threshold calibration guide, and model licence terms before selecting a configuration for deployment.

BiSeNet or XSeg? Choosing the Right Face Mask for an Image Pipeline

Yakhyokhuja Valikhujaev — Fri, 16 Oct 2026 09:34:25 +0000

A face parser can return a map of facial parts or a mask of the face as a whole. Those outputs can look similar in a visualization, but they support different operations.

If an editor needs to select hair or lips, it needs region labels. If a compositing step needs a face-shaped selection, a single mask may be sufficient. Choosing between BiSeNet and XSeg starts with that distinction, before comparing model size or inference time.

This article adapts my original BiSeNet/XSeg comparison into an implementation guide for UniFace. It retains the output examples while separating API behavior from observations on a small set of portraits.

Two outputs with different meanings

Property	BiSeNet in UniFace	XSeg in UniFace
Output	Integer class map, IDs 0–18	Floating-point mask, values 0–1
Selection	Individual regions such as hair, skin, and lips	A face region, without separate part labels
Input to the normal parsing call	Face-centered BGR crop	BGR image and five alignment landmarks
Output coordinates	Same dimensions as the supplied crop	Warped back to the supplied image dimensions

BiSeNet's 19 classes include background, skin, eyes, eyebrows, nose, lips, and hair. A selection is a comparison against one or more class IDs. XSeg supplies one mask; it cannot tell the application which selected pixels are lips or skin.

In this example, XSeg's mask excludes the hair. It should not be treated as a full portrait or head mask. If the task is separating a person, including hair, from a background, portrait matting is a separate option.

Coordinate space is part of the interface

A mask is only useful if it lines up with the pixels being edited. BiSeNet returns labels in the coordinate system of its input crop. XSeg's normal parsing call aligns the face using landmarks, runs inference, then transforms the result back into the original image.

The following example makes those two coordinate systems explicit. Install UniFace with the CPU runtime using pip install "uniface[cpu]" and supply a portrait containing one face.

import cv2
import numpy as np
from uniface import BiSeNet, RetinaFace, XSeg

image = cv2.imread('portrait.jpg')
if image is None:
    raise FileNotFoundError('Could not read portrait.jpg')

faces = RetinaFace().detect(image)
if len(faces) != 1:
    raise ValueError(f'Expected one face, found {len(faces)}')
face = faces[0]

# Expand the detector box to retain more hair and surrounding context.
x1, y1, x2, y2 = face.bbox[:4]
bw, bh = x2 - x1, y2 - y1
height, width = image.shape[:2]
left = max(0, int(np.floor(x1 - 0.2 * bw)))
top = max(0, int(np.floor(y1 - 0.4 * bh)))
right = min(width, int(np.ceil(x2 + 0.2 * bw)))
bottom = min(height, int(np.ceil(y2 + 0.2 * bh)))
crop = image[top:bottom, left:right]

labels = BiSeNet().parse(crop)
hair_in_crop = (labels == 17).astype(np.uint8) * 255
cv2.imwrite('hair_crop.png', hair_in_crop)

face_mask = XSeg().parse(image, landmarks=face.landmarks)
cv2.imwrite('face_mask.png', (face_mask * 255).astype(np.uint8))

The crop margins are a preprocessing choice, not a guarantee that every hairstyle fits. The saved hair mask belongs to the expanded crop. To position it in the full frame, use the recorded left and top offsets. The XSeg mask already has the full image dimensions.

UniFace also exposes XSeg.parse_aligned() for callers that already have an aligned crop. That path returns a mask in crop coordinates and does not perform the full-image transformation.

What the example portraits can establish

The original comparison examined three faces. In that small sample, the larger BiSeNet backbone did not consistently preserve more detail, and XSeg produced an almost binary mask despite its floating-point output.

These are observations about those examples. They do not establish a general backbone ranking or a minimum usable face size. Counting which classes appear also does not measure whether the boundaries are correct; that requires reference annotations and a segmentation metric.

This occluded portrait illustrates another evaluation question: does the mask include the obstruction? The example is worth inspecting, but one scarf image does not establish performance on hands, glasses, or other occlusions.

Match the evaluation to the edit

For region-specific editing, evaluate the classes the editor actually uses and inspect boundaries at the intended image resolution. For face compositing, examine mask coverage, alignment errors, and leakage into hair or foreground objects.

A value between zero and one is not evidence of physically accurate transparency or a calibrated probability. Smoothing a face mask can soften an edge; it does not recover hair detail or turn the output into a portrait alpha matte.

BiSeNet and XSeg provide different selections. The useful comparison is whether each output supports the next image operation with acceptable errors on representative inputs.

See the parsing API documentation, the BiSeNet implementation and weights, and the XSeg ONNX repository for implementation details. Check the model licence terms before deployment.

UniFace: Face Analysis Beyond the Bounding Box

Yakhyokhuja Valikhujaev — Thu, 01 Jan 2026 16:18:30 +0000

A bounding box tells you where a face is. What happens next depends on the application. A photo search tool needs a representation it can compare. A portrait editor needs the boundary between skin, hair, and background. A video workflow may need to follow a face across frames or obscure it before the footage is shared.

UniFace is an open-source Python library for face detection, recognition, facial geometry, segmentation, and tracking. Most neural models run through ONNX Runtime. Developers can use the modules individually or combine them into a pipeline.

This article examines how detection results feed recognition, geometry, and image processing. The images are selected examples from the project; they illustrate outputs rather than measure accuracy, robustness, or speed.

See nine tasks running on video in the UniFace animated demo: detection, landmarks, face mesh, tracking, recognition, attributes, head pose, face parsing, and anonymization.

Detection is the beginning of a pipeline

In UniFace, a detection becomes a structured Face object containing a bounding box, a confidence score, and, for compatible detectors, alignment landmarks. That gives subsequent stages a common starting point.

Alignment matters because a recognition model should compare faces in a consistent pose and crop. The landmarks around the eyes, nose, and mouth provide reference points for that transformation. Small differences in preprocessing can affect the embedding that comes out, even when the underlying recognition model is unchanged.

UniFace handles this connection between detection and recognition. The detector locates the face; the recognizer uses its landmarks to align the image before extracting a vector. Developers can configure the detector and recognizer separately, provided the detector supplies the alignment landmarks required by the recognizer.

That separation is also useful when recognition has no role in the application. A face-blurring workflow can stop at detection and pass the results directly to anonymization.

A face has more than one useful representation

An embedding is useful when the question is whether two face images are similar. A recognition model maps an aligned face to a numerical vector that can be compared with another vector or searched in a collection. UniFace supports recognizers including ArcFace, AdaFace, and EdgeFace, along with an optional FAISS-backed store for embedding search.

Those scores still need interpretation. A threshold suitable for organizing a personal photo collection may be unsuitable for a verification workflow. Model choice, image quality, and the cost of false matches all influence that decision; a demo score cannot settle it for every application.

Geometry answers a different set of questions. A few alignment landmarks describe the broad arrangement of a face, while dense landmarks describe its contours in much greater detail. UniFace includes 68-, 98-, and 106-point landmark options, as well as a 468- or 478-point face mesh with relative depth.

For an overlay or an effect that follows the shape of a face, those points are often the more useful output. Head pose and gaze estimation extend this spatial view with estimates of head orientation and viewing direction.

The choice of representation follows the job: vectors for comparison, landmarks for geometry, and masks when the next operation happens at the pixel level.

From analyzing an image to changing it

Face parsing predicts a semantic label for each pixel. UniFace's BiSeNet models use 19 classes, including regions such as skin, hair, eyes, and lips. The resulting mask can select a component for a downstream edit.

A portrait editor, for example, could use the predicted skin region to select where to apply a color adjustment. The quality of that selection depends on the segmentation result. A face mask from XSeg serves a broader selection task. Portrait matting with MODNet produces an alpha matte for separating a person from the background, including partially transparent boundaries.

These outputs have different meanings, even though they may look similar in a demonstration. A semantic label identifies a region; an alpha matte describes how foreground and background mix. The downstream operation needs to account for that distinction.

Anonymization is another practical destination for a detection. UniFace can apply pixelation, blur, or a solid fill to detected face regions. This is useful for preparing images or video for sharing, provided the output is reviewed for missed faces and adequate coverage.

The architecture follows the task

UniFace exposes individual modules alongside a higher-level FaceAnalyzer. The modules give developers control over each stage; the analyzer connects detection, alignment, recognition, and optional attribute predictors in one call.

A small example shows that composition. After installing pip install "uniface[cpu]", the following uses RetinaFace for detection and ArcFace for embeddings:

import cv2
from uniface import ArcFace, FaceAnalyzer, RetinaFace

image = cv2.imread('portrait.jpg')
if image is None:
    raise FileNotFoundError('Could not read portrait.jpg')

analyzer = FaceAnalyzer(
    detector=RetinaFace(),
    recognizer=ArcFace(),
)

for face in analyzer.analyze(image):
    print('Face bounds:', face.bbox)
    if face.embedding is not None:
        print('Embedding dimensions:', face.embedding.shape)

Additional predictors can enrich each face with selected attributes. Other workflows can use the modules directly: a video application might combine detection with tracking, while a face search system might assess image quality before retaining an embedding. There is no need to run every available model on every image.

ONNX Runtime provides a common inference layer for most of these components, with CPU execution and acceleration through supported CUDA or CoreML environments. Execution-provider availability and model compatibility depend on the runtime build and environment. Latency and memory use need to be measured on the target machine. The emotion module is an exception that uses optional PyTorch.

Model weights download on first use, undergo SHA-256 verification, and are cached locally. They can also be prepared ahead of time for offline use. Offline execution requires the selected weights and runtime dependencies to be available on the target machine.

Evaluation and limitations

The examples here do not establish a deployment accuracy or performance level. Recognition thresholds need evaluation on representative data, including false matches and missed matches. Attribute predictions can be inaccurate and biased. Tracking IDs indicate continuity across frames, not verified identity. Face obscuring requires checking for missed detections and insufficient coverage.

The same care applies to model selection. UniFace's code is MIT-licensed, while individual pretrained weights have their own terms. The licence and attribution guide documents those distinctions.

UniFace provides model wrappers, preprocessing, and pipeline composition. Whether a particular configuration meets an application's requirements depends on the selected weights, input data, hardware, and evaluation criteria.

Explore the examples in the interactive demo, find implementation details in the documentation, or browse the models and source on GitHub.