### Discover Devices and Run Examples

Source: https://context7.com/realsenseai/realsenseid/llms.txt

Discovers available RealSense ID devices and runs enrollment and authentication examples on the first discovered device. This is a common starting point for integrating the SDK.

```python
# Auto-discover and run
if __name__ == "__main__":
    devices = rsid_py.discover_devices()
    if devices:
        port = devices[0].serial_port
        enroll_example(port)
        auth_example(port)
```

--------------------------------

### Discover and Start Preview (Python)

Source: https://context7.com/realsenseai/realsenseid/llms.txt

Shows how to discover connected RealSense ID devices and start a video preview stream, with a callback for received frames.

```APIDOC
### Preview

```python
def preview_example():
    devices = rsid_py.discover_devices()
    if not devices:
        print("No device found"); return

    dev = devices[0]
    cfg = rsid_py.PreviewConfig()
    cfg.camera_number = dev.camera_number
    cfg.device_type   = dev.device_type
    cfg.preview_mode  = rsid_py.PreviewMode.MJPEG_1080P

    def on_frame(frame):
        print(f"Frame #{frame.number}  {frame.width}x{frame.height}  {frame.size/1024:.1f} KB")
        # Access raw bytes: frame.get_buffer()

    p = rsid_py.Preview(cfg)
    p.start(on_frame, snapshot_callback=None)
    # call p.stop() when done
```
```

--------------------------------

### Configure and Start Camera Preview (C++)

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Illustrates setting up camera preview parameters such as device type, camera number, preview mode, and portrait mode. Requires implementing the PreviewImageReadyCallback interface.

```cpp
RealSenseID::PreviewConfig config;
config.deviceType = RealSenseID::DeviceType::F45x;
config.cameraNumber = -1;  // auto-detect
config.previewMode = RealSenseID::PreviewMode::MJPEG_1080P;  // or MJPEG_720P, RAW10_1080P
config.portraitMode = true;

RealSenseID::Preview preview(config);
MyPreviewClbk clbk;  // implement PreviewImageReadyCallback::OnPreviewImageReady(const Image&)
preview.StartPreview(clbk);
// Image fields: buffer (RGB), width, height, stride, size, metadata (timestamp, exposure, gain)
preview.StopPreview();
```

--------------------------------

### User Enrollment Example (Python)

Source: https://context7.com/realsenseai/realsenseid/llms.txt

Shows how to enroll a new user with the RealSense ID Python API. It utilizes callbacks for result, progress, hints, and detected faces.

```python
import rsid_py

# --- Enroll ---
def enroll_example(port: str):
    with rsid_py.FaceAuthenticator(port) as f:
        f.enroll(
            user_id="Alice",
            on_result=lambda r: print("Enroll result:", r),
            on_progress=lambda p: print("Pose required:", p),
            on_hint=lambda h, score: print(f"Hint: {h}  score={score:.2f}"),
            on_faces=lambda faces, ts: [print(f"Face {face.x},{face.y}") for face in faces],
        )
        print("Enrolled users:", f.query_user_ids())

```

--------------------------------

### Install RealSense ID Udev Rules (Linux)

Source: https://github.com/realsenseai/realsenseid/blob/master/Readme.md

Run this script with sudo to install udev rules for RealSense ID devices on Linux. Use the -u flag to uninstall.

```bash
sudo script/udev-setup.sh -i
```

--------------------------------

### Camera Preview

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Configures and starts a camera preview stream, providing image data through a callback.

```APIDOC
## Camera Preview

### Description
Enables and manages a camera preview stream. The preview can be configured for different resolutions and modes, and image data is delivered via a callback.

### Configuration (`PreviewConfig`)
- **`deviceType`** (DeviceType) - The type of device (e.g., `F45x`).
- **`cameraNumber`** (int) - The camera number (-1 for auto-detect).
- **`previewMode`** (PreviewMode) - The preview mode (e.g., `MJPEG_1080P`, `MJPEG_720P`, `RAW10_1080P`).
- **`portraitMode`** (bool) - Enable portrait mode.

### Methods
- **`StartPreview(clbk)`**: Starts the preview stream, using the provided callback `clbk` which must implement `PreviewImageReadyCallback::OnPreviewImageReady(const Image&)`.
- **`StopPreview()`**: Stops the preview stream.

### Image Fields
- **`buffer`** (RGB data)
- **`width`**
- **`height`**
- **`stride`**
- **`size`**
- **`metadata`** (timestamp, exposure, gain)

### Example (C++)
```cpp
RealSenseID::PreviewConfig config;
config.deviceType = RealSenseID::DeviceType::F45x;
config.cameraNumber = -1;
config.previewMode = RealSenseID::PreviewMode::MJPEG_1080P;
config.portraitMode = true;

RealSenseID::Preview preview(config);
MyPreviewClbk clbk;  // implement PreviewImageReadyCallback::OnPreviewImageReady(const Image&)
preview.StartPreview(clbk);
preview.StopPreview();
```
```

--------------------------------

### Camera Preview Stream (Python)

Source: https://context7.com/realsenseai/realsenseid/llms.txt

Shows how to discover devices and start a camera preview stream using the RealSense ID Python API. Callbacks are used to process incoming frames.

```python
import rsid_py

# --- Preview ---
def preview_example():
    devices = rsid_py.discover_devices()
    if not devices:
        print("No device found"); return

    dev = devices[0]
    cfg = rsid_py.PreviewConfig()
    cfg.camera_number = dev.camera_number
    cfg.device_type   = dev.device_type
    cfg.preview_mode  = rsid_py.PreviewMode.MJPEG_1080P

    def on_frame(frame):
        print(f"Frame #{frame.number}  {frame.width}x{frame.height}  {frame.size/1024:.1f} KB")
        # Access raw bytes: frame.get_buffer()

    p = rsid_py.Preview(cfg)
    p.start(on_frame, snapshot_callback=None)
    # call p.stop() when done

```

--------------------------------

### User Authentication Example (Python)

Source: https://context7.com/realsenseai/realsenseid/llms.txt

Demonstrates how to authenticate a user using the RealSense ID Python API. The `on_result` callback handles success or failure.

```python
import rsid_py

# --- Authenticate ---
def auth_example(port: str):
    def on_result(result, user_id):
        if result == rsid_py.AuthenticateStatus.Success:
            print(f"Authenticated: {user_id}")
        else:
            print(f"Failed: {result}")

    with rsid_py.FaceAuthenticator(port) as f:
        f.authenticate(on_result=on_result)

```

--------------------------------

### Enroll User (Python)

Source: https://context7.com/realsenseai/realsenseid/llms.txt

Example of enrolling a new user with the RealSense ID Python API. It includes callbacks for result, progress, hints, and detected faces.

```APIDOC
## Python API — rsid_py

### Enroll

```python
import rsid_py

def enroll_example(port: str):
    with rsid_py.FaceAuthenticator(port) as f:
        f.enroll(
            user_id="Alice",
            on_result=lambda r: print("Enroll result:", r),
            on_progress=lambda p: print("Pose required:", p),
            on_hint=lambda h, score: print(f"Hint: {h}  score={score:.2f}"),
            on_faces=lambda faces, ts: [print(f"Face {face.x},{face.y}") for face in faces],
        )
        print("Enrolled users:", f.query_user_ids())
```
```

--------------------------------

### Install RealSense ID Metadata Script (Windows)

Source: https://github.com/realsenseai/realsenseid/blob/master/Readme.md

Run these PowerShell scripts as Administrator to install metadata for RAW format capture on Windows 10. Choose the script based on your device model.

```powershell
# F450 / F455
.\scripts\realsenseid_metadata_win10-f450.ps1

# F500 / F505
.\scripts\realsenseid_metadata_win10-f500.ps1
```

--------------------------------

### Enrollment

Source: https://github.com/realsenseai/realsenseid/blob/master/include/RealSenseID/README.md

Starts the device, runs the neural network algorithm, and stores encrypted faceprints on secured flash. It sends status hints and progress updates to a callback.

```APIDOC
## Enrollment

Starts the device, runs the neural network algorithm, and stores encrypted faceprints on secured flash on the RealSense™ ID device. Stored faceprints are matched against enrolled users during authentication.

For best performance, enroll under normal lighting conditions and look directly at the device.
During the enrollment process, the device sends status _hints_ to the callback. The full list of hints can be found in [EnrollStatus.h](EnrollStatus.h).

```cpp
class MyEnrollClbk : public RealSenseID::EnrollmentCallback
{
public:
    void OnResult(const RealSenseID::EnrollStatus status) override
    {
        std::cout << "on_result: status: " << status << std::endl;
    }

    void OnProgress(const RealSenseID::FacePose pose) override
    {
        std::cout << "on_progress: pose: " << pose << std::endl;
    }

    void OnHint(const RealSenseID::EnrollStatus hint) override
    {
        std::cout << "on_hint: hint: " << hint << std::endl;
    }
};

const char* user_id = "John";
MyEnrollClbk enroll_clbk;
Status status = authenticator.Enroll(enroll_clbk, user_id);
```
```

--------------------------------

### RealSense ID Preview Streaming Demo

Source: https://context7.com/realsenseai/realsenseid/llms.txt

Demonstrates how to start, pause, resume, and stop the device preview stream. Requires implementing the PreviewImageReadyCallback and SnapshotImageReadyCallback interfaces. The preview stream supports MJPEG and RAW10 modes.

```cpp
#include "RealSenseID/Preview.h"
#include <iostream>
#include <fstream>
#include <thread>
#include <chrono>

class MyPreview : public RealSenseID::PreviewImageReadyCallback
{
public:
    void OnPreviewImageReady(const RealSenseID::Image& img) override
    {
        printf("Frame #%u  %ux%u  %zu bytes  ts=%u ms\n",
               img.number, img.width, img.height, (size_t)img.size,
               img.metadata.timestamp);
        // img.buffer: raw RGB bytes (width * height * 3)
    }

    void OnSnapshotImageReady(const RealSenseID::Image& img) override
    {
        // Triggered by DeviceConfig::DumpMode (CroppedFace or FullFrame)
        std::ofstream f("snapshot.jpg", std::ios::binary);
        f.write(reinterpret_cast<const char*>(img.buffer), img.size);
        std::cout << "Snapshot saved\n";
    }
};

void preview_demo()
{
    RealSenseID::PreviewConfig cfg;
    cfg.deviceType   = RealSenseID::DeviceType::F45x;
    cfg.previewMode  = RealSenseID::PreviewMode::MJPEG_1080P;
    cfg.portraitMode = true;
    cfg.cameraNumber = -1; // auto-detect

    MyPreview cb;
    RealSenseID::Preview preview(cfg);
    preview.StartPreview(cb);

    std::this_thread::sleep_for(std::chrono::seconds(5));
    preview.PausePreview();
    std::this_thread::sleep_for(std::chrono::seconds(2));
    preview.ResumePreview();
    std::this_thread::sleep_for(std::chrono::seconds(3));
    preview.StopPreview();
}

```

--------------------------------

### Start RealSense ID Preview

Source: https://github.com/realsenseai/realsenseid/blob/master/include/RealSenseID/README.md

Callback invoked for each newly arrived image. Use this to process preview frames. Ensure metadata is enabled for timestamps on Windows and Linux.

```cpp
class PreviewRender : public RealSenseID::PreviewImageReadyCallback
{
public:
    void OnPreviewImageReady(const Image& image) override
    {
        // Provides RGB preview image (for RAW10_1080P PreviewMode: raw converted to RGB).
    }

    void OnSnapshotImageReady(const Image& image) override // optional
    {
        // Provides images triggered by DeviceConfig::DumpMode (cropped face or full frame).
    }
};

PreviewConfig previewConfig;
PreviewRender image_clbk;
Preview preview(previewConfig);
bool success = preview.StartPreview(image_clbk);
```

--------------------------------

### DeviceController::QueryFirmwareVersion

Source: https://github.com/realsenseai/realsenseid/blob/master/include/RealSenseID/README.md

Retrieves the current firmware version installed on the device.

```APIDOC
## DeviceController::QueryFirmwareVersion

### Description
Retrieves the firmware version string from the device.

### Method Signature
`Status QueryFirmwareVersion(std::string& version)`

### Parameters
* `version` (std::string&): An output string parameter that will be populated with the firmware version upon success.

### Example
```cpp
std::string version;
Status status = deviceController.QueryFirmwareVersion(version);
```
```

--------------------------------

### Implement Enrollment Callback

Source: https://github.com/realsenseai/realsenseid/blob/master/include/RealSenseID/README.md

Provides a sample implementation of the EnrollmentCallback interface to handle results, progress, and hints during the enrollment process. Override OnResult, OnProgress, and OnHint methods.

```cpp
class MyEnrollClbk : public RealSenseID::EnrollmentCallback
{
public:
    void OnResult(const RealSenseID::EnrollStatus status) override
    {
        std::cout << "on_result: status: " << status << std::endl;
    }

    void OnProgress(const RealSenseID::FacePose pose) override
    {
        std::cout << "on_progress: pose: " << pose << std::endl;
    }

    void OnHint(const RealSenseID::EnrollStatus hint) override
    {
        std::cout << "on_hint: hint: " << hint << std::endl;
    }
};

const char* user_id = "John";
MyEnrollClbk enroll_clbk;
Status status = authenticator.Enroll(enroll_clbk, user_id);
```

--------------------------------

### Connect and Query Firmware with DeviceController (Python)

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Shows how to establish a connection, retrieve the firmware version, and reboot a device using the Python API. The 'with' statement ensures automatic disconnection.

```python
with rsid_py.DeviceController(port) as ctrl:
    print(ctrl.query_firmware_version())
    ctrl.reboot()
```

--------------------------------

### Version Information

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Provides functions to get the RealSense ID version and check firmware compatibility.

```APIDOC
## Version Information

### Description
Functions to retrieve version information and check firmware compatibility.

### Functions
- **`RealSenseID::Version()`**: Returns the current RealSense ID version.
- **`CompatibleFirmwareVersion(deviceType)`**: Checks for compatible firmware versions for a given device type.
- **`IsFwCompatibleWithHost(deviceType, fw_ver)`**: Determines if the device firmware is compatible with the host system.
```

--------------------------------

### Host Mode Faceprints (Python)

Source: https://context7.com/realsenseai/realsenseid/llms.txt

Example of using RealSense ID in host mode, where faceprints are extracted and matched on the host system rather than the device.

```APIDOC
### Host Mode

```python
db = []

def on_enroll(status, extracted_fp):
    if status == rsid_py.EnrollStatus.Success:
        fp = rsid_py.Faceprints()
        fp.version = extracted_fp.version
        fp.features_type = extracted_fp.features_type
        fp.flags = extracted_fp.flags
        fp.adaptive_descriptor_nomask = extracted_fp.features
        fp.enroll_descriptor = extracted_fp.features
        db.append(fp)
        print("Faceprints stored in host DB")

def on_auth(status, new_fp, authenticator):
    if status != rsid_py.AuthenticateStatus.Success:
        return
    for i, stored in enumerate(db):
        updated = rsid_py.Faceprints()
        result = authenticator.match_faceprints(new_fp, stored, updated)
        if result.success:
            print(f"Host-matched user index={i}  score={result.score}")
            return
    print("No match in host DB")

with rsid_py.FaceAuthenticator(port) as f:
    f.extract_faceprints_for_enroll(on_progress=lambda p: None, on_result=on_enroll)
    f.extract_faceprints_for_auth(
        on_result=lambda status, fp: on_auth(status, fp, f))
```
```

--------------------------------

### Connect and Query Firmware with DeviceController (C++)

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Demonstrates connecting to a device using SerialConfig, querying its firmware version, and initiating a reboot. The DeviceController automatically disconnects upon destruction.

```cpp
RealSenseID::DeviceController ctrl;
ctrl.Connect(RealSenseID::SerialConfig{dev.serialPort});
std::string fw_ver;
ctrl.QueryFirmwareVersion(fw_ver);
ctrl.Reboot();  // auto-disconnects on destruction
```

--------------------------------

### Discover and Connect to Device (C#)

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Discover RealSense ID devices and connect using a serial configuration. Throws an exception if no device is found.

```csharp
var devices = rsid.Discover.DiscoverDevices();
if (devices.Length == 0) throw new Exception("No device found");
var dev = devices[0];
using var auth = new rsid.Authenticator();
var status = auth.Connect(new rsid.SerialConfig { port = dev.SerialPort });
```

--------------------------------

### Discover and Connect to Device (Python)

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Discover RealSense ID devices and use a context manager for connection and authentication. Raises an error if no device is found.

```python
devices = rsid_py.discover_devices()
if not devices:
    raise RuntimeError("No device found")
dev = devices[0]
with rsid_py.FaceAuthenticator(dev.device_type, dev.serial_port) as f:
    f.authenticate(on_result=on_result)
```

--------------------------------

### Add Preview C++ Sample

Source: https://github.com/realsenseai/realsenseid/blob/master/samples/cpp/CMakeLists.txt

Defines the build target for the simple 'preview' C++ sample application. Links against the 'rsid' library.

```cmake
add_executable(preview-cpp-sample preview.cc)
    target_link_libraries(preview-cpp-sample PRIVATE rsid)
    set_target_properties(preview-cpp-sample PROPERTIES FOLDER "samples/cpp")
```

--------------------------------

### Run Python Samples on Windows

Source: https://github.com/realsenseai/realsenseid/blob/master/samples/python/Readme.md

Navigate to the Release directory within the build folder and execute Python scripts using the python interpreter. This command assumes you are in the build/bin/Release directory.

```bash
# Windows
cd build/bin/Release
python ../../../samples/python/authenticate.py
```

--------------------------------

### Run Python Samples on Linux

Source: https://github.com/realsenseai/realsenseid/blob/master/samples/python/Readme.md

Navigate to the build directory and execute Python scripts using the python3 interpreter. This command assumes you are in the build/bin directory.

```bash
# Linux
cd build/bin
python3 ../../../samples/python/authenticate.py
```

--------------------------------

### Add Preview Snapshot C++ Sample (Secure Mode)

Source: https://github.com/realsenseai/realsenseid/blob/master/samples/cpp/CMakeLists.txt

Defines the build target for the 'preview-snapshot' C++ sample application in secure mode. Links against 'rsid' and 'mbedtls' libraries.

```cmake
add_executable(preview-snapshot-cpp-sample preview_snapshot.cc secure_mode_helper.cc secure_mode_helper.h)
        target_link_libraries(preview-snapshot-cpp-sample PRIVATE rsid mbedtls)
```

--------------------------------

### Authenticate User with FaceAuthenticator (Python)

Source: https://github.com/realsenseai/realsenseid/blob/master/Readme.md

Example of authenticating a user using the FaceAuthenticator in Python. Requires a callback function to handle authentication results. Ensure the correct serial port is specified.

```python
import rsid_py

def on_result(result, user_id):
    if result == rsid_py.AuthenticateStatus.Success:
        print('Authenticated user:', user_id)

with rsid_py.FaceAuthenticator("COM4") as f:
    f.authenticate(on_result=on_result)
```

--------------------------------

### FaceAuthenticator::Enroll

Source: https://context7.com/realsenseai/realsenseid/llms.txt

Initiates the user enrollment process. This method activates the camera, guides the user through necessary poses, extracts faceprints, and stores them on the device. Callbacks provide progress and results.

```APIDOC
## FaceAuthenticator::Enroll

Starts the enrollment flow: activates the camera, guides the user through face poses, extracts neural-network faceprints, and writes encrypted templates to the device's secured flash. Callbacks deliver progress, hints, and the final result.

```cpp
#include "RealSenseID/FaceAuthenticator.h"
#include "RealSenseID/EnrollmentCallback.h"
#include <iostream>

class MyEnrollClbk : public RealSenseID::EnrollmentCallback
{
public:
    void OnResult(const RealSenseID::EnrollStatus status) override
    {
        std::cout << "Enroll result: " << status << "\n";
        // EnrollStatus::Success on success; other values indicate failure reason
    }

    void OnProgress(const RealSenseID::FacePose pose) override
    {
        std::cout << "Required pose: " << pose << "\n";
        // Poses: Center, Up, Down, Left, Right
    }

    void OnHint(const RealSenseID::EnrollStatus hint, float frameScore) override
    {
        std::cout << "Hint: " << hint << "  frame_score=" << frameScore << "\n";
        // Hints: FaceDetected, MultipleFacesDetected, Spoof, DeviceError, etc.
    }
};

void enroll_user(RealSenseID::FaceAuthenticator& authenticator)
{
    const char* user_id = "Alice";  // max 30 ASCII chars
    MyEnrollClbk clbk;
    RealSenseID::Status status = authenticator.Enroll(clbk, user_id);
    // Status::Ok means the enroll flow completed; check OnResult for EnrollStatus::Success
    std::cout << "Enroll call status: " << status << "\n";
}
```
```

--------------------------------

### Set Preview Snapshot Sample Properties

Source: https://github.com/realsenseai/realsenseid/blob/master/samples/cpp/CMakeLists.txt

Sets the folder property for the 'preview-snapshot' C++ sample application.

```cmake
target_link_libraries(preview-snapshot-cpp-sample PRIVATE rsid)
    set_target_properties(preview-snapshot-cpp-sample PROPERTIES FOLDER "samples/cpp")
```

--------------------------------

### Build RealSense ID SDK (Linux/Windows)

Source: https://github.com/realsenseai/realsenseid/blob/master/Readme.md

Quickly build the RealSense ID SDK and tools using provided shell scripts. Use --help or /help for optional flags.

```bash
# Linux
scripts/build.sh
```

```bat
# Windows
scripts\build.bat
```

--------------------------------

### Discover and Connect to Device

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Demonstrates how to discover available RealSense ID devices and establish a connection using C++, Python, and C#.

```APIDOC
## Discover and Connect to Device

### C++ Example
```cpp
auto devices = RealSenseID::DiscoverDevices();
if (devices.empty()) { /* handle no device */ return; }
auto& dev = devices.front();
RealSenseID::FaceAuthenticator authenticator(dev.deviceType);
auto status = authenticator.Connect({dev.serialPort});
if (status != RealSenseID::Status::Ok) { /* handle error */ }
// ... use authenticator ...
// auto-disconnects on destruction
```

### Python Example
```python
devices = rsid_py.discover_devices()
if not devices:
    raise RuntimeError("No device found")
dev = devices[0]
with rsid_py.FaceAuthenticator(dev.device_type, dev.serial_port) as f:
    f.authenticate(on_result=on_result)
```

### C# Example
```csharp
var devices = rsid.Discover.DiscoverDevices();
if (devices.Length == 0) throw new Exception("No device found");
var dev = devices[0];
using var auth = new rsid.Authenticator();
var status = auth.Connect(new rsid.SerialConfig { port = dev.SerialPort });
```
```

--------------------------------

### Discover RealSense ID Devices (Python)

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Use discover_devices to find connected RealSense ID devices. Loop through the returned list to get information such as the serial port, device type, and serial number.

```python
import rsid_py
devices = rsid_py.discover_devices()
for dev in devices:
    # dev.serial_port, dev.device_type, dev.serial_number, dev.camera_number
```

--------------------------------

### Add Preview Snapshot C++ Sample (Non-Secure Mode)

Source: https://github.com/realsenseai/realsenseid/blob/master/samples/cpp/CMakeLists.txt

Defines the build target for the 'preview-snapshot' C++ sample application in non-secure mode. Links against the 'rsid' library.

```cmake
add_executable(preview-snapshot-cpp-sample preview.cc)
        target_link_libraries(preview-snapshot-cpp-sample PRIVATE rsid)
```

--------------------------------

### AuthenticateLoop

Source: https://github.com/realsenseai/realsenseid/blob/master/include/RealSenseID/README.md

Starts the device and runs authentication in a loop until Cancel() is called. Each iteration runs the neural network algorithm pipeline, extracts facial features, matches them against enrolled users, and reports the result via callback.

```APIDOC
## AuthenticateLoop

### Description
Starts the device and runs authentication in a loop until `Cancel()` is called. Each iteration:

- Runs the neural network algorithm pipeline
- Extracts facial features
- Matches them against all previously enrolled users in the database
- Reports the result via callback: whether authentication was allowed or denied, and the matched user ID

### Usage Example
```cpp
class MyAuthClbk : public RealSenseID::AuthenticationCallback
{
public:
    // Called when result is available for a detected face.
    // If the status==AuthenticateStatus::Success then the user_id will point to c string of the authenticated user id.
    void OnResult(const RealSenseID::AuthenticateStatus status, const char* user_id) override
    {
        if (status == RealSenseID::AuthenticateStatus::Success)
        {
            std::cout << "******* Authenticate success.  user_id: " << user_id << " *******" << std::endl;
        }
        else
        {
            std::cout << "on_result: status: " << status << std::endl;
        }
    }

    void OnHint(const RealSenseID::AuthenticateStatus hint) override
    {
        std::cout << "on_hint: hint: " << hint << std::endl;
    }

    // Called when faces are detected. Can be single or multiple faces.
    // The faces vector contains coord X(,y,h,w) of faces detected.
    // Coords are in full HD resolution (1920x1080):
    //   x,y: top left face rect
    //   w,h: width/height of the face rect
    //   Note: The `X` coords are flipped — X==0 is most right, and X==1920 is most left.
    // The timestamp argument is the timestamp in millis of the frame that the faces were found in.
    void OnFaceDetected(const std::vector<RealSenseID::FaceRect>& faces, const unsigned int timestamp) override
    {
        _faces = faces;
    }
};

MyAuthClbk auth_clbk;
Status status = authenticator.AuthenticateLoop(auth_clbk);
```
```

--------------------------------

### Add Enroll C++ Sample

Source: https://github.com/realsenseai/realsenseid/blob/master/samples/cpp/CMakeLists.txt

Defines the build target for the 'enroll' C++ sample application. Links against the 'rsid' library.

```cmake
add_executable(enroll-cpp-sample enroll.cc)
    target_link_libraries(enroll-cpp-sample PRIVATE rsid)
    set_target_properties(enroll-cpp-sample PROPERTIES FOLDER "samples/cpp")
```

--------------------------------

### Configure RealsenseID Logger Sources and Includes

Source: https://github.com/realsenseai/realsenseid/blob/master/src/Logger/CMakeLists.txt

Sets up the source files and include directories for the RealsenseID C++ logger library target.

```cmake
set(SRC_DIR ${CMAKE_CURRENT_SOURCE_DIR})

target_sources(${LIBRSID_CPP_TARGET} PRIVATE "${SRC_DIR}/Logger.h")
target_include_directories(${LIBRSID_CPP_TARGET} PRIVATE "${SRC_DIR}")
target_sources(${LIBRSID_CPP_TARGET} PRIVATE 
	"${SRC_DIR}/LoggingApi.cc"
	"${SRC_DIR}/Logger.cc"
)
```

--------------------------------

### Define F50x Firmware Update Source and Header Files

Source: https://github.com/realsenseai/realsenseid/blob/master/src/FwUpdate/F50x/CMakeLists.txt

This snippet sets up variables for source and header directories and lists the files to be included in the build for the F50x firmware update module. These files are then added to the target library.

```cmake
set(SRC_DIR ${CMAKE_CURRENT_SOURCE_DIR})
set(HEADERS     
    "${SRC_DIR}/Utilities.h"
    "${SRC_DIR}/Cmds.h"
    "${SRC_DIR}/ModuleInfo.h"
    "${SRC_DIR}/FwUpdaterCommF50x.h"
    "${SRC_DIR}/FwUpdateEngineF50x.h"
	"${SRC_DIR}/FwUpdaterF50x.h"
)

set(SOURCES 
    "${SRC_DIR}/Utilities.cc"
    "${SRC_DIR}/Cmds.cc"
    "${SRC_DIR}/FwUpdaterCommF50x.cc"
    "${SRC_DIR}/FwUpdateEngineF50x.cc"
	"${SRC_DIR}/FwUpdaterF50x.cc"
)

target_sources(${LIBRSID_CPP_TARGET} PRIVATE ${HEADERS} ${SOURCES})
```

--------------------------------

### Enroll User with Camera

Source: https://context7.com/realsenseai/realsenseid/llms.txt

Initiates the user enrollment process using the device's camera. Callbacks provide progress, hints, and the final enrollment status. The user ID must be a maximum of 30 ASCII characters.

```cpp
#include "RealSenseID/FaceAuthenticator.h"
#include "RealSenseID/EnrollmentCallback.h"
#include <iostream>

class MyEnrollClbk : public RealSenseID::EnrollmentCallback
{
public:
    void OnResult(const RealSenseID::EnrollStatus status) override
    {
        std::cout << "Enroll result: " << status << "\n";
        // EnrollStatus::Success on success; other values indicate failure reason
    }

    void OnProgress(const RealSenseID::FacePose pose) override
    {
        std::cout << "Required pose: " << pose << "\n";
        // Poses: Center, Up, Down, Left, Right
    }

    void OnHint(const RealSenseID::EnrollStatus hint, float frameScore) override
    {
        std::cout << "Hint: " << hint << "  frame_score=" << frameScore << "\n";
        // Hints: FaceDetected, MultipleFacesDetected, Spoof, DeviceError, etc.
    }
};

void enroll_user(RealSenseID::FaceAuthenticator& authenticator)
{
    const char* user_id = "Alice";  // max 30 ASCII chars
    MyEnrollClbk clbk;
    RealSenseID::Status status = authenticator.Enroll(clbk, user_id);
    // Status::Ok means the enroll flow completed; check OnResult for EnrollStatus::Success
    std::cout << "Enroll call status: " << status << "\n";
}
```

--------------------------------

### Add Host Mode C++ Sample

Source: https://github.com/realsenseai/realsenseid/blob/master/samples/cpp/CMakeLists.txt

Defines the build target for the 'host-mode' C++ sample application. Links against the 'rsid' library.

```cmake
add_executable(host-mode-cpp-sample host-mode.cc)
    target_link_libraries(host-mode-cpp-sample PRIVATE rsid)
    set_target_properties(host-mode-cpp-sample PROPERTIES FOLDER "samples/cpp")
```

--------------------------------

### Enroll User (C++)

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Enroll a new user with a given ID using a callback for status updates. Optional overrides for detailed face detection events are available.

```cpp
class MyEnrollClbk : public RealSenseID::EnrollmentCallback {
public:
    void OnResult(const RealSenseID::EnrollStatus status) override { /* handle */ }
    void OnProgress(const RealSenseID::FacePose pose) override { /* handle */ }
    void OnHint(const RealSenseID::EnrollStatus hint, float frameScore) override { /* handle */ }
};
MyEnrollClbk clbk;
auto status = authenticator.Enroll(clbk, "john");
// Optional overrides: OnFaceDetected, OnLandmarksDetected, OnFaceCroppedImage
```

--------------------------------

### Basic RealSense ID Library Usage (C++)

Source: https://github.com/realsenseai/realsenseid/blob/master/Readme.md

Demonstrates essential RealSense ID library functions including connecting to a device, enrolling a user, authenticating a user, and removing a user. Ensure necessary callbacks (MyEnrollClbk, MyAuthClbk) are defined.

```cpp
RealSenseID::FaceAuthenticator authenticator;
connect_status = authenticator.Connect({"COM4"});

// Enroll a user
const char* user_id = "John";
MyEnrollClbk enroll_clbk;
auto status = authenticator.Enroll(enroll_clbk, user_id);

// Authenticate a user
MyAuthClbk auth_clbk;
status = authenticator.Authenticate(auth_clbk);

// Remove the user from device
success = authenticator.RemoveUser(user_id);
```

--------------------------------

### Enroll User (Python)

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Enroll a user by providing a user ID and callback functions for results, progress, and hints.

```python
f.enroll(user_id="john", on_result=on_result, on_progress=on_progress, on_hint=on_hint)
```

--------------------------------

### Build RealSense ID with Preview Enabled (Windows)

Source: https://github.com/realsenseai/realsenseid/blob/master/tools/README.md

Enable preview features by using the -DRSID_PREVIEW=1 flag during the CMake configuration on Windows.

```console
> mkdir build
> cd build
> cmake -DRSID_PREVIEW=1 ..

```

--------------------------------

### Add Pair Device C++ Sample (Secure Mode)

Source: https://github.com/realsenseai/realsenseid/blob/master/samples/cpp/CMakeLists.txt

Defines the build target for the 'pair-device' C++ sample application in secure mode. Links against 'rsid' and 'mbedtls' libraries.

```cmake
add_executable(pair-device-cpp-sample pair-device.cc secure_mode_helper.cc secure_mode_helper.h)
    target_link_libraries(pair-device-cpp-sample PRIVATE rsid mbedtls)
    set_target_properties(pair-device-cpp-sample PROPERTIES FOLDER "samples/cpp")
```

--------------------------------

### Manage Users with FaceAuthenticator

Source: https://context7.com/realsenseai/realsenseid/llms.txt

Demonstrates how to query the number of enrolled users, list their IDs, remove a specific user, and wipe the entire user database. Ensure proper memory management when handling user IDs.

```cpp
#include "RealSenseID/FaceAuthenticator.h"
#include <iostream>

void manage_users(RealSenseID::FaceAuthenticator& authenticator)
{
    // How many users are enrolled?
    unsigned int count = 0;
    authenticator.QueryNumberOfUsers(count);
    std::cout << "Enrolled users: " << count << "\n";

    if (count > 0)
    {
        // Allocate and populate ID list
        char** ids = new char*[count];
        for (unsigned int i = 0; i < count; i++)
            ids[i] = new char[RealSenseID::MAX_USERID_LENGTH];

        authenticator.QueryUserIds(ids, count);
        for (unsigned int i = 0; i < count; i++)
            std::cout << "  [" << i << "] " << ids[i] << "\n";

        // Remove one user
        authenticator.RemoveUser(ids[0]);
        std::cout << "Removed user: " << ids[0] << "\n";

        for (unsigned int i = 0; i < count; i++) delete[] ids[i];
        delete[] ids;
    }

    // Remove everyone
    RealSenseID::Status s = authenticator.RemoveAll();
    std::cout << "RemoveAll: " << s << "\n";
}
```

--------------------------------

### Add Preview Source and Header Files

Source: https://github.com/realsenseai/realsenseid/blob/master/src/Preview/CMakeLists.txt

Appends header and source files for the preview module to the respective lists, which are then added to the C++ target.

```cmake
list(APPEND HEADERS "${SRC_DIR}/PreviewImpl.h")
list(APPEND SOURCES 
	"${SRC_DIR}/PreviewApi.cc"
	"${SRC_DIR}/PreviewImpl.cc"
)

target_sources(${LIBRSID_CPP_TARGET} PRIVATE ${SOURCES})
```

--------------------------------

### Enroll User

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Shows how to enroll a new user with RealSense ID, including progress and hint callbacks, and image enrollment.

```APIDOC
## Enroll User

### C++ Example
```cpp
class MyEnrollClbk : public RealSenseID::EnrollmentCallback {
public:
    void OnResult(const RealSenseID::EnrollStatus status) override { /* handle */ }
    void OnProgress(const RealSenseID::FacePose pose) override { /* handle */ }
    void OnHint(const RealSenseID::EnrollStatus hint, float frameScore) override { /* handle */ }
};
MyEnrollClbk clbk;
auto status = authenticator.Enroll(clbk, "john");
// Optional overrides: OnFaceDetected, OnLandmarksDetected, OnFaceCroppedImage
```

### Python Example
```python
f.enroll(user_id="john", on_result=on_result, on_progress=on_progress, on_hint=on_hint)
```

### C# Example
```csharp
auth.Enroll(new rsid.EnrollArgs {
    userId = "john", resultClbk = (s, ctx) => {}, progressClbk = (p, ctx) => {}, hintClbk = (h, sc, ctx) => {}
});
```

### Image Enrollment
**Image enrollment** (BGR24, face ≥75% of area, max 900KB): `EnrollImage("john", buf, w, h)` / `enroll_image(...)` / `auth.EnrollImage(...)`.
```

--------------------------------

### Implement Authentication Callback

Source: https://github.com/realsenseai/realsenseid/blob/master/include/RealSenseID/README.md

Shows how to implement the AuthenticationCallback to handle authentication results and hints. The OnResult method is called for each detected face, providing success status and user ID.

```cpp
class MyAuthClbk : public RealSenseID::AuthenticationCallback
{
public:
    // Called when authentication result is available.
    // If there are multiple faces it will be called for each face detected.
    void OnResult(const RealSenseID::AuthenticateStatus status, const char* user_id) override
    {
        if (status == RealSenseID::AuthenticateStatus::Success)
        {
            std::cout << "******* Authenticate success.  user_id: " << user_id << " *******" << std::endl;
        }
        else
        {
            std::cout << "on_result: status: " << status << std::endl;
        }
    }

    void OnHint(const RealSenseID::AuthenticateStatus hint) override
    {
        std::cout << "on_hint: hint: " << hint << std::endl;
    }
};

MyAuthClbk auth_clbk;
Status status = authenticator.Authenticate(auth_clbk);
```

--------------------------------

### Add Authenticate C++ Sample

Source: https://github.com/realsenseai/realsenseid/blob/master/samples/cpp/CMakeLists.txt

Defines the build target for the 'authenticate' C++ sample application. Links against the 'rsid' library.

```cmake
add_executable(authenticate-cpp-sample authenticate.cc)
    target_link_libraries(authenticate-cpp-sample PRIVATE rsid)
    set_target_properties(authenticate-cpp-sample PROPERTIES FOLDER "samples/cpp")
```

--------------------------------

### Initialize and Check Firmware Compatibility

Source: https://github.com/realsenseai/realsenseid/blob/master/include/RealSenseID/README.md

Initializes the FwUpdater for a specific device type and checks if a firmware binary is compatible before attempting an update. Inspect FwCompatibilityInfo for details on any incompatibilities.

```cpp
RealSenseID::FwUpdater updater(RealSenseID::DeviceType::F45x);
RealSenseID::FwUpdater::Settings settings;
settings.serial_config = {"COM4"};

// Check compatibility before updating
RealSenseID::FwUpdater::FwCompatibilityInfo info;
if (!updater.CheckCompatibility(settings, "path/to/fw.bin", info))
{
    // inspect info fields to determine what is incompatible
    return;
}
```

--------------------------------

### Add Detect Poses C++ Sample

Source: https://github.com/realsenseai/realsenseid/blob/master/samples/cpp/CMakeLists.txt

Defines the build target for the 'detect-poses' C++ sample application. Links against the 'rsid' library.

```cmake
add_executable(detect-poses-cpp-sample detect-poses.cc)
    target_link_libraries(detect-poses-cpp-sample PRIVATE rsid)
    set_target_properties(detect-poses-cpp-sample PROPERTIES FOLDER "samples/cpp")
```

--------------------------------

### C++ Full Faceprint Extraction and Matching Pattern

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Demonstrates the complete workflow for enrolling faceprints, extracting faceprints for authentication, and matching them with adaptive updates. Requires implementing callback classes for asynchronous operations.

```cpp
// Step 1: Enroll — extract faceprints and store in DB
class EnrollExtractClbk : public RealSenseID::EnrollFaceprintsExtractionCallback {
public:
    RealSenseID::Faceprints db_entry;
    void OnResult(const RealSenseID::EnrollStatus status,
                  const RealSenseID::ExtractedFaceprints* fp) override {
        if (status != RealSenseID::EnrollStatus::Success) return;
        db_entry.data.version = fp->data.version;
        db_entry.data.flags = fp->data.flags;
        db_entry.data.featuresType = fp->data.featuresType;
        ::memcpy(db_entry.data.adaptiveDescriptorWithoutMask,
                 fp->data.featuresVector, sizeof(fp->data.featuresVector));
        ::memcpy(db_entry.data.enrollmentDescriptor,
                 fp->data.featuresVector, sizeof(fp->data.featuresVector));
    }
    void OnProgress(const RealSenseID::FacePose) override {}
    void OnHint(const RealSenseID::EnrollStatus, float) override {}
};
EnrollExtractClbk enroll_clbk;
authenticator.ExtractFaceprintsForEnroll(enroll_clbk);

// Step 2: Auth — extract faceprints from probe face
class AuthExtractClbk : public RealSenseID::AuthFaceprintsExtractionCallback {
public:
    RealSenseID::ExtractedFaceprints extracted;
    void OnResult(const RealSenseID::AuthenticateStatus status,
                  const RealSenseID::ExtractedFaceprints* fp) override {
        if (status == RealSenseID::AuthenticateStatus::Success) extracted = *fp;
    }
    void OnHint(const RealSenseID::AuthenticateStatus, float) override {}
};
AuthExtractClbk auth_clbk;
authenticator.ExtractFaceprintsForAuth(auth_clbk);
// Or continuous: authenticator.ExtractFaceprintsForAuthLoop(auth_clbk);

// Step 3: Match + adaptive update
RealSenseID::MatchElement scanned;
scanned.data.version = auth_clbk.extracted.data.version;
scanned.data.featuresType = auth_clbk.extracted.data.featuresType;
scanned.data.flags = RealSenseID::FaOperationFlagsEnum::OpFlagAuthWithoutMask;
::memcpy(scanned.data.featuresVector, auth_clbk.extracted.data.featuresVector,
         sizeof(auth_clbk.extracted.data.featuresVector));
RealSenseID::Faceprints updated;
auto result = authenticator.MatchFaceprints(scanned, enroll_clbk.db_entry, updated,
    RealSenseID::ThresholdsConfidenceEnum::ThresholdsConfidenceLevel_High);
if (result.success && result.should_update)
    enroll_clbk.db_entry = updated;  // persist adaptive update

```

--------------------------------

### Set Device Permissions (Linux - Alternative)

Source: https://github.com/realsenseai/realsenseid/blob/master/tools/README.md

Alternatively, you can set read/write permissions for the device file directly for the current session. Replace '#' with the actual port number.

```console
sudo chmod 666 /dev/ttyACM#

```

--------------------------------

### Discover and Connect to Device (C++)

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Discover available RealSense ID devices and establish a connection using the serial port. The authenticator automatically disconnects on destruction.

```cpp
auto devices = RealSenseID::DiscoverDevices();
    if (devices.empty()) { /* handle no device */ return; }
    auto& dev = devices.front();
    RealSenseID::FaceAuthenticator authenticator(dev.deviceType);
    auto status = authenticator.Connect({dev.serialPort});
    if (status != RealSenseID::Status::Ok) { /* handle error */ }
```

--------------------------------

### Configure and Query Device Settings

Source: https://context7.com/realsenseai/realsenseid/llms.txt

Sets and retrieves device configuration parameters such as algorithm flow, security level, face selection policy, and camera rotation. This allows fine-tuning of the authentication process.

```cpp
#include "RealSenseID/FaceAuthenticator.h"
#include "RealSenseID/DeviceConfig.h"
#include <iostream>

void configure_device(RealSenseID::FaceAuthenticator& authenticator)
{
    RealSenseID::DeviceConfig cfg;

    // Run full pipeline: face detection + spoof check + recognition
    cfg.algo_flow = RealSenseID::DeviceConfig::AlgoFlow::All;

    // Medium security (balanced FAR/FRR)
    cfg.security_level = RealSenseID::DeviceConfig::SecurityLevel::Medium;

    // Authenticate all faces in frame (up to 5), not just the closest
    cfg.face_selection_policy = RealSenseID::DeviceConfig::FaceSelectionPolicy::All;

    // High matcher confidence (lowest False Positive Rate)
    cfg.matcher_confidence_level = RealSenseID::DeviceConfig::MatcherConfidenceLevel::High;

    // Lock device after 3 consecutive spoof attempts
    cfg.max_spoofs = 3;

    // Enable GPIO pin #1 toggle on successful auth
    cfg.gpio_auth_toggling = 1;

    // Restrict detection to a 400x400 ROI at top-left
    cfg.detection_rois[0] = {0, 0, 400, 400};
    cfg.num_rois = 1;

    RealSenseID::Status set_status = authenticator.SetDeviceConfig(cfg);
    std::cout << "SetDeviceConfig: " << set_status << "\n";

    // Read back
    RealSenseID::DeviceConfig read_cfg;
    RealSenseID::Status q_status = authenticator.QueryDeviceConfig(read_cfg);
    std::cout << "QueryDeviceConfig: " << q_status << "\n";
}
```

--------------------------------

### Build RealSense ID Tools (Linux)

Source: https://github.com/realsenseai/realsenseid/blob/master/tools/README.md

Compile the RealSense ID tools on Linux by creating a build directory, configuring with CMake, and then using make.

```console
> mkdir build
> cd build
> cmake ..
> make

```

--------------------------------

### Query Firmware Version

Source: https://github.com/realsenseai/realsenseid/blob/master/include/RealSenseID/README.md

Retrieves the current firmware version string from the device. The version is returned via the provided string reference.

```cpp
std::string version;
Status status = deviceController.QueryFirmwareVersion(version);
```

--------------------------------

### Enroll User (C#)

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Enroll a user using an arguments object that specifies callback functions for result, progress, and hint events.

```csharp
auth.Enroll(new rsid.EnrollArgs {
    userId = "john", resultClbk = (s, ctx) => {}, progressClbk = (p, ctx) => {}, hintClbk = (h, sc, ctx) => {}
});
```

--------------------------------

### Python Faceprint Extraction and Matching

Source: https://github.com/realsenseai/realsenseid/blob/master/SKILL.md

Shows how to perform faceprint enrollment and authentication using callbacks. Adaptive updates are handled when `should_update` is true.

```python
def on_enroll(status, extracted):
    if status == rsid_py.EnrollStatus.Success:
        db = rsid_py.Faceprints()
        db.version, db.features_type, db.flags = extracted.version, extracted.features_type, extracted.flags
        db.adaptive_descriptor_nomask = extracted.features
        db.enroll_descriptor = extracted.features
        faceprints_db.append(db)
f.extract_faceprints_for_enroll(on_result=on_enroll, on_progress=lambda p: None)

def on_auth(status, new_prints):
    if status != rsid_py.AuthenticateStatus.Success: return
    for db_item in faceprints_db:
        updated = rsid_py.Faceprints()
        result = f.match_faceprints(new_prints, db_item, updated)
        if result.success:
            if result.should_update: db_item = updated  # adaptive update
            break
f.extract_faceprints_for_auth(on_result=on_auth)

```