Luxand FaceSDK – Tracker Functions

  FSDK_CreateTracker Function

Creates a new tracker handle to be passed to other Tracker API functions.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – pointer to the integer variable that will to store the created tracker handle.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

New Tracker object.

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – handle of the tracker to be freed.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Note:

Tracker object is freed automatically by destructor.

  FSDK_ClearTracker Function

Clears the content of a tracker, releasing all its memory. The tracker handle stays valid. 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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – handle of the tracker to be cleared.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

Note.

  FSDK_SetTrackerParameter Function

Sets the parameter of a tracker. See the Tracker Parameters section for details.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – handle of the tracker to have parameters set parameters.

ParameterName – name of the parameter to be set.

ParameterValue – value of the parameter.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

None.

Note:

The type of parameterValue can be of types: str, int, float ot bool.

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – handle of the tracker to have parameters set.

Parameters – string containing the parameters and corresponding values to be set.

ErrorPosition – pointer to the integer variable that will receive the position of the character that caused syntax error in the string.

Return Value:

Returns FSDKE_OK if successful. In case of syntax error returns FSDKE_SYNTAX_ERROR and sets the value of the ErrorPosition variable.

Example:

Python Syntax:

Return Value:

None.

Note:

Keyword argumets are interpreted as parameter names with their values to be set.

  FSDK_GetTrackerParameter Function

Retrieves the value of a tracker parameter. See the Tracker Parameters section for details.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – handle of the tracker whose parameter value is desired.

ParameterName – name of the parameter to be retrieved.

ParameterValue – pointer to the output null-terminated string that will store the value of the parameter.

MaxSizeInBytes –amount of memory allocated for the output string.

Return Value:

Returns FSDKE_OK if successful. 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.

Python Syntax:

Return Value:

The value of parameter as string.

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

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.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

The list of identifiers of the tracked faces.

Parameters:

maxIDs – the maximum number of faces tracked in the current frame.

Note:

The list of identifiers of the tracked faces.

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Android Syntax:

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. Returns FSDKE_ATTRIBUTE_NOT_DETECTED if eye centers were not tracked on the previous FSDK_FeedFrame call.

Python Syntax:

Return Value:

The Eyes object.

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Android Syntax:

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. ReturnsFSDKE_ATTRIBUTE_NOT_DETECTED if facial features were not tracked on the previous FSDK_FeedFrame call.

Python Syntax:

Return Value:

The Features object.

Exceptions:

FSDK.IdNotFound
FSDK.AttributeNotDetected

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Android Syntax:

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.

Python Syntax:

Return Value:

The FacePosition object.

Exceptions:

FSDK.IdNotFound

  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_GetTrackerFacialAttribute before the next call of FSDK_FeedFrame with the same tracker.

The function allows for detecting gender when provided with the "Gender" attribute name, for detecting age when provided with the "Age" attribute name and for detecting expression when provided with the "Expression" attribute name. Refer to the FSDK_DetectFacialAttributeUsingFeatures function description for details on attributes, their Values and Confidences.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – handle of the tracker whose attribute will be retrieved.

CameraIdx – index of the camera; should be equal to 0 in the current release.

ID – identifier of a subject returned by FSDK_FeedFrame whose attribute will be retrieved.

AttributeName – name of the attribute.

AttributeValues – pointer to the null-terminated string that will receive the attribute Values and their Confidences.

MaxSizeInBytes – amount of memory allocated for the output string.

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. ReturnsFSDKE_ATTRIBUTE_NOT_DETECTED if the specified attribute was not detected on the previous FSDK_FeedFrame call. Returns FSDKE_UNKNOWN_ATTRIBUTE if the specified attribute name is not supported. 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.

Python Syntax:

Return Value:

The attribute Values and their Confidences as string.

Exceptions:

FSDK.IdNotFound
FSDK.AttributeNotDetected
FSDK.UnknownAttribute

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

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.

Python Syntax:

Return Value:

None.

Exceptions:

FSDK.IdNotFound.

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – handle of the tracker in which to unlock an identifier.

ID – identifier of the subject to unlock.

Return Value:

Returns FSDKE_OK if successful. Returns FSDKE_ID_NOT_FOUND if the specified ID is not present in the tracker memory.

Python Syntax:

Return Value:

None.

Exceptions:

FSDK.IdNotFound

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

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.

Python Syntax:

Return Value:

None.

Exceptions:

FSDK.IdNotFound.

  FSDK_GetName Function

Returns the name the identifier has been tagged with. 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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – handle of the tracker in which to retrieve the name.

ID – identifier of a subject to retrieve the name of.

Name – identifier of the subject whose name is to be retrieved.

MaxSizeInBytes – amount of memory allocated for the output string.

Return Value:

Returns FSDKE_OK if successful. 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. Returns FSDKE_ID_NOT_FOUND if the specified ID is not present in the tracker memory.

Python Syntax:

Return Value:

Identifier of the subject whose name is to be retrieved.

Exceptions:

FSDK.IdNotFound

  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.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java Syntax:

Parameters:

Tracker – handle of the tracker in which to set the name.

ID – identifier of the subject whose name is to be set.

Name – pointer to the null-terminated string containing the name of an identifier.

Return Value:

Returns FSDKE_OK if successful. Returns FSDKE_ID_NOT_FOUND if the specified ID is not present in the tracker memory.

Returns FSDKE_INSUFFICIENT_TRACKER_MEMORY_LIMIT if there is not enough room to store the identifier’s facial appearances in memory. See the Tracker Memory section for details.

Python Syntax:

Return Value:

None.

Exceptions:

FSDK.IdNotFound.

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – handle of the tracker in which to get the reassigned ID value.

ID – identifier of the subject whose reassigned identifier is sought.

ReassignedID – pointer to the 64-bit integer value that will store the reassigned value of an identifier.

Return Value:

Returns FSDKE_OK if successful.

Python Syntax:

Return Value:

Identifier of the subject whose reassigned identifier is sought.

Exceptions:

FSDK.IdNotFound

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

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.

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.

Python Syntax:

Return Value:

The number of similar identifiers.

Exceptions:

FSDK.IdNotFound

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

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.

Python Syntax:

Return Value:

The list of similar identifiers.

Exceptions:

FSDK.IdNotFound

  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 before the next call of FSDK_FeedFrame with the same tracker. See the Understanding Identifiers and Dealing with false acceptances sections for details.

The function returns all names that belong to a given identifier, and similar identifiers, separated by a semicolon. The output format is:

"Name1[;Name2[;…]]"

You should call this function instead of FSDK_GetName whenever possible, and then parse the returned string for all returned names. Alternatively, you may implement the functionality of FSDK_GetAllNames, calling FSDK_GetName on the given identifier, then FSDK_GetSimilarIDCount and FSDK_GetSimilarIDList to get the list of similar identifiers, then finally call FSDK_GetName on that list.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – handle of the tracker in which to retrieve the names.

ID – identifier of the subject whose possible names are to be retrieved.

Names – pointer to the null-terminated string that will receive the possible names of an identifier.

MaxSizeInBytes – amount of memory allocated for the output string.

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.

Python Syntax:

Return Value:

The list of possible names of an identifier.

Exceptions:

FSDK.IdNotFound.

  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.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and AndroidSyntax:

Parameters:

Tracker – handle of the tracker to save.

FileName – pointer to the null-terminated string containing the name of the file to which the tracker memory will be saved.

Return Value:

Returns FSDKE_OK if successful. Returns FSDKE_IO_ERROR if an I/O error has occurred.

Python Syntax:

Return Value:

None.

Exceptions:

FSDK.IOError

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – pointer that will store the handle of the loaded tracker.

FileName – pointer to the null-terminated string containing the name of a file from which the tracker memory will be to loaded.

Return Value:

Returns FSDKE_OK if successful. Returns FSDKE_BAD_FILE_FORMAT if the file has unsupported format. Returns FSDKE_UNSUPPORTED_FILE_VERSION if the file was saved with Luxand FaceSDK of an unsupported version. Returns FSDKE_FILE_NOT_FOUND if there was an error opening the file. Returns FSDKE_IO_ERROR if an I/O error has occurred.

Python Syntax:

Return Value:

New Tracker object loaded from file.

Exceptions:

FSDK.IOError
FSDK.BadFileFormat
FSDK.UnsupportedFileVersion
FSDK.FileNotFound

  FSDK_GetTrackerMemoryBufferSize Function

Returns the size of a buffer (in bytes) needed to save the memory of a tracker.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

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.

Python Syntax:

Return Value:

The size of a buffer.

  FSDK_SaveTrackerMemoryToBuffer Function

Saves the memory of a tracker to a buffer. Note that tracker parameters, along with its face tracking state, are not saved. See the Saving and Loading Tracker Memory section for details.

C++ Syntax:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – handle of the tracker to save.

Buffer – pointer to the buffer to which the tracker memory will be saved.

MaxSizeInBytes – amount of memory allocated for the output buffer, in bytes.

Return Value:

Returns FSDKE_OK if successful. Returns FSDKE_INSUFFICIENT_BUFFER_SIZE if there is not enough room to store the output buffer.

Python Syntax:

Return Value:

The bytes objects containing tracker memory.

  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:

Delphi Syntax:

C# Syntax:

VB Syntax:

Java and Android Syntax:

Parameters:

Tracker – pointer to store the handle of a loaded tracker.

Buffer – pointer to the buffer from which to load the tracker memory.

Return Value:

Returns FSDKE_OK if successful. Returns FSDKE_BAD_FILE_FORMAT if the file has unsupported format. Returns FSDKE_UNSUPPORTED_FILE_VERSION if the file was saved with Luxand FaceSDK of an unsupported version.

Python Syntax:

Return Value:

New Tracker objects loaded from a buffer.

 

Next chapter: Multi-Core Support

Contents