Overview


This article explains how to normalize a face image and import it as a Visual Face credential using Suprema G-SDK.


The Visual Face credential uses a visual camera to capture a user’s facial image. It differs from the traditional face credential that uses an infrared camera and is available only on FaceStation F2, BioStation 3, and BioEntry W3, which support the Visual Face credential.


For face enrollment, the original face image prepared for registration will be referred to as the raw image in this document.


A raw image may include background or other unnecessary areas outside the face.By applying "Normalization" to extract and standardize only the face region, the system can enhance matching accuracy and reduce data size, which in turn helps reduce the device’s resource load.


Normalization refers to the process of extracting the facial region from the raw face image that may contain other body parts.


When enrolling a face, in addition to the method of extracting and importing the face template as described below, you can also enroll a Visual Face using a raw image or a warped image.

In this article, we will explain how to extract a face template and enroll a Visual Face using that template.



Important: Without a device, Normalization is impossible. This feature only runs on the device.


Workflow


The overall process can be divided into four steps: 


1. Connect to the device and prepare the environment.

2. Normalize the raw face image using Suprema G-SDK to obtain a warped image.

3. Extract the face template from the warped image.

4. Import the result as a Visual Face credential on the device.


Step 1. Prepare the Image File


Before normalization, prepare a raw facial image that will be used as input.

Refer to the image below for an example of an appropriate face capture.




Step 2. Normalize the Face Image


Normalization extracts the face region and scale to a fixed size. It generalizes the image by extracting only the facial region from the original image that may contain various body parts, to obtain more accurate and reliable facial data.


In the context of Suprema G-SDK, normalization produces a warped image, which is a fixed-size face representation from which the face template will be extracted in the next step.


There may be differences in warped image size for each firmware version:


AlgorithmEquipped OnDetect FaceGenerate Warped ImageExtract Template
Old AlgorithmFaceStation F2 v1.x.xYY
(250 x 250 px)		Y
New Algorithm
(for GPU)		BioStar 2
v2.9.0 and above		Y
* Same way		Y
(112 x 112 px)		Y
FaceStation F2 v2.x.x
New Algorithm
(for NPU)		BioStation 3Y


This example demonstrates the workflow using Suprema G-SDK and Python. Replace stubs (userSvc, faceSvc) with your actual gRPC service instances.


Code Snippet


path = input("Enter the image file path: ")
if path:
    with open(path, 'rb') as f:
        imageData = f.read()
    warpedImageData = faceSvc.normalize(devID, imageData)
    if not warpedImageData:
        print("Failed to normalize the image.")
        return False



Step 3. Extract the Face Template from the Warped Image


After normalization, extract the face template according to the template structure. The device takes the warped image and outputs template data suitable for enrollment.


Code Snippet


templateData = faceSvc.extract(devID, warpedImageData, True)
if not templateData:
        print("Failed to extract face template.")
        return False


Step 4. Import to Device


Once the template is ready, create or update the user on the device, then import it as a Visual Face credential.


Note: Visual Face credentials are not interchangeable with IR face images.


Code Snippet


userID = input("Enter user ID for enrollment: ")
    if not userID:
        print("No user ID provided. Enrollment cancelled.")
        return False
numOfFace = 1
hdr = user_pb2.UserHdr(ID=userID, userFlag=user_pb2.USER_FLAG_CREATED, numOfFace=numOfFace)
setting = user_pb2.UserSetting()
faceData = face_pb2.FaceData (
    index = 0,
    flag = face_pb2.BS2_FACE_FLAG_EX | face_pb2.BS2_FACE_FLAG_TEMPLATE_ONLY,
    templates = [templateData],
)
userInfo = user_pb2.UserInfo(hdr=hdr, setting = setting, name=f"user_{userID}", faces=[faceData])
userSvc.enroll(devID, [userInfo], True)
print(f"Face template enrolled successfully for user ID: {userID}")



Full Example Code


def exportFromImageAndEnroll(devID, faceSvc, userSvc):
    try:
        path = input("Enter the image file path: ")
        if not path:
            print("No file path provided.")
            return False
        with open(path, "rb") as f:
            imageData = f.read()

        warpedImageData = faceSvc.normalize(devID, imageData)
        if not warpedImageData:
            print("Failed to normalize the image.")
            return False
        print("Image normalized successfully.")

        templateData = faceSvc.extract(devID, warpedImageData, True)
        if not templateData:
            print("Failed to extract face template.")
            return False
        print("Face template extracted successfully.")

        desktop = desktop_path()
        os.makedirs(desktop, exist_ok=True)
        base = os.path.splitext(os.path.basename(path))[0]

        warped_file = os.path.join(desktop, f"{base}_warped.jpg")
        template_file = os.path.join(desktop, f"{base}.dat")

        with open(warped_file, "wb") as f:
            f.write(warpedImageData)
        with open(template_file, "wb") as f:
            f.write(templateData)

        print(f"Warped image saved to: {warped_file}")
        print(f"Template data saved to: {template_file}")
        
        if (yes_or_no("Do you want to enroll this face template to the device? y or n: ")):
            userID = input("Enter user ID for enrollment: ")
            if not userID:
                print("No user ID provided. Enrollment cancelled.")
                return False
            numOfFace = 1
            hdr = user_pb2.UserHdr(ID=userID, userFlag=user_pb2.USER_FLAG_CREATED, numOfFace=numOfFace)
            setting = user_pb2.UserSetting()
            faceData = face_pb2.FaceData (
                index = 0,
                flag = face_pb2.BS2_FACE_FLAG_EX | face_pb2.BS2_FACE_FLAG_TEMPLATE_ONLY,
                templates = [templateData],
            )
            userInfo = user_pb2.UserInfo(hdr=hdr, setting = setting, name=f"user_{userID}", faces=[faceData])
            userSvc.enroll(devID, [userInfo], True)
            print(f"Face template enrolled successfully for user ID: {userID}")
    except Exception as e:
        logging.error(f"Failed to get image file path: {e}")
        print("An error occurred while getting the image file path.")
        return False