Luxand FaceSDK – Migration
Migration from FaceSDK 7.2, 7.2.1 to FaceSDK 8.0, 8.1
For compatibility with the latest Xcode versions the libfsdk-static.a and libfsdk-static_64.a libraries for iOS have been joined into a single library libfsdk-static.a.
.NET applications now use FaceSDK.NET.dll built from the samples\advanced\.NET wrapper source, so adding the appropriate binary file (facesdk.dll, libfsdk.dylib or libfsdk.so) is required.
The minimum supported iOS version is 9.0.
The minimum supported Android version is 5.0.
The minimum supported Windows version is Windows 7.
The minimum supported macOS version is 10.13.
Migration from FaceSDK 7.1 to FaceSDK 7.2, 7.2.1
InternalResizeWidth parameter values larger than 512 are now supported to allow for the detection of even small faces on high-resolution images.
JPEG images are now automatically rotated on load using the EXIF data.
The minimum supported Linux versions are CentOS/RHEL 7. Older Linux versions are no longer supported.
The minimum supported Windows version is Windows Vista.
Migration from FaceSDK 6.5.1 to FaceSDK 7.0, 7.1
Face Detection
Version 7.0 introduces a new face detection engine, which is more accurate when detecting faces that are rotated out of plane, blurred, backlit, or in low lighting conditions.
The new engine does not currently support InternalResizeWidth parameter values larger than 512 (see the FSDK_SetFaceDetectionParameters chapter). If you are detecting small faces on high-resolution images with large InternalResizeWidth values, consider splitting such images into parts.
When the InternalResizeWidth is set to 512, faces that are heavily cropped and occupy almost all of the image (such as when a face is too close to the camera) could be detected less often than when smaller InternalResizeWidth values are used. However, large InternalResizeWidth values are not necessary when detecting such faces. In this case, consider setting the InternalResizeWidth to 256 or less.
As the new engine uses color information, the face detection rates on grayscale images could be lower (especially on small faces).
You may find that small faces are detected less often. In this case, try increasing the InternalResizeWidth value, as the internal meaning of InternalResizeWidth has changed in the engine.
Template format changes
Version 7.0 improves the accuracy of the FSDK_GetFaceTemplate and FSDK_MatchFaces functions. Templates are extracted in such a way that the false acceptance rates are decreased when matching blurred, low-lit, and out-of-plane faces.
The accuracy of matching templates extracted by previous FaceSDK versions is unchanged. To enjoy the increased accuracy, consider re-extracting your templates from the source images by using version 7.0.
If you are 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 versions 6.5 or 6.5.1, is loaded (using the FSDK_LoadTrackerMemoryFromFile or FSDK_LoadTrackerMemoryFromBuffer functions). This may take some time, depending on the size of your Tracker memory.
Removal of libstdc++ dependency on iOS
FaceSDK 7.0 for iOS has removed the dependency on the libstdc++ library to increase compatibility with Xcode 10. FaceSDK sample applications for iOS are no longer using libstdc++. To switch from using libstdc++ to using libc++ in your Xcode project, visit Build Settings – C++ Standard Library. iOS 5.x and 6.x are no longer supported.
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.
Migration from FaceSDK 6.3, 6.3.1, 6.4 to FaceSDK 6.5
Template format changes
The 6.5 version improves face matching accuracy. It achieves a true acceptance rate of 99.83% and a false acceptance rate of 0.1% for the NIST FRGC protocol, ROC1 (compared to the 93.9% true acceptance rate achieved by the 6.4 version).
To achieve the accuracy increase, it was necessary to change the format of the face template (the FSDK_FaceTemplate structure). The size of the face template was decreased to 1040 bytes. To migrate to the 6.5 version and start using the new face templates, you need to update the Luxand FaceSDK interface header files in your project (see Using FaceSDK with Programming Languages) and rebuild your application. If you were relying on the size of the old face template structure (13324 bytes), for example, while saving it to a database, you need to change this value to 1040.
As the new face template is not compatible with the face template from previous versions, you need to re-extract the templates for every face in your database (with the FSDK_GetFaceTemplate, FSDK_GetFaceTemplateInRegion, or FSDK_GetFaceTemplateUsingFeatures functions) from the source pictures. As the template format may change again in future versions, it is recommended that you store both the original face images and their templates in the database.
The 6.5 version increased its matching accuracy, because of its more sophisticated models. However, such models require more calculations. The speed of template extraction is now lower than in the 6.4 version. This means that on slow devices, you may get lower frame rates when extracting face templates, with either the FSDK_GetFaceTemplate, FSDK_GetFaceTemplateInRegion, or FSDK_GetFaceTemplateUsingFeatures functions.
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.
Tracker API changes
Since the template format has changed, the Tracker memory from previous Luxand FaceSDK versions is not compatible with the 6.5 version. This means you cannot load the Tracker memory saved with Luxand FaceSDK 6.4 (and earlier) using the FSDK_LoadTrackerMemoryFromFile or FSDK_LoadTrackerMemoryFromBuffer functions. To migrate to the 6.5 version, you need to start a new Tracker memory file and enroll all your subjects again.
If it is not possible for you to regenerate the templates or start a new Tracker memory, please contact our support at https://www.luxand.com/support/.
To make the transition to new template formats easier when using Tracker API, we added the KeepFaceImages parameter. When set to true (which is the default value), it will store the original facial images in the Tracker memory. If the template format changes in the new version of Tracker API, you will be able to convert your previous Tracker memory to the new template format automatically, so you won’t need to reenroll your subjects. If you don’t like the original facial images to be stored in the Tracker memory, you need to explicitly set this parameter to false. See the Storing original facial images section for more details.
As the speed of template extraction has decreased compared to the 6.4 version, you may get lower frame rates when the RecognizeFaces parameter is set to true. In older versions, it was recommended that higher frame rates were preferable, in order that Tracker API could collect more facial appearances of a person per unit of time, which positively affected the accuracy (see the Tuning for Optimal Performance chapter). However, the Tracker API in the 6.5 version is less affected by the frame rate, because it has more robust face matching. Even if you’re processing about 1 frame per second on a slow device, it is usually enough for Tracker API to efficiently recognize persons; even with that frame rate, you’re likely to get much higher recognition rates than in the 6.4 version with higher frame rates.
Note that if your RecognizeFaces is set to false when using Tracker API (for example, when you only detect faces or facial features), your frame rate will not decrease.
The RecognitionPrecision parameter now has no effect and is not recommended for use.
Migration from FaceSDK 6.2 to FaceSDK 6.3, 6.3.1, 6.4
The 6.3 version increases minimal OS version requirements. Applications developed with Luxand FaceSDK 6.3 will not support any Windows versions earlier than Windows XP SP3 or Windows 2003 SP2 and will not support any macOS versions earlier than 10.7.
If you are using Luxand FaceSDK with Microsoft .NET, note that FaceSDK.NET.dll now requires .NET 4.0 or higher. You need to redistribute Microsoft Visual C++ Redistributable for Visual Studio 2017 with your application.
If you are using an older version of .NET (for example, 2.0, 3.0 or 3.5), you must switch to the component available in the source code form in the samples\advanced\.NET wrapper directory. Note that this component is actually a wrapper for facesdk.dll that is linked dynamically, so facesdk.dll must be redistributed with the application that uses this wrapper. The LiveRecognition sample includes projects for Microsoft C# 2005/2008 and Visual Basic .NET 2005/2008 that are using this wrapper.
The LiveFacialFeatures, GenderRecognition and ExpressionRecognition samples were updated to be compatible with iOS 11. If your code was based on these samples, update your code as indicated below. You need to implement the changes as per the illustration (in short, moving the code that creates the cache from drawFrameWithWidth to onGLInit). These changes were implemented in the TrackingViewController.mm file of the samples.
Migration from FaceSDK 6.0, 6.0.1, 6.1 to FaceSDK 6.2
The 6.2 version adds 4 new facial feature points (numbered 66 to 69), detecting 70 facial features instead of 66 in the previous release. The following constants are added:
- FSDKP_FACE_CONTOUR14,
- FSDKP_FACE_CONTOUR15,
- FSDKP_FACE_CONTOUR16,
- FSDKP_FACE_CONTOUR17.
The numbering of the 66 facial features detected previously was not changed. It means that the new numbering is backwards compatible with the previous numbering. When migrating to the 6.2 version, make sure that you are using the new header files (or wrappers), since the FSDK_Features type now contains 4 more points.
The FSDK_GetFaceTemplateUsingFeatures function still employs only the first 66 facial features.
The performance of retrieving live video in the LiveFacialFeatures sample for iOS and Android is increased. If you were using this sample code in your project, consider replacing the corresponding parts of your code to increase the performance of your app.
Migration from FaceSDK 5.0, 5.0.1 to FaceSDK 6.0, 6.0.1, 6.1
Important changes for users migrating to Luxand FaceSDK 6.1, 6.0.1 or 6.0 from the 5.0.1 or 5.0 versions:
The FSDK_GetFaceTemplate and FSDK_GetFaceTemplateInRegion functions now detect facial features with the same accuracy as the FSDK_DetectFacialFeatures function. The accuracy of face recognition isnow the same regardless of whether you call FSDK_GetFaceTemplate/FSDK_GetFaceTemplateInRegion or first detect facial features and then pass them to the FSDK_GetFaceTemplateUsingFeatures function.
The recognition accuracy of Tracker API when RecognitionPrecision=1 is now independent of the values of the DetectFacialFeatures or DetectGender parameters.
The FacialFeatureJitterSuppression parameter of Tracker API now allows for better facial feature smoothing; however, its default setting may consume more processor resources. You may set its value to 0 if you need to consume fewer resources.
Migration from FaceSDK 4.0 to FaceSDK 5.0, 5.0.1
Important changes for users migrating to Luxand FaceSDK 5.0 or 5.0.1 from the 4.0 version:
The function FSDK_GetFaceTemplateUsingFeatures is no longer deprecated. The function expects that the coordinates of all facial features are detected. If you are passing just the coordinates of eye centers (detected with FSDK_DetectEyes, FSDK_DetectEyesInRegion) to the function, call FSDK_GetFaceTemplateUsingEyes instead.
The format of the face template has changed. The size of the template is now 13324 bytes. If you have stored face templates in a database, you must recreate them from the original photos by calling the FSDK_GetFaceTemplate or FSDK_GetFaceTemplateInRegion functions.
The FSDK_MatchFaces function now returns an error when the template has an invalid format or when the formats of the templates are not supported (that is, when face templates was created with an unsupported version of Luxand FaceSDK).
If you were calling FSDK_GetFaceTemplate or FSDK_GetFaceTemplateInRegion, you may find that they consume more time. This is because these functions extract face templates with higher accuracy. If you need higher performance, replace these calls with FSDK_DetectEyes or FSDK_DetectEyesInRegion, and call FSDK_GetFaceTemplateUsingEyes. See the Face Matching section for details.
On the other hand, if you were detecting eyes and then passing their coordinates to FSDK_GetFaceTemplateUsingEyes, you need to replace this call together with the detection of eye centers to the FSDK_GetFaceTemplate or FSDK_GetFaceTemplateInRegion function to achieve the higher accuracy available in the 5.0 version.
Migration from FaceSDK 3.0 to FaceSDK 4.0
Recommendations on how to migrate from version 3.0 to version 4.0 are included.
- The 4.0 version introduces a new high-quality algorithm for facial feature detection. The new version detects 66 facial features (see the Detected Facial Features chapter).
- The 4.0 version enhances the accuracy of inner facial feature (nose, eyes, and mouth) detection. To make this enhancement possible, facial feature points of the upper part of the head were removed. The following facial feature points (and their corresponding constants) were removed:
- FSDKP_FACE_CONTOUR3, FSDKP_FACE_CONTOUR4, FSDKP_FACE_CONTOUR5, FSDKP_FACE_CONTOUR6, FSDKP_FACE_CONTOUR7, FSDKP_FACE_CONTOUR8, FSDKP_FACE_CONTOUR9, FSDKP_FACE_CONTOUR10, FSDKP_FACE_CONTOUR11
- If you were using some of these features, you may calculate their approximate positions by relying on the coordinates of other facial features.
- 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.
- The following functions are deprecated and will not be supported in the future Luxand FaceSDK versions: FSDK_GetFaceTemplateUsingFeatures.
Migration from FaceSDK 2.0 to FaceSDK 3.0
This section tells about changes in FaceSDK 3.0 as compared to FaceSDK 2.0. There are also recommendations on how to migrate from version 2.0 to version 3.0.
- As version 3.0 has introduced a new enhanced face recognition algorithm, the format of a template changed as well. Now it is enough to detect only eye centers, rather than all features to build a template. If your application used to detect facial features and then created a template using detected features, now the feature detection stage can be skipped or replaced by detection of eye centers (i.e. FSDK_DetectFacialFeatures can be replaced by FSDK_DetectEyes). The size of a template was reduced to 16384 bytes. If your application used a database of saved templates, it is necessary to recreate these templates using source images.
- New version introduces new functions for quick detection of eye centers – FSDK_DetectEyes and FSDK_DetectEyesInRegion. These functions are recommended for use if it is necessary to detect eye centers in real time.
- The meaning of similarity returned by FSDK_MatchFaces function has changed. Now similarity is approximately equal to the probability that templates belong to one and the same person. More information on this topic can be found in Face Matching chapter.
- The new FSDK_SetCameraNaming function is added. It determines what the FSDK_GetCameraList function returns – either the list of camera names available in the system, or the list of unique device paths of these cameras. (It may be required if two similar webcams of the same manufacturer are plugged in to the computer.)
- Camera management functions are included into facesdk.dll. If you used camera management in your applications, you may remove facesdkcam.dll and header files related to facesdkcam.
- .NET wrapper does not require facesdk.dll. The camera management functions are also included into FaceSDK.NET.dll (but they are still located in class FSDKcam). Now the wrapper is located in the directories \bin\win32\ for 32-bit applications and \bin\win64\ for 64-bit applications.
- The following functions have been removed from the library and will not be supported: FSDK_LocateFace, FSDK_LocateFacialFeatures, FSDK_ExtractFaceImage.
- The following functions are deprecated and will not be supported in the future Luxand FaceSDK versions: FSDK_GetFaceTemplateUsingFeatures.