================================================================================
                        Luxand FaceSDK Python Samples
================================================================================

ABOUT LUXAND FACESDK
--------------------
Luxand FaceSDK is a comprehensive face recognition and facial feature detection
library that enables developers to implement face detection, recognition, and
facial analysis capabilities in their applications. The SDK provides advanced
features including face detection, facial feature tracking, face recognition,
liveness detection, and facial attribute analysis.

FaceSDK supports multiple platforms (Windows, Linux, macOS) and offers a rich
Python API for easy integration into Python applications.


REQUIRED LIBRARIES
------------------
The fsdk directory must contain the appropriate native library for your platform:

  Windows (32-bit):     fsdk/win32/facesdk.dll
  Windows (64-bit):     fsdk/win64/facesdk.dll
  Linux (32-bit):       fsdk/linux32/libfsdk.so
  Linux (64-bit):       fsdk/linux64/libfsdk.so
  Linux (ARM 32-bit):   fsdk/linux32_arm/libfsdk.so
  Linux (ARM 64-bit):   fsdk/linux64_arm/libfsdk.so
  macOS (x86_64):       fsdk/osx_x86_64/libfsdk.dylib

Make sure the correct library is present in the corresponding subdirectory
before running the samples.


PYTHON SAMPLES
--------------

1. ActiveLiveness.py
   Demonstrates active liveness detection through user interaction.
   The sample detects faces and prompts users to perform random actions
   (turn left/right, look up/down, smile) to verify they are real persons.
   Helps prevent spoofing attacks with photos or videos.
   
   Requirements: Camera, Tkinter
   Usage: python ActiveLiveness.py

2. PassiveLiveness.py
   Demonstrates passive liveness detection that automatically analyzes faces
   to determine if they belong to real persons without requiring user actions.
   Uses AI-based analysis to detect spoofing attempts.
   
   Requirements: Camera, Tkinter, PIL
   Usage: python PassiveLiveness.py

3. FacialFeatures.py
   Detects facial features in static images and visualizes them.
   Draws detected facial feature points (eyes, nose, mouth, etc.) on the image.
   Windows-only sample that demonstrates GDI+ graphics capabilities.
   
   Requirements: Windows OS
   Usage: python FacialFeatures.py <input_file> [output_file]
   Example: python FacialFeatures.py photo.jpg features.photo.jpg

4. LiveFacialFeatures.py
   Real-time facial feature detection from video camera feed.
   Displays live video with facial feature points overlaid on detected faces.
   Windows-only sample using native Windows API for display.
   
   Requirements: Windows OS, Camera
   Usage: python LiveFacialFeatures.py

5. LiveFacialFeatures_tk.py
   Cross-platform version of live facial feature detection using Tkinter.
   Provides the same functionality as LiveFacialFeatures.py but works on all
   platforms with Tkinter support.
   
   Requirements: Camera, Tkinter, PIL
   Usage: python LiveFacialFeatures_tk.py

6. LiveRecognition.py
   Real-time face recognition from video camera feed.
   Allows users to enroll new faces and recognize previously enrolled persons.
   Saves face database to tracker70.dat file for persistence.
   Windows-only sample using native Windows API.
   
   Requirements: Windows OS, Camera
   Usage: python LiveRecognition.py

7. LiveRecognition_tk.py
   Cross-platform version of live face recognition using Tkinter.
   Provides interactive face enrollment and recognition with visual feedback.
   Saves and loads face recognition data from tracker70.dat file.
   
   Requirements: Camera, Tkinter, PIL
   Usage: python LiveRecognition_tk.py

8. Lookalikes.py
   Finds similar-looking faces in a database.
   Allows adding photos to a database, removing photos, and searching for
   the most similar faces based on facial templates.
   
   Usage: 
     Add photo to database:    python Lookalikes.py <image_file> -a
     Remove photo from DB:     python Lookalikes.py <image_file> -r
     Find similar faces:       python Lookalikes.py <image_file>

9. Portrait.py
   Extracts and crops face portraits from images.
   Detects a face in the input image, crops it, and saves as a separate file.
   Useful for creating standardized portrait photos.
   
   Usage: python Portrait.py <input_file> [output_file]
   Example: python Portrait.py photo.jpg face.photo.jpg

10. Thermal.py
    Detects faces in thermal camera images.
    Uses a specialized thermal detection model (thermal.bin) to process
    infrared/thermal imagery. Crops and saves detected faces.
    
    Requirements: thermal.bin model file
    Usage: python Thermal.py <input_file> [output_file]
    Example: python Thermal.py thermal_image.jpg face.thermal_image.jpg

11. trackerMemoryTool.py
    Utility for managing FSDK tracker data files.
    Converts tracker data between binary (.dat) and JSON formats, allowing
    inspection, editing, and merging of face recognition databases. 
    For more information read the trackerMemoryTool_manual.pdf.
    
    Usage: 
      Convert to JSON:   python trackerMemoryTool.py tracker70.dat tracker.json
      Convert to binary: python trackerMemoryTool.py tracker.json tracker70.dat
      Merge databases:   python trackerMemoryTool.py db1.dat db2.dat merged.dat


HELPER MODULES
--------------

tk.py
  Helper module providing Tkinter-based window and drawing utilities for
  cross-platform samples.

win.py
  Helper module providing Windows GDI+ graphics wrapper for Windows-only
  samples (FacialFeatures.py, LiveFacialFeatures.py, LiveRecognition.py).

fsdk/
  Python package containing the FaceSDK wrapper and platform-specific
  native libraries.


COMMON DEPENDENCIES
-------------------
- Python 2.7 or Python 3.x
- PIL/Pillow (for image processing in Tkinter samples)
- Tkinter (for cross-platform GUI samples)
- Windows OS (for win.py-based samples)
- Video camera (for live detection/recognition samples)


GETTING STARTED
---------------
1. Ensure the appropriate native library (facesdk.dll, libfsdk.so, or
   libfsdk.dylib) is present in the fsdk subdirectory for your platform.

2. Install required Python dependencies:
   pip install Pillow

3. For simple testing, try the Portrait.py sample with any photo:
   python Portrait.py your_photo.jpg

4. For live camera samples, ensure a camera is connected and run:
   python LiveFacialFeatures_tk.py

5. For face recognition, use LiveRecognition_tk.py to enroll and recognize
   faces interactively.


LICENSE ACTIVATION
------------------
All samples call FSDK.ActivateLibrary("") which uses a trial or registered
license. To use a commercial license, replace the empty string with your
license key.


SUPPORT
-------
For more information about Luxand FaceSDK, visit:
https://www.luxand.com

For technical support and documentation:
https://www.luxand.com/facesdk/


================================================================================
