This is an old revision of the document!


Face API

This API allows to scan/verify the face template.

FaceEx API

  • BS2_ScanFaceEx: FaceStation F2 Scans the face from a device and extracts template and image data. [+ V2.7.1]
  • BS2_ExtractTemplateFaceEx: FaceStation F2 Extracts template data by the face image. [+ V2.7.1]

BS2Face

typedef struct {
	uint8_t faceIndex;		
	uint8_t numOfTemplate;		
	uint8_t flag;		        
	uint8_t reserved;		
 
	uint16_t imageLen;		
	uint8_t reserved2[2];		
 
	uint8_t imageData[BS2_FACE_IMAGE_SIZE];
	uint8_t templateData[BS2_TEMPLATE_PER_FACE][BS2_FACE_TEMPLATE_LENGTH];
} BS2Face;

1. faceIndex
Index of face

2. numOfTemplate
Number of face templates.

3. flag
Not used.

4. reserved
Reserved space.

5. imageLen
Size of the face image.

6. reserved2
Reserve space.

4. imageData
Face image data.

5. data
Face template data.

BS2AuthGroup

typedef struct {
	BS2_AUTH_GROUP_ID		id;
	char				name[BS2_MAX_AUTH_GROUP_NAME_LEN];
	uint8_t				reserved[32];
} BS2AuthGroup;

1. id
Group ID for group matching.

2. name
Name of the matching group that will be displayed on BioStar 2

3. reserved
Reserved space.

BS2TemplateEx

typedef struct {
    uint8_t       data[552];
    uint8_t       isIR;
    uint8_t       reserved[3];
} BS2TemplateEx;

FaceStation F2

1. data
IR or visual image template data

2. isIR
True when it comes to an IR image, false when it comes to a visual image

3. reserved
Reserved

BS2FaceEx

typedef struct {
    uint8_t       faceIndex;
    uint8_t       numOfTemplate;
    uint8_t       flag;
    uint8_t       reserved;
 
    uint32_t      imageLen;
    union {
        struct {
            uint16_t irImageLen;
            uint8_t  unused[6];			///< 6 bytes (packing)
            uint8_t  imageData[BS2_MAX_WARPED_IMAGE_LENGTH];            ///< 40 * 1024 bytes
            uint8_t  irImageData[BS2_MAX_WARPED_IR_IMAGE_LENGTH];       ///< 30 * 1024 bytes
            BS2TemplateEx templateEx[BS2_MAX_TEMPLATES_PER_FACE_EX];    ///< 20 * 556 bytes
        };
 
        uint8_t   *rawImageData;
    };
} BS2FaceEx;

FaceStation F2

1. faceIndex
Index of face

2. numOfTemplate
The number of template including Visual, IR

3. flag
Flag whether the image is a WARPed image.
WARP is a kind of generalization that extracts the face among the physical image which contains different body parts.
When flag is set to 1, the device refers to 5 pieces of information defined by the struct in the union.
When flag is set to 0, the device refers to rawImageData in the union.
If the user wants to register a face with a random image that is not WARPed,
please set the flag as BS2_FACE_EX_FLAG_NONE(0), set as image data in the address space of rawImageData, and set the size of image data as imageLen.
When this happens, the device will automatically go through the WARP process with rawImageData and fill in the information in the struct.
Please note that rawImageData and struct are tied in an union.

Value Description
BS2_FACE_EX_FLAG_NONE 0x00
BS2_FACE_EX_FLAG_WARPED 0x01
BS2_FACE_EX_FLAG_ALL 0xFF

4. reserved
Reserved

5. imageLen
The size of image data

6. irImageLen
The size of IR image data

7. unused
Unused space. (for packing)

8. imageData
WARPed facial image data. This is made by rawImageData automatically.

9. irImageData
IR image data. IR image might not exist in the WARP process.
It is generated automatically when trying authentication.
10. templateEx
Template data of Visual or IR image

11. rawImageData
Non-WARPed image data