Events and face metadata

Face Matcher reports what happens in the video streams as events (notifications) the moment they occur: a face was detected, its attributes were extracted, it matched a watchlist member, the person left the scene. Integrations react to these events in real time; the same information is also stored in the database so it can be queried later.

Providers

Provider	Endpoint	Use it when
GraphQL subscriptions	ws://localhost:8097/graphql (in-network graphql-api:8080); schema at http://localhost:8097/graphql?sdl	You want a typed, filterable stream in a web or backend client and can hold a WebSocket. See GraphQL API.
RabbitMQ	AMQP on rmq:5672 (host port 5672)	You need durable delivery, several consumers or a message-driven backend. See RabbitMQ notifications.

With Notifications__IncludeTemplates=true (the release package default) match and face events carry the face template, so a consumer such as a corridor controller can re-verify or cache it without another API call.

Two kinds of events

Direct events are sent as soon as the data exists, before anything is written to the database, and regardless of the save strategy; even with storage switched off you still receive them. Database events are sent after the record has been stored, so the entity they reference can be queried through the API immediately.

Because writing to the database takes a variable amount of time, database events can arrive in a different order than the underlying detections. Match events in particular are published as soon as the match result is known, not when it is stored.

Direct events

GraphQL subscription	Trigger	Contains
FaceProcessed	A face was detected and processed in a frame.	Face, frame, match result (if any) and spoof check.
PedestrianProcessed	A pedestrian was detected.	Pedestrian and frame.
ObjectProcessed	An object was detected.	Object and frame.

Database events

GraphQL subscription	Trigger
faceCreated	A detected face was stored; some attributes are not extracted yet.
faceExtracted	Age, gender, face mask and the other attributes were extracted and updated.
matchResultInsert	A face matched a watchlist member and the match result was stored.
trackletCompleted	A tracked face or pedestrian was lost and its tracklet closed.
pedestrianInserted	A detected pedestrian was stored.
heartbeat	Sent every second with the current UTC time; use it to detect a broken connection.

Which events are emitted depends on the storage mode: with video storage set to None only direct events remain, see Data retention.

Face metadata

Every face event, and every match and no-match record shown in Station, carries the same set of face attributes. Match events add the identity fields.

Field	Example	Description
Date and time	2024-02-08 07:02:23	When the event was created.
Camera or edge stream	Lobby north	Source the face came from.
Watchlist name (match only)	Employees	Watchlist the identified member belongs to.
Watchlist member (match only)	John Smith	Display name of the identified member.
Matching score (match only)	76	Score 0 – 100 of the best match, see Face processing pipeline.
Age	30	Estimated age.
Gender	Male	Estimated gender.
Detection quality	2146	Detector confidence, 0 – 10,000.
Template quality	188	Quality of the extracted template; higher is better.
Yaw angle	-23	Head rotation left or right, degrees.
Pitch angle	-6	Head rotation up or down, degrees.
Roll angle	5	Head tilt, degrees.
Face size	38	Face size in pixels.
Face mask status	NoMask	Mask, NoMask or Unknown.
Face mask confidence	-3222	Confidence that a mask is present, -10,000 – 10,000.
Nose tip confidence	7998	Confidence that the nose tip is visible, 0 – 10,000.
Face area	3.38 %	Share of the frame covered by the face.
Face area change	1.12	Ratio of the face area to the previous tracked image; grows as the person approaches.
Face order	1	Rank of the face by size among the faces in the frame.
Faces on frame	1	Number of faces detected in the frame.
Face template	binary	Included when Notifications__IncludeTemplates is on.

Spoof attributes

When liveness is enabled on the source, match events and Station's match detail also carry the spoof check outcome, see Liveness.

Field	Values	Description
Distant check	Passed, Not passed, Not performed, Disabled	Result of the distant liveness check; when not performed, the failed condition is given as reason.
Distant score	0 – 100	Distant liveness score.
Nearby check	Passed, Not passed, Not performed, Disabled	Result of the nearby liveness check.
Nearby score	0 – 100	Nearby liveness score.

In Station an orange icon on a tracklet image means the check was not performed and a red icon means a spoof; a passed check shows no icon.