Differences

This shows you the differences between two versions of the page.

--- en:face_api [2017/03/07 15:35]
127.0.0.1 external edit
+++ en:face_api [2025/02/18 11:36] (current)
alex Update rawImageData description
@@ Line 2: / Line 2: @@
 This API allows to scan/verify the face template.
-  * [[BS2_ScanFace]]: Scans the face from a device and extracts template and image data.
+  * [[BS2_ScanFace]]: ''IR Face based'' Scans the face from a device and extracts template and image data.
   * [[BS2_GetAuthGroup]]: Retrieves selected authentication groups.
   * [[BS2_GetAllAuthGroup]]: Retrieves all authentication groups.
@@ Line 8: / Line 8: @@
   * [[BS2_RemoveAuthGroup]]: Removes selected authentication groups.
   * [[BS2_RemoveAllAuthGroup]]: Remove all authentication groups.
+====== FaceEx API ======
+  * [[BS2_ScanFaceEx]]: ''Visual Face based'' Scans the face from a device and extracts template and image data. [+ 2.7.1]
+  * [[BS2_ExtraceTemplateFaceEx]]: ''Visual Face based'' Extracts template data by the face image. [+ 2.7.1]
+  * [[BS2_GetNormalizedImageFaceEx]]: ''Visual Face based'' Create a WARP image with an un-warped (unprocessed) face image. [+ 2.8]
 ===== Structure =====
 ==== BS2Face ====
@@ Line 29: / Line 35: @@
 Number of face templates. \\ \\
 . //flag// \\
-Not used. \\ \\
+This values is used inside the device based on FaceStation2 V1.4.0 and FaceLite V1.2.0. \\
+The flag value received from the device can be used, but if it is not known, it can be set to 0. \\ \\
 . //reserved// \\
 Reserved space. \\ \\
@@ Line 57: / Line 64: @@
 Reserved space. \\ \\
+==== BS2TemplateEx ====
+<code cpp>
+typedef struct {
+    uint8_t       data[552];
+    uint8_t       isIR;
+    uint8_t       reserved[3];
+} BS2TemplateEx;
+</code>
+''Visual Face based'' \\ \\
+. //data// \\
+IR or visual image template data \\ \\
+. //isIR// \\
+True when it comes to an IR image, false when it comes to a visual image \\ \\
+. //reserved// \\
+Reserved \\ \\
+==== BS2FaceEx ====
+<code cpp>
+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;
+        BS2TemplateEx *onlyTemplateEx;
+    };
+} BS2FaceEx;
+</code>
+''Visual Face based'' \\ \\
+. //faceIndex// \\
+Index of face \\ \\
+. //numOfTemplate// \\
+The number of template including Visual, IR \\ \\
+. //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. \\
+[+ 2.9.6] An option BS2_FACE_EX_FLAG_TEMPLATE_ONLY(0x20) has been added to allow transmitting only the template excluding the facial image when sending facial data. \\
+This is particularly useful in environments where privacy protection is emphasized. \\
+When using this option, the onlyTemplateEx should be allocated with template data for each numOfTemplate. \\
+Additionally, unableToSaveImageOfVisualFace in [[configuration_api#BS2FaceConfig]] must be set to 1 (true). \\
+<WRAP group 50%>
+^Value  ^Description  ^
+|BS2_FACE_EX_FLAG_NONE  |0x00  |
+|BS2_FACE_EX_FLAG_WARPED  |0x01  |
+|BS2_FACE_EX_FLAG_TEMPLATE_ONLY  |0x20  |
+|BS2_FACE_EX_FLAG_ALL  |0xFF  |
+</WRAP>
+. //reserved// \\
+Reserved \\ \\
+. //imageLen// \\
+The size of image data \\ \\
+. //irImageLen// \\
+The size of IR image data \\ \\
+. //unused// \\
+Unused space. (for packing) \\ \\
+. //imageData// \\
+WARPed facial image data. This is made by rawImageData automatically. \\
+<WRAP group 70%>
+^Device type  ^Version  ^FW version  ^Image size  ^Image type  ^''rawImageData''  ^
+|FaceStation F2  |V1  |less than 2.0.0  |250 * 250  |JPG  |JPG  |
+|FaceStation F2  |V2  |2.0.0 or later  |112 * 112  |PNG  |JPG, PNG  |
+|BioStation 3  |V1  |All version  |112 * 112  |PNG  |JPG, PNG  |
+</WRAP>
+. //irImageData// \\
+IR image data. IR image might not exist in the WARP process. \\
+It is generated automatically when trying authentication. \\ \\
+. //templateEx// \\
+Template data of Visual or IR image \\ \\
+. //rawImageData// \\
+Non-WARPed image data. See ''imageData'' \\
+The maximum resolution for an unwarped image is 4000 pixels in both width and height. However, a resolution of 1920 pixels or less is recommended. \\
+A clear and high-quality facial image is recommended. If the original image is blurred or distorted, Warped Image generation may fail.\\
+It is recommended to use an image where the total image width is at least 190% larger than the face width. \\ \\
+. //onlyTemplateEx// \\
+[+ 2.9.6] This represents contiguous memory information of BS2TemplateEx data, which is template information, and must be allocated as many as numOfTemplate. \\
+This is only used when the flag is BS2_FACE_EX_FLAG_TEMPLATE_ONLY. \\ \\