Face API

Face authentication is provided by FaceStation 2, FaceLite, FaceStation F2, and BioStation 3. The newest model, FaceStation F2 and BioStation 3 uses a fusion matching algorithm to improve its authentication performance. Due to this, there are a couple of differences between them.

		FaceStation 2 & FaceLite	FaceStation F2 & BioStation 3
FaceData	flag	BS2_FACE_FLAG_NONE	BS2_FACE_FLAG_WARPED / BS_FACE_FLAG_EX
	templates	Maximum 30	Maximum 10
	imageData	Visual Image	Visual Image
	irTemplates	Not Used	Maximum 10
	irImageData	Not Used	IR Image
Auth Group		Supported	Not Supported

Scan

enum FaceFlag {
  BS2_FACE_FLAG_NONE = 0x00;
  BS2_FACE_FLAG_WARPED = 0x01;
  BS2_FACE_FLAG_EX = 0x100;
}

message FaceData {
  int32 index;
  uint32 flag;
  repeated bytes templates;
  bytes imageData;

  // Only for FaceStation F2 and BioStation 3
  repeated bytes irTemplates;
  bytes irImageData;
}

index: Can be used for managing face data in your applications. Not used by the device.
flag: If BS2_FACE_FLAG_EX is set, it means that the face data is acquired by FaceStation F2 or BioStation 3. And, the data will include irTemplates and irImageData. Otherwise, it is from FaceStation 2 or FaceLite, and there will be neither irTemplates nor irImageData. BS2_FACE_FLAG_WARPED indicates that the image has been normalized.

Basically, the IR-based face recognition device (FaceStation 2, FaceLite) is very different from the visual camera-based face recognition device (FaceStation F2, BioStation 3) in its method. G-SDK’s FaceData message structure is a single structure designed to transmit face data to both IR-based and visual camera-based devices of different styles. This does not mean that template mixing is supported. For example, you can set FaceStation 2 face data in the FaceData message and send it to FaceStation 2 or FaceLite. That data cannot be transferred to BioStation 3 and used as is.

templates: Maximum 30 face templates can be returned from FaceStation 2 or FaceLite. For FaceStation F2 or BioStation 3, the maximum number is 10.
imageData: A BMP image of the face will be returned.
irTemplates: Maximum 10 IR templates can be returned from FaceStation F2 or BioStation 3.
irImageData: An IR image of the face will be returned.

enum FaceEnrollThreshold {
  BS2_FACE_ENROLL_THRESHOLD_0 = 0x00;
  BS2_FACE_ENROLL_THRESHOLD_1 = 0x01;
  BS2_FACE_ENROLL_THRESHOLD_2 = 0x02;
  BS2_FACE_ENROLL_THRESHOLD_3 = 0x03;
  BS2_FACE_ENROLL_THRESHOLD_4 = 0x04;
  BS2_FACE_ENROLL_THRESHOLD_5 = 0x05;
  BS2_FACE_ENROLL_THRESHOLD_6 = 0x06;
  BS2_FACE_ENROLL_THRESHOLD_7 = 0x07;
  BS2_FACE_ENROLL_THRESHOLD_8 = 0x08;
  BS2_FACE_ENROLL_THRESHOLD_9 = 0x09;
}

BS2_FACE_ENROLL_THRESHOLD_0: The least strict threshold.
BS2_FACE_ENROLL_THRESHOLD_4: The default.
BS2_FACE_ENROLL_THRESHOLD_9: The most strict threshold.

Scan

Scan a face and get its template data. With higher enrollThreshold, you can get face templates with better qualities. However, it will take more time to scan a face.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device
enrollThreshold	FaceEnrollThreshold	The strictness of face enrollment

Response

Parameter	Type	Description
faceData	FaceData	The scanned face data

Extract

Extract face templates from normalized images. It can be used to write a face template on a smart card.

Only supported by FaceStation F2 and BioStation 3. If the image file is not acquired by FaceStation F2 or BioStation 3, the image data should be in JPG or PNG file format.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device
imageData	byte[]	If the image file is acquired by FaceStation F2 or BioStation 3, it will be in BMP file format. Otherwise, only JPG file format is supported.
isWarped	bool	If the image file is acquired by FaceStation F2 or BioStation 3, it should be true. Otherwise, it should be false.

Response

Parameter	Type	Description
templateData	byte[]	The template data extracted from the image

Normalize

Extract warped images from unwarped images.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device
unwrappedImageData	byte[]	Unwarped image data.

Response

Parameter	Type	Description
wrappedImageData	byte[]	Warped image data.

Config

The default values would be good for most cases. Since some of these parameters could have a bad effect on the authentication performance, read the descriptions carefully before changing them.

message FaceConfig {
  FaceSecurityLevel securityLevel;
  FaceLightCondition lightCondition;
  FaceEnrollThreshold enrollThreshold;
  FaceDetectSensitivity detectSensitivity;
  uint32 enrollTimeout; 
}

securityLevel: With more secure levels, False Acceptance Ratio(FAR) would get lower. However, False Rejection Ratio(FRR) would become higher. The default is BS2_FACE_SECURITY_NORMAL.
lightCondition: The lighting condition could have a big effect on the authentication performance. The default is BS2_FACE_LIGHT_CONDITION_INDOOR.
enrollThreshold: The strictness of face enrollment. The default is BS2_FACE_ENROLL_THRESHOLD_4.
detectSensitivity: Face authentication starts automatically after detecting a face. This parameter specifies the sensitivity of detecting faces. The default is BS2_FACE_DETECT_SENSITIVITY_MIDDLE.
enrollTimeout: Timeout in seconds for enrolling a face. The default is 60 seconds.

enum FaceSecurityLevel {
  BS2_FACE_SECURITY_NORMAL = 0x00;
  BS2_FACE_SECURITY_SECURE = 0x01;
  BS2_FACE_SECURITY_MORE_SECURE = 0x02;
}

enum FaceLightCondition {
  BS2_FACE_LIGHT_CONDITION_INDOOR = 0x00;
  BS2_FACE_LIGHT_CONDITION_OUTDOOR = 0x01;
  BS2_FACE_LIGHT_CONDITION_AUTO = 0x02;
  BS2_FACE_LIGHT_CONDITION_DARK = 0x03;
}

enum FaceDetectSensitivity {
  BS2_FACE_DETECT_SENSITIVITY_OFF = 0x00;
  BS2_FACE_DETECT_SENSITIVITY_LOW = 0x01;
  BS2_FACE_DETECT_SENSITIVITY_MIDDLE = 0x02;
  BS2_FACE_DETECT_SENSITIVITY_HIGH = 0x03;
}

GetConfig

Get the face configuration of a device.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device

Response

Parameter	Type	Description
config	FaceConfig	The face configuration of the device

SetConfig

Change the face configuration of a device.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device
config	FaceConfig	The face configuration to be written to the device

SetConfigMulti

Change the face configurations of multiple devices.

Request

Parameter	Type	Description
deviceIDs	uint32[]	The IDs of the devices
config	FaceConfig	The face configuration to be written to the devices

Auth group

The more the number of face templates, the higher the False Acceptance Ratio(FAR). To lower this error, you can divide users into several groups, and try face authentication in a specific group only. To use this feature, you have to do the followings.

Enable AuthConfig.useGroupMatching.
Create the authentication groups using AddAuthGroup or AddAuthGroupMulti.
Set UserHdr.authGroupID.
Enroll or update users using Enroll or EnrollMulti.

Authentication groups are not supported by FaceStation F2 and BioStation 3.

message AuthGroup {
  uint32 ID;
  string name; 
}

GetAuthGroup

Get the list of authentication groups stored in a device.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device

Response

Parameter	Type	Description
authGroups	AuthGroup[]	The authentication groups stored in the device

AddAuthGroup

Add authentication groups to a device.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device
authGroups	AuthGroup[]	The authentication groups to be added to the device

AddAuthGroupMulti

Add authentication groups to multiple devices.

Request

Parameter	Type	Description
deviceIDs	uint32[]	The IDs of the devices
authGroups	AuthGroup[]	The authentication groups to be added to the devices

DeleteAuthGroup

Delete authentication groups from a device.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device
groupIDs	uint32[]	The IDs of the groups to be deleted from the device

DeleteAuthGroupMulti

Delete authentication groups from multiple devices.

Request

Parameter	Type	Description
deviceIDs	uint32[]	The IDs of the devices
groupIDs	uint32[]	The IDs of the groups to be deleted from the devices

DeleteAllAuthGroup

Delete all authentication groups from a device.

Request

Parameter	Type	Description
deviceID	uint32	The ID of the device

DeleteAllAuthGroupMulti

Delete all authentication groups from multiple devices.

Request

Parameter	Type	Description
deviceIDs	uint32[]	The IDs of the devices