Face Recognition

Overview

Face Recognition node detects faces in the input frame and matches each detected face against a library of known reference images.

Each match is scored by two complementary metrics — cosine similarity and L2-norm distance — so you can tune acceptance behavior for your use case. Use this node in identity verification flows, access control, or attendance tracking.

Input

Input Image

image required

The image frame to analyze. Connect this to a camera or upstream image output.

Known faces images and names

array required

Library of reference faces to match against. Each entry contains:

• Face Image (img) — reference image showing the person's face.
• Name (name) — string label returned in the output when this face is matched.

Provide at least one clear, front-facing image per person for best accuracy. Maximum entries: 20.

Detection model

string required advanced

Face detection backend used to locate faces before recognition.

Values:

• ONNX_YUNET (default) — faster, recommended for most use cases.
• TFDNN — OpenCV / TensorFlow DNN-based detector.

Overlap threshold

number required advanced

Boxes overlapping Filter (higher allows more overlap), a.k.a. NMS threshold. Shown for ONNX_YUNET and TFDNN.

Range: 0.0 to 1.0
Default: 0.3

Confidence threshold

number required advanced

Minimum detection confidence used to filter face boxes. Shown for ONNX_YUNET and TFDNN.

Range: 0.0 to 1.0
Default: 0.5

Top K value

integer required advanced

Keep the top K bounding boxes before NMS. Shown when Detection model is ONNX_YUNET.

Range: 0 to 10000
Default: 5000

Cosine Similarity Threshold

number required advanced

Minimum cosine similarity score required to accept a match. Cosine similarity measures the angle between face feature vectors.

Range: 0.0 to 1.0
Default: 0.5

Higher values require closer feature alignment for a match to be accepted.

L2 Normalisation Similarity Threshold

number required advanced

Maximum L2-norm distance allowed for an accepted match. Lower distances mean more similar faces.

Range: 0.0 to 2.0
Default: 1.0

Overlay results

boolean required advanced

Whether to draw recognition results (matched name and bounding box) on the output frame. See Overlay Results.

Default: true

Draw facial landmarks

boolean required advanced

When enabled, draws facial landmark points on each detected face in the overlay.

Default: false

Output

Overlay Image

image

Output frame from the node. If overlays are enabled, each detected face is annotated with a bounding box and the matched name (or an "unknown" label if no match meets the threshold).

Detected Count

integer

Number of faces detected in the current frame.

Detected Faces

array

Array of recognition results. Each object contains:

• Bounding Box (bbox) — [x, y, width, height] of the detected face.
• Name (label) — name from the matched Known Faces entry, or unrecognized if no match meets the threshold.
• Landmarks Points (points) — facial landmark [x, y] pairs.
• Landmarks Labels (pointLabels) — labels for each landmark point.