{"id":20850638,"url":"https://github.com/intelrealsense/realsenseid","last_synced_at":"2025-05-16T14:07:59.600Z","repository":{"id":50639120,"uuid":"293796123","full_name":"IntelRealSense/RealSenseID","owner":"IntelRealSense","description":"Intel® RealSense™ ID SDK","archived":false,"fork":false,"pushed_at":"2025-03-17T18:36:58.000Z","size":13791,"stargazers_count":107,"open_issues_count":34,"forks_count":60,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-05-15T21:18:28.461Z","etag":null,"topics":["c","cpp","csharp","face-recognition"],"latest_commit_sha":null,"homepage":"https://intelrealsense.com/facial-authentication/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IntelRealSense.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-09-08T11:57:33.000Z","updated_at":"2025-04-21T16:48:53.000Z","dependencies_parsed_at":"2023-02-10T22:45:53.912Z","dependency_job_id":"918845d9-440f-4315-b914-94fd001776ac","html_url":"https://github.com/IntelRealSense/RealSenseID","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntelRealSense%2FRealSenseID","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntelRealSense%2FRealSenseID/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntelRealSense%2FRealSenseID/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IntelRealSense%2FRealSenseID/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IntelRealSense","download_url":"https://codeload.github.com/IntelRealSense/RealSenseID/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254422789,"owners_count":22068682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","cpp","csharp","face-recognition"],"created_at":"2024-11-18T03:10:47.497Z","updated_at":"2025-05-16T14:07:59.545Z","avatar_url":"https://github.com/IntelRealSense.png","language":"C++","readme":"# Intel® RealSense™ ID Solution for Facial Authentication\n\n## Table of Contents\n1. [Overview](#overview)\n2. [Platforms](#platforms)\n3. [Building](#building)\n4. [Sample Code](#sample-code)\n5. [Secure Communication](#secure-communication)\n6. [Server and Device APIs](#server-and-device-apis)\n7. [Project Structure](#project-structure)\n8. [Setting Product Key](#product-keys)\n9. [License](#license)\n9. [Intel RealSense ID F450 and F455 Architecure Diagram](#intel-realsense-id-f450-and-f455-architecure-diagram)\n\n## Overview\nIntel RealSense ID is your trusted facial authentication on-device solution.\n\nIntel RealSense ID combines an active depth sensor with a specialized neural network designed to deliver an intuitive, secure and accurate facial authentication solution that adapts over time.\nThis solution offers user privacy and is activated by user awareness. Built-in anti spoofing technology protects against attacks using photographs, videos or masks.\n\nIntel RealSense ID is a natural solution simplifying secure entry for everyone, everywhere. Supports children to tall adults and designed for Smart Locks, Access Control, PoS, ATMs, and Kiosks.\n\nDeveloper kits containing the necessary hardware to use this library are available for purchase at store.intelrealsense.com. \nSee information about the Intel RealSense ID technology at https://www.intelrealsense.com/facial-authentication/\n\nFor high-level architecture, see [Intel RealSense ID F450 / F455 Architecture Diagram](#Intel-RealSense-ID-F450-and-F455-Architecure-Diagram).\n\nNote: Device = Intel RealSense ID F450 / F455\n\n## Platforms\n * Linux (tested on Ubuntu 18, gcc 7.5+)\n * Windows (tested on Windows 10, msvc 2019) \n\n## Building\nUse CMake version 3.14 or above:\n\n```console\n$ cd \u003cproject_dir\u003e\n$ mkdir build \u0026\u0026 cd build\n$ cmake .. //in case preview is required run: cmake .. -DRSID_PREVIEW=1 //in case secure is required run: cmake .. -DRSID_SECURE=1\n$ make -j\n```\n\n### CMake Options\n\nThe following possible options are available for the `cmake` command\n\n| Option               | Default | Feature                                                    |\n|----------------------|:-------:|:-----------------------------------------------------------|\n| `RSID_DEBUG_CONSOLE` |  `ON`   | Log everything to console                                  |\n| `RSID_DEBUG_FILE`    |  `OFF`  | Log everything to _rsid_debug.log_ file                    |\n| `RSID_DEBUG_SERIAL`  |  `OFF`  | Log all serial communication                               |\n| `RSID_DEBUG_PACKETS` |  `OFF`  | Log packet sent/received over the serial line              |\n| `RSID_DEBUG_VALUES`  |  `OFF`  | Replace default common values with debug ones              |\n| `RSID_PREVIEW`       |  `OFF`  | Enables preview feature.                                   |\n| `RSID_SAMPLES`       |  `OFF`  | Build samples                                              |\n| `RSID_TIDY`          |  `OFF`  | Enable clang-tidy                                          |\n| `RSID_PEDANTIC`      |  `OFF`  | Enable extra compiler warnings                             |\n| `RSID_PROTECT_STACK` |  `OFF`  | Enable stack protection compiler flags                     |\n| `RSID_DOXYGEN`       |  `OFF`  | Build doxygen docs                                         |\n| `RSID_SECURE`        |  `OFF`  | Enable secure communication with device                    |\n| `RSID_TOOLS`         |  `ON`   | Build additional tools                                     |\n| `RSID_PY`            |  `OFF`  | Build python wrapper                                       |\n| `RSID_INSTALL`       |  `OFF`  | Generate the install target and rsidConfig.cmake           |\n| `RSID_NETWORK`       |  `ON`   | Enable networking. Required for license and update checker.|\n\n\n### Linux Post Install\n\nIn order to install the udev rules for the F450/F455 devices, run the command:\n```bash\nsudo script/udev-setup.sh -i\n```\nNote: You can undo the changes/uninstall by using the `-u` flag. \n\nThe capture device will be available to `plugdev` users while the serial port will be available to `dialout` users.\nOn Debian/Ubuntu, you can add current user to those groups by issuing the commands:\n```bash\nsudo adduser $USER dialout\nsudo adduser $USER plugdev\n```\n\nNote: Changes in group membership will take effect after logout/login (or reboot). \n\n### Windows Post Install\n\nIn order to be able to capture metadata for RAW format, open a `PowerShell` terminal as Administrator and run the command\n```shell\n.\\scripts\\realsenseid_metadata_win10.ps1\n```\n\n## Sample Code\nThis snippet shows the basic usage of our library.\n```cpp\n// Create face authenticator and connect it to the device on port COM9\nRealSenseID::FaceAuthenticator authenticator;\nconnect_status = authenticator.Connect({RealSenseID::SerialType::USB, \"COM9\"});\n\n// Enroll a user\nconst char* user_id = \"John\";\nMyEnrollClbk enroll_clbk;\nauto status = authenticator.Enroll(enroll_clbk, user_id);\n\n// Authenticate a user\nMyAuthClbk auth_clbk;\nstatus = authenticator.Authenticate(auth_clbk);\n\n// Remove the user from device\nsuccess = authenticator.RemoveUser(user_id);\n\n```\n\nFor additional languages, build instruction and detailed code please see our code [samples](./samples) and [tools](tools).\n\n## Secure Communication\nThe library can be compiled in secure mode. Once paired with the device, all communications will be protected.\nIf you wish to get back to non-secure communcations, you must first unpair your device.\n\nCryptographic algorithms that are used for session protection:\n* Message signing - ECDSA P-256 (secp256-r1).\n* Shared session key generation - ECDH P-256 (secp256-r1)\n* Message encryption - AES-256, CTR mode.\n* Message integrity - HKDF-256.\n\nTo enable secure mode, the host should perform the following steps:\n* Compile the library with RSID_SECURE enabled.\n* Generate a set of ECDSA P-256 (secp256-r1) public and private keys. The host is responsible for keeping his private key safe.\n* Pair with the device to enable secure communication. Pairing is performed once using the FaceAuthenticator API.\n* Implement a SignatureCallback. Signing and verifying is done with the ECDSA P-256 (secp256-r1) keys. Please see the pairing sample on how to pair the device and use keys.\n\nEach request (a call to one of the main API functions listed below) from the host to the device starts a new encrypted session, which performs an ECDH P-256 (secp256-r1) key exchange to create the shared secret for encrypting the current session.\n\n```cpp\nclass MySigClbk : public RealSenseID::SignatureCallback\n{\npublic:\n    bool Sign(const unsigned char* buffer, const unsigned int buffer_len, unsigned char* out_sig) override\n    {\n      // Sign buffer with host ECDSA private key\n    }\n\n    bool Verify(const unsigned char* buffer, const unsigned int buffer_len, const unsigned char* sig,const unsigned int sign_len) override\n    {\n      // Verify buffer with device ECDSA public key\n    }\n};\n\nMySigClbk sig_clbk;\nRealSenseID::FaceAuthenticator authenticator {\u0026sig_clbk};\nStatus connect_status = authenticator.Connect({RealSenseID::SerialType::USB, \"COM9\"});\nauthenticator.Disconnect();\nchar* hostPubKey = getHostPubKey(); // 64 bytes ECDSA public key of the host\nchar host_pubkey_signature[64];\nif (!sig_clbk.Sign((unsigned char*)hostPubKey, 64, host_pubkey_signature))\n{\n    printf(\"Failed to sign host ECDSA key\\n\");\n    return;\n}\nchar device_pubkey[64]; // Save this key after getting it to use it for verification\nStatus pair_status = authenticator.Pair(host_pubkey, host_pubkey_signature, device_pubkey);\n```\n\n## Server and Device APIs\n### Device Mode\nDevice Mode is a set of APIs enable the user to enroll and authenticate on the device itself, \nincluding database management and matching on the device.\n\n### Server Mode\nServer Mode is a set of APIs for users who wish to manage a faceprints database\non the host or the server. In this mode F450 is used as a Faceprints-Extraction device only.\n\nThe API provides a 'matching' function which predicts whether two faceprints belong to the same person,\nthus enabling the user to scan their database for similar users.\n\n\n## Project Structure\n### RealSenseID API\nThe [RealSenseID](./include/RealSenseID/) is the main API to the communication with the device.\nC, C++ and C# API wrappers are provided as part of the library.\nJava and python API is under development.\nAll APIs are synchronous and assuming a new operation will not be activated till previous is completed.\n\n* C++ [API](./include/RealSenseID) and [samples](./samples/cpp).\n* C/C#/Python [API](./wrappers) and [samples](./samples).\n\n\n#### FaceAuthenticator\n##### Connect / Disconnect\nConnects host to device using USB (```RealSenseID::SerialType::USB```) or UART interfaces (```RealSenseID::SerialType::UART```).\n```cpp\nclass MySigClbk : public RealSenseID::SignatureCallback\n{\npublic:\n    bool Sign(const unsigned char* buffer, const unsigned int buffer_len, unsigned char* out_sig) override\n    {\n      // Sign buffer with host ECDSA private key\n    }\n\n    bool Verify(const unsigned char* buffer, const unsigned int buffer_len, const unsigned char* sig,const unsigned int sign_len) override\n    {\n      // Verify buffer with device ECDSA public key\n    }\n};\n\nMySigClbk sig_clbk;\nRealSenseID::FaceAuthenticator authenticator {\u0026sig_clbk};\nStatus connect_status = authenticator.Connect({RealSenseID::SerialType::USB, \"COM9\"});\nauthenticator.Disconnect();\n```\n\n##### Pair\nPerform an ECDSA key exchange.\nIn pairing, the host sends the following:\n* ECDSA public key.\n* ECDSA public key signature with the previous ECDSA private key. If this is the first pairing, the signature is ignored.\n```cpp\nStatus pair_status = authenticator.Pair(host_pubkey, host_pubkey_signature, device_pubkey);\n```\n\nThe Host will receive the device's ECDSA public key, and should save it for verification in the implementation of SignatureCallback::Verify.\n\n##### Enrollment\nStarts device, runs neural network algorithm and stores encrypted faceprints on database.\nA faceprint is a set number of points which is represented as mathematical transformation of the user’s face. saves encrypted facial features to secured flash on Intel RealSense ID F450 / F455.\nStored encrypted faceprints are matched with enrolled faceprints later during authentication.\nFor best performance, enroll under normal lighting conditions and look directly at the device.\nDuring the enrollment process, device will send a status *hint* to the callback provided by application.\nFull list of the *hint* can be found in [EnrollStatus.h](./include/RealSenseID/).\n```cpp\nclass MyEnrollClbk : public RealSenseID::EnrollmentCallback\n{\npublic:\n    void OnResult(const RealSenseID::EnrollStatus status) override\n    {\n        std::cout \u003c\u003c \"on_result: status: \" \u003c\u003c status \u003c\u003c std::endl;\n    }\n\n    void OnProgress(const RealSenseID::FacePose pose) override\n    {\n        std::cout \u003c\u003c \"on_progress: pose: \" \u003c\u003c pose \u003c\u003c std::endl;\n    }\n\n    void OnHint(const RealSenseID::EnrollStatus hint) override\n    {\n        std::cout \u003c\u003c \"on_hint: hint: \" \u003c\u003c hint \u003c\u003c std::endl;\n    }\n};\n\nconst char* user_id = \"John\";\nMyEnrollClbk enroll_clbk;\nStatus status = authenticator.Enroll(enroll_clbk, user_id);\n```\n\n##### Authenticate\nSingle authentication attempt: Starts device, runs neural network algorithm, generates faceprints and compares them to all enrolled faceprints in database.\nFinally, returns whether the authentication was forbidden or allowed with enrolled user id. During the authentication process, device will send a status *hint* to the callback provided by application.\nFull list of the *hint* can be found in [AuthenticationStatus.h](./include/RealSenseID/).\n\n\nThis operation can be further configured by passing [DeviceConfig](include/RealSenseID/DeviceConfig.h) struct to the ```FaceAuthenticator::SetDeviceConfig(const DeviceConfig\u0026)``` function.\nSee the [Device Configuration](#device-configuration-api) below for details.\n```cpp\nclass MyAuthClbk : public RealSenseID::AuthenticationCallback\n{\npublic:\n    // Called when authentication result is available.\n    // If there are multiple faces it will be called for each face detected.\n    void OnResult(const RealSenseID::AuthenticateStatus status, const char* user_id) override\n    {\n        if (status == RealSenseID::AuthenticateStatus::Success)\n        {\n            std::cout \u003c\u003c \"******* Authenticate success.  user_id: \" \u003c\u003c user_id \u003c\u003c \" *******\" \u003c\u003c std::endl;\n        }\n        else\n        {\n            std::cout \u003c\u003c \"on_result: status: \" \u003c\u003c status \u003c\u003c std::endl;\n        }\n    }\n\n    void OnHint(const RealSenseID::AuthenticateStatus hint) override\n    {\n        std::cout \u003c\u003c \"on_hint: hint: \" \u003c\u003c hint \u003c\u003c std::endl;\n    }\n};\n\nMyAuthClbk auth_clbk;\nStatus status = authenticator.Authenticate(auth_clbk);\n```\n\n##### AuthenticateLoop\nStarts device, runs authentication in a loop until Cancel() API is invoked.\nStarts camera and running loop of\n- NN algo(s) pipeline\n- Facial features extraction\n- Matches them to all previously stored features in database.\n- Returns result whether the authentication was forbidden or allowed with pre-enrolled user id.\nDuring the authentication process hint statuses might be sent to the callback provided by application.\nFull list of the hints can be found in [AuthenticationStatus.h](./include/RealSenseID/).\n```cpp\nclass MyAuthClbk : public RealSenseID::AuthenticationCallback\n{\npublic:\n    // Called when result is available for a detected face.\n    // If the status==AuthenticateStatus::Success then the user_id will point to c string of the authenenticated user id.\n    void OnResult(const RealSenseID::AuthenticateStatus status, const char* user_id) override\n    {\n        if (status == RealSenseID::AuthenticateStatus::Success)\n        {\n            std::cout \u003c\u003c \"******* Authenticate success.  user_id: \" \u003c\u003c user_id \u003c\u003c \" *******\" \u003c\u003c std::endl;\n        }\n        else\n        {\n            std::cout \u003c\u003c \"on_result: status: \" \u003c\u003c status \u003c\u003c std::endl;\n        }\n    }\n\n    void OnHint(const RealSenseID::AuthenticateStatus hint) override\n    {\n        std::cout \u003c\u003c \"on_hint: hint: \" \u003c\u003c hint \u003c\u003c std::endl;\n    }\n\n   \n    // Called when faces are detected. Can be single or multiple faces.\n    // The faces vector contains coord X(,y,h,w)of faces detected \n    // Coords are in full HD resolution (1920x1080):\n    //   x,y: top left face rect\n    //   w,h: width/height of the face rect\n    //   Note: The `X` coords are flipped which means X==0 is most right, and X==1920 is most left.         \n    // The timestamp argument is the timestamp in millis of the frame that the faces were found in.    \n    void OnFaceDetected(const std::vector\u003cRealSenseID::FaceRect\u003e\u0026 faces, const unsigned int timestamp) override\n    {\n        _faces = faces;\n    }\n};\n\nMyAuthClbk auth_clbk;\nStatus status = authenticator.AuthenticateLoop(auth_clbk);\n```\n\n##### Device Configuration API\nThe device operation can be configured by passing the [DeviceConfig](include/RealSenseID/DeviceConfig.h) struct to the ```FaceAuthenticator::SetDeviceConfig(const DeviceConfig\u0026)``` function.\n\nThe various options and default values are described below:\n```cpp\nstruct RSID_API DeviceConfig\n{\n    /**\n     * @enum CameraRotation\n     * @brief Camera rotation.\n     */\n    enum class CameraRotation\n    {\n        Rotation_0_Deg = 0, // default\n        Rotation_180_Deg = 1,\n        Rotation_90_Deg = 2,\n        Rotation_270_Deg =3\n    };\n\n    /**\n     * @enum SecurityLevel\n     * @brief SecurityLevel to allow. (default is Low)\n     */\n    enum class SecurityLevel\n    {\n        High = 0,   // high security level\n        Medium = 1, // medium security level\n        Low = 2,    // low security level\n    };\n    \n    /**\n     * @enum AlgoFlow\n     * @brief Algorithms which will be used during authentication\n     */\n    enum class AlgoFlow\n    {\n        All = 0,               // spoof and face detection\n        FaceDetectionOnly = 1, // face detection only (default)\n        SpoofOnly = 2,         // spoof only\n        RecognitionOnly = 3    // recognition only\n    };\n\n    \n    enum class DumpMode\n    {\n        None = 0,        // default\n        CroppedFace = 1, // sends snapshot of the detected face (as jpg)\n        FullFrame = 2,   // sends left+right raw frames with metadata\n    };\n\n    \n    /**\n     * @brief Defines three confidence levels used by the Matcher during authentication.\n     *\n     * Each confidence level corresponds to a different set of thresholds, providing the user with the flexibility to\n     * choose between three different False Positive Rates (FPR): Low, Medium, and High. Currently, all sets use the\n     * thresholds associated with the \"Low\" confidence level by default.\n     */\n    enum class MatcherConfidenceLevel\n    {\n        High = 0,   \n        Medium = 1, \n        Low = 2 // default\n    };\n\n    CameraRotation camera_rotation = CameraRotation::Rotation_0_Deg;\n    SecurityLevel security_level = SecurityLevel::Low;\n    AlgoFlow algo_flow = AlgoFlow::FaceDetectionOnly;\n    DumpMode dump_mode = DumpMode::None;\n    MatcherConfidenceLevel matcher_confidence_level = MatcherConfidenceLevel::Low;\n\n    \n     /**\n     * @brief Specifies the maximum number of consecutive spoofing attempts allowed before the device rejects further\n     * authentication requests.\n     *\n     * Setting this value to 0 disables the check, which is the default behavior. If the number of consecutive spoofing\n     * attempts reaches max_spoofs, the device will reject any subsequent authentication requests. To reset this\n     * behavior and allow further authentication attempts, the device must be unlocked using the Unlock() API call.\n     */\n    unsigned char max_spoofs = 0; \n};\n```\n\nNotes: \n  * If ```SetDeviceConfig()``` never called, the device will use the default values described above.  \n  * ```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).\n\nThe following example configures the device to only detect spoofs (instead of the default full authentication):\n```cpp\n...\nusing namespace RealSenseID;\n// config with default options except for the algo flow which is set to spoof only \nDeviceConfig device_config; \ndevice_config.algo_flow = AlgoFlow::SpoofOnly;\nauto status = authenticator-\u003eSetDeviceConfig(device_config);\n\n```\n\n##### Cancel\nStops current operation (Enrollment/Authenticate/AuthenticateLoop).\n```cpp\nauthenticator.Cancel();\n```\n\n##### RemoveAll\nRemoves all enrolled users in the device database.\n```cpp\nbool success = authenticator.RemoveAll();\n```\n\n##### RemoveUser\nRemoves a specific user from the device database.\n```cpp\nconst char* user_id = \"John\";\nbool success = authenticator.RemoveUser(user_id);\n```\n\n#### DeviceController\n##### Connect / Disconnect\nConnects host to device using USB (```RealSenseID::SerialType::USB```) or UART interfaces (```RealSenseID::SerialType::UART```).\n```cpp\nRealSenseID::DeviceController deviceController;\nStatus connect_status = deviceController.Connect({RealSenseID::SerialType::USB, \"COM9\"});\ndeviceController.Disconnect();\n```\n\n##### Reboot\nResets and reboots device.\n```cpp\nbool success = deviceController.Reboot();\n```\n\n##### FW Upgrade (Not supported yet)\n\n\n#### Preview API\nCurrently 704x1280 or 1056x1920 RGB formats is available.\n\n##### Preview Configuration\n```cpp\n/**\n * Preview modes\n */\nenum class PreviewMode\n{\n    MJPEG_1080P = 0, // default\n    MJPEG_720P = 1,\n    RAW10_1080P = 2,\n};\n\n/**\n * Preview configuration\n */\nstruct RSID_API PreviewConfig\n{\n    int cameraNumber = -1; // attempt to auto detect by default\n    PreviewMode previewMode = PreviewMode::MJPEG_1080P; // RAW10 requires custom fw support\n    bool portraitMode = true; \n};\n```\nNotes:\n* The rotation used by algorithm is based only on DeviceConfig.camera_rotation attribute.\n* Indepedently, you can choose each preview mode (except raw) to be portrait or non-portrait. \n* Keep in mind that if you want preview to match algo:  \nCameraRotation::Rotation_0_Deg and CameraRotation::Rotation_180_Deg is for portraitMode == true.(default)  \nCameraRotation::Rotation_90_Deg and CameraRotation::Rotation_270_Deg is for portraitMode == false.\n\n##### Sensor Timestamps\nAccess to the sensor timestamps (in milliseconds).  \nTo enable it on Windows please turn on the Metadata option in when using the SDK installer.\nThe installer create specific dedicated registry entry to be present for each unique RealSenseID device.\nFor Linux, Metadata is supported on kernels 4.16 + only.\n\nThe timestamps can be acquired in OnPreviewImageReady under *image.metadata.timestamp* . Other metadata isn't valid.\n\nmore 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)\n\n##### StartPreview\nStarts preview. Callback function that is provided as parameter will be invoked for a newly arrived image and can be rendered by your application.\n```cpp\nclass PreviewRender : public RealSenseID::PreviewImageReadyCallback\n{\npublic:\n\tvoid OnPreviewImageReady(const Image image)\n\t{\n\t\t// Callback will be used to provide RGB preview image (for RAW10_1080P PreviewMode - raw converted to RGB).\n\t}\n\n    \tvoid OnSnapshotImageReady(const Image image) // Not mandatory. To enable it, see Device Configuration API.\n\t{\n\t\t// Callback will be used to provide images destined to be dumped (cropped/full). See DeviceConfig::DumpMode attribute.\n\t\t// Raw formatted images will be raised by this function.\n\t}\n};\n\nPreviewRender image_clbk;\nPreview preview;\nbool success = preview.StartPreview(image_clbk);\n```\n\n##### PausePreview\nPause preview.\n```cpp\nbool success = preview.PausePreview();\n```\n\n##### ResumePreview\nResumes the preview.\n```cpp\nbool success = preview.ResumePreview();\n```\n\n##### StopPreview\nStops preview.\n```cpp\nbool success = preview.StopPreview();\n```\n\n#### Server Mode Methods\n##### ExtractFaceprintsForAuth\nExtracts faceprints from a face, in the device, and sends them to the host.\nUses 'Authentication Flow' to eliminate spoof attempts and verify a face was detected.\n\n```cpp\n// extract faceprints using authentication flow\nclass FaceprintsAuthClbk : public RealSenseID::AuthFaceprintsExtractionCallback\n{\npublic:\n    void OnResult(const RealSenseID::AuthenticateStatus status, const Faceprints* faceprints) override\n    {\n        std::cout \u003c\u003c \"result: \" \u003c\u003c status \u003c\u003c std::endl;\n        s_extraction_status = status;\n        // if status was success pass '_faceprints' to user \n    }\n\n    void OnHint(const RealSenseID::AuthenticateStatus hint) override\n    {\n        std::cout \u003c\u003c \"hint: \" \u003c\u003c hint \u003c\u003c std::endl;\n    }\n};\n\nFaceprintsAuthClbk clbk;\nauto status = authenticator-\u003eExtractFaceprintsForAuth(clbk);\n```\n\n##### ExtractFaceprintsForEnroll\nExtracts faceprints from a face, in the device, and sends them to the host.\nUses 'Enrollment Flow' to verify face-pose is correct and that a face was detected.\n\n```cpp\n// extract faceprints using enrollment flow\nclass MyEnrollServerClbk : public RealSenseID::EnrollmentCallback\n{\n    const char* _user_id = nullptr;\n\npublic:\n    explicit MyEnrollServerClbk(const char* user_id) : _user_id {user_id}\n    {        \n    }\n\n    void OnResult(const RealSenseID::EnrollStatus status, const Faceprints* faceprints) override\n    {\n        std::cout \u003c\u003c \"result: \" \u003c\u003c status \u003c\u003c \"for user: \" \u003c\u003c _user_id \u003c\u003c std::endl;\n        s_extraction_status = status;    \n        // if status was success pass '_faceprints' to user            \n    }\n\n    void OnProgress(const RealSenseID::FacePose pose) override\n    {\n        std::cout \u003c\u003c \"pose: \" \u003c\u003c pose \u003c\u003c std::endl;\n    }\n\n    void OnHint(const RealSenseID::EnrollStatus hint) override\n    {\n        std::cout \u003c\u003c \"hint: \" \u003c\u003c hint \u003c\u003c std::endl;\n    }\n};\n\nMyEnrollServerClbk enroll_clbk {user_id.c_str()};\nauto status = authenticator-\u003eExtractFaceprintsForEnroll(enroll_clbk);\n```\n\n##### ExtractFaceprintsForAuthLoop\nExtracts faceprints in a loop, each iteration extracts from a single face and sends it to the host.\nUses 'Authentication Flow' to eliminate spoof attempts and verify a face was detected.\n\n```cpp\n// extract faceprints in a loop using authentication flow\nclass AuthLoopExtrClbk : public RealSenseID::AuthFaceprintsExtractionCallback\n{    \npublic:\n    void OnResult(const RealSenseID::AuthenticateStatus status, const Faceprints* faceprints) override\n    {        \n        std::cout \u003c\u003c \"result: \" \u003c\u003c status \u003c\u003c std::endl;\n        s_extraction_status = status;\n        // if status was success pass '_faceprints' to user \n    }\n\n    void OnHint(const RealSenseID::AuthenticateStatus hint) override\n    {\n        std::cout \u003c\u003c \"hint: \" \u003c\u003c hint \u003c\u003c std::endl;\n    }\n};\n\nAuthLoopExtrClbk clbk;\nauto status = authenticator-\u003eExtractFaceprintsForAuthLoop(clbk);\n```\n\n##### MatchFaceprints\nMatches two faceprints to each other and calculates a prediction of whether they belong to\nthe same person.\n\n```cpp\n// match extracted faceprints to the ones in the user-managed database\nfor (auto\u0026 db_item : db)\n{\n    auto match_result = authenticator-\u003eMatchFaceprints(scanned_faceprints, db_item.faceprints, updated_faceprints);    \n    if (match_result.success)\n    {\n        std::cout \u003c\u003c \"Match succeeded with user id: \" \u003c\u003c db_item.id \u003c\u003c std::endl;\n        break;\n    }\n}\n```\n\n### Python API (new)\nStarting with version 0.22.0 we provide python API:\n\n\n```python\n\"\"\" \nAuthenticate example\n\"\"\"\nimport rsid_py\n\ndef on_result(result, user_id):    \n    if result == rsid_py.AuthenticateStatus.Success:\n        print('Authenticated user:', user_id)\n\nwith rsid_py.FaceAuthenticator(\"COM9\") as f:\n    f.authenticate(on_result=on_result)\n\n```\n\n\nPlease visit the python [samples](./samples/python) page for details and samples.\n\n\n## Product Keys\nUsers need to obtain product/license key from the RealSense licensing portal. If no license is available the device will only \naccept basic face detection operations. Product keys are tied to specific device serial numbers. The activation process is done through\nthe RealSense licensing portal\n\nOnce you have a product key that is activated in the protal for your device, you need to provide the key to the device through one of the following ways:\n\n**RealSenseID Tool (GUI or CLI)**:\n1. In the cli `rsid-cli`: use the option `l` to pass the product key.\n2. In the `rsid-viewer`: you need to click settings, click `Activate License` and enter the product key.\n\nNOTE:\n  - Device needs to be connected while providing the product key to the cli/gui tools.\n  - Host needs access to the internet while providing the product key to the cli/gui tools.\n\n**Product/License Key API (Programatically):**\n1. If you're develping a custom app, you can use the `Authenticator::SetLicenseKey` and `Authenticator::ProvideLicense` APIs to \nsupply the product key. More details: [FaceAuthenticator.h](include/RealSenseID/FaceAuthenticator.h)\n\nFor non-perpetual licenses, the device may respond with `Status::LicenseCheck` to indicate that the license needs re-validation. \nIn such cases, the host must perform a license validation session with the cloud-based license server and the device.\nSee the `EnableLicenseCheckHandler(..)` and `DisableLicenseCheckHandler()` in [FaceAuthenticator.h](include/RealSenseID/FaceAuthenticator.h) for details.\n\nNOTE:\n  - Device needs to be connected while providing the product key to the API.\n  - Host needs access to the internet while providing the product key to the API.\n\n\n**Globally Stored Product key:**\n1. You may also use the global configuration  (Registry on Windows, config files on Linux)\n\n\n## Setting Product Key Programatically\n### Using the authenticator api \n```c++\nauthenticator-\u003eSetLicenseKey(license_key);\n```\nThis will set the license key for the current session in memory.\n\n## Deployment / Persisting Product Keys\nIn order to handle deployment and not having to enter the license key through the tools and/or the API, users may opt to choose to persist/store\nthe product key so that it can be picked up when needed by the SDK. This can be done by setting the product key in the resitry (Windows) or in \nconfiguration files (Linux). The steps below desribe the process to perform this opteration.\n\nWhen using this option, developers do not need to call the `SetLicenseKey` API. Developers must call the `ProvideLicense` at least once.\nFor furhter information, please refer to the API documentation for `ProvideLicense` in [FaceAuthenticator.h](include/RealSenseID/FaceAuthenticator.h)\n\n### Setting Product Key on Windows\nSet license/product key in Windows using PowerShell as follows:\n* Open PowerShell \u003cb\u003eas administrator\u003c/b\u003e\n* Create registry Key\n```\nNew-Item -Path \"HKLM:\\Software\\Intel\\VisionPlatform\"\n```\n* Set registry value example\n```\nSet-ItemProperty -Path \"HKLM:\\Software\\Intel\\VisionPlatform\" -Name \"License\" -Value \"ac87f323-1a91-4959-abe8-488fb5df5f12\"\n```\n* Verify that the value has been correctly set by issuing the command:\n```\nGet-ItemPropertyValue  -Path \"HKLM:\\Software\\Intel\\VisionPlatform\\\" -Name License\n```\nThe license key should be printed out.\n\n### Setting Product Key on Linux\nSame as with Windows, users need to obtain the license key from the RealSense licensing portal. If the user obtains a \nlicense key `ac87f323-1a91-4959-abe8-488fb5df5f12`, user can set the license/product key as follows:\n\nThe library will check for a `license.json` file in the following directories in the following order: \n1. In user home folder: `~/.intel/visionplatform/license.json`\n2. In system folder: `/etc/intel/visionplatform/license.json` \n\nIf the file is present and readable in any of the directories, the file will be parsed and the `license_key` will be\nutilized. \nThe file should look like the following:\n```json\n{\n    \"license_key\": \"ac87f323-1a91-4959-abe8-488fb5df5f12\"\n}\n```\n\nNOTE: When running with `sudo`, the home directory path will be `/root/.intel/visionplatform/license.json`. \nIn which case it is advisable to use the system path `/etc/intel/..` instead of the user path `~/.intel/..` \n\n## Notes on Deployment with Perpetual/Subscription Product Key Types\nPerpetual Product Keys are handled differently that subscription-based Product Keys. While subscription-based keys will trigger\na license check after a few thousand of API calls, perpetual keys will never trigger a license check once installed to the device.\n\nDevelopers are encouraged to use the `ProvideLicense` API before deploying the devices to the field. For developers with perpetual product keys \nthe devices will continue operation without having to perform any license checks and will not require internet connection.\n\nAdditionally, developers with subscription-based keys should validate that their setup is functional by calling `ProvideLicense` before \nthe deployment starts. It is also important for developers with subscription-based keys to:\n\n1. Ensure that the product key is stored in the host.\n2. Ensure that the host has internet connectivity in the deployment locations.\n\n\n## UpdateChecker API\nYou can use the [UpdateChecker](include/RealSenseID/UpdateChecker.h) API to obtain latest release info from the web. \n\nThe following example verifies whether a new firmware or host library is available, and prints the release and release notes URLs.\n\n```c++\nvoid check_for_updates(const RealSenseID::SerialConfig\u0026 serial_config)\n{\n    auto update_checker = RealSenseID::UpdateCheck::UpdateChecker();\n    RealSenseID::UpdateCheck::ReleaseInfo remote {};\n    RealSenseID::UpdateCheck::ReleaseInfo local {};    \n    auto status1 = update_checker.GetRemoteReleaseInfo(remote);\n    auto status2 = update_checker.GetLocalReleaseInfo(serial_config, local);\n    if (status1 != RealSenseID::Status::Ok || status2 != RealSenseID::Status::Ok)\n    {\n       throw std::runtime_error(\"Failed to fetch release info\");\n    }\n\n    bool update_available = (remote.sw_version \u003e local.sw_version) || (remote.fw_version \u003e local.fw_version);\n    if (update_available)\n    {\n        std::cout \u003c\u003c \"Update available\\n\";\n        std::cout \u003c\u003c \" * Release notes: \" \u003c\u003c remote.release_notes_url \u003c\u003c std::endl;\n        std::cout \u003c\u003c \" * Update URL: \" \u003c\u003c remote.release_url \u003c\u003c std::endl;\n    }\n    else\n    {\n        std::cout \u003c\u003c \"No updates available\\n\";\n    }\n}\n```\n\n## Proxy Setup\nLicense verification and UpdateChecker are built on top of libcurl and will honor the curl environment variables proxy settings:\n\nLinux:\n``` console\nexport http_proxy=\"http://user:pwd@proxy:port\"\nexport https_proxy=\"http://user:pwd@proxy:port\"\n```\n\nWindows PowerShell:\n``` console\n$env:http_proxy=\"http://user:pwd@proxy:port\"\n$env:https_proxy=\"http://user:pwd@proxy:port\"\n```\n\n\n3. Please refer to the main documentation for libcurl proxy configuration here: [Everything CURL/Proxies](https://everything.curl.dev/transfers/conn/proxies)\n\n## License\nThis project is licensed under Apache 2.0 license. Relevant license info can be found in \"License Notices\" folder.\n\n## Intel RealSense ID F450 and F455 Architecture Diagram\n![plot](./docs/F450_Architecture.png?raw=true)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintelrealsense%2Frealsenseid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintelrealsense%2Frealsenseid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintelrealsense%2Frealsenseid/lists"}