V0.42.0 (#173)

* version 0.42.0

* release notes

.clang-format

@@ -25,7 +25,7 @@ BinPackParameters: true
 BreakAfterJavaFieldAnnotations: true
 BreakConstructorInitializers: AfterColon
 BreakInheritanceList: AfterColon
-ColumnLimit: 120
+ColumnLimit: 140
 CompactNamespaces: true
 DerivePointerAlignment: false
 DisableFormat: false

include/RealSenseID/AuthFaceprintsExtractionCallback.h

@@ -23,7 +23,7 @@ class AuthFaceprintsExtractionCallback
      * Called to inform the client on the result of faceprints extraction, and pass the faceprints in case of success
      *
      * @param[in] status Final authentication status.
-     * @param[in] faceprints Pointer to the requested faceprints which were just extracted from the device.     
+     * @param[in] faceprints Pointer to the requested faceprints which were just extracted from the device.
      */
     virtual void OnResult(const AuthenticateStatus status, const ExtractedFaceprints* faceprints) = 0;
 

include/RealSenseID/AuthenticateStatus.h

@@ -24,6 +24,7 @@ enum class RSID_API AuthenticateStatus
     FaceTiltIsTooDown,
     FaceTiltIsTooRight,
     FaceTiltIsTooLeft,
+    FaceIsNotFrontal,
     CameraStarted,
     CameraStopped,
     MaskDetectedInHighSecurity,
@@ -35,7 +36,7 @@ enum class RSID_API AuthenticateStatus
     InvalidFeatures,
     AmbiguiousFace,
     /// Accessories
-    Sunglasses = 50, 
+    Sunglasses = 50,
     /// serial statuses
     Ok = 100,
     Error,
@@ -51,7 +52,7 @@ enum class RSID_API AuthenticateStatus
     Spoof_LR,
     Spoof_Disparity,
     Spoof_Surface,
-    Spoof_Plane_Disparity,  
+    Spoof_Plane_Disparity,
     Spoof_2D_Right,
     /* Note: Should not exceed 127 - to be a legal ascii*/
 };

include/RealSenseID/AuthenticationCallback.h

@@ -5,7 +5,7 @@
 
 #include "AuthenticateStatus.h"
 #include "FaceRect.h"
-#include<vector>
+#include <vector>
 
 namespace RealSenseID
 {
@@ -42,7 +42,7 @@ class RSID_API AuthenticationCallback
      */
     virtual void OnFaceDetected(const std::vector<FaceRect>& /* faces */, const unsigned int /* ts */)
     {
-        //default empty impl for backward compatibilty
+        // default empty impl for backward compatibilty
     }
 };
 } // namespace RealSenseID

include/RealSenseID/DeviceConfig.h

@@ -18,7 +18,7 @@ struct RSID_API DeviceConfig
         Rotation_0_Deg = 0, // default
         Rotation_180_Deg = 1,
         Rotation_90_Deg = 2,
-        Rotation_270_Deg =3
+        Rotation_270_Deg = 3
     };
 
     /**
@@ -31,7 +31,7 @@ struct RSID_API DeviceConfig
         Medium = 1, // medium security level
         Low = 2,    // low security level
     };
-    
+
     /**
      * @enum AlgoFlow
      * @brief Algorithms which will be used during authentication
@@ -44,15 +44,15 @@ struct RSID_API DeviceConfig
         RecognitionOnly = 3    // recognition only
     };
 
-    
+
     enum class DumpMode
     {
         None = 0,        // default
         CroppedFace = 1, // sends snapshot of the detected face (as jpg)
         FullFrame = 2,   // sends left+right raw frames with metadata
     };
 
-    
+
     /**
      * @brief Defines three confidence levels used by the Matcher during authentication.
      *
@@ -62,8 +62,8 @@ struct RSID_API DeviceConfig
      */
     enum class MatcherConfidenceLevel
     {
-        High = 0,   
-        Medium = 1, 
+        High = 0,
+        Medium = 1,
         Low = 2 // default
     };
 
@@ -73,16 +73,27 @@ struct RSID_API DeviceConfig
     DumpMode dump_mode = DumpMode::None;
     MatcherConfidenceLevel matcher_confidence_level = MatcherConfidenceLevel::Low;
 
-    
-     /**
+
+    /**
      * @brief Specifies the maximum number of consecutive spoofing attempts allowed before the device rejects further
      * authentication requests.
      *
      * Setting this value to 0 disables the check, which is the default behavior. If the number of consecutive spoofing
      * attempts reaches max_spoofs, the device will reject any subsequent authentication requests. To reset this
      * behavior and allow further authentication attempts, the device must be unlocked using the Unlock() API call.
      */
-    unsigned char max_spoofs = 0; 
+    unsigned char max_spoofs = 0;
+
+
+    /**
+     * @brief Controls whether GPIO toggling is enabled(1) or disabled(0, default) after successful authentication.
+     *
+     * Set this value to 1 to enable toggling of GPIO pin #1 after each successful authentication.
+     * Set this value to 0 to disable GPIO toggling (default).
+     *
+     * @note Only GPIO pin #1 can be toggled. Other values are not supported.
+     */
+    int gpio_auth_toggling = 0;
 };
 
 RSID_API const char* Description(DeviceConfig::CameraRotation rotation);

include/RealSenseID/DeviceController.h

@@ -83,12 +83,12 @@ class RSID_API DeviceController
      * seconds to complete.
      */
     Status FetchLog(std::string& log);
-    
+
     /**
      * Get color gains packet from device and fill the red, blue values
      * @return SerialStatus::Success on success.
      */
-    Status GetColorGains(int &red, int  &blue);
+    Status GetColorGains(int& red, int& blue);
 
     /**
      * Send color gains packet to device. Valid range: 0-511

include/RealSenseID/DiscoverDevices.h

@@ -15,7 +15,6 @@ struct RSID_API DeviceInfo
     static constexpr std::size_t MaxBufferSize = 256;
 
     char serialPort[MaxBufferSize];
-
 };
 
 std::vector<DeviceInfo> RSID_API DiscoverDevices();

include/RealSenseID/EnrollFaceprintsExtractionCallback.h

@@ -9,7 +9,7 @@
 #include <vector>
 #include "Faceprints.h"
 
-//    
+//
 namespace RealSenseID
 {
 /**

include/RealSenseID/EnrollStatus.h

@@ -27,10 +27,10 @@ enum class RSID_API EnrollStatus
     FaceIsNotFrontal,
     CameraStarted,
     CameraStopped,
-    MultipleFacesDetected,    
+    MultipleFacesDetected,
     Failure,
     DeviceError,
-    EnrollWithMaskIsForbidden,  // for mask-detector : we'll forbid enroll if used wears mask.
+    EnrollWithMaskIsForbidden, // for mask-detector : we'll forbid enroll if used wears mask.
     Spoof,
     InvalidFeatures,
     AmbiguiousFace,

include/RealSenseID/EnrollmentCallback.h

@@ -40,14 +40,14 @@ class RSID_API EnrollmentCallback
      */
     virtual void OnHint(const EnrollStatus hint) = 0;
 
-     /**
+    /**
      * Called to inform the client about detected faces during the authentication operation.
      *
      * @param[in] face Detected faces. First item is the selected one for the authentication operation.
      */
-    virtual void OnFaceDetected(const std::vector<FaceRect> &/*faces*/, const unsigned int /*ts*/)
+    virtual void OnFaceDetected(const std::vector<FaceRect>& /*faces*/, const unsigned int /*ts*/)
     {
-        //default empty impl for backward compatibilty
+        // default empty impl for backward compatibilty
     }
 };
 } // namespace RealSenseID

include/RealSenseID/FaceAuthenticator.h

@@ -99,27 +99,35 @@ class RSID_API FaceAuthenticator
      * Enroll a user using an image of his face.
      * Note: The face should occupy at least 75% of image area
      * @param[in] user_id Null terminated C string of ascii chars. Max user id size is MAX_USERID_LENGTH bytes
-     * @param[in] buffer bgr24 image buffer of the enrolled user face. 
-     * should not exceed it)
+     * @param[in] buffer bgr24 image buffer of the enrolled user face.
      * @param[in] width image width.
      * @param[in] height image height.
      * @return EnrollStatus (EnrollStatus::Success on success).
      */
     EnrollStatus EnrollImage(const char* user_id, const unsigned char* buffer, unsigned int width, unsigned int height);
 
     /**
-     * Extract features from RGB image. 
+     * Enroll a user using a normalized cropped image of his face.
+     * Note: The image should be provided only by our face detection and image normalization code (see reference in our sample applications)
+     * Important: This API clears the DB.
+     * @param[in] user_id Null terminated C string of ascii chars. Max user id size is MAX_USERID_LENGTH bytes
+     * @param[in] buffer bgr24 144x144 image buffer of the enrolled user
+     * @return EnrollStatus (EnrollStatus::Success on success).
+     */
+    EnrollStatus EnrollCroppedFaceImage(const char* user_id, const unsigned char* buffer);
+
+    /**
+     * Extract features from RGB image.
      * Note: The face should occupy at least 75% of image area
      * @param[in] user_id Null terminated C string of ascii chars. Max user id size is MAX_USERID_LENGTH bytes
-     * @param[in] buffer bgr24 image buffer of the enrolled user face. Max buffer size is 900KB(i.e. Width x Height x 3
-     * should not exceed it)
+     * @param[in] buffer bgr24 image buffer of the enrolled user face. Max buffer size is 900KB(i.e. Width x Height x 3)
      * @param[in] width image width.
      * @param[in] height image height.
      * @param[out] the extracted faceprints from the image.
      * @return EnrollStatus (EnrollStatus::Success on success).
      */
-    EnrollStatus EnrollImageFeatureExtraction(const char* user_id, const unsigned char* buffer, unsigned int width,
-                                              unsigned int height, ExtractedFaceprints* pExtractedFaceprints);
+    EnrollStatus EnrollImageFeatureExtraction(const char* user_id, const unsigned char* buffer, unsigned int width, unsigned int height,
+                                              ExtractedFaceprints* pExtractedFaceprints);
 
     /**
      * Attempt to authenticate.
@@ -199,12 +207,20 @@ class RSID_API FaceAuthenticator
     Status QueryNumberOfUsers(unsigned int& number_of_users);
 
     /**
-     * Prepare device to standby - for now it's saving database of users to flash.
+     * Send device to standby for lower power consumption - will auto wake up upon any action.
      *
      * @return Status (Status::Ok on success).
      */
     Status Standby();
 
+    /**
+     * Send device to hibernate. Lowest power consumption. Will wake up only upon GPIO 10 signal or power reset.
+     *
+     * @return Status (Status::Ok on success).
+     */
+    Status Hibernate();
+
+
     /**
      * Unlock the device that was locked due to too many spoof attempts.
      *
@@ -328,7 +344,7 @@ class RSID_API FaceAuthenticator
      * re-validation. In such cases, the host must perform a license validation session with the cloud-based license
      * server and the device.
      *
-     * Note: License validation operations may take a few seconds to complete, depending on network conditions.     
+     * Note: License validation operations may take a few seconds to complete, depending on network conditions.
      *
      * Note: Perpetual licenses never require re-validation of the license and the operation will not be triggered.
      *
@@ -341,7 +357,7 @@ class RSID_API FaceAuthenticator
     void EnableLicenseCheckHandler(OnStartLicenseSession on_start_license_session, OnEndLicenseSession on_end_license_session);
 
     /**
-     * Disable automatic automatic handling of license check requests from the device.      
+     * Disable automatic automatic handling of license check requests from the device.
      */
     void DisableLicenseCheckHandler();
 

include/RealSenseID/FaceRect.h

@@ -16,7 +16,7 @@ namespace RealSenseID
  * Upper left corner, width and height
  */
 struct RSID_API FaceRect
-{    
+{
     uint32_t x = 0;
     uint32_t y = 0;
     uint32_t w = 0;

include/RealSenseID/Faceprints.h

@@ -7,23 +7,23 @@ Copyright(c) 2011-2020 Intel Corporation. All Rights Reserved.
 *******************************************************************************/
 #ifndef __FACEPRINTSS__H___
 #define __FACEPRINTSS__H___
-// #pragma once  
+// #pragma once
 // pragma once ends with redefinition errors on jenkins.
 
 #include <cstddef>
-#include <cstdint> 
+#include <cstdint>
 #include <string>
 #include "FaceprintsDefines.h"
 
-namespace RealSenseID 
+namespace RealSenseID
 {
 
 static constexpr size_t RSID_MAX_USER_ID_LENGTH_IN_DB = 31;
 
 // extracted faceprints element
 // a reduced structure that is used to represent the extracted faceprints been transferred from the device to the host
-// through the packet layer. 
-class ExtractedFaceprints 
+// through the packet layer.
+class ExtractedFaceprints
 {
 public:
     RealSenseID::ExtractedFaceprintsElement data;
@@ -32,27 +32,27 @@ class ExtractedFaceprints
 // db layer faceprints element.
 // a structure that is used in the DB layer, to save user DBFaceprintsElement plus additional metadata to the DB.
 // the struct includes several vectors and metadata to support all our internal matching mechanism (e.g. adaptive-learning etc..).
-class Faceprints  
+class Faceprints
 {
 public:
-    RealSenseID::DBFaceprintsElement data; 
+    RealSenseID::DBFaceprintsElement data;
 };
 
 // match element used during authentication flow, where we match between faceprints object received from the device
-// to user objects read from the DB. 
+// to user objects read from the DB.
 class MatchElement
 {
 public:
     RealSenseID::ExtractedFaceprintsElement data;
 };
 
 // faceprints plus username element.
-typedef struct UserFaceprints  
+typedef struct UserFaceprints
 {
-    char        user_id[RSID_MAX_USER_ID_LENGTH_IN_DB];
-    Faceprints  faceprints;
+    char user_id[RSID_MAX_USER_ID_LENGTH_IN_DB];
+    Faceprints faceprints;
 } UserFaceprints_t;
 
-} // namespace RealSenseID 
+} // namespace RealSenseID
 
 #endif // __FACEPRINTSS__H___