Version 0.21.0

CMakeLists.txt

@@ -55,6 +55,7 @@ message(STATUS "Build type: " ${CMAKE_BUILD_TYPE})
 option(RSID_DEBUG_CONSOLE "Log everything to console" ON)
 option(RSID_DEBUG_FILE "Log everything to rsid_debug.log file" OFF)
 option(RSID_DEBUG_SERIAL "Log all serial communication" OFF)
+option(RSID_DEBUG_PACKETS "Log packet sent/received over the serial line" ON)
 option(RSID_DEBUG_VALUES "Replace default common values with debug ones" OFF)
 option(RSID_PREVIEW "Enable preview" OFF)
 option(RSID_SAMPLES "Build samples" OFF)

Readme.md

@@ -285,21 +285,32 @@ The various options and default values are described below:
 ```cpp
 struct RSID_API DeviceConfig
 {
-    // Camera rotation. Use Rotation_180_Deg if the camera is upside down.
+    /**
+     * @enum CameraRotation
+     * @brief Camera rotation.
+     */
     enum class CameraRotation
     {
         Rotation_0_Deg = 0, // default
-        Rotation_180_Deg = 1
+        Rotation_180_Deg = 1,
+        Rotation_90_deg = 2,
+        Rotation_270_deg = 3
     };
 
-    //SecurityLevel for authentication
+    /**
+     * @enum SecurityLevel
+     * @brief SecurityLevel to allow
+     */
     enum class SecurityLevel
     {
         High = 0,   // high security, no mask support, all AS algo(s) will be activated
         Medium = 1, // default mode to support masks, only main AS algo will be activated.
     };
-
-    // Select which algorithm to run during authentication    
+
+    /**
+     * @enum AlgoFlow
+     * @brief Algorithms which will be used during authentication
+     */
     enum class AlgoFlow
     {
         All = 0,               // default
@@ -308,43 +319,35 @@ struct RSID_API DeviceConfig
         RecognitionOnly = 3    // recognition only
     };
 
-    // Can be used to authenticate single/multiple (up to 5) faces.
-    // If All is used, the OnResult callback will be called for each detected face.
+    /**
+     * @enum FaceSelectionPolicy
+     * @brief To run authentication on all (up to 5) detected faces vs single (closest) face
+     */
     enum class FaceSelectionPolicy
     {
         Single = 0, // default, run authentication on closest face
         All = 1     // run authentication on all (up to 5) detected faces
     };
 
-    // Preview mode. 
-    enum class PreviewMode
-    {
-        MJPEG_1080P = 0, // 1080p mjpeg
-        MJPEG_720P = 1,  // 720p mjpeg
-        RAW10_1080P = 2  // 1080p raw10 for debugging purposes. 
-    };
-
-    // Can be used to receive from the device frames that where used during the authentication
-    // If CroppedFace is set then the OnSnapshotImageReady() can be used to received cropped images of the detected faces.    
     enum class DumpMode
     {
         None = 0,
-        CroppedFace = 1, 
+        CroppedFace = 1,
         FullFrame = 2,
     };
-    
+
     CameraRotation camera_rotation = CameraRotation::Rotation_0_Deg;
     SecurityLevel security_level = SecurityLevel::Medium;
     AlgoFlow algo_flow = AlgoFlow::All;
     FaceSelectionPolicy face_selection_policy = FaceSelectionPolicy::Single;
-    PreviewMode preview_mode = PreviewMode::MJPEG_1080P;
     DumpMode dump_mode = DumpMode::None;
-
+};
 ```
 
 Notes: 
   * If ```SetDeviceConfig()``` never called, the device will use the default values described above.
   * ```SetDeviceConfig()``` can be called once. The settings will take effect for all future authentication sessions (until the device is restarted).
+  * ```CameraRotation``` enable the algorithm to work with a rotated device. For preview rotation to match, you'll need to define previewConfig.portraitMode accordingly (see Preview section).
 
 The following example configures the device to only detect spoofs (instead of the default full authentication):
 ```cpp
@@ -398,14 +401,44 @@ bool success = deviceController.Reboot();
 #### Preview API
 Currently 704x1280 or 1056x1920 RGB formats is available.
 
+##### Preview Configuration
+```cpp
+/**
+ * Preview modes
+ */
+enum class PreviewMode
+{
+    MJPEG_1080P = 0, // default
+    MJPEG_720P = 1,
+    RAW10_1080P = 2,
+};
+
+/**
+ * Preview configuration
+ */
+struct RSID_API PreviewConfig
+{
+    int cameraNumber = -1; // attempt to auto detect by default
+    PreviewMode previewMode = PreviewMode::MJPEG_1080P; // RAW10 requires custom fw support
+    bool portraitMode = true; 
+};
+```
+Notes:
+* The rotation used by algorithm is based only on DeviceConfig.camera_rotation attribute.
+* Indepedently, you can choose each preview mode (except raw) to be portrait or non-portrait. 
+* Keep in mind that if you want preview to match algo:  
+CameraRotation::Rotation_0_Deg and CameraRotation::Rotation_180_Deg is for portraitMode == true.(default)  
+CameraRotation::Rotation_90_Deg and CameraRotation::Rotation_270_Deg is for portraitMode == false.
+
 ##### Sensor Timestamps
-Access to the sensor timestamps (in milliseconds) of each frame is available **on Windows only**.  
-To enable it please turn on the Metadata option in when using the SDK installer.
+Access to the sensor timestamps (in milliseconds).  
+To enable it on Windows please turn on the Metadata option in when using the SDK installer.
 The installer create specific dedicated registry entry to be present for each unique RealSenseID device.
+For Linux, Metadata is supported on kernels 4.16 + only.
 
 The timestamps can be acquired in OnPreviewImageReady under *image.metadata.timestamp* . Other metadata isn't valid.
 
-more information about metadata on windows can be found in [microsoft uvc documetnation](https://docs.microsoft.com/en-us/windows-hardware/drivers/stream/uvc-extensions-1-5#2211-still-image-capture--method-2)
+more information about metadata on Windows can be found in [microsoft uvc documetnation](https://docs.microsoft.com/en-us/windows-hardware/drivers/stream/uvc-extensions-1-5#2211-still-image-capture--method-2)
 
 ##### StartPreview
 Starts preview. Callback function that is provided as parameter will be invoked for a newly arrived image and can be rendered by your application.
@@ -415,7 +448,12 @@ class PreviewRender : public RealSenseID::PreviewImageReadyCallback
 public:
 	void OnPreviewImageReady(const Image image)
 	{
-		// render image
+		// render preview image
+	}
+
+    void OnSnapshotImageReady(const Image image) // Not mandatory. To enable it, see Device Configuration API.
+	{
+		// render or dump cropped face snapshot image
 	}
 };
 

include/RealSenseID/DeviceConfig.h

@@ -16,7 +16,9 @@ struct RSID_API DeviceConfig
     enum class CameraRotation
     {
         Rotation_0_Deg = 0, // default
-        Rotation_180_Deg = 1
+        Rotation_180_Deg = 1,
+        Rotation_90_deg = 2,
+        Rotation_270_deg =3
     };
 
     /**
@@ -43,25 +45,14 @@ struct RSID_API DeviceConfig
 
     /**
      * @enum FaceSelectionPolicy
-     * @brief To run authentication on all (up to 5) detected faces vs single (closest) face
+     * @brief Controls whether to run authentication on all (up to 5) detected faces vs single (closest) face
      */
     enum class FaceSelectionPolicy
     {
         Single = 0, // default, run authentication on closest face
         All = 1     // run authentication on all (up to 5) detected faces
     };
 
-    /**
-     * @enum PreviewMode
-     * @brief Defines preview mode
-     */
-    enum class PreviewMode
-    {
-        MJPEG_1080P = 0, // 1080p mjpeg
-        MJPEG_720P = 1,  // 720p mjpeg
-        RAW10_1080P = 2  // 1080p raw10
-    };
-
     enum class DumpMode
     {
         None = 0,
@@ -73,13 +64,11 @@ struct RSID_API DeviceConfig
     SecurityLevel security_level = SecurityLevel::Medium;
     AlgoFlow algo_flow = AlgoFlow::All;
     FaceSelectionPolicy face_selection_policy = FaceSelectionPolicy::Single;
-    PreviewMode preview_mode = PreviewMode::MJPEG_1080P;
     DumpMode dump_mode = DumpMode::None;
 };
 
 RSID_API const char* Description(DeviceConfig::CameraRotation rotation);
 RSID_API const char* Description(DeviceConfig::SecurityLevel level);
-RSID_API const char* Description(DeviceConfig::PreviewMode previewMode);
 RSID_API const char* Description(DeviceConfig::AlgoFlow algoMode);
 RSID_API const char* Description(DeviceConfig::FaceSelectionPolicy policy);
 RSID_API const char* Description(DeviceConfig::DumpMode dump_mode);
@@ -105,13 +94,6 @@ inline OStream& operator<<(OStream& os, const DeviceConfig::SecurityLevel& level
     return os;
 }
 
-template <typename OStream>
-inline OStream& operator<<(OStream& os, const DeviceConfig::PreviewMode& previewMode)
-{
-    os << Description(previewMode);
-    return os;
-}
-
 template <typename OStream>
 inline OStream& operator<<(OStream& os, const DeviceConfig::FaceSelectionPolicy& policy)
 {

include/RealSenseID/FaceAuthenticator.h

@@ -109,6 +109,16 @@ class RSID_API FaceAuthenticator
      */
     Status Enroll(EnrollmentCallback& callback, const char* user_id);
 
+    /**
+     * Enroll a user using an image of his face.
+     * @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 950MB(i.e. Width x Height x 3 should not exceed it)
+     * @param[in] width image width.
+     * @param[in] width image height.
+     * @return EnrollStatus (EnrollStatus::Success on success).
+     */
+    EnrollStatus EnrollImage(const char* user_id, unsigned char* buffer, unsigned int width, unsigned int height);
+
     /**
      * Attempt to authenticate.
      * Starts the authentication procedure, which starts the camera, captures frames and tries to match
@@ -252,15 +262,15 @@ class RSID_API FaceAuthenticator
      * @param[out] Number of users exported from the device.
      * @return Status (Status::Ok on success).
      */
-    Status GetUsersFaceprints(Faceprints* user_features, unsigned int&num_of_users);
+    Status GetUsersFaceprints(Faceprints* user_features, unsigned int& num_of_users);
 
     /**
      * Insert each user entry from the array into the device's database.
      * @param[in] Array of user IDs and feature descriptors.
      * @param[in] Number of users in the array.
      * @return Status (Status::Ok on success).
      */
-    Status SetUsersFaceprints (UserFaceprints * user_features, unsigned int num_of_users);
+    Status SetUsersFaceprints(UserFaceprints* user_features, unsigned int num_of_users);
 
 private:
     FaceAuthenticatorImpl* _impl = nullptr;

include/RealSenseID/Faceprints.h

@@ -13,7 +13,7 @@ Copyright(c) 2011-2020 Intel Corporation. All Rights Reserved.
 #include <cstddef>
 #include <cstdint> 
 #include <string>
-#include "../../src/Common/CommonDefines.h"
+#include "FaceprintsDefines.h"
 
 namespace RealSenseID 
 {

src/Common/CommonDefines.h → include/RealSenseID/FaceprintsDefines.h

@@ -34,7 +34,8 @@ typedef enum FaOperationFlags
     OpFlagAuthWithoutMask = 1,
     OpFlagAuthWithMask = 2,
     OpFlagEnrollWithoutMask = 3,
-    OpFlagError2 = 4,
+    OpFlagBenchmarksMode = 4,
+    OpFlagError2 = 5,
     NumOpFlags
 } FaOperationFlagsEnum;
 

include/RealSenseID/FwUpdater.h

@@ -52,6 +52,21 @@ class RSID_API FwUpdater
     FwUpdater() = default;
     ~FwUpdater() = default;
 
+    // TODO: Document
+    struct UpdatePolicyInfo
+    {
+        enum class UpdatePolicy
+        {
+            CONTINOUS,
+            OPFW_FIRST,
+            REQUIRE_INTERMEDIATE_FW,
+            NOT_ALLOWED
+        };
+        UpdatePolicy policy;
+        std::string intermediate;
+    };
+
+
     /**
      * Extracts the firmware and recognition version from the firmware package, as well as all the modules names.
      *
@@ -66,10 +81,10 @@ class RSID_API FwUpdater
     /**
      * Check encryption used in the binary file and answer whether a device with given serial number can decrypt it.
      *
-	 * @param[in] binPath Path to the firmware binary file.
+     * @param[in] binPath Path to the firmware binary file.
      * @param[in] deviceSerialNumber The device serial number as it was extracted prior to calling this function.
-	 */
-    bool IsEncryptionSupported(const char* binPath, const std::string& deviceSerialNumber);
+     */
+    bool IsEncryptionSupported(const char* binPath, const std::string& deviceSerialNumber) const;
 
     /**
      * Performs a firmware update for the modules listed in moduleNames
@@ -81,5 +96,8 @@ class RSID_API FwUpdater
      * @return OK if update succeeded matching error status if it failed.
      */
     Status UpdateModules(EventHandler* handler, Settings settings, const char* binPath, const std::vector<std::string>& moduleNames) const;
+
+    // TODO: document
+    UpdatePolicyInfo DecideUpdatePolicy(const Settings& settings, const char* binPath) const;
 };
 } // namespace RealSenseID

include/RealSenseID/Preview.h

@@ -16,7 +16,7 @@ enum class PreviewMode
 {
     MJPEG_1080P = 0, // default
     MJPEG_720P = 1,
-    RAW10_1080P = 2 // dump all frames
+    RAW10_1080P = 2,
 };
 
 /**
@@ -26,6 +26,7 @@ struct RSID_API PreviewConfig
 {
     int cameraNumber = -1; // attempt to auto detect by default
     PreviewMode previewMode = PreviewMode::MJPEG_1080P; // RAW10 requires custom fw support
+    bool portraitMode = true;  // change Preview to get portrait or landscape images. Algo process is defined seperatly in DeviceConfig::CameraRotation
 };
 
 /**

include/RealSenseID/Version.h

@@ -8,13 +8,13 @@
 #include <string>
 
 #define RSID_VER_MAJOR 0
-#define RSID_VER_MINOR 19
+#define RSID_VER_MINOR 21
 #define RSID_VER_PATCH 0
 
 #define RSID_VERSION (RSID_VER_MAJOR * 10000 + RSID_VER_MINOR * 100 + RSID_VER_PATCH)
 
-#define RSID_FW_VER_MAJOR 3
-#define RSID_FW_VER_MINOR 1
+#define RSID_FW_VER_MAJOR 4
+#define RSID_FW_VER_MINOR 0
 
 namespace RealSenseID
 {

release_notes.txt

@@ -1,3 +1,27 @@
+Realsense ID version 0.21.0
+-----------------------------------
+* Enroll with RGB image, 
+* Added option in the app to batch enroll using a json file.
+* Example JSON for enrol:
+    [       
+        {
+            "userId": "user1",
+            "filename": "user1.png"
+
+        },      
+        {
+            "userId": "user2",            
+            "filename": "C:\\devel\\user2.jpg"
+        }     
+    ]
+
+* Full device rotation support - device can now be used at 0/90/180/270 degrees.    
+* Improved multiple faces processing.
+* Improved significantly Anti-spoofing accuracy.
+* Increased max serial packets to 8k for improved serial performace.
+* Known issues: Spoof algo flow is not supported in 90/270 degrees.
+
+
 Realsense ID version 0.19.0
 -----------------------------------
 * New dump and preview menu in rsid-viewer.