Auto Enrollment Module

SmartFace provides face biometry for various purposes including the access control and attendance use cases. The Auto Enrollment module helps automate the process of enrolling new faces into watchlists based on specific criteria.

Auto Enrollment module#

The Auto Enrollment module connects to SmartFace GraphQL endpoint and listens for NoMatch notifications. When an unmatched face is detected, the module evaluates it against defined criteria and automatically enrolls it into one or multiple watchlists if the criteria are met.

Development#

The source code is available on our Github repository. To run the application locally, follow these steps:

• Clone the https://github.com/innovatrics/smartface-integrations/ Github repository using git commands or download the code using the “Download Zip” button
• Open terminal
• Navigate to /src/AutoEnrollment
• Run dotnet run

Configuration#

When running the application you can configure it via the appsettings.json file in the Windows version, or using the environment variables in the .env.rc file when the module is deployed as a docker container. Here’s a comprehensive example of the configuration:

services:
  ...
  
  auto-enroll:
    image: ${REGISTRY}integrations-auto-enroll
    restart: unless-stopped
    environment:
      - Source__GraphQL__Host=SFGraphQL
      - Source__GraphQL__Port=8097

      - Source__OAuth__Url=https://?????.eu.auth0.com/oauth/token
      - Source__OAuth__ClientId=
      - Source__OAuth__ClientSecret=
      - Source__OAuth__Audience=

      - Target__Host=SFApi
      - Target__Port=8098

      - Config__MaxParallelActionBlocks=1
      - Config__DuplicateSearchThreshold=35
      - Config__EnrollStrategy=FirstPassingCriteria
      - Config__HardAbsoluteExpirationMs=300000
      - Config__TrackletTimeoutMs=5000

      - StreamConfigurations__0__StreamId=<<camera_id>>
      - StreamConfigurations__0__WatchlistIds__0=<<id-of-watchlist>>
      - StreamConfigurations__0__FaceQuality__Min=4500
      - StreamConfigurations__0__FaceSize__Min=70
      - StreamConfigurations__0__FaceSize__Max=450
      - StreamConfigurations__0__FaceArea__Min=0.01
      - StreamConfigurations__0__FaceArea__Max=1.50
      - StreamConfigurations__0__FaceOrder__Max=1
      - StreamConfigurations__0__FacesOnFrameCount__Max=2
      - StreamConfigurations__0__FaceQuality__Min=1000
      - StreamConfigurations__0__TemplateQuality__Min=80
      - StreamConfigurations__0__Brightness__Min=0.001
      - StreamConfigurations__0__Brightness__Max=1000
      - StreamConfigurations__0__Sharpness__Min=0.001
      - StreamConfigurations__0__Sharpness__Max=1000
      - StreamConfigurations__0__YawAngle__Min=-7
      - StreamConfigurations__0__YawAngle__Max=7
      - StreamConfigurations__0__PitchAngle__Min=-25
      - StreamConfigurations__0__PitchAngle__Max=25
      - StreamConfigurations__0__RollAngle__Min=-15
      - StreamConfigurations__0__RollAngle__Max=15
      - StreamConfigurations__0__FramePaddingAbsolute=50
      - StreamConfigurations__0__FramePaddingRelative=0.15

      - StreamConfigurations__1__StreamId=<<camera_id>>
      - StreamConfigurations__1__WatchlistIds__0=<<id-of-watchlist>>

networks:
  default:
    external:
      name: sf-network

Configuration Options#

Source Configuration#

• Source__GraphQL__Host: Hostname of the GraphQL service
• Source__GraphQL__Port: Port number for the GraphQL service
• Source__OAuth__Url: OAuth token endpoint URL
• Source__OAuth__ClientId: OAuth client ID for authentication
• Source__OAuth__ClientSecret: OAuth client secret for authentication
• Source__OAuth__Audience: OAuth audience identifier

Target Configuration#

• Target__Host: Hostname of the target API service
• Target__Port: Port number for the target API service

General Configuration#

• Config__MaxParallelActionBlocks: Maximum number of parallel action blocks to process
• Config__DuplicateSearchThreshold: Threshold for duplicate face detection (0-100)
• Config__EnrollStrategy: Strategy for enrollment (e.g., FirstPassingCriteria)
• Config__HardAbsoluteExpirationMs: Hard expiration time for tracklets in milliseconds
• Config__TrackletTimeoutMs: Timeout for tracklets in milliseconds

Stream Configuration#

Each stream can have its own configuration with the following options:

• StreamId: Unique identifier for the stream
• WatchlistIds: Array of watchlist IDs to enroll faces into
• FaceQuality__Min: Minimum face quality score (0-10000)
• FaceSize__Min: Minimum face size in pixels
• FaceSize__Max: Maximum face size in pixels
• FaceArea__Min: Minimum face area ratio (0-1)
• FaceArea__Max: Maximum face area ratio (0-1)
• FaceOrder__Max: Maximum face order in the frame
• FacesOnFrameCount__Max: Maximum number of faces allowed in a single frame
• TemplateQuality__Min: Minimum template quality score (0-100)
• Brightness__Min: Minimum brightness threshold
• Brightness__Max: Maximum brightness threshold
• Sharpness__Min: Minimum sharpness threshold
• Sharpness__Max: Maximum sharpness threshold
• YawAngle__Min: Minimum yaw angle in degrees
• YawAngle__Max: Maximum yaw angle in degrees
• PitchAngle__Min: Minimum pitch angle in degrees
• PitchAngle__Max: Maximum pitch angle in degrees
• RollAngle__Min: Minimum roll angle in degrees
• RollAngle__Max: Maximum roll angle in degrees
• FramePaddingAbsolute: Absolute padding around the face in pixels
• FramePaddingRelative: Relative padding around the face (0-1)

Usage#

Add the following pattern to your existing docker compose file (docker-compose.yml) and set up the .env.rc file as described above:

services:
  sf-station:
    image: ${REGISTRY}sf-station:${SFS_VERSION}
    container_name: SFStation
    restart: unless-stopped
    ports:
      - 8000:8000
    env_file: .env.sfstation

  auto-enrollment:
    image: ${REGISTRY}integrations-auto-enrollment
    container_name: SFAutoEnrollment
    restart: unless-stopped
    env_file: .env.rc

networks:
  default:
    external:
      name: sf-network

If needed, the environment variables normally defined in the .env.rc file can be defined directly in the docker-compose.yml file:

services:
  auto-enrollment:
    image: ${REGISTRY}integrations-auto-enrollment
    container_name: SFAutoEnrollment
    restart: unless-stopped
    environment:
      - SmartFace__GraphQL__Url=http://sf-station:8000/graphql
      - SmartFace__GraphQL__ApiKey=your-api-key
      - AutoEnrollment__Criteria__MinFaceSize=100
      - AutoEnrollment__Criteria__MinConfidence=0.8
      - AutoEnrollment__Criteria__MaxAge=30
      - AutoEnrollment__Watchlists__0__Id=watchlist-id-1
      - AutoEnrollment__Watchlists__0__Name=Auto Enrolled Watchlist 1
      - AutoEnrollment__Watchlists__1__Id=watchlist-id-2
      - AutoEnrollment__Watchlists__1__Name=Auto Enrolled Watchlist 2

The Auto Enrollment module will now:

1. Connect to the SmartFace GraphQL endpoint
2. Listen for NoMatch notifications
3. Evaluate unmatched faces against the defined criteria
4. Automatically enroll faces that meet the criteria into the specified watchlists