Luxand FaceSDK Documentation
Luxand FaceSDK Documentation
Luxand FaceSDK Documentation
http://www.luxand.com
Luxand FaceSDK
6.5.1
Face Detection and Recognition Library
Developer’s Guide
Overview ................................................................................................................................... 6
Requirements ............................................................................................................................ 6
Technical Specifications ........................................................................................................... 7
Face Detection .............................................................................................................................................. 7
Face Matching ............................................................................................................................................... 7
Live Video Recognition with Tracker API .................................................................................................... 7
Facial Feature Detection ............................................................................................................................... 8
Eye Centers Detection................................................................................................................................... 8
Gender Recognition ...................................................................................................................................... 8
Age Recognition ............................................................................................................................................ 8
Facial Expression Recognition ..................................................................................................................... 8
Multi-Core Support ....................................................................................................................................... 8
Library Size ................................................................................................................................................... 8
Installation ................................................................................................................................ 9
Windows ........................................................................................................................................................ 9
Linux/macOS ................................................................................................................................................. 9
Directory Structure ......................................................................................................................................... 9
Sample Applications ................................................................................................................. 9
Using FaceSDK with Programming Languages .................................................................. 11
Using with .NET (C# and VB) ..................................................................................................................... 11
Using CImage class in .NET......................................................................................................................... 12
CImage(); ................................................................................................................................................ 13
CImage(Int); ............................................................................................................................................ 13
CImage.ReloadFromHandle(); ................................................................................................................ 13
Using with C/C++ ........................................................................................................................................ 13
Using with Delphi ........................................................................................................................................ 14
Using with Java ............................................................................................................................................ 14
Using with Cocoa ......................................................................................................................................... 14
Using with VisualBasic 6.0 .......................................................................................................................... 14
Using with iOS ............................................................................................................................................. 15
Using with Android ...................................................................................................................................... 15
Unicode support ........................................................................................................................................... 15
Redistributables ...................................................................................................................... 15
Usage Scenarios ...................................................................................................................... 16
Library Activation.................................................................................................................. 17
FSDK_GetHardware_ID Function ................................................................................................................ 17
FSDK_ActivateLibrary Function .................................................................................................................. 18
FSDK_GetLicenseInfo Function .................................................................................................................. 18
Initialization ............................................................................................................................ 19
FSDK_Initialize Function ............................................................................................................................. 19
FSDK_Finalize Function .............................................................................................................................. 19
Working with Images ............................................................................................................. 20
FSDK_CreateEmptyImage Function ............................................................................................................ 21
FSDK_LoadImageFromFile Function .......................................................................................................... 21
FSDK_LoadImageFromFileW Function ....................................................................................................... 22
FSDK_SaveImageToFile Function ............................................................................................................... 22
Requirements
The FaceSDK library supports the following platforms:
Windows XP SP3/2003 SP2/Vista/2008/2012, Windows 7, Windows 8, Windows 10
Linux (RHEL 5+, CentOS 5+ and other)
Linux/ARMv7 (Raspberry Pi2+)
macOS 10.7+ x86_64
iOS 5.0+, armv7/x86 (iPhone 3GS+, iPad 1+, simulator)
iOS 7.0+, arm64/x86_64(iPhone 5S+, iPad Air+, iPad mini retina+, simulator)
Android 4.0+ (platform version 14+), armv7 (armeabi-v7a)/x86
An Intel processor is recommended for better performance.
Minimum system requirements:
1 GHz processor
256 MB RAM
Recommended system requirements:
Intel Core i7 or Xeon processor
2 GB RAM
DirectShow-compatible webcam (on Windows)
IP camera with MJPEG interface (like AXIS IP cameras)
Note that the web camera functions are available only for the Windows platform. IP cameras
are accessible on all platforms.
Face Detection
Robust frontal face detection
Detection of multiple faces in a photo
Head rotation support: –30..30 degrees of in-plane rotation and –30..30 degrees out-
of-plane rotation
Determines in-plane face rotation angle
Detection speed:
o Realtime detection (webcam resolution, –15..15 degrees of in-plane head
rotation): 0.0009 seconds (1111 FPS) (Intel*), 0.0011 seconds (909 FPS)
(iOS*), 0.006 seconds (166 FPS) (Android*)
o Reliable detection (digital camera resolution, –30..30 degrees of in-plane head
rotation): 0.014 seconds (Intel), 0.037 seconds (iOS), 0.19 seconds (Android)
Returned information for each detected face: (x,y) coordinates of face center, face
width and rotation angle
Easy configuration of face detection parameters
Face Matching
Matching of two faces at given FAR (False Acceptance Rate) and FRR (False
Rejection Rate)
Enrollment time:
o Webcam resolution, using FSDK_GetFaceTemplate: 0.015 seconds (67 FPS)
(Intel), 0.026 seconds (38 FPS) (iOS), 0.14 seconds (7 FPS) (Android)
Template Size: 1040 bytes
Matching speed:
o Single thread, templates per second: 3571428 (Intel), 3205128 (iOS), 93284
(Android)
o Multiple parallel threads, templates per second: 26595745 (Intel), 10948905
(iOS), 287811 (Android)
Returned information: facial similarity level
Gender Recognition
Recognition of different genders
Gender recognition time (not including face and facial feature detection stages):
0.0052 seconds (Intel), 0.0076 seconds (iOS), 0.015 seconds (Android)
Returned information: confidence level in each gender
Age Recognition
Recognition of age
Age recognition time (not including face and facial feature detection stages): 0.0056
seconds (Intel), 0.014 seconds (iOS), 0.016 seconds (Android)
Returned information: age of a person
Multi-Core Support
The library uses all available processor cores when executing face detection or
recognition functions to maximize the performance.
Library Size
The size of the redistributables does not exceed 110 MB for each platform.
*
Measured on Intel Xeon 8124M processor with 8 threads, iPhone X with 6 threads, Xiaomi
mi5 (Snapdragon 820) with 4 threads.
Linux/macOS
Unpack the Luxand_FaceSDK.tar.bz2 archive into the desired directory.
Directory Structure
The FaceSDK directory contains the following directories and files:
Sample Applications
FaceSDK is distributed with the following sample applications (they can be found in the
FaceSDK samples\ directory):
CImage();
Creates an empty CImage instance.
Syntax:
FSDK.CImage();
CImage(Int);
Creates a CImage instance from image already loaded to FaceSDK.
Syntax:
FSDK.CImage(int ImageHandle);
Parameters:
ImageHandle – the internal handle of an image already loaded to FaceSDK. The destructor
will free the ImageHandle handle.
CImage.ReloadFromHandle();
Updates the internal properties of a CImage instance in accordance with the ImageHandle.
Syntax:
FSDK.CImage.ReloadFromHandle();
Unicode support
The library supports Unicode filenames on the Windows platform. If you work with file
names in the Unicode character set, use functions FSDK_LoadImageFromFileW and
FSDK_SaveImageToFileW to open and save files.
Redistributables
The following files may be redistributed with your application:
Usage Scenarios
The library usage level depends on the functionality required from Luxand FaceSDK.
If you work with video, consider using Tracker API, as the API provides high-level functions
to recognize subjects and tag them with names, to track their faces and facial features, and to
recognize gender, age and facial expressions. The usage scenario for Tracker API can be
found in the Usage Scenario section of the Tracker API chapter.
Otherwise, the typical scenario is as follows:
1. Activate FaceSDK by calling up the FSDK_ActivateLibrary function with the key
sent by Luxand, Inc.
2. Initialize FaceSDK by calling up the FSDK_Initialize function.
3. Load images either from a file, a buffer or the HBITMAP handle
(FSDK_LoadImageFromFile, FSDK_LoadImageFromBuffer,
FSDK_LoadImageFromHBitmap functions).
4. Set face detection parameters if needed (FSDK_SetFaceDetectionParameters,
FSDK_SetFaceDetectionThreshold).
5. Use FaceSDK functions:
Detect a face (FSDK_DetectFace) or multiple faces
(FSDK_DetectMultipleFaces) in an image
Detect facial features if needed (FSDK_DetectFacialFeatures,
FSDK_DetectFacialFeaturesInRegion)
Extract a face template from the image (FSDK_GetFaceTemplate,
FSDK_GetFaceTemplateInRegion,
FSDK_GetFaceTemplateUsingFeatures)
Match the face templates (FSDK_MatchFaces) and acquire the facial
similarity level
To find out if a face belongs to the same person, calculate the matching
threshold at a given FAR or FRR rate
(FSDK_GetMatchingThresholdAtFAR and
FSDK_GetMatchingThresholdAtFRR functions).
6. Finalize the FaceSDK library (FSDK_Finalize function).
*
If you work with an IP camera, you should not follow steps 2, 3, 4, 8 and 9.
Library Activation
FaceSDK is a copy-protected library, and must be activated with a license key before its use.
You need to pass the license key received from Luxand, Inc. to the FSDK_ActivateLibrary
function before initializing Luxand FaceSDK. Almost all FaceSDK functions will return the
FSDKE_NOT_ACTIVATED error code in case the library is not activated. To retrieve your
license information, call FSDK_GetLicenseInfo. This function returns the name the library is
licensed to. You may need to use the FSDK_GetHardware_ID function to obtain your
hardware ID if your license is restricted to one machine only. Additionally, you can find out
hardware ID by running the hardwareid program (ShowHardwareID.exe for
Windows), which is located in the bin directory.
To get a temporary evaluation key from Luxand, Inc., run License Key Wizard from the Start
– Luxand – FaceSDK menu.You may also request this key at
http://luxand.com/facesdk/requestkey/.
FSDK_GetHardware_ID Function
Generates a Hardware ID code.
C++ Syntax:
int FSDK_GetHardware_ID(char* HardwareID);
Delphi Syntax:
function FSDK_GetHardware_ID(HardwareID: PChar): integer;
C# Syntax:
int FSDK.GetHardwareID(out string HardwareID);
VB Syntax:
Function FSDKVB_GetHardwareID(ByRef HardwareID As Byte) As
Long
Parameters:
HardwareID – address of the null-terminated string for receiving the Hardware ID code.
Return Value:
Returns FSDKE_OK if successful.
FSDK_ActivateLibrary Function
Activates the FaceSDK library.
C++ Syntax:
int FSDK_ActivateLibrary(char* LicenseKey);
Delphi Syntax:
function FSDK_ActivateLibrary(LicenseKey: PChar): integer;
C# Syntax:
int FSDK.ActivateLibrary(out string LicenseKey);
VB Syntax:
Function FSDKVB_ActivateLibrary(ByVal LicenseKey As String) As
Long
Java and Android Syntax:
int FSDK.ActivateLibrary(String LicenseKey);
Parameters:
LicenseKey– License key you received from Luxand, Inc.
Return Value:
Returns FSDKE_OK if the registration key is valid and not expired.
FSDK_GetLicenseInfo Function
Retrieves license information.
C++ Syntax:
int FSDK_GetLicenseInfo(char* LicenseInfo);
Delphi Syntax:
function FSDK_GetLicenseInfo(LicenseInfo: PAnsiChar): integer;
C# Syntax:
int FSDK.GetLicenseInfo(out string LicenseInfo);
Initialization
FSDK_Initialize Function
Initializes the FaceSDK library. Should be called before using of any face detection functions.
C++ Syntax:
int FSDK_Initialize(char* DataFilesPath);
Delphi Syntax:
function FSDK_Initialize(DataFilesPath: PChar): integer;
C# Syntax:
int FSDK.InitializeLibrary();
VB Syntax:
Function FSDKVB_Initialize(ByRef DataFilesPath As Byte) As
Long
Java and Android Syntax:
int FSDK.Initialize();
Parameters:
DataFilesPath – pointer to the null-terminated string specifying the path where
facesdk.dll is stored. An empty string means the current directory. (Note: the parameter is not
used since FaceSDK 1.8; an empty string might be passed as this parameter.)
Return Value:
Returns FSDKE_OK if successful or FSDK_IO_ERROR if an I/O error occurs.
FSDK_Finalize Function
Finalizes the FaceSDK library. Should be called when the application is exited.
C++ Syntax:
FaceSDK provides a number of functions to load images to the internal representation from
files, buffers or HBITMAP handles and to save images from the internal representation to
files, buffers and HBITMAP handles. Each FSDK_LoadImageFromXXXX function creates a
new HImage handle, which can be deleted using the FSDK_FreeImage function.
Note that when you perform multiple stages of recognition on large images (for example,
when you first detect a face, and then create its template using
FSDK_GetFaceTemplateInRegion), consider first resizing the image to a smaller size to
speed up operations. Note that you must resize the image to dimensions no smaller than the
InternalResizeWidth parameter of the FSDK_SetFaceDetectionParameters function if you
perform face detection, in order to keep the same accuracy of face detection.
FSDK_LoadImageFromFile Function
Loads the image from a file and provides the internal handle of this image.
C++ Syntax:
int FSDK_LoadImageFromFile(HImage* Image, char* FileName);
Delphi Syntax:
function FSDK_LoadImageFromFile(Image: PHImage; FileName:
PAnsiChar): integer;
C# Syntax:
int FSDK.LoadImageFromFile(ref int Image, string FileName)
VB Syntax:
Function FSDKVB_LoadImageFromFile(ByRef Image As Long, ByVal
FileName As String) As Long
Java and Android Syntax:
int FSDK.LoadImageFromFile(HImage Image, String FileName);
FSDK_LoadImageFromFileW Function
Loads the image from a file path in the Unicode character set and provides the internal handle
of this image. The function is available only on Windows platforms.
C++ Syntax:
int FSDK_LoadImageFromFileW(HImage* Image, wchar_t* FileName);
Delphi Syntax:
function FSDK_LoadImageFromFileW(Image: PHImage; FileName:
PWideChar): integer;
C# Syntax:
int FSDK.LoadImageFromFileW(ref int Image, string FileName)
Java Syntax:
int FSDK.LoadImageFromFileW(HImage Image, String FileName);
Parameters:
Image – pointer to HImage for receiving the loaded image handle.
FileName – filename of the image to be loaded. FaceSDK supports the JPG, PNG and BMP
file formats.
Return Value:
Returns FSDKE_OK if successful.
This function is not available in Visual Basic 6.0.
FSDK_SaveImageToFile Function
Saves an image to a file. When saving to .jpg files, you can set the quality of JPEG
compression using the FSDK_SetJpegCompressionQuality function.
C++ Syntax:
int FSDK_SaveImageToFile(HImage Image, char* FileName);
Delphi Syntax:
function FSDK_SaveImageToFile(Image: HImage; FileName:
PAnsiChar): integer;
Example
int img1;
FSDK_Initialize("");
FSDK_LoadImageFromFile(&img1, "test.bmp"); // load .bmp file
FSDK_SaveImageToFile(img1, "test.jpg"); // save as .jpg
FSDK_SaveImageToFileW Function
Saves an image to a file path in the Unicode character set. The function is available only on
Windows platforms. When saving to .jpg files, you can set the quality of the JPEG
compression using the FSDK_SetJpegCompressionQuality function.
C++ Syntax:
int FSDK_SaveImageToFileW(HImage Image, wchar_t* FileName);
Delphi Syntax:
function FSDK_SaveImageToFileW(Image: HImage; FileName:
PWideChar): integer;
C# Syntax:
int FSDK.SaveImageToFileW(int Image, string FileName);
Java Syntax:
int FSDK.SaveImageToFileW(HImage Image, String FileName);
FSDK_LoadImageFromBuffer Function
Loads an image from a buffer and provides the internal handle of this image. The function
suggests that the image data is organized in a top-to-bottom order, and the distance between
adjacent rows is ScanLine bytes (for example, in the 24-bit image, the ScanLine value might
be 3*Width bytes if there is no spacing between adjacent rows). The following image modes
are supported:
C++ Syntax:
int FSDK_LoadImageFromBuffer(HImage* Image, unsigned char*
Buffer, int Width, int Height, int ScanLine, FSDK_IMAGEMODE
ImageMode);
Delphi Syntax:
function FSDK_LoadImageFromBuffer(Image: PHImage; var Buffer;
Width, Height: integer; ScanLine: integer; ImageMode:
FSDK_IMAGEMODE): integer;
C# Syntax:
int FSDK.LoadImageFromBuffer(ref int Image, byte[] Buffer, int
Width, int Height, int ScanLine, FSDK_IMAGEMODEImageMode);
VB Syntax:
Function FSDKVB_LoadImageFromBuffer(ByRef Image As Long, ByRef
Buffer As Byte, ByVal Width As Long, ByVal Height As Long,
ByVal ScanLine As Long, ByVal ImageMode As FSDK_IMAGEMODE) As
Long
FSDK_LoadImageFromJpegBuffer Function
Loads an image from a buffer containing JPEG data, and provides the handle of this image.
C++ Syntax:
int FSDK_LoadImageFromJpegBuffer (HImage* Image, unsigned
char* Buffer, unsigned int BufferLength);
Delphi Syntax:
function FSDK_LoadImageFromJpegBuffer (Image: PHImage; var
Buffer; BufferLength: integer): integer;
VB Syntax:
Function FSDKVB_LoadImageFromJpegBuffer (ByRef Image As Long,
ByRef Buffer As Byte, ByVal BufferLength As Long) As Long
Android Syntax:
int FSDK.LoadImageFromJpegBuffer(HImage Image, byte Buffer[],
int BufferLength);
Parameters:
Image – pointer to HImage for receiving the loaded image handle.
Buffer – pointer to the buffer containing the image data in JPEG format (usually loaded
from a JPEG file).
BufferLength – size of buffer in bytes.
Return Value:
Returns FSDKE_OK if successful.
FSDK_LoadImageFromPngBuffer Function
Loads an image from a buffer containing PNG data and provides the handle of this image.
C++ Syntax:
int FSDK_LoadImageFromPngBuffer (HImage* Image, unsigned char*
Buffer, unsigned int BufferLength);
Delphi Syntax:
function FSDK_LoadImageFromPngBuffer (Image: PHImage; var
Buffer; BufferLength: integer): integer;
VB Syntax:
Function FSDKVB_LoadImageFromPngBuffer (ByRef Image As Long,
ByRef Buffer As Byte, ByVal BufferLength As Long) As Long
Android Syntax:
int FSDK.LoadImageFromPngBuffer(HImage Image, byte Buffer[],
int BufferLength);
Parameters:
Image – pointer to HImage for receiving the loaded image handle.
Buffer – pointer to the buffer containing the image data in PNG format (usually loaded
from a PNG file).
BufferLength – size of buffer in bytes.
Return Value:
Returns FSDKE_OK if successful.
The function is not available in .NET and Java.
FSDK_GetImageBufferSize Function
Returns the size of the buffer required to store an image.
C++ Syntax:
int FSDK_GetImageBufferSize(HImage Image, int * BufSize,
FSDK_IMAGEMODE ImageMode);
Delphi Syntax:
function FSDK_GetImageBufferSize(Image: HImage; BufSize:
PInteger; ImageMode: FSDK_IMAGEMODE): integer;
C# Syntax:
int FSDK.GetImageBufferSize(intImage, ref int BufSize,
FSDK_IMAGEMODEImageMode);
FSDK_SaveImageToBuffer Function
Saves an image to a buffer in the desired image mode. Refer to the
FSDK_LoadImageFromBuffer function description to read more about image modes.
C++ Syntax:
int FSDK_SaveImageToBuffer(HImage Image, unsigned char*
Buffer, FSDK_IMAGEMODE ImageMode);
Delphi Syntax:
function FSDK_SaveImageToBuffer(Image: HImage; var Buffer;
ImageMode: FSDK_IMAGEMODE): integer;
C# Syntax:
int FSDK.SaveImageToBuffer(intImage, out byte[]Buffer,
FSDK_IMAGEMODEImageMode);
VB Syntax:
Function FSDKVB_SaveImageToBuffer(ByVal Image As Long, ByRef
Buffer As Byte, ByVal ImageMode As FSDK_IMAGEMODE) As Long
Android Syntax:
int FSDK.SaveImageToBuffer(HImage Image, byte Buffer[],
FSDK_IMAGEMODE ImageMode);
Java Syntax:
int FSDK.SaveImageToBuffer(HImage Image, byte Buffer[],
intImageMode);
FSDK_LoadImageFromHBitmap Function
Loads the image from an HBITMAP handle and provides the internal handle of this image.
C++ Syntax:
int FSDK_LoadImageFromHBitmap(HImage* Image, HBITMAP*
BitmapHandle);
Delphi Syntax:
function FSDK_LoadImageFromHBitmap(Image: PHImage;
BitmapHandle: HBitmap): integer;
C# Syntax:
int FSDK.LoadImageFromHBitmap(ref int Image, IntPtr
BitmapHandle);
VB Syntax:
Function FSDKVB_LoadImageFromHBitmap(ByRef Image As Long,
ByVal BitmapHandle As Integer) As Long
CImage Syntax:
FSDK.CImage(IntPtr BitmapHandle);
Parameters:
Image – pointer to HImage for receiving the loaded image handle.
BitmapHandle – handle of the image to be loaded.
Return Value:
Returns FSDKE_OK if successful.
FSDK_SaveImageToHBitmap Function
Creates an HBITMAP handle containing the image.
C++ Syntax:
int FSDK_SaveImageToHBitmap(HImage Image, HBITMAP*
BitmapHandle);
Delphi Syntax:
function FSDK_SaveImageToHBitmap(Image: HImage; BitmapHandle:
PHBitmap): integer;
FSDK.LoadImageFromCLRImage Function
Loads the image from the System.Drawing.Image object and provides the internal handle of
this image.
C# Syntax:
int FSDK.LoadImageFromCLRImage(ref int Image,
System.Drawing.Image ImageObject);
CImage Syntax:
FSDK.CImage(System.Drawing.Image ImageObject);
Parameters:
Image – reference to HImage for receiving the loaded image handle.
ImageObject – object of the image to be loaded.
Return Value:
Returns FSDKE_OK if successful.
FSDK.SaveImageToCLRImage Function
Creates a System.Drawing.Image object containing the image.
C# Syntax:
int FSDK.SaveImageToCLRImage(int Image, ref
System.Drawing.Image ImageObject);
CImage Syntax:
System.Drawing.Image FSDK.CImage.ToCLRImage();
Parameters:
Image – internal handle of the image to be saved to System.Drawing.Image.
FSDK.LoadImageFromAWTImage Function
Loads the image from the java.awt.Image object and provides the internal handle of this
image.
Java Syntax:
int FSDK.LoadImageFromAWTImage(HImage Image, java.awt.Image
SourceImage, int ImageMode);
Parameters:
Image – HImage for receiving the loaded image.
SourceImage – java.awt.Image object of the image to be loaded.
ImageMode - mode of an image. (See FSDK_LoadImageFromBuffer for more
information about image modes.)
Return Value:
Returns FSDKE_OK if successful.
FSDK.SaveImageToAWTImage Function
Creates a java.awt.Image object containing the image.
Java Syntax:
int FSDK.SaveImageToAWTImage(HImage Image, java.awt.Image
DestImage[], int ImageMode);
Parameters:
Image – internal handle of the image to be saved to System.Drawing.Image.
DestImage[] – java.awt.Image object the image will be saved to.
ImageMode - desired mode an image will be saved in.
Return Value:
Returns FSDKE_OK if successful.
FSDK_SetJpegCompressionQuality
Sets the quality of the JPEG compression to use in the FSDK_SaveImageToFile function.
C++ Syntax:
int FSDK_SetJpegCompressionQuality(int Quality);
Delphi Syntax:
function FSDK_SetJpegCompressionQuality(Quality: integer):
integer;
FSDK_GetImageWidth Function
Returns the width of an image.
C++ Syntax:
int FSDK_GetImageWidth(HImage SourceImage, int* Width);
Delphi Syntax:
function FSDK_GetImageWidth(SourceImage: HImage; Width:
PInteger): integer;
C# Syntax:
int FSDK.GetImageWidth(int SourceImage, ref int Width);
VB Syntax:
Function FSDKVB_GetImageWidth(ByVal SourceImage As Long, ByRef
Width As Long) As Long
Java and Android Syntax:
int FSDK.GetImageWidth(HImage SourceImage, int Width[]);
CImage Syntax:
int FSDK.CImage.Width;
Parameters:
SourceImage – internal handle of an image.
Width – pointer to an integer variable to store the width of an image.
Return Value:
Returns FSDKE_OK if successful.
FSDK_CopyImage Function
Creates a copy of an image. The handle of the destination image should be created with
the FSDK_CreateEmptyImage function.
C++ Syntax:
int FSDK_CopyImage(HImage SourceImage, HImage DestImage);
Delphi Syntax:
function FSDK_CopyImage(SourceImage: HImage; DestImage:
HImage): integer;
C# Syntax:
int FSDK.CopyImage(int SourceImage, int DestImage);
VB Syntax:
Function FSDKVB_CopyImage(ByVal SourceImage As Long, ByVal
DestImage As Long) As Long
FSDK_ResizeImage Function
Changes the size of an image. The handle of the destination image should be created with
the FSDK_CreateEmptyImage function.
C++ Syntax:
int FSDK_ResizeImage(HImage SourceImage, double ratio, HImage
DestImage);
Delphi Syntax:
function FSDK_ResizeImage (SourceImage: HImage; ratio: double;
DestImage: HImage): integer;
C# Syntax:
int FSDK.ResizeImage(int SourceImage, double ratio, int
DestImage);
VB Syntax:
Function FSDKVB_ResizeImage (ByVal SourceImage As Long, ByVal
ratio As Double, ByVal DestImage As Long) As Long
Java and Android Syntax:
int FSDK.ResizeImage(HImage SourceImage, double ratio, HImage
DestImage);
CImage Syntax:
FSDK.CImage FSDK.CImage.Resize(double ratio);
Parameters:
SourceImage – handle of an image to be resized.
Ratio – factor by which the x and y dimensions of the source image are changed. A factor
value greater than 1 corresponds to increasing the image size.
DestImage – handle of the destination image.
Return Value:
Returns FSDKE_OK if successful.
FSDK_RotateImageCenter Function
Rotates an image around an arbitrary center. The handle of the destination image should be
created with the FSDK_CreateEmptyImage function.
C++ Syntax:
int FSDK_RotateImageCenter(HImage SourceImage, double angle,
double xCenter, double yCenter, HImage DestImage);
Delphi Syntax:
function FSDK_RotateImageCenter (SourceImage: HImage; angle:
double; xCenter: double; yCenter: double; DestImage:
HImage;): integer;
FSDK_RotateImage90 Function
Rotates the image by 90 or 180 degrees clockwise or counter-clockwise. The handle of the
destination image should be created with the FSDK_CreateEmptyImage function.
C++ Syntax:
int FSDK_RotateImage90(HImage SourceImage, int Multiplier,
HImage DestImage);
Delphi Syntax:
function FSDK_RotateImage90(SourceImage: HImage; Multiplier:
integer;DestImage: HImage): integer;
C# Syntax:
int FSDK.RotateImage90(int SourceImage, int Multiplier, int
DestImage);
VB Syntax:
Function FSDKVB_RotateImage90(ByVal SourceImage As Long, ByVal
Multiplier As Long, ByVal DestImage As Long) As Long
Java and Android Syntax:
int FSDK.RotateImage90(HImage SourceImage, int Multiplier,
HImage DestImage);
FSDK_CopyRect Function
Creates a copy of a rectangular area of an image. The handle of the destination image should
be created with the FSDK_CreateEmptyImage function. If some apex of a rectangle is located
outside the source image, rectangular areas that do not contain the source image will be black.
C++ Syntax:
int FSDK_CopyRect(HImage SourceImage, int x1, int y1, int x2,
int y2, HImage DestImage);
Delphi Syntax:
function FSDK_CopyRect (SourceImage: HImage; x1, y1, x2, y2:
integer; DestImage: HImage): integer;
C# Syntax:
int FSDK.CopyRect (int SourceImage, int x1, int y1, int x2,
int y2, int DestImage);
VB Syntax:
Function FSDKVB_CopyRect (ByVal SourceImage As Long, ByVal x1
As Long, ByVal y1 As Long, ByVal x2 As Long, ByVal y2 As Long,
ByVal DestImage As Long) As Long
Java and Android Syntax:
int FSDK.CopyRect(HImage SourceImage, int x1, int y1, int x2,
int y2, HImage DestImage);
CImage Syntax:
FSDK.CImage FSDK.CImage.CopyRect(int x1, int y1, int x2, int
y2);
Parameters:
SourceImage – handle of an image to copy the rectangle from.
x1 – the X coordinate of the bottom left corner of the copied rectangle.
y1 – the Y coordinate of the bottom left corner of the copied rectangle.
x2 – the X coordinate of the top right corner of the copied rectangle.
FSDK_CopyRectReplicateBorder Function
Creates a copy of a rectangular area of an image and adds replicated border pixels. The handle
of the destination image should be created with the FSDK_CreateEmptyImage function.
This function copies the source image to the destination image and fills pixels ("border")
outside the copied area in the destination image with the values of the nearest source image
pixels.
C++ Syntax:
int FSDK_CopyRectReplicateBorder(HImage SourceImage, int x1,
int y1, int x2, int y2, HImage DestImage);
Delphi Syntax:
function FSDK_CopyRectReplicateBorder(SourceImage: HImage; x1,
y1, x2, y2: integer; DestImage: HImage): integer;
C# Syntax:
int FSDK.CopyRectReplicateBorder(int SourceImage, int x1, int
y1, int x2, int y2, int DestImage);
VB Syntax:
Function FSDKVB_CopyRectReplicateBorder(ByVal SourceImage As
Long, ByVal x1 As Long, ByVal y1 As Long, ByVal x2 As Long,
ByVal y2 As Long, ByVal DestImage As Long) As Long
Java and Android Syntax:
int FSDK.CopyRectReplicateBorder(HImage SourceImage, int x1,
int y1, int x2, int y2, HImage DestImage);
CImage Syntax:
FSDK.CImage FSDK.CImage.CopyRectReplicateBorder(int x1, int
y1, int x2, int y2);
Parameters:
SourceImage – handle of an image to copy the rectangle from.
x1 – the X coordinate of the left bottom corner of the copied rectangle.
y1 – the Y coordinate of the left bottom corner of the copied rectangle.
x2 – the X coordinate of the right top corner of the copied rectangle.
y2 – the Y coordinate of the right top corner of the copied rectangle.
DestImage –handle of the destination image.
Return Value:
Returns FSDKE_OK if successful.
FSDK_FreeImage Function
Frees the internal representation of an image.
C++ Syntax:
int FSDK_FreeImage(HImage Image);
Delphi Syntax:
function FSDK_FreeImage(Image: HImage): integer;
C# Syntax:
int FSDK.FreeImage(int Image);
Face Detection
You can use the FSDK_DetectFace function to detect a frontal face in an image. The function
returns the position of the face in the image. The performance and reliability of face detection
is controlled by the FSDK_SetFaceDetectionParametersand
FSDK_SetFaceDetectionThreshold functions.
Typical parameters for face detection are:
To detect faces from a webcam in real time, call:
FSDK_SetFaceDetectionParameters(false, false, 100);
To reliably detect faces in digital camera photos, call
FSDK_SetFaceDetectionParameters(true, false, 500);
Data types
Luxand FaceSDK introduces the TFacePosition data type that stores the information about the
position of the face. The xc and yc fields specifies the X and Y coordinates of the center of
the face, w specifies the width of the face, and angle specifies the in-plane rotation angle of
the face in degrees.
C++ Declaration:
typedef struct {
int xc, yc, w;
int padding;
double angle;
} TFacePosition;
C# Declaration:
public struct TFacePosition {
public int xc, yc, w;
public double angle;
}
Delphi Declaration:
TFacePosition = record
xc, yc, w: integer;
The class TFaces encapsulates an array of TFacePosition classses. It has the following
properties:
public TFacePosition faces[];
int maxFaces;
FSDK_DetectFace Function
Detects a frontal face in an image and stores information about the face position into the
TFacePosition structure.
C++ Syntax:
int FSDK_DetectFace(HImage Image, TFacePosition*
FacePosition);
Delphi Syntax:
function FSDK_DetectFace(Image: HImage; FacePosition:
PFacePosition): integer;
C# Syntax:
int FSDK.DetectFace(int Image, ref FSDK.TFacePosition
FacePosition);
VB Syntax:
Function FSDKVB_DetectFace(ByVal Image As Long, ByRef
FacePosition As TFacePosition) As Long
Java Syntax:
int FSDK.DetectFace(HImage Image, TFacePosition.ByReference
FacePosition);
Example
int img1;
TFacePosition FacePosition;
FSDK_Initialize("");
FSDK_LoadImageFromFile(&img1, "test.jpg");
FSDK_DetectFace(img1, &FacePosition);
FSDK_DetectMultipleFaces Function
Detects multiple faces in an image.
C++ Syntax:
int FSDK_DetectMultipleFaces(HImage Image, int* DetectedCount,
TFacePosition* FaceArray, int MaxSizeInBytes);
Delphi Syntax:
function FSDK_DetectMultipleFaces(Image: HImage;
DetectedCount: PInteger; FaceArray: PFacePositionArray;
MaxSizeInBytes: integer): integer;
C# Syntax:
int FSDK.DetectMultipleFaces(int Image, ref int DetectedCount,
out FSDK.TFacePosition[] FaceArray, int MaxSizeInBytes);
VB Syntax:
Function FSDKVB_DetectMultipleFaces(ByVal Image As Long, ByRef
DetectedCount As Long, ByRef FaceArray As TFacePosition, ByVal
MaxSizeInBytes As Long) As Long
FSDK_Initialize("");
FSDK_LoadImageFromFile(&img1, "test.jpg");
FSDK_DetectMultipleFaces(img1, &DetectedCount , FaceArray,
sizeof(FaceArray));
FSDK_SetFaceDetectionParameters Function
Allows setting a number of face detection parameters to control the performance and
reliability of face detector.
The function allows configuring the following parameters: HandleArbitraryRotations,
DetermineFaceRotationAngle and InternalResizeWidth.
HandleArbitraryRotations, DetermineFaceRotationAngle can be TRUE or FALSE, while
InternalResizeWidth is an integer.
C++ Syntax:
int FSDK_SetFaceDetectionParameters(bool
HandleArbitraryRotations, bool DetermineFaceRotationAngle, int
InternalResizeWidth);
FSDK_SetFaceDetectionThreshold Function
Sets a threshold value for face detection. The default value is 5. The lowest possible value is
1.
The function allows adjusting the sensitivity of the detection. If the threshold value is set to a
higher value, the detector will only recognize faces with sharp, clearly defined details, thus
reducing the number of false positive detections. Setting the threshold lower allows detecting
more faces with less clearly defined features at the expense of increased number of false
positives.
C++ Syntax:
int FSDK_SetFaceDetectionThreshold(int Threshold);
Delphi Syntax:
function FSDK_SetFaceDetectionThreshold(Threshold: integer):
integer;
C# Syntax:
int FSDK.SetFaceDetectionThreshold(int Threshold);
VB Syntax:
Function FSDKVB_SetFaceDetectionThreshold(ByVal Threshold As
Long) As Long
Java and Android Syntax:
int FSDK.SetFaceDetectionThreshold(int Threshold);
Parameters:
Threshold – Threshold value.
Return Value:
Returns FSDKE_OK if successful.
C# Declaration:
public struct TPoint {
public int x, y;
}
Delphi Declaration:
TPoint = record
x, y: integer;
end;
FSDK_Features = array[0..FSDK_FACIAL_FEATURE_COUNT - 1] of
TPoint;
PFSDK_Features = ^FSDK_Features;
VB Declaration:
Type TPoint
x As Long
y As Long
End Type
Java and Android Declaration:
The class TPoint has the following properties:
public int x, y;
Example
int img1;
FSDK_Features Features;
FSDK_Initialize("");
FSDK_LoadImageFromFile(&img1, "test.jpg");
FSDK_DetectFacialFeatures(img1, Features);
FSDK_DetectFacialFeaturesInRegion Function
Detects facial features in an image region returned by FSDK_DetectFace or
FSDK_DetectMultipleFaces. This function can be useful if an approximate face size is
known, or to detect facial features of a specific face returned by FSDK_DetectMultipleFaces.
C++ Syntax:
int FSDK_DetectFacialFeaturesInRegion(HImage Image,
TFacePosition* FacePosition, FSDK_Features* FacialFeatures);
Delphi Syntax:
function FSDK_DetectFacialFeaturesInRegion(Image: HImage;
FacePosition: PFacePosition; FacialFeatures: PFSDK_Features):
integer;
C# Syntax:
int FSDK.DetectFacialFeaturesInRegion(int Image, ref
FSDK.TFacePosition FacePosition, out FSDK.TPoint[]
FacialFeatures);
VB Syntax:
Function FSDKVB_DetectFacialFeaturesInRegion(ByVal Image As
Long, ByRef FacePosition As TFacePosition, ByRef
FacialFeatures As TPoint) As Long
Java Syntax:
int FSDK.DetectFacialFeaturesInRegion(HImage Image,
TFacePosition FacePosition, FSDK_Features.ByReference
FacialFeatures);
Android Syntax:
int FSDK.DetectFacialFeaturesInRegion(HImage Image,
TFacePosition FacePosition, FSDK_Features FacialFeatures);
C# Syntax:
FSDK.TPoint[] FSDK.CImage.DetectFacialFeaturesInRegion(ref
FSDK.TFacePosition FacePosition);
Parameters:
Image – handle of the image facial features should be detected in.
FacePosition – pointer to the face position structure.
FacialFeatures – pointer to the FSDK_Features array for receiving the detected facial
features.
Return Value:
Returns FSDKE_OK if successful.
FSDK_Initialize("");
FSDK_LoadImageFromFile(&img1, "test.jpg");
FSDK_DetectEyes Function
Detects a frontal face in an image and detects its eye centers.
C++ Syntax:
int FSDK_DetectEyes(HImage Image, FSDK_Features*
FacialFeatures);
Delphi Syntax:
function FSDK_DetectEyes(Image: HImage; FacialFeatures:
PFSDK_Features): integer;
C# Syntax:
int FSDK.DetectEyes(int Image, out FSDK.TPoint[]
FacialFeatures);
VB Syntax:
Function FSDKVB_DetectEyes(ByVal Image As Long, ByRef
FacialFeatures As TPoint) As Long
Java Syntax:
int FSDK.DetectEyes(HImage Image, FSDK_Features.ByReference
FacialFeatures);
Android Syntax:
int FSDK.DetectEyes(HImage Image, FSDK_Features
FacialFeatures);
CImage Syntax:
FSDK.TPoint[] FSDK.CImage.DetectEyes();
FSDK_DetectEyesInRegion Function
Detects eye centers in an image region returned by FSDK_DetectFace or
FSDK_DetectMultipleFaces.
C++ Syntax:
int FSDK_DetectEyesInRegion(HImage Image, TFacePosition*
FacePosition, FSDK_Features* FacialFeatures);
Delphi Syntax:
function FSDK_DetectEyesInRegion(Image: HImage; FacePosition:
PFacePosition; FacialFeatures: PFSDK_Features): integer;
C# Syntax:
int FSDK.DetectEyesInRegion(int Image, ref FSDK.TFacePosition
FacePosition, out FSDK.TPoint[] FacialFeatures);
VB Syntax:
Function FSDKVB_DetectEyesInRegion(ByVal Image As Long, ByRef
FacePosition As TFacePosition, ByRef FacialFeatures As TPoint)
As Long
Java Syntax:
int FSDK.DetectEyesInRegion(HImage Image, TFacePosition
FacePosition, FSDK_Features.ByReference FacialFeatures);
Android Syntax:
int FSDK.DetectEyesInRegion(HImage Image, TFacePosition
FacePosition, FSDK_Features FacialFeatures);
CImage Syntax:
FSDK.TPoint[] FSDK.CImage.DetectEyesInRegion(ref
FSDK.TFacePosition FacePosition);
Parameters:
Image – handle of the image eye centers should be detected in.
FacePosition – pointer to the face position structure.
FacialFeatures – pointer to the FSDK_Features array for receiving the detected eye
centers.
Return Value:
Returns FSDKE_OK if successful.
Face Matching
Luxand FaceSDK provides the API to extract face templates and match them. A template
extracted from a face can be stored in a database and can then be used to match faces using
the FSDK_MatchFaces function.
To extract a face template, use the FSDK_GetFaceTemplate,
FSDK_GetFaceTemplateInRegion or FSDK_GetFaceTemplateUsingFeatures functions. The
FSDK_MatchFaces function returns the facial similarity level. You may consider similarity to
be equal to the probability that templates belong to the same person.
More precisely: if the access control system provides access to a person when similarity is
higher of threshold х, the possibility of providing erroneous access to another person is 1-х.
For example, if the decision to provide access to a person is based on the code
if (similarity > 0.99)
AllowAccess();
the possibility of erroneous access to another person is 0.01, or 1%.
A facial template contains data that describes the face. There is no direct way to re-create the
original face image from a template. However, when using Tracker API, it may store the
original facial images in Tracker memory (see the Storing original facial images section).
To determine if the matched templates belong to the same person (with a specified error
possibility), you can compare the facial similarity value with a threshold calculated by the
FSDK_GetMatchingThresholdAtFAR or FSDK_GetMatchingThresholdAtFRR functions.
Note: it is recommended to retain both the original face images and their templates in the
database. This is because future versions of Luxand FaceSDK may offer an improved
template extraction algorithm, together with changes to the template format. If you are using
Tracker API, there is an option to convert its memory automatically if the template format
changes (see the Storing original facial images section).
A face template is stored in the FSDK_FaceTemplate data structure.
In .NET, there is no specific data type for a template. Instead, it is stored in an array of bytes
of FSDK.TemplateSize length. Below is an example of retrieving facial template in C#.
C# Example:
templateData = new byte[FSDK.TemplateSize];
FSDK.GetFaceTemplate(imageHandle, out templateData);
C++ Declaration:
typedef struct {
char ftemplate [1040];
} FSDK_FaceTemplate;
Delphi Declaration:
FSDK_FaceTemplate = record
Template: array[0.. 1040-1] of byte;
end;
PFSDK_FaceTemplate = ^FSDK_FaceTemplate;
FSDK_GetFaceTemplate Function
This function is used to extract a template from a facial image. The function first detects a
face, then detects its facial features and extracts the template.
If there is more than one face in the image, the template is extracted for the face with the most
clearly visible details. If there is no clearly visible face, the function returns an error code. To
set the threshold determining the accepted quality for faces, use the
FSDK_SetFaceDetectionThreshold function.
If the face position or its features or eye centers are known, it is more efficient to use the
FSDK_GetFaceTemplateInRegion or FSDK_GetFaceTemplateUsingEyes functions. To
extract the template for a specific face, use the FSDK_GetFaceTemplateInRegion function.
C++ Syntax:
int FSDK_GetFaceTemplate(HImage Image, FSDK_FaceTemplate*
FaceTemplate);
Delphi Syntax:
function FSDK_GetFaceTemplate(Image: HImage; FaceTemplate:
PFSDK_FaceTemplate): integer;
C# Syntax:
int FSDK.GetFaceTemplate(int Image, out byte[] FaceTemplate);
VB Syntax:
Function FSDKVB_GetFaceTemplate(ByVal Image As Long, ByRef
FaceTemplate As Byte) As Long
Java Syntax:
int FSDK.GetFaceTemplate(HImage Image,
FSDK_FaceTemplate.ByReference FaceTemplate);
Android Syntax:
int FSDK.GetFaceTemplate(HImage Image, FSDK_FaceTemplate
FaceTemplate);
CImage Syntax:
byte[] FSDK.CImage.GetFaceTemplate();
FSDK_GetFaceTemplateInRegion Function
Extracts a template for a face located in a specific region returned by FSDK_DetectFace or
FSDK_DetectMultipleFaces.
The function detects facial features in a specific region and extracts a template. The face
detection stage is not performed. This function can be useful if an approximate face size and
position is known, or to process a specific face returned by FSDK_DetectFace or
FSDK_DetectMultipleFaces. The function returns no error if the face is not clearly visible.
This is because it assumes that if face detection functions return a detected face position, the
face is of sufficient quality.
If facial features or eye centers are known, it is more efficient to use the
FSDK_GetFaceTemplateUsingFeatures or FSDK_GetFaceTemplateUsingEyes function.
C++ Syntax:
int FSDK_GetFaceTemplateInRegion(HImage Image, TFacePosition*
FacePosition, FSDK_FaceTemplate* FaceTemplate);
Delphi Syntax:
function FSDK_ GetFaceTemplateInRegion (Image: HImage;
FacePosition: PFacePosition; FaceTemplate:
PFSDK_FaceTemplate): integer;
C# Syntax:
int FSDK.GetFaceTemplateInRegion(int Image, ref
FSDK.TFacePosition FacePosition, out byte[] FaceTemplate);
VB Syntax:
Function FSDKVB_GetFaceTemplateInRegion(ByVal Image As Long,
ByRef FacePosition As TFacePosition, ByRef FaceTemplate As
Byte) As Long
Java Syntax:
int FSDK.GetFaceTemplateInRegion(HImage Image, TFacePosition
FacePosition, FSDK_FaceTemplate.ByReference FaceTemplate);
Android Syntax:
int FSDK.GetFaceTemplateInRegion(HImage Image, TFacePosition
FacePosition, FSDK_FaceTemplate FaceTemplate);
FSDK_GetFaceTemplateUsingEyes Function
Extracts a face template using the detected eye centers.
The function receives eye centers coordinates detected by the FSDK_DetectFacialFeatures,
FSDK_DetectFacialFeaturesInRegion, FSDK_DetectEyes or FSDK_DetectEyesInRegion
functions and extracts a face template. Face detection, facial feature detection, and eye centers
detection are not performed. This function can be useful when facial features or eye centers
for a specific face are already detected. The function returns no error if the face is not clearly
visible, since it assumes that if the face and its facial features or eye centers are already
detected, the face is of sufficient quality.
Note that the FSDK_GetFaceTemplate, FSDK_GetFaceTemplateInRegion and
FSDK_GetFaceTemplateUsingFeatures functions return templates that could be matched with
higher accuracy, so it is recommended to use these functions instead.
C++ Syntax:
int FSDK_GetFaceTemplateUsingEyes(HImage Image, FSDK_Features*
eyeCoords, FSDK_FaceTemplate* FaceTemplate);
Delphi Syntax:
function FSDK_ GetFaceTemplateUsingEyes(Image: HImage;
eyeCoords: PFSDK_Features; FaceTemplate: PFSDK_FaceTemplate):
integer;
C# Syntax:
int FSDK.GetFaceTemplateUsingEyes(int Image, ref FSDK.TPoint[]
eyeCoords, out byte[] FaceTemplate);
VB Syntax:
Function FSDKVB_GetFaceTemplateUsingEyes(ByVal Image As Long,
ByRef eyeCoords As TPoint, ByRef FaceTemplate As Byte) As Long
Java Syntax:
int FSDK.GetFaceTemplateUsingEyes(HImage Image, FSDK_Features
eyeCoords, FSDK_FaceTemplate.ByReference FaceTemplate);
FSDK_GetFaceTemplateUsingFeatures Function
Extracts a face template using the detected facial feature coordinates.
The function receives facial feature coordinates detected by the FSDK_DetectFacialFeatures
or FSDK_DetectFacialFeaturesInRegion functions and extracts a face template. Face
detection, facial feature detection, and eye centers detection are not performed. This function
can be useful when facial features for a specific face are already detected. The function
produces no error if the face is not clearly visible, since it assumes that if the face and its
facial features are already detected, the face is of sufficient quality.
The function determines if facial features, starting with the 2nd, are equal to zero or
uninitialized. In this case, the functions calls FSDK_GetFaceTemplateUsingEyes instead.
C++ Syntax:
int FSDK_GetFaceTemplateUsingFeatures(HImage Image,
FSDK_Features* FacialFeatures, FSDK_FaceTemplate*
FaceTemplate);
Delphi Syntax:
function FSDK_ GetFaceTemplateUsingFeatures(Image: HImage;
FacialFeatures: PFSDK_Features; FaceTemplate:
PFSDK_FaceTemplate): integer;
C# Syntax:
int FSDK.GetFaceTemplateUsingFeatures(int Image, ref
FSDK.TPoint[]FacialFeatures, out byte[] FaceTemplate);
VB Syntax:
Function FSDKVB_GetFaceTemplateUsingFeatures(ByVal Image As
Long, ByRef FacialFeaturesAs TPoint, ByRef FaceTemplate As
Byte) As Long
FSDK_MatchFaces Function
Match two face templates. The returned value determines the similarity of the faces.
C++ Syntax:
int FSDK_MatchFaces(FSDK_FaceTemplate* FaceTemplate1,
FSDK_FaceTemplate* FaceTemplate2, float* Similarity);
Delphi Syntax:
function FSDK_MatchFaces(FaceTemplate1, FaceTemplate2:
PFSDK_FaceTemplate; Similarity: PSingle): integer;
C# Syntax:
int FSDK.MatchFaces(ref byte[] FaceTemplate1, ref byte[]
FaceTemplate2, ref float Similarity);
VB Syntax:
Function FSDKVB_MatchFaces(ByRef FaceTemplate1 As Byte, ByRef
FaceTemplate2 As Byte, ByRef Similarity As Single) As Long
Java Syntax:
int FSDK.MatchFaces(FSDK_FaceTemplate.ByReference
FaceTemplate1, FSDK_FaceTemplate.ByReference FaceTemplate2,
float Similarity[]);
FSDK_GetMatchingThresholdAtFAR Function
This function returns the threshold value for similarity to determine if two matched templates
belong to the same person at a given FAR (False Acceptance Rate) value. The FAR
determines the acceptable error rate when two different people’s templates are mistakenly
recognized as the same person. Decreasing FAR leads to an increase in FRR – i.e. with low
FAR it becomes more probable that two templates from the same person will be determined
as belonging to different people.
C++ Syntax:
int FSDK_GetMatchingThresholdAtFAR(float FARValue, float*
Threshold);
Delphi Syntax:
function FSDK_GetMatchingThresholdAtFAR(FARValue: single; var
Threshold: single): integer;
C# Syntax:
int FSDK.GetMatchingThresholdAtFAR(float FARValue, ref float
Threshold);
VB Syntax:
Function FSDKVB_GetMatchingThresholdAtFAR(ByVal FARValue As
Single, ByRef Threshold As Single) As Long
Java and Android Syntax:
int FSDK.GetMatchingThresholdAtFAR(float FARValue, float
Threshold[]);
Parameters:
FARValue – the desired FAR value. Varies from 0.0 (means 0%) to 1.0 (means 100%).
Threshold – pointer to a float variable to store the calculated Threshold value.
Example
FSDK_FaceTemplate template1, template2;
FSDK_GetFaceTemplate(img1, &template1);
FSDK_GetFaceTemplate(img2, &template2);
FSDK_MatchFaces(&template1, &template2, &Similarity);
if (Similarity > MatchingThreshold)
printf("Same Person\n");
else
printf("Different Person\n");
FSDK_GetMatchingThresholdAtFRR Function
This function returns the threshold value for similarity to determine if two matched templates
belong to the same person at a given FRR (False Rejection Rate) value. The FRR determines
the acceptable error rate when two templates of the same person are identified as belonging to
different people. Decreasing FRR leads to an increase in FAR – i.e. with low FRR it becomes
more probable that two different people’s templates will be recognized as the same person.
C++ Syntax:
int FSDK_GetMatchingThresholdAtFRR(float FRRValue, float*
Threshold);
Delphi Syntax:
function FSDK_GetMatchingThresholdAtFRR(FRRValue: single; var
Threshold: single): integer;
C# Syntax:
int FSDK.GetMatchingThresholdAtFRR(float FRRValue, ref float
Threshold);
VB Syntax:
Function FSDKVB_GetMatchingThresholdAtFRR(ByVal FRRValue As
Single, ByRef Threshold As Single) As Long
Java and Android Syntax:
int FSDK.GetMatchingThresholdAtFRR(float FRRValue, float
Threshold[]);
Parameters:
FRRValue – the desired FRR value. Varies from 0.0 (means 0%) to 1.0 (means 100%).
Threshold – pointer to a float variable, used to store the calculated Threshold value.
FSDK_DetectFacialAttributeUsingFeatures Function
Detects an attribute of a face, and returns the Values of a particular attribute, and Confidences
in these Values.
Each facial attribute has a number of Values, and each Value has an associated Confidence. A
Value is a string, and a Confidence is a float from 0 to 1, which represents confidence level of
this particular value of the attribute.
The following attribute names are supported:
"Gender" – to detect the gender of a face. The attribute has "Male" and "Female"
values.
"Age" – to detect the age of a face. The attribute has "Age" value.
"Expression" – to detect the expression of a face. The attribute has "Smile" and
"EyesOpen" values. The Values and their Confidences are returned in a string of the
following format:
"Value1=Confidence1[;Value2=Confidence2[;…]]"
For example, when calling the function with the "Gender" attribute, the following string
may be returned:
"Male=0.95721;Female=0.04279”
It means that the subject has male gender with a confidence of 95.7%, and female gender with
a confidence of 4.3%.
When calling the function with the "Age" attribute, the following string may be returned:
"Age=37"
When calling the function with the "Expression" attribute, the following string may be
returned:
"Smile=0.987;EyesOpen=0.9952"
It means that the subject smiles with a confidence of 98.7%, and the eyes are open with a
confidence of 99.5%. You may use several attributes in a single function call separated by
";". For example, if AttributeName is "Gender; Age; Expression", the result
may be the following:
"Male=0.95721;Female=0.04279;Age=37;Smile=0.987;EyesOpen=0.995
"
FSDK_GetValueConfidence Function
Parses the string returned by FSDK_DetectFacialAttributeUsingFeatures or
FSDK_GetTrackerFacialAttribute, and returns the Confidence in an individual Value.
Data Types
There are data types to store the information about video formats. Note that the names of
video cameras are stored in wide char format (each char occupies two bytes).
C++ Declaration:
typedef struct {
int Width;
int Height;
int BPP;
} FSDK_VideoFormatInfo;
typedef enum {
FSDK_MJPEG
} FSDK_VIDEOCOMPRESSIONTYPE;
Delphi Declaration:
FSDK_VideoFormatInfo = record
Width: integer;
Height: integer;
BPP: integer;
end;
PFSDK_VideoFormatInfo = ^FSDK_VideoFormatInfo;
FSDK_VideoFormatInfoArray =
array[0..255] of FSDK_VideoFormatInfo;
PFSDK_VideoFormatInfoArray = ^FSDK_VideoFormatInfoArray;
FSDK_CameraList = array[0..255] of PWideChar;
PFSDK_CameraList = ^FSDK_CameraList;
FSDK_VIDEOCOMPRESSIONTYPE = (
FSDK_MJPEG
);
VB Declaration:
Type FSDK_VideoFormatInfo
Width As Long
Height As Long
BPP As Long
End Type
Enum FSDK_VIDEOCOMPRESSIONTYPE
FSDK_MJPEG
End Enum
Java Declaration:
The class FSDK_VideoFormatInfo has the following properties:
class FSDK_VideoFormats {
public FSDK_VideoFormatInfo.ByValue formats[];
}
class TCameras {
public String cameras[];
}
class FSDK_VIDEOCOMPRESSIONTYPE {
public static final int FSDK_MJPEG = 0;
}
FSDK_InitializeCapturing Function
This function initializes the capturing process (but does not open a camera). This function
should be called in a certain thread that works with cameras. Note that on Windows platforms
this function initializes COM in the thread; if you already initialized COM, you must not call
this function, and you must not call FSDK_FinalizeCapturing.
C++ Syntax:
int FSDK_InitializeCapturing(void);
Delphi Syntax:
function FSDK_InitializeCapturing: integer;
C# Syntax:
int FSDKCam.InitializeCapturing();
VB Syntax:
Function FSDKVB_InitializeCapturing() As Long
Java Syntax:
int FSDKCam.InitializeCapturing();
Android Syntax:
int FSDK.InitializeCapturing();
Return Value:
Returns FSDKE_OK if successful.
FSDK_SetCameraNaming Function
Sets the retrieval format for the FSDK_GetCameraList function. Depending on the value of
the argument, either web camera names (by default) or their unique IDs (Device Path) are
returned. Device Path may be necessary if the system has several web cameras from the same
manufacturer that have the same name. This function does not support IP cameras.
C++ Syntax:
int FSDK_SetCameraNaming(bool UseDevicePathAsName);
Delphi Syntax:
function FSDK_SetCameraNaming(UseDevicePathAsName: boolean):
integer;
C# Syntax:
int FSDKCam.SetCameraNaming(bool UseDevicePathAsName)
VB Syntax:
Function FSDKVB_SetCameraNaming(ByVal UseDevicePathAsName As
Boolean) As Long
Java Syntax:
int FSDKCam.SetCameraNaming (boolean UseDevicePathAsName);
FSDK_GetCameraList Function
This function retrieves the list of web cameras available in the system. The name of each
camera is stored in wide char format (each character occupies two bytes). The function does
not support IP cameras. The camera list must be destroyed by calling the
FSDK_FreeCameraList function after the list is no longer needed.
C++ Syntax:
int FSDK_GetCameraList(wchar_t*** CameraList, int*
CameraCount);
Delphi Syntax:
function FSDK_GetCameraList(CameraList: PWideChar;CameraCount:
Pinteger): integer;
C# Syntax:
int FSDKCam.GetCameraList(out string[] CameraList, out int
CameraCount)
VB Syntax:
Function FSDKVB_GetCameraList(ByRef CameraList As Variant,
ByRef CameraCount As Long) As Long
Java Syntax:
int FSDKCam.GetCameraList(TCameras CameraList, int
CameraCount[]);
Parameters:
CameraList – pointer to wchar_t** variable to store the camera list.
CameraCount – pointer to integer variable to store the count of cameras in the system.
Return Value:
Returns FSDKE_OK if successful.
Example
wchar_t** CameraList;
int CameraCount;
FSDK_InitializeCapturing();
if (FSDK_GetCameraList(&CameraList, &CameraCount)==FSDKE_OK)
for (int i=0; i<CameraCount; i++)
FSDK_GetCameraListEx Function
This function retrieves the list of names and the device paths of the web cameras available in
the system. The name and the device path of each camera are stored in wide char format (each
character occupies two bytes) at the same indices at the corresponding arrays. The function
does not support IP cameras. Both lists must be destroyed by calling the
FSDK_FreeCameraList function after they are no longer needed.
C++ Syntax:
int FSDK_GetCameraListEx(wchar_t*** CameraNameList, wchar_t***
CameraDevicePathList, int* CameraCount);
Delphi Syntax:
function FSDK_GetCameraListEx(CameraNameList: PWideChar;
CameraDevicePathList: PWideChar; CameraCount: PInteger):
integer;
C# Syntax:
int FSDKCam.GetCameraListEx(out string[] CameraNameList, out
string[] CameraDevicePathList, out int CameraCount)
VB Syntax:
Function FSDKVB_GetCameraListEx(ByRef VCameraNameList As
Variant, ByRef VCameraDevicePathList As Variant, ByRef
CameraCount As Long) As Long
Java Syntax:
int FSDKCam.GetCameraListEx(TCameras CameraNameList, TCameras
CameraDevicePathList, int CameraCount[]);
Parameters:
CameraNameList – pointer to wchar_t** variable to store the camera name list.
CameraDevicePathList – pointer to wchar_t** variable to store the camera device
path list.
CameraCount – pointer to integer variable to store the number of cameras in the system.
Return Value:
Returns FSDKE_OK if successful.
FSDK_FreeCameraList Function
This function frees the list of web cameras obtained from the FSDK_GetCameraList or
FSDK_GetCameraListEx function. The call of the function is not required in .NET, VB and
Java.
FSDK_GetVideoFormatList Function
This function returns the list of video formats supported by a given camera. This function
does not support IP cameras.
C++ Syntax:
int FSDK_GetVideoFormatList(wchar_t* CameraName,
FSDK_VideoFormatInfo** VideoFormatList, int*
VideoFormatCount);
Delphi Syntax:
function FSDK_GetVideoFormatList(CameraName: PWideChar;
VideoFormatList: PFSDK_VideoFormatInfo; VideoFormatCount:
Pinteger): integer;
C# Syntax:
int FSDKCam.GetVideoFormatList(string CameraName, out
FSDKcam.VideoFormatInfo[] VideoFormatList, out int
VideoFormatCount)
VB Syntax:
Function FSDKVB_GetVideoFormatList(ByVal CameraName As String,
ByRef VideoFormatList As Variant, ByRef VideoFormatCount As
Long) As Long
Java Syntax:
int FSDKCam.GetVideoFormatList(String CameraName,
FSDK_VideoFormats VideoFormatList, int VideoFormatCount[]);
Parameters:
CameraName – pointer to name of desired video camera.
FSDK_FreeVideoFormatList Function
This function frees the list of video formats obtained from
FSDK_GetVideoFormatList.Calling this function is not required in .NET, VB and Java.
C++ Syntax:
int FSDK_FreeVideoFormatList(FSDK_VideoFormatInfo *
VideoFormatList);
Delphi Syntax:
function FSDK_FreeVideoFormatList(VideoFormatList: Pointer):
integer;
Parameters:
VideoFormatList – pointer to FSDK_VideoFormatInfo* variable where the list of video
formats is stored.
Return Value:
Returns FSDKE_OK if successful.
FSDK_SetVideoFormat Function
The function sets the format of camera output. The function does not support IP cameras.
C++ Syntax:
int FSDK_SetVideoFormat(wchar_t* CameraName,
FSDK_VideoFormatInfo VideoFormat);
Delphi Syntax:
function FSDK_SetVideoFormat(CameraName: PWideChar;
VideoFormat: FSDK_VideoFormatInfo): integer;
C# Syntax:
int FSDKCam.SetVideoFormat(ref string CameraName,
FSDKcam.VideoFormatInfo VideoFormat);
VB Syntax:
Function FSDKVB_SetVideoFormat(ByVal CameraName As String,
ByRef VideoFormat As FSDK_VideoFormatInfo) As Long
Java Syntax:
int FSDKCam.SetVideoFormat(String CameraName,
FSDK_VideoFormatInfo.ByValue VideoFormat);
Example
wchar_t** CameraList;
int CameraCount;
FSDK_VideoFormatInfo* VideoFormatList;
int VideoFormatCount;
FSDK_GetCameraList(&CameraList, &CameraCount);
FSDK_GetVideoFormatList(CameraList[0], &VideoFormatList,
&VideoFormatCount);
FSDK_SetVideoFormat(CameraList[0], VideoFormatList[0]);
FSDK_OpenVideoCamera Function
The function opens the web camera of a given name and returns its handle.
C++ Syntax:
int FSDK_OpenVideoCamera(wchar_t* CameraName, int*
CameraHandle);
Delphi Syntax:
function FSDK_OpenVideoCamera(CameraName: PWideChar;
CameraHandle: Pinteger): integer;
C# Syntax:
int FSDKCam.OpenVideoCamera(ref string CameraName, ref int
CameraHandle);
VB Syntax:
Function FSDKVB_OpenVideoCamera(ByVal CameraName As String,
ByRef CameraHandle As Long) As Long
Java Syntax:
int FSDKCam.OpenVideoCamera (String CameraName, HCamera
CameraHandle);
Parameters:
CameraName – pointer to name of web camera to open.
CameraHandle – pointer to integer variable to store the opened camera handle.
Return Value:
Returns FSDKE_OK if successful.
FSDK_GrabFrame Function
Retrieves the current frame from a web camera or an IP camera and stores the frame in the
created HImage handle. If a camera returns an image, mirrored horizontally (it depends on the
camera settings), then you can mirror it by using FSDK_MirrorImage.
C++ Syntax:
int FSDK_GrabFrame(int CameraHandle, HImage* Image);
FSDK_CloseVideoCamera Function
This function closes the camera, opened by the FSDK_OpenVideoCamera or
FSDK_OpenIPVideoCamera function.
C++ Syntax:
int FSDK_CloseVideoCamera(int CameraHandle);
Delphi Syntax:
function FSDK_CloseVideoCamera(CameraHandle: integer):
integer;
C# Syntax:
int FSDKCam.CloseVideoCamera(int CameraHandle);
VB Syntax:
Function FSDKVB_CloseVideoCamera(ByVal CameraHandle As Long)
As Long
Java Syntax:
int FSDKCam.CloseVideoCamera(HCamera CameraHandle);
Parameters:
CameraHandle – handle of opened video camera to close.
Understanding Identifiers
The API analyzes the video stream sequentially, frame by frame. For each frame, the function
FSDK_FeedFrame returns the list of identifiers (integer numbers) of faces recognized in this
frame. The purpose of an identifier is to assign a unique number to each subject in the video.
If a face is similar to one recognized previously, it receives the same identifier. Otherwise, a
new identifier (in ascending numeric order) is assigned. Thus, subjects recognized as different
should get different identifiers.
It is important to note that the identifier value is meaningful only within a particular video
stream. Identifiers of the same subject are not expected to be the same across different video
streams.
Merger of identifiers
However, as the video progresses, the system learns more about the appearance of each
person; at some point it may deduce that ID1 and ID2 actually represent the same person. In
such a case (and if it is possible) it merges both identifiers into ID1, further returning ID1 for
every novel recognized occurrence of this subject. The system retains the information of all
merger events, so it is possible to receive the resulting value of an early assigned identifier
(for example, receive the ID1 value when providing the ID2 value) by calling the
FSDK_GetIDReassignment function. Note that if an identifier was tagged with a name, it can
be merged only with other identifiers that are untagged; in such a case the tagged name is
retained.
When calling Tracker API functions with identifiers received on earlier frames, it is always
recommended to convert the identifier values with the FSDK_GetIDReassignment function
first, and only then pass them to Tracker API. The reason is that they may have been merged
Similar identifiers
The identifier returned by the FSDK_FeedFrame function can be similar enough to other
identifiers for the API to decide they represent the same person. Still, some reason (such as
the one described above) may prevent them from merging. In such case, similar identifiers of
an ID can be retrieved using the FSDK_GetSimilarIDList function.
You should always retrieve the list of similar identifiers when deciding if therecognized face
belongs to a certain subject or not. Let us assume that you have a particular subject of interest
and should respond when it is recognized. You may have stored an identifier of that subject,
or assigned a name to it with FSDK_SetName, and wait for such identifier (or name) to
appear. (Keep in mind that you need to adjust the stored identifier with
FSDK_GetIDReassignment after calling FSDK_FeedFrame.) When the subject appears,
however, there is no guarantee that the stored identifier will be returned by the
FSDK_FeedFrame function. Instead, it may appear in the list of similar identifiers. Therefore,
you should compare your identifier against the list of similar identifiers for each ID returned
by FSDK_FeedFrame. Accordingly, you need to retrieve the names of each similar identifier,
for each ID returned by FSDK_FeedFrame, to find if any of these names belong to the subject
of interest. If you are not considering such lists of similar identifiers, your recognition rate
will be lower (that is, you may miss the appearance of the subject of interest). Of course, your
false acceptance rate will be lower as well. But the drop in recognition rate will be higher
compared to when you set a higher recognition threshold (see the Recognition Performance
section), and handle similar identifiers.
The function FSDK_GetAllNames implements the above functionality – it returns the name
of an identifier, concatenated with the names (if any) of similar identifiers, separated by a
semicolon.
Tracker Memory
The API allows limiting the memory used by a tracker. The memory size is measured in the
total number of facial appearances stored (about 11 Kbytes per appearance when the
KeepFaceImages parameter is set to true, and about 1.5 Kbytes when set to false). By default,
the limit is 2150 appearances (about 24 Mbytes or 3 Mbytes depending on the value of the
KeepFaceImages parameter). You can change the limit by setting the MemoryLimit
parameter (see the Tracker Parameters section) to your desired value.
Tracker Parameters
Each HTracker instance allows setting a number of parameters with the
FSDK_SetTrackerParameter or FSDK_SetTrackerMultipleParameters function.
Locking identifiers
There are cases when you need to work with (or tag) an identifier across several frames. For
example, you may have the user interface running in a different thread than
Usage Scenario
The following scenario is employed when using Tracker API.
1. Create a tracker (FSDK_CreateTracker) or load it from a file
(FSDK_LoadTrackerMemoryFromFile) or from a memory buffer
(FSDK_LoadTrackerMemoryFromBuffer).
2. Set tracker parameters (FSDK_SetTrackerParameter,
FSDK_SetTrackerMultipleParameters), such as face detection parameters, recognition
precision, or the option to recognize gender/age/facial expression or to detect facial
features.
3. Open a video camera (FSDK_OpenVideoCamera, FSDK_OpenIPVideoCamera), or
prepare to receive video frames from another source.
4. In a loop:
1) Receive a frame from a camera (FSDK_GrabFrame) or another source.
2) Send the image to the FSDK_FeedFrame function.
Enrollment
To enroll a subject, the user is usually only required to click a subject’s face and enter the
name. If the subject has been already present in front of the camera for a certain time (for
example, while approaching the user’s desk), it is likely that the API has stored enough facial
appearances of the subject to recognize it again. If this is not the case, the subject may be
asked to tilt or rotate its head, to walk closer to or further away from the camera, and the
lighting can be altered. If the frame rate is especially low, or if environmental conditions
Recognition Performance
The performance of face recognition (i.e. how often a subject is recognized, and how often
different subjects are confused) is controlled with the Threshold and MemoryLimit
parameters. The higher the Threshold parameter (and the lower the MemoryLimit parameter),
the less often a subject will be recognized, and the less often confusions will occur.
Performance measures
Tracker API employs two performance measures: false acceptance rate (FAR) and
recognition rate (R). FAR measures the rate of confusing different subjects (that is, assigning
different subjects with equal identifier values) during a certain number of storage events, once
the memory becomes full. R measures the rate of recognizing a person after tagging, once all
available memory is full.
Understanding R
R is the rate of recognizing a subject after it was tagged a single time, and all memory
available for a subject becomes full. A subject is successfully recognized, if its name is
present among the names returned by FSDK_GetAllNames. R is measured from 0 to 1, which
translates to recognition in 0% and 100%, respectively, of frames received by
FSDK_FeedFrame.
R depends mainly on the amount of memory available for each subject. For example, if there
are 30 subjects in your system, and you allow 20 units of memory for each subject, your
memory limit should be (30+1)*20=620.
For example, let us assume that you have 30 subjects in an office setting, your frame rate is 12
per second, and you decide to allow 21 units of memory per subject. Therefore, your memory
limit is (30+1)*21 = 651 (see the formula in the Memory available for each subject section).
You decide to have a FAR of 0.000050 and calculate that with 30 subjects, there will be 2.2%
rate that a subject will be given with an ID of any other subject (see the formula in the
Understanding FAR section) during 2000 storage events (approximately 5 hours in an office
setting). To have a FAR of 0.000050 with MemoryLimit=700 (the value closest to 651 in the
table), you choose Threshold=0.996566. You note that at such a threshold and 21 units of
memory per subject, you have a 0.997 recognition rate (meaning subjects will be recognized
in 99.7% of frames in the video).
Note: it is not recommended to use Threshold higher than 0.999, since it will make Tracker
API recognize faces less often.
FSDK_CreateTracker Function
Creates a new tracker handle to be passed to other Tracker API functions.
C++ Syntax:
int FSDK_CreateTracker(HTracker * Tracker);
Delphi Syntax:
function FSDK_CreateTracker(Tracker: PHTracker): integer;
C# Syntax:
int FSDK.CreateTracker(ref int Tracker);
VB Syntax:
Function FSDKVB_CreateTracker(ByRef Tracker As Long) As Long
Java and Android Syntax:
int FSDK.CreateTracker(HTracker Tracker);
Parameters:
Tracker – pointer to the integer variable that will to store the created tracker handle.
Return Value:
Returns FSDKE_OK if successful.
FSDK_FreeTracker Function
Frees a tracker handle. The handle becomes invalid, and all memory associated with it is
released. You should not pass the tracker handle to any other Tracker API functions after the
handle was freed.
C++ Syntax:
int FSDK_FreeTracker(HTracker Tracker);
Delphi Syntax:
function FSDK_FreeTracker(Tracker: HTracker): integer;
C# Syntax:
int FSDK.FreeTracker(int Tracker);
FSDK_ClearTracker Function
Clears the content of a tracker, releasing all its memory. The tracker handle stays valid. The
parameters are reset to their default values, so if you just need to clear the tracker’s memory,
consider setting the parameters with the FSDK_SetTrackerParameter or the
FSDK_SetTrackerMultipleParameters function again.
C++ Syntax:
int FSDK_ClearTracker(HTracker Tracker);
Delphi Syntax:
function FSDK_ClearTracker(Tracker: HTracker): integer;
C# Syntax:
int FSDK.ClearTracker(int Tracker);
VB Syntax:
Function FSDKVB_ClearTracker(ByVal Tracker As Long) As Long
Java and Android Syntax:
int FSDK.ClearTracker(HTracker Tracker);
Parameters:
Tracker – handle of the tracker to be cleared.
Return Value:
Returns FSDKE_OK if successful.
FSDK_SetTrackerParameter Function
Sets the parameter of a tracker. See the Tracker Parameters section for details.
C++ Syntax:
int FSDK_SetTrackerParameter(HTracker Tracker, const char *
ParameterName, const char * ParameterValue);
FSDK_SetTrackerMultipleParameters Function
Sets multiple parameters of a tracker.The parameters and their values are specified in the
following format:
"Parameter1=Value1[;Parameter2=Value2[;…]]"
See the Tracker Parameters section for details.
C++ Syntax:
int FSDK_SetTrackerMultipleParameters(HTracker Tracker, const
char * Parameters, int * ErrorPosition);
Delphi Syntax:
function FSDK_SetTrackerMultipleParameters(Tracker: HTracker;
Parameters: PAnsiChar; ErrorPosition: PInteger): integer;
C# Syntax:
int FSDK.SetTrackerMultipleParameters(int Tracker, string
Parameters, ref int ErrorPosition);
VB Syntax:
Function FSDKVB_SetTrackerMultipleParameters(ByVal Tracker As
Long, ByVal Parameters As String, ByRef ErrorPosition As Long)
As Long
FSDK_GetTrackerParameter Function
Retrieves the value of a tracker parameter. See the Tracker Parameters section for details.
C++ Syntax:
int FSDK_GetTrackerParameter(HTracker Tracker, const char *
ParameterName, char * ParameterValue, long long
MaxSizeInBytes);
Delphi Syntax:
function FSDK_GetTrackerParameter(Tracker: HTracker;
ParameterName, ParameterValue: PAnsiChar; MaxSizeInBytes:
int64): integer;
C# Syntax:
int FSDK.GetTrackerParameter(int Tracker, string
ParameterName, out string ParameterValue, long MaxSizeInBytes)
VB Syntax:
Function FSDKVB_GetTrackerParameter(ByVal Tracker As Long,
ByVal ParameterName As String, ByRef ParameterValue As String,
ByVal MaxSizeInBytes As Currency) As Long
Java and Android Syntax:
int FSDK.GetTrackerParameter(HTracker Tracker, String
ParameterName, String ParameterValue[], long MaxSizeInBytes);
Parameters:
Tracker – handle of the tracker whose parameter value is desired.
FSDK_FeedFrame Function
Processes a video frame according to tracker’s parameters, and returns the identifiers of the
tracked faces. See the Understanding Identifiers, Tracker Memory and Tracker Parameters
sections for details.
C++ Syntax:
int FSDK_FeedFrame(HTracker Tracker, long long CameraIdx,
HImage Image, long long * FaceCount, long long * IDs, long
long MaxSizeInBytes);
Delphi Syntax:
function FSDK_FeedFrame(Tracker: HTracker; CameraIdx: int64;
Image: HImage; FaceCount: PInt64; IDs: PIDArray;
MaxSizeInBytes: int64): integer;
C# Syntax:
int FSDK.FeedFrame(int Tracker, long CameraIdx, int Image, ref
long FaceCount, out long[] IDs, long MaxSizeInBytes)
VB Syntax:
Function FSDKVB_FeedFrame(ByVal Tracker As Long, ByVal
CameraIdx As Currency, ByVal Image As Long, ByRef FaceCount As
Currency, ByRef IDs As Currency, ByVal MaxSizeInBytes As
Currency) As Long
Java and Android Syntax:
int FSDK.FeedFrame(HTracker Tracker, long CameraIdx, HImage
Image, long FaceCount[], long IDs[], long MaxSizeInBytes);
Parameters:
Tracker – handle of the tracker in which to process the frame.
CameraIdx – index of the camera; should be equal to 0 in the current release.
Image – the HImage handle of the video frame to process.
FaceCount – address of the 64-bit integer value that will receive the count of faces tracked
in the current frame.
IDs – address of the array of 64-bit integer values that will receive the identifiers of the
tracked faces.
MaxSizeInBytes – amount of memory allocated for the IDs array.
FSDK_GetTrackerEyes Function
Retrieves the coordinates of the eye centers of a tracked face. The function accepts the
identifier returned by FSDK_FeedFrame. This identifier should be passed to
FSDK_GetTrackerEyes before the next call of FSDK_FeedFrame using the same tracker.
For the function to return the eye center coordinates, at least one of the parameters
DetectEyes, DetectFacialFeatures, RecognizeFaces, DetectGender, DetectAge or
DetectExpression must be set to true.
C++ Syntax:
int FSDK_GetTrackerEyes(HTracker Tracker, long long CameraIdx,
long long ID, FSDK_Features * FacialFeatures);
Delphi Syntax:
function FSDK_GetTrackerEyes(Tracker: HTracker; CameraIdx, ID:
int64; FacialFeatures: PFSDK_Features): integer;
C# Syntax:
int FSDK.GetTrackerEyes(int Tracker, long CameraIdx, long ID,
out TPoint[] FacialFeatures)
VB Syntax:
Function FSDKVB_GetTrackerEyes(ByVal Tracker As Long, ByVal
CameraIdx As Currency, ByVal ID As Currency, ByRef
FacialFeatures As TPoint) As Long
Java Syntax:
int FSDK.GetTrackerEyes(HTracker Tracker, long CameraIdx, long
ID, FSDK_Features.ByReference FacialFeatures);
Android Syntax:
int FSDK.GetTrackerEyes(HTracker Tracker, long CameraIdx, long
ID, FSDK_Features FacialFeatures);
Parameters:
Tracker – handle of the tracker where the coordinates of the eye centers will be retrieved.
CameraIdx – index of the camera; should be equal to 0 in the current release.
ID – identifier of the subject returned by FSDK_FeedFrame, whose eye center coordinates
will be received.
FacialFeatures – pointer to the FSDK_Features variable that will receive the eye center
coordinates.
Return Value:
Returns FSDKE_OK if successful. Returns FSDKE_ID_NOT_FOUND if the specified ID
was not returned by the previous FSDK_FeedFrame call.
FSDK_GetTrackerFacialFeatures Function
Retrieves the coordinates of a tracked face’s features. The function accepts the identifier
returned by FSDK_FeedFrame. This identifier should be passed to
FSDK_GetTrackerFacialFeatures before the next call of FSDK_FeedFrame with the same
tracker.
For the function to return the facial feature coordinates, either of the parameters
DetectFacialFeatures, DetectGender, DetectAge or DetectExpression should be set to true.
See the Tracker Parameters section for details.
C++ Syntax:
int FSDK_GetTrackerFacialFeatures(HTracker Tracker, long long
CameraIdx, long long ID, FSDK_Features * FacialFeatures);
Delphi Syntax:
function FSDK_GetTrackerFacialFeatures(Tracker: HTracker;
CameraIdx, ID: int64; FacialFeatures: PFSDK_Features):
integer;
C# Syntax:
int FSDK.GetTrackerFacialFeatures(int Tracker, long CameraIdx,
long ID, out TPoint[] FacialFeatures)
VB Syntax:
Function FSDKVB_GetTrackerFacialFeatures(ByVal Tracker As
Long, ByVal CameraIdx As Currency, ByVal ID As Currency, ByRef
FacialFeatures As TPoint) As Long
Java Syntax:
int FSDK.GetTrackerFacialFeatures(HTracker Tracker, long
CameraIdx, long ID, FSDK_Features.ByReference FacialFeatures);
Android Syntax:
int FSDK.GetTrackerFacialFeatures(HTracker Tracker, long
CameraIdx, long ID, FSDK_Features FacialFeatures);
Parameters:
Tracker – handle of the tracker from which to retrieve the facial feature coordinates.
CameraIdx – index of the camera; should be equal to 0 in the current release.
ID – identifier of the subject returned by FSDK_FeedFrame, whose facial feature coordinates
will be received.
FacialFeatures – pointer to the FSDK_Features variable to receive facial feature
coordinates.
Return Value:
Returns FSDKE_OK if successful. Returns FSDKE_ID_NOT_FOUND if the specified ID
was not returned by the previous FSDK_FeedFrame call.
FSDK_GetTrackerFacePosition Function
Retrieves the position of a tracked face. The function accepts the identifier returned by
FSDK_FeedFrame. This identifier should be passed to FSDK_GetTrackerFacePosition before
the next call of FSDK_FeedFrame with the same tracker.
C++ Syntax:
int FSDK_GetTrackerFacePosition(HTracker Tracker, long long
CameraIdx, long long ID, TFacePosition * FacePosition);
Delphi Syntax:
function FSDK_GetTrackerFacePosition(Tracker: HTracker;
CameraIdx, ID: int64; FacePosition: PFacePosition): integer;
C# Syntax:
int FSDK.GetTrackerFacePosition(int Tracker, long CameraIdx,
long ID, ref TFacePosition FacePosition);
VB Syntax:
Function FSDKVB_GetTrackerFacePosition(ByVal Tracker As Long,
ByVal CameraIdx As Currency, ByVal ID As Currency, ByRef
facePosition As TFacePosition) As Long
Java Syntax:
int FSDK.GetTrackerFacePosition(HTracker Tracker, long
CameraIdx, long ID, TFacePosition.ByReference FacePosition);
Android Syntax:
int FSDK.GetTrackerFacePosition(HTracker Tracker, long
CameraIdx, long ID, TFacePosition FacePosition);
Parameters:
Tracker – handle of the tracker from which to retrieve the face position.
CameraIdx – index of the camera; should be equal to 0 in the current release.
ID – identifier of the subject returned by FSDK_FeedFrame whose face position will be
received.
FacePosition – pointer to the TFacePosition variable that will receive the face position.
Return Value:
Returns FSDKE_OK if successful. Returns FSDKE_ID_NOT_FOUND if the specified ID
was not returned by the previous FSDK_FeedFrame call.
FSDK_GetTrackerFacialAttribute Function
Given an attribute of a tracked face, retrieves its Values and their Confidences. The function
accepts the identifier returned by FSDK_FeedFrame. This identifier should be passed to
FSDK_LockID Function
Locks an identifier. When an identifier is locked, at least one facial appearance of an identifier
will not be deleted during any possible purge. You should call this function before the
FSDK_SetName function. The function has no effect on identifiers which were already
tagged with a name. The call should be usually paired with FSDK_UnlockID call. When the
user does not set a name to a locked identifier, unlocking it allows it to become purged if
necessary for memory efficient memory use.
See the Locking Identifiers section for details. You may call this function with any identifier
regardless of when it was returned as long as it remains present in the tracker memory.
C++ Syntax:
int FSDK_LockID(HTracker Tracker, long long ID);
Delphi Syntax:
function FSDK_LockID(Tracker: HTracker; ID: int64): integer;
C# Syntax:
int FSDK.LockID(int Tracker, long ID);
VB Syntax:
Function FSDKVB_LockID(ByVal Tracker As Long, ByVal ID As
Currency) As Long
Java and Android Syntax:
int FSDK.LockID(HTracker Tracker, long ID);
Parameters:
Tracker – handle of the tracker in which to lock an identifier.
ID – identifier of the subject to lock.
Return Value:
Returns FSDKE_OK if successful. Returns FSDKE_ID_NOT_FOUND if the specified ID is
not present in the tracker memory.
FSDK_UnlockID Function
Unlocks the ID so it may be purged. You should call this function after the FSDK_LockID
call. The function has no effect on identifiers which were already tagged with a name.
See the Locking identifiers section for details. You may call this function with any identifier
regardless of when it was returned, as long as it is present in the tracker memory.
C++ Syntax:
int FSDK_UnlockID(HTracker Tracker, long long ID);
FSDK_PurgeID Function
Removes all facial appearances of the ID from the tracker memory. You must call this
function if there was a false acceptance (see the Dealing with false acceptances section) or if
you erroneously assigned equal names to different persons.
C++ Syntax:
int FSDK_PurgeID(HTracker Tracker, long long ID);
Delphi Syntax:
function FSDK_PurgeID(Tracker: HTracker; ID: int64): integer;
C# Syntax:
int FSDK.PurgeID(int Tracker, long ID);
VB Syntax:
Function FSDKVB_PurgeID(ByVal Tracker As Long, ByVal ID As
Currency) As Long
Java and Android Syntax:
int FSDK.PurgeID(HTracker Tracker, long ID);
Parameters:
Tracker – handle of the tracker in which to purge an identifier.
ID – identifier of the subject to purge.
Return Value:
Returns FSDKE_OK if successful. Returns FSDKE_ID_NOT_FOUND if the specified ID is
not present in the tracker memory.
FSDK_SetName Function
Sets the name of an identifier. To erase the name tag, specify an empty name string. When
erasing the name tag because of a false acceptance, or because you erroneously assigned equal
names to different persons, you must also call the FSDK_PurgeID function (see the Dealing
with false acceptances section). The function will unlock the identifier if the name is
successfully set.
You may call this function with any identifier regardless of when it was returned, as long as it
is present in the tracker memory.
FSDK_GetIDReassignment Function
When provided with a subject’s ID received on earlier frames, returns the new subject’s ID if
there was a merger. See the Understanding Identifiers section for details. If an identifier was
not merged, the function returns the same ID value in the output variable. Note that the
function does not return an error if an identifier is not present in the tracker memory; instead;
the same ID value is returned in the output variable.
C++ Syntax:
int FSDK_GetIDReassignment(HTracker Tracker, long long ID,
long long * ReassignedID);
Delphi Syntax:
function FSDK_GetIDReassignment(Tracker: HTracker; ID: int64;
ReassignedID: PInt64): integer;
C# Syntax:
int FSDK.GetIDReassignment(int Tracker, long ID, ref long
ReassignedID);
FSDK_GetSimilarIDCount Function
Returns the number of identifiers that are similar to a given identifier. The function accepts
the identifier returned by FSDK_FeedFrame. This identifier should be passed to
FSDK_GetSimilarIDCount before the next call of FSDK_FeedFrame with the same tracker.
See the Understanding Identifiers section for details.
C++ Syntax:
int FSDK_GetSimilarIDCount(HTracker Tracker, long long ID,
long long * Count);
Delphi Syntax:
function FSDK_GetSimilarIDCount(Tracker: HTracker; ID: int64;
Count: PInt64): integer;
C# Syntax:
int FSDK.GetSimilarIDCount(int Tracker, long ID, ref long
Count);
VB Syntax:
FSDKVB_GetSimilarIDCount(ByVal Tracker As Long, ByVal ID As
Currency, ByRef Count As Currency) As Long
Java and Android Syntax:
int FSDK.GetSimilarIDCount(HTracker Tracker, long ID, long
Count[]);
Parameters:
Tracker – handle of the tracker in which to retrieve the number of similar identifiers.
ID – identifier of the subject for which to return the number of similar identifiers.
Count – pointer to the 64-bit integer value that will store the number of similar identifiers.
FSDK_GetSimilarIDList Function
Returns the list of identifiers that are similar to a given identifier. The function accepts the
identifier returned by FSDK_FeedFrame. This identifier should be passed to
FSDK_GetSimilarIDList before the next call of FSDK_FeedFrame with the same tracker. See
the Understanding Identifiers section for details.
C++ Syntax:
int FSDK_GetSimilarIDList(HTracker Tracker, long long ID, long
long * SimilarIDList, long long MaxSizeInBytes);
Delphi Syntax:
function FSDK_GetSimilarIDList(Tracker: HTracker; ID: int64;
SimilarIDList: PIDArray; MaxSizeInBytes: int64): integer;
C# Syntax:
int FSDK.GetSimilarIDList(int Tracker, long ID, out long[]
SimilarIDList, long MaxSizeInBytes)
VB Syntax:
Function FSDKVB_GetSimilarIDList(ByVal Tracker As Long, ByVal
ID As Currency, ByRef SimilarIDList As Currency, ByVal
MaxSizeInBytes As Currency) As Long
Java and Android Syntax:
int FSDK.GetSimilarIDList(HTracker Tracker, long ID, long
SimilarIDList[], long MaxSizeInBytes);
Parameters:
Tracker – handle of the tracker in which to get the list of similar identifiers.
ID – identifier of the subject for which to return the list of similar identifiers.
SimilarIDList – pointer to the array of 64-bit integer values that will store the list of
similar identifiers.
MaxSizeInBytes – amount of memory allocated for the output array.
Return Value:
Returns FSDKE_OK if successful. Returns FSDKE_ID_NOT_FOUND if the specified ID
was not returned by the previous FSDK_FeedFrame call. Returns
FSDKE_INSUFFICIENT_BUFFER_SIZE if there is not enough room to store the output
string; however, the output string still fills up all the space available.
FSDK_GetAllNames Function
Returns the list of names that an identifier can have. The function accepts the identifier
returned by FSDK_FeedFrame. This identifier should be passed to FSDK_GetAllNames
FSDK_SaveTrackerMemoryToFile Function
Saves the memory of a tracker to a file. Note that tracker parameters, along with its face
tracking state, are not saved. See the Saving and Loading Tracker Memory section for details.
FSDK_LoadTrackerMemoryFromFile Function
Loads the memory of a tracker from a file. Note that tracker parameters, along with its face
tracking state, are not loaded. See the Saving and Loading Tracker Memory section for
details.
C++ Syntax:
int FSDK_LoadTrackerMemoryFromFile(HTracker * Tracker, const
char * FileName);
Delphi Syntax:
function FSDK_LoadTrackerMemoryFromFile(Tracker: PHTracker;
FileName: PAnsiChar): integer;
C# Syntax:
int FSDK.LoadTrackerMemoryFromFile(ref int Tracker, string
FileName);
VB Syntax:
Function FSDKVB_LoadTrackerMemoryFromFile(ByRef Tracker As
Long, ByVal FileName As String) As Long
FSDK_GetTrackerMemoryBufferSize Function
Returns the size of a buffer (in bytes) needed to save the memory of a tracker.
C++ Syntax:
int FSDK_GetTrackerMemoryBufferSize(HTracker Tracker, long
long * BufSize);
Delphi Syntax:
function FSDK_GetTrackerMemoryBufferSize(Tracker: HTracker;
BufSize: PInt64): integer;
C# Syntax:
int FSDK.GetTrackerMemoryBufferSize(int Tracker, ref long
BufSize);
VB Syntax:
Function FSDKVB_GetTrackerMemoryBufferSize(ByVal Tracker As
Long, ByRef BufSize As Currency) As Long
Java and Android Syntax:
int FSDK.GetTrackerMemoryBufferSize(HTracker Tracker, long
BufSize[]);
Parameters:
Tracker – handle of the tracker whose buffer size needs calculation.
BufSize – pointer to the 64-bit integer variable that will store the size of a buffer.
Return Value:
Returns FSDKE_OK if successful.
FSDK_LoadTrackerMemoryFromBuffer Function
Loads the memory of a tracker from a buffer. Note that tracker parameters, along with its face
tracking state, are not loaded. See the Saving and Loading Tracker Memory section for
details.
C++ Syntax:
int FSDK_LoadTrackerMemoryFromBuffer(HTracker * Tracker, const
unsigned char * Buffer);
Delphi Syntax:
function FSDK_LoadTrackerMemoryFromBuffer(Tracker: PHTracker;
var Buffer): integer;
Multi-Core Support
The following FaceSDK functions use multiple CPU cores, thus speeding up the calculations:
FSDK_DetectEyes,
FSDK_DetectEyesInRegion,
FSDK_DetectFace,
FSDK_DetectMultipleFaces,
FSDK_DetectFacialFeatures,
FSDK_DetectFacialFeaturesInRegion,
FSDK_GetFaceTemplate,
FSDK_GetFaceTemplateInRegion,
FSDK_GetFaceTemplateUsingFeatures,
FSDK_GetFaceTemplateUsingEyes,
FSDK_FeedFrame.
By default, these functions use all available processor cores. To get the number of processor
cores used, call the FSDK_GetNumThreads function. To limit the number of processor cores
used, call the FSDK_SetNumThreads function. Calling FSDK_SetNumThreads(1) will
disable multi-core support.
Note that each of these functions forks into a number of threads on each call. It is not
recommended to use nested parallelism when calling these functions; if you need nested
parallelism, you may limit the number of threads with the FSDK_SetNumThreads functions.
For example, if your application runs in several threads, and each thread executes
FSDK_DetectFace (which uses all available cores), this is acceptable; however, if each thread
forks into several threads, each executing FSDK_DetectFace, this could potentially reach the
limit of resources available.
FSDK_GetNumThreads Function
Retrieves the number of processor cores used by FaceSDK.
C++ Syntax:
int FSDK_GetNumThreads(int * Num);
Delphi Syntax:
function FSDK_GetNumThreads(Num: PInteger): integer;
C# Syntax:
int FSDK.GetNumThreads(ref int Num);
VB Syntax:
Function FSDKVB_GetNumThreads(ByRef Num As Long) As Long
Java and Android Syntax:
int FSDK.GetNumThreads(int Num[]);
Parameters:
Num – pointer to an integer valueto receive the number of threads used by FaceSDK.
Return Value:
Returns FSDKE_OK if successful.
FSDK_SetNumThreads Function
Sets the number of processor cores to be used by FaceSDK. If you set the number of cores to
1, support for multiple cores will be disabled, and the SDK will use only a single processor
core.
C++ Syntax:
int FSDK_SetNumThreads(int Num);
Delphi Syntax:
function FSDK_SetNumThreads(Num: integer): integer;
C# Syntax:
int FSDK.SetNumThreads(int Num);
Thread Safety
This chapter describes using FaceSDK in applications that execute FaceSDK functions from
multiple threads. If your program runs in a single thread (by default, this happens in almost all
environments), you can skip this chapter.
Most FaceSDK functions are safe for multithreaded operations. The functions not guaranteed
to be thread-safe are
FSDK_Initialize,
FSDK_Finalize,
FSDK_ActivateLibrary,
FSDK_GetLicenseInfo,
FSDK_GetHardware_ID,
FSDK_SetNumThreads.
When working with cameras in multiple threads on Windows platforms, make sure that each
thread calls the FSDK_InitializeCapturing function and the FSDK_FinalizeCapturing function
when the thread is done. The following functions are thread safe (on all supported platforms)
given that no different threads are simultaneously accessing the same camera handle:
FSDK_GetVideoFormatList,
FSDK_FreeVideoFormatList,
FSDK_SetVideoFormat,
FSDK_OpenVideoCamera,
FSDK_CloseVideoCamera,
FSDK_GrabFrame.
The following functions set global parameters that have effect on each thread:
FSDK_SetFaceDetectionParameters,
FSDK_SetFaceDetectionThreshold,
FSDK_SetJpegCompressionQuality,
FSDK_SetCameraNaming,
FSDK_SetHTTPProxy,
FSDK_SetNumThreads.
Note that HImage is safe only for multiple simultaneous reads or single write. Do not read
from (e.g. with FSDK_DetectFace) and write to (e.g. with FSDK_FreeImage) the same
HImage handle at one time.
Migration
Migration from FaceSDK 6.5 to FaceSDK 6.5.1
The 6.5.1 version improves the extraction of facial templates from images taken under very
low lighting conditions. As the 6.5 version might produce higher false acceptance rates on
such images, it is recommended that you re-extract your facial templates from the source
pictures using the 6.5.1 version.
If you were using Tracker API with the KeepFaceImages parameter set to true, the Tracker
facial appearances will be automatically re-extracted when the Tracker memory, saved with
the 6.5 version, is loaded (using the FSDK_LoadTrackerMemoryFromFile or
FSDK_LoadTrackerMemoryFromBuffer functions). This may take some time, depending on
the size of your Tracker memory. If you were using the Tracker API in very low light, it is
recommended that you start the Tracker memory from scratch and re-enroll your subjects.
Template matching
The 6.5 version substantially increases the speed of face matching on most platforms. You are
unlikely to require any code changes to adapt to this.
If you were using some of these features, you may calculate their approximate
positions by relying on the coordinates of other facial features.
3. You may find that FaceSDK consumes more CPU resources than the previous version.
The SDK uses all available CPU cores for face detection and recognition functions,
achieving higher speed. If you need the SDK to use just a single core (as in the
previous version), use the FSDK_SetNumThreads function.
4. The following functions are deprecated and will not be supported in the future Luxand
FaceSDK versions: FSDK_GetFaceTemplateUsingFeatures
Error Codes
The FaceSDK library defines the following error codes:
Library Information
The FaceSDK library uses:
libjpeg-turbo (copyright by Miyasaka Masaru, TigerVNC and VirtualGL projects);
libcurl © Daniel Stenberg;
libpng © Glenn Randers-Pehrson;
easybmp © The EasyBMP Project (http://easybmp.sourceforge.net);
RSA Data Security, Inc. MD5 Message-Digest Algorithm.