================================================================================
                    LUXAND FACESDK - IBETA LIVENESS CHECK
                         Advanced Python Sample
================================================================================

DESCRIPTION
-----------
This sample demonstrates how to use Luxand FaceSDK to check liveness of a face
in an image using the IBeta-compliant liveness detection model. The script
analyzes a face image and returns a liveness score indicating whether the face
is real or a presentation attack (photo, video, mask, etc.).

REQUIREMENTS
------------
- Python 3.x
- Luxand FaceSDK license key
- Required library files (see below)

SETUP INSTRUCTIONS
------------------
1. Obtain a valid Luxand FaceSDK license key
2. Open check_liveness.py and insert your license key:
   Replace "INSERT THE LICENSE KEY HERE" with your actual license key

3. Ensure all required library files are in place (see REQUIRED FILES section)

USAGE
-----
Basic command syntax:
    python check_liveness.py <imagefile>

Example:
    python check_liveness.py face_photo.jpg

The script will output:
- Liveness score (confidence value indicating if the face is real)
- Image quality score (if available)

REQUIRED FILES
--------------
The following files must be present in the sample directory:

Core Files:
    - check_liveness.py       Main script
    - fsdk/                   Python module directory
    - data/                   Liveness model data files

For Windows also:
    - win.py                  Windows-specific implementation

For Windows (win64):
--------------------
Place the following DLL files in the same directory as check_liveness.py:

    - idliveface.dll
    - IBetaPlugin.dll
    - openvino.dll
    - openvino_ir_frontend.dll
    - openvino_onnx_frontend.dll
    - openvino_intel_cpu_plugin.dll
    - tbb12.dll
    - plugins.xml

Place the facesdk.dll in the fsdk/win64/ directory.

For Linux (linux64):
--------------------
Place the following shared library files in the fsdk/linux64/ directory:

    - libfsdk.so
    - libIBetaPlugin.so
    - libidliveface.so
    - libopenvino.so.X
    - libopenvino_ir_frontend.so.X
    - libopenvino_onnx_frontend.so.X
    - libopenvino_intel_cpu_plugin.so
    - libtbb.so.X
    - plugins.xml

Note: Files with .X extension indicate versioned libraries (e.g., .so.2024.0)

DIRECTORY STRUCTURE
-------------------
The sample should have the following structure:

    check_liveness.py
    win.py (Windows only)
    readme.txt
    [Library files - .dll for Windows]
    data/
        [Liveness model files]
    fsdk/
        __init__.py
        const.py
        win64/
            facesdk.dll
        linux64/
            libfsdk.so
            [Library files - .so for Linux]

OUTPUT INTERPRETATION
---------------------
Liveness Score:
    - Range: 0 to 100
    - Higher values indicate higher confidence that the face is real
    - Lower values suggest a presentation attack (fake face)

Image Quality:
    - Range: 0 to 100
    - Higher values indicate better image quality for liveness detection

LivenessError:
    - If present, indicates an error during liveness detection
    - Check that the data/ folder contains the required model files

TROUBLESHOOTING
---------------
1. "Luxand FaceSDK activation error"
   -> Check that you've entered a valid license key

2. "Couldn't initialize external liveness model"
   -> Ensure the data/ folder is present and contains liveness model files
   -> Verify all required library files are in the correct location

3. DLL/shared library errors
   -> Verify all library files listed above are present
   -> On Windows: ensure all DLLs are in the same directory as the script
   -> On Linux: ensure libraries are in the library path (LD_LIBRARY_PATH)

4. "Error checking liveness"
   -> Ensure the image file exists and is a valid image format
   -> Check that a face is clearly visible in the image

SUPPORTED IMAGE FORMATS
------------------------
- JPEG (.jpg, .jpeg)
- PNG (.png)
- BMP (.bmp)
- And other common image formats supported by FaceSDK

FOR MORE INFORMATION
--------------------
Visit: https://www.luxand.com/facesdk/
Support: support@luxand.com

================================================================================
Copyright (c) Luxand, Inc.
================================================================================
