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; 
  FaceLFDLevel LFDLevel;
  bool quickEnrollment;
  FacePreviewOption previewOption;
  bool checkDuplicate;
  FaceOperationMode operationMode;
  uint32 maxRotation;
  uint32 faceWidthMin;
  uint32 faceWidthMax;
  uint32 searchRangeX;
  uint32 searchRangeWidth;
  uint32 detectDistanceMin;
  uint32 detectDistanceMax;
  bool wideSearch;
}

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.
LFDLevel: Configuration for the LFD(Live Face Detection - fake face detection) sensitivity.

Device Type	Default
IR-Based Face Authentication Device	0
RGB-Based Visual Face Authentication Device	1

Value	Description
0	Not use
1	Strict
2	More Strict
3	Most Strict

quickEnrollment: Quick face enrollment process. Please use false if you want to enroll with a high quality of face templates.

Value	Description
true	Face enrollment process with a single step
false	Face enrollment process with 3 steps

previewOption: IR camera preview option when you authenticate with the face. Only used to FaceLite.

Value	Description
0	Preview not used
1	Preview not used at first of authentication, preview at 1/2 stage
2	Preview of all stages on authentication

checkDuplicate: Check whether the scanned face is duplicated in the device.

operationMode

FaceStation F2 V1.0.0 can be set to the following operation modes, default is Fusion mode.

Value	Mode	Description	Default
0	Fusion Mode	Visual matching + IR matching	Default
1	Visual Mode	Visual matching
2	Visual + IR	Visual matching, IR detects only face

FaceStation F2 V1.0.1 or later versions, RGB-Based Visual Face Authentication Device are used in the following sense.

Value	Mode	Description	Default
0	Fusion Mode Visual matching + IR matching	Default
1	Fast Mode Visual matching

maxRotation: RGB-Based Visual Face Authentication Device When face is recognized normally it’s front side. Still, it is possible to determine how many degrees the image has been rotated from the front when device detects a face. This enables detection failure in the case of images rotated over a certain angle. maxRotation represents the maximum allowable value in this case, and the default value is 15 degrees.

Definition	Value
BS2_MAX_ROTATION_DEFAULT	15
BS2_MAX_ROTATION_ANGLE_15	15
BS2_MAX_ROTATION_ANGLE_30	30
BS2_MAX_ROTATION_ANGLE_45	45
BS2_MAX_ROTATION_ANGLE_60	60
BS2_MAX_ROTATION_ANGLE_75	75
BS2_MAX_ROTATION_ANGLE_90	90
BS2_MAX_ROTATION_ANGLE_MAX	90

faceWidthMin: Not used. Replaced by detectDistanceMin.
faceWidthMax: Not used. Replaced by detectDistanceMax.
searchRangeX: Not used. Replaced by wideSearch.
searchRangeWidth: Not used. Replaced by wideSearch.
detectDistance (detectDistanceMin, detectDistanceMax): RGB-Based Visual Face Authentication Device This configures the minimum and maximun detection range for facial recognition. We no longer support faceWidth to pinpoint the face location using pixel units due to its complexity. Instead, we set the detection range of the subject(face). The unit is set to cm, and the value must be inputted as a multiple of 10.

Type	Min limit for min detection range	Max limit for min detection range	Min detection range(Default)	Min limit for max detection range	Max limit for max detection range	Max sensing range(No limit)	Max sensing range(Default)
FSF2	30	130	30	40	130	255	130
BS3	30	100	30	40	100	255	100
BEW3	30	100	30	40	100	255	100

detectDistanceMin: The minimum detection range for facial recognition.

detectDistanceMax: The maximum detection range for facial recognition.

wideSearch: RGB-Based Visual Face Authentication Device except FSF2 This can increase the detection range for face detection. We no longer support searchRange to set the x-coordinate and width due to its complexity. Instead, we set the face detection setting as default(FALSE), or a wide area(TRUE). The details of the settings and protocols for the detection of wide area is set within the device, which the user cannot change. If this setting is set to TRUE, the camera detects subjects within a large range, and unintentionally detect and authenticate multiple subjects at once. Therefore, the default setting is at FALSE.

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