Detection and matching settings

Two layers of settings shape the face processing pipeline. Per-camera settings are stored with the camera entity and changed through Station or the REST API (PUT /api/v1/Cameras); they choose which detector a camera uses and how strict it is. Service-level settings live in .env of the release package and select the neural networks a service loads; changing them needs docker compose up -d and, for extraction, a template migration. Edge streams have their own equivalents, see the edge settings reference.

Face detector resource ID

The per-camera faceDetectorResourceId selects where and how face detection runs. The _remote suffix moves detection from the camera service into the dedicated detector service; cpu, gpu or any picks the processing unit; the accurate_ prefix switches from the default Balanced network to Accurate.

Value	Where	Unit	Network
none	detection disabled	—	—
cpu	in the camera service	CPU	Balanced
gpu	in the camera service	GPU	Balanced
accurate_cpu	in the camera service	CPU	Accurate
accurate_gpu	in the camera service	GPU	Accurate
cpu_remote	detector service	CPU	Balanced
gpu_remote	detector service	GPU	Balanced
any_remote	detector service	any available	Balanced
accurate_cpu_remote	detector service	CPU	Accurate
accurate_gpu_remote	detector service	GPU	Accurate
accurate_any_remote	detector service	any available	Accurate

GPU values require GPU acceleration to be enabled on the service (Gpu__GpuEnabled=true), see the GPU acceleration guide. Pedestrian and object detection use the same pattern (pedestrianDetectorResourceId with cpu_remote / gpu_remote / any_remote; objectDetectorResourceId with sfe_object_cpu_remote / sfe_object_gpu_remote / sfe_object_any_remote).

Detection algorithms

The detector service preloads the networks listed in Warmup__DetectionAlgorithms (.env, comma-separated). Supported values are fast, balanced_mask and accurate_mask; the default is balanced_mask. The _mask networks also produce the face-mask attributes; fast does not.

Warmup__DetectionAlgorithms=balanced_mask

Confidence threshold and face size

Camera setting	Range	Default	Effect
Detection confidence threshold	0 – 10,000	450	Minimum detector confidence for a face to be accepted. Higher values reject non-faces but may miss real faces; 3,000 and above is a safe choice.
Minimum face size	pixels	—	Faces smaller than this are ignored. Faces under 25 px have poor biometric quality; 30 px or more is recommended.
Maximum face size	pixels	—	Faces larger than this are ignored; useful to skip people very close to the lens.
Detection interval	ms	—	How often full-frame detection runs; tracking covers the frames in between.

Face size is the larger of the eye distance and the eye-to-mouth distance. The Station camera settings reference lists every per-camera field.

Face mask detection

The extractor reports three mask-related attributes on Face and MatchResult entities, available in REST, GraphQL and notifications:

Attribute	Range	Meaning
FaceMaskConfidence	-10,000 – 10,000	Confidence that a mask is present; higher means more likely.
NoseTipConfidence	0 – 10,000	Confidence that the nose tip is visible, i.e. that a mask is not worn properly.
FaceMaskStatus	Mask, NoMask, Unknown	Derived from FaceMaskConfidence using the FaceMaskThreshold of FaceMaskConfidenceConfig.

Mask detection is not available with the fast detection network. Faces created before mask detection existed have null confidences and status Unknown. The watchlist autolearn feature uses these attributes to keep masked and unmasked reference faces apart.

Extraction algorithm

The extractor service generates templates with one algorithm, selected by Extraction__Algorithm in .env. Each algorithm produces templates of a specific template version; the watchlist matcher and the face search service can only compare templates of the versions they were seeded with.

Extraction__Algorithm	Template version	Notes
fast	52	Fastest, lowest accuracy.
balanced	53	Default.
accurate	54	Higher accuracy, more CPU per face.
accurate_server	55	Highest accuracy, intended for server-class hardware.

The release package also lists specialised algorithms (accurate_mask, accurate_server_nist, accurate_server_nist_p1, accurate_server_visa, accurate_server_wild, frte_1N_014). They are not covered by the bundled migration scripts and are outside the scope of this documentation.

Choose the algorithm right after installation, before any watchlist member is enrolled. If the database already holds templates of another version, run the template migration (migrate-faces.sh, with FACE_MODEL_VERSION set to the target version) after changing the setting; otherwise enrolled members will not match. Back up the database first. The procedure is in the template migration guide.

# .env
Extraction__Algorithm=accurate

docker compose up -d extractor

Matching threshold

The matching threshold is the score (0 – 100) at or above which a comparison counts as a match. It is set per watchlist, so a VIP list can be stricter than a staff list. The platform default is 40. Only the best-scoring member is reported for a face. The matcher service itself has one tuning knob in .env, Matching__ThreadCount (default 4), which sets how many threads compare templates in parallel.

Raise the threshold when false matches are the problem, lower it when genuine members are rejected, and re-measure after each change; the reasoning is in Tuning identification. Watchlist search through the REST API takes its own threshold parameter per request.

Other detectors

Object detection algorithm

The object-detector service selects its network with Detection__Algorithm (balanced default, fast, accurate) and applies Detection__ClassThreshold (default 5000) as the minimum class confidence. Which object types a camera reports, the object size range and the per-camera confidence threshold are part of the camera's objectDetectorConfig.

Pedestrian attribute thresholds

The pedestrian-extractor service interprets raw attribute confidences (0 – 10,000) with upper and lower thresholds: above the upper threshold the attribute is true, below the lower threshold false, in between it is left out of the response.

Setting	Default
Extraction__Attributes__AppendInterpretedAttributes	true
Extraction__Attributes__AppendConfidenceAttributes	false
Extraction__Attributes__AppendInterpretedAttributesUnderLowerThreshold	false
Extraction__Attributes__InterpretationThresholds__CommonThresholdUpper / Lower	8000 / 4000
Extraction__Attributes__InterpretationThresholds__GlassesThresholdUpper / Lower	8000 / 4000
Extraction__Attributes__InterpretationThresholds__HoldThresholdUpper / Lower	7000 / 3000

Palm processing

Face Matcher Server can also identify people by the palm of the hand. The palm-detector service finds palms in camera frames, edge stream data and still images, and the palm-extractor service turns each palm crop into a palm template. Palm templates are matched against the palm images of watchlist members like face templates, with a threshold of their own. A camera or edge stream processes palms once a palm detector resource is selected in its settings; on the REST API, palms are enrolled with modality: "Palm" and searched with POST /api/v1/Watchlists/SearchByPalm (see Watchlists).

Palm matching threshold

Every watchlist has a palmThreshold next to the face threshold; the recommended default is 75. Set it when you create the watchlist (POST /api/v1/Watchlists) or change it later in Station. Palm scores are compared only with the palm threshold, never with the face threshold. Palm templates have their own version, and a palm model change needs a palm template migration.

Palm detector and enrollment validation

Setting	Default	Effect
palmDetectorConfig.minPalmSize / maxPalmSize	200 / 1200	Palm size range in pixels; other palms are ignored.
palmDetectorConfig.maxPalms	1 per request, 3 per camera	Maximum number of palms processed on one image or frame.
palmDetectorConfig.confidenceThreshold	5000	Minimum detection confidence, 0 – 10,000.
PalmValidation__PalmQuality__Min / Max (api, .env)	not set in .env	Palm quality range an enrollment image must reach; when unset, the service default applies.

Palm validation applies when a request uses palmValidationMode: "predefined", the default of Register, AddNewPalm and AddPalmFromSystem; SearchByPalm defaults to none.