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.
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 |