General questions

What skills do I need in order to use visage|SDK?

Software development skills are required to make use of visage|SDK.

visage|SDK is a Software Development Kit - a set of documented software libraries that software developers can use to integrate Visage Technologies' face tracking, analysis and recognition algorithms into their applications.

See also:

Can I install your software on my computer and just run it?

No. visage|SDK is not a finalized application, but a Software Development Kit that you use to develop/integrate your application. This is what your software development team can hopefully do, based on the documentation delivered as part of visage|SDK.

See also:

Can you develop an application for me?

Visage Technologies' software development team is available to develop custom-made applications to your requirements, using our face technology as the basis (we don’t do general app development). To do that, we need specific and detailed requirements for the application, including:

Some additional remarks on the way of working:

Your contact person can provide further details.

See also:

Am I entitled to receive technical support?

See also:

How to request technical support?

If you have a technical issue using visage|SDK, please email your Visage Technologies contact person the following information:







See also:

How do I migrate to a newer version of visage|SDK?

Migration to a new version of visage|SDK is covered on the migration page. See Migration guide.

Typical steps when upgrading visage|SDK are:

  1. Obtain new library files (usually in visageSDK/lib) (.dll, .so, .a, .lib) and overwrite the old ones in your application.

  2. Obtain new header files (usually in visageSDK/include) and overwrite the old ones in your application.

  3. Obtain new data files (usually in visageSDK/Samples/data) and overwrite the old ones in your application (models as well).

  4. Read about the changes in parameters of the configuration files and apply them to your configuration. In case you use default configuration, just overwrite it with the new one.

How does visage|SDK handle privacy? GDPR compliance?

Regarding GDPR and privacy issues in general: visage|SDK runs entirely on the client device and it does not store or transmit any personal information (photos, names or similar), or even any other information (other than Visage Technologies License Key File, for licensing purposes).

Languages, platforms, tools etc.

Can I use visage|SDK with Unity?

Integration with Unity 3D game engine is available with visage|SDK packages for Windows, iOS, Android, MAC OS X and HTML5. Each of these packages includes Unity sample projects to help you get started. Unity 3D integration is implemented via the VisageTrackerUnityPlugin plugin. This is a wrapper that exposes visage|SDK functionalities for use in C#.

You can either start your own project from scratch (Unity3D integration), or look for the VisageTrackerUnityDemo sample that comes with full source code so you can use it as know-how for your project.

Can I use visage|SDK with C#?


For the C# API, please look in the API Reference. This is a managed C# wrapper that exposes all of visage|SDK functionalities – face tracking, analysis and recognition.

The C# API is implemented in VisageCSWrapper.dll library (libVisageVision64.dll and other dependencies are required for running).

Additionally, we provide VisageTrackerUnityPlugin, which is a C# wrapper made specifically for integration with Unity 3D engine. For more information, please take a look at Unity3D. The VisageTrackerUnityPlugin comes included with visage|SDK for Windows, MAC OS X, iOS and Android.

Can I use visage|SDK with Java?

visage|SDK is implemented in C++. It provides C++ and C# APIs, but unfortunately currently does not include a Java API. visage|SDK for Android includes JNI-based Java wrappers as part of the sample projects provided in the package. You can use these wrappers as a starting point for your own projects in Java. In conclusion, it is certainly possible to use visage|SDK with Java, but it requires some additional effort for interfacing via JNA wrappers.

Can I use visage|SDK with VB.NET (Visual Basic)?


visage|SDK does not currently provide a VB.NET API.

For users willing to experiment, there is an undocumented and currently unsupported workaround that should allow to use it.

visage|SDK is implemented in C++. It provides C++ and C# APIs. On Windows, the C# API is implemented as a C++/CLI library (VisageCSWrapper.dll) which, in theory, should be usable in other NET languages, e.g. VB.NET. However, we have not tested this. The C# API documentation may be used as a basis for usage of VisageCSWrapper C++/CLI library in VB.NET.

Can I use visage|SDK with Python?


visage|SDK does not currently provide a Python API.

For users willing to experiment, there is an undocumented workaround that allows users to use Python.

visage|SDK is implemented in C++ and provides C++ API which cannot easily be used directly in Python without a C functions wrapper. visage|SDK provides such a wrapper in the form of VisageTrackerUnityPlugin which was made specifically for integration with Unity 3D engine. However, it can also be used by other applications/languages that support importing C functions from a library. At its core, the VisageTrackerUnityPlugin is a high-level C functions API wrapper around C++ API. In the case of Python, ctypes library (foreign function library for Python) can be used to import and use C functions from VisageTrackerUnityPlugin. As the source code is provided, VisageTrackerUnityPlugin can also be used to implement custom Python wrapper.
Even though it was tested, such usage of VisageTrackerUnityPlugin is not officially supported.

Can I use visage|SDK with UWP?

Our API is a lower-level C++ API and we have no specific UWP integration features, but we see no reason why you would not be able to use it in a UWP app.

Can I use visage|SDK with React Native?

visage|SDK does not currently provide direct support for React Native.

For users willing to experiment, there is an undocumented workaround that allows use of visage|SDK in React Native.

visage|SDK is implemented in C++ and provides C++ API, therefore direct calls from React Native are not possible without a wrapper with C-interface functions. An example of such a wrapper is provided in visage|SDK in the form of VisageTrackerUnityPlugin which provides simpler, high-level API through a C-interface. It is intended for integration with Unity 3D (in C# with P/Invoke), but it can also be used by other applications/languages that support importing and calling C-functions from a native library, including React Native.

Can I use visage|SDK with Flutter?

visage|SDK does not currently provide direct support for Flutter.

For users willing to experiment, there is an undocumented workaround that allows use of visage|SDK in Flutter.
visage|SDK is implemented in C++ and provides C++ API. Therefore, direct calls from Flutter are not possible without a wrapper with C-interface functions. An example of such a wrapper is provided in visage|SDK in the form of VisageTrackerUnity Plugin which provides simpler, high-level API through a C-interface. It is intended for integration with Unity 3D (in C# with P/Invoke), but it can also be used by other applications/languages that support importing and calling C-functions from a native library, including Flutter.

See also

Can I use visage|SDK with Swift?

visage|SDK does not currently provide a Swift API.

visage|SDK is implemented in C++ and provides C++ API which cannot be used directly in Swift without first wrapping C++ API in an NSObject and exposing it to Swift through bridging-header. Wrapping in an NSObject does not have to be one-on-one mapping with C++ classes. Instead, it can be a higher level mapping and fragments of source code from provided iOS sample projects can be used as building blocks.

A general example of how this technique is usually implemented can be found here:
https://stackoverflow.com/questions/48971931/bridging-c-code-into-my-swift-code-what-file-extensions-go-to-which-c-based-l

A way without wrapping NSObject is by wrapping C++ API in C-interface functions and exposing them through bridging-header. Example of such a wrapper is provided in visage|SDK in the form of VisageTrackerUnityPlugin which provides simpler, high-level API through a C-interface.

A general example of how this technique is usually implemented can be found here:
https://www.swiftprogrammer.info/swift_call_cpp.html

Can I use visage|SDK in WebView (in iOS and Android)?

We believe that it should be possible to use visage|SDK in WebView, but we have not tried that nor have any clients currently who have done that so we cannot guarantee it. Performance will almost certainly be lower than with a native app.

Is there visage|SDK for Raspberry PI?


visage|SDK 8.4 for rPI can be downloaded from the following link: https://www.visagetechnologies.com/downloads/visageSDK-rPI-linux_v8.4.tar.bz2
Once you unpack it, you will find the documentation in the root folder. It will guide you through the API and the available sample projects.

Important notes:

Will visage|SDK for HTML5 work in browsers on smartphones?


The HTML5 demo page contains the list of supported browsers: https://visagetechnologies.com/demo/#supported-browsers

Please note that the current HTML5 demos have not been optimized for use in mobile browsers. Therefore, for the best results it is recommended to use a desktop browser.

On iOS, the HTML5 demos work in Safari browser version 14 and higher. They do not work in Chrome and Firefox browsers due to limitations on camera access.
(https://stackoverflow.com/questions/59190472/webrtc-in-chrome-ios)

Which browsers does visage|SDK for HTML5 support?


The HTML5 demo page contains the list of supported browsers: https://visagetechnologies.com/demo/#supported-browsers

Please note that the current HTML5 demos have not been optimized for use in mobile browsers. Therefore, for the best results it is recommended to use a desktop browser.

Internet connection and privacy issues

Does my device/app need internet connection?

Applications developed using visage|SDK do not need an internet connection for operation.

Internet connection is needed only for license registration, which happens only once, when the application is used for the first time.

For hardware devices, this can typically be done at installation time – you would connect the device to the network, run the application once, the license registration would happen automatically, and after that no network connection is needed.

How do you handle privacy of user data? Does visage|SDK store or send it to a cloud server?

visage|SDK never transfers any user information to any server.

visage|SDK never automatically stores any user information locally.

In summary, you as the application developer have full control and responsibility for any storage or transfer of user data that you may implement in your application.

Cameras, hardware

Can I use visage|SDK with an IP camera?

Yes, visage|SDK can be used with any IP camera. However, note that visage|SDK actually does not include camera support as part of the API; the API simply takes a bitmap image. Image grabbing from camera is implemented at the application level.

Our sample projects show how to access local cameras and we currently have no ready-to-go code for accessing IP cameras. There are various ways to grab images from IP cameras, for example by using libVLC.
Usually, IP cameras should provide a URL from which you can access the raw camera feed. If you can open the URL and see the feed in VideoLAN VLC Media Player, the same URL can be used in libVLC to access the feed programmatically.

See also:

Are these camera specs OK for visage|SDK: 1920 x 1080, 30 fps, mono?

The mentioned camera parameters (1920 x 1080, 30 fps, mono) should be appropriate for our software and most of the use cases.

This text requires review after the introduction of new face detector in V8.7b2. Also, https://visagetechnologies.com/facetrack-features/ needs to be reviewed.

In general, visage|SDK works with a very wide range of camera resolutions and can provide sustainable tracking on faces as small as 30×30 pixels. For further details on inputs and other features specifically for face tracking, please see https://visagetechnologies.com/facetrack-features.

What should be the camera Field of View (FoV)?

Regarding the FoV, the selection should primarily depend on the use case (planned position of the camera and the captured scene). Our algorithm should be robust enough to handle some optical distortions that may be a consequence of lenses with large FoV. However, extreme distortions (e.g. fish-eye lens) will negatively affect the algorithm's performance.

Face Tracking

Can I process a video and save tracking data/information to a file?

There is no ready-made application to do this, but it can be achieved by modifying the existing sample projects. Such modification should be simple to do for any software developer, based on the documentation delivered as part of visage|SDK. We provide some instructions here.

To get you started, each platform specific visage|SDK package contains sample projects with full source code that can be modified for that purpose. See Samples page to find the documentation of the specific sample projects.

On Windows, there are Visual Studio 2015 samples: ShowcaseDemo which is written in C# and FaceTracker2 which is written in C++.

On macOS, there is an Xcode sample: VisageTrackerDemo which is written in Objective-C++.

Processing and saving information to a file can be implemented in parts of the sample projects where tracking from video file is performed:

Please search source code of each sample for the exact location.

Sample projects have “video_file_sync“ (or similarly named functionality) enabled, which skips video frames if tracking is slower than real-time. This functionality should be disabled for full video processing i.e processing of all video frames.


See also:

How many faces can be tracked simultaneously?

The maximum number of faces that can be tracked simultaneously is internally limited to 20 for performance reasons.

Using API Reference → VisageFeaturesDetector, any number of faces can be detected in an image.

How far from the camera can the face be tracked/detected?

This text requires review after the introduction of new face detector in V8.7b2.

The tracking distance depends on the camera resolution. For the face to be detected and tracked, it should be at least 30 pixels wide in the image. For example, for a webcam with resolution 1920×1080 (Logitech C920), the tracker can be configured to detect and track faces up to ~7.25 meters from the camera (with performance trade-off).

See also:

Face tracking does not work as I expected

Our face tracking algorithm is among the best ones available, but like all Computer Vision algorithms it has its limits related to image quality, light conditions, occlusions or specific reasons such as head pose.

If you notice specific issues or have special requirements, you may send us your test video footage and any specific requests, and we will process it and send you back the tracking results. This can allow us to fine-tune the tracker configuration to your specific requirements and send you the best possible results.

How can I test and use ear tracking?

The fastest way to test ear tracking is in the online Showcase Demo (https://visagetechnologies.com/demo/). Simply enable Ears in the Draw Options menu.

The online demo is based on visage|SDK for HTML5 and has some limitations due to the HTML5 implementation. For even better performance, you may want to download other visage|SDK for Windows, Android or iOS - each of these packages contains a native ShowcaseDemo in which ear tracking can be tried.

If you are already developing using visage|SDK and want to enable ear tracking, you can use the ready-made configuration file “Facial Features Tracker - High - With Ears.cfg“. Ear tracking is enabled using the refine_ears configuration parameter.

See also:


Face Recognition

How far from a camera can a face be recognized?

This depends on camera resolution. Face Recognition works best when the size of the face in the image is at least 100 pixels.

See also:

High-level functionalities

How do I perform liveness detection with visage|SDK?

visage|SDK includes active liveness detection. The user is required to perform a simple facial gesture (smile, blink or raise eyebrows). Face tracking is then used to verify that the gesture is actually performed. You can configure which gesture(s) you want to include. As the app developer, you also need to take care of displaying appropriate messages to the user.

All visage|SDK packages include the API for liveness detection. However, only the visage|SDK for Windows and visage|SDK for Android contain a ready-to-run demo of Liveness Detection. So, for a quick test of the liveness detection function, it would probably be the easiest to downoad visage|SDK for Windows, run “DEMO_FaceTracker2.exe” and select “Perform Liveness” from the Liveness menu.

The technical demos in Android and Windows packages of visage|SDK include the source code intended to help you integrate liveness detection into your own application.

See also:

How do I perform identification of a person from a database?

This article outlines the implementation of using face recognition for identifying a person from a database of known people. It may be applied to cases such as whitelists for access control or attendance management, blacklists for alerts, and similar. The main processes involved in implementing this scenario are registration and matching, as follows.

Registration

Assuming that you have an image and an ID (name, number or similar) for each person, you register each person by storing their face descriptor into a gallery (database). For each person, the process is as follows:

Matching

An this stage, you match a new facial image (for example, a person arriving at a gate, reception, control point or similar) against the previously stored gallery, and obtain IDs of one or more most similar persons registered in the gallery.

Need to insert links to relevant API parts in text and/or as “See also” section.

How do I perform verification of a live face vs. an ID photo?

The scenario is the verification of a live face image against the image of a face from an ID. This is done in four main steps:

These steps are described here with further detail:

Need to insert links to relevant API parts in text and/or as “See also” section.

How do I determine if a person is looking at the screen?

visage|SDK does not have an out-of-the box option to determine if the person is looking at the screen. However, it should not be too difficult to implement that. What visage|SDK does provide is:

Now, if you also know the size of the screen and the position of the camera with respect to the screen, you can:

Please also note that the estimated gaze direction may be a bit unstable (the gaze vectors appearing “shaky”) due to the difficulty of accurately locating the pupils. At the same time, the 3D head pose (head direction) is much more stable. Because people usually turn their head in the direction in which they are looking, it may also be interesting to use the head pose as the approximation of the direction of gaze.

Here is a code snippet used to roughly calculate screen space gaze by combining data from visage|SDK and external information about screen (in meters) and camera relation which can be used to determine if user is looking at the screen or not (if calculated coordinates are outside the screen range):


   // formula to get screen space gaze

    x = faceData->faceTranslation[2] * tan(faceData->faceRotation[1] + faceData->gazeDirection[0] + rOffsetX) / screenWidth; // rOffsetX angle of camera in relation to screen, ideally 0

    y = faceData->faceTranslation[2] * tan(faceData->faceRotation[0] + faceData->gazeDirection[1] + rOffsetY) / screenHeight; // rOffsetY angle of camera in relation to screen, ideally 0

    // apply head and camera offset

    x += -(faceData->faceTranslation[0] + camOffsetX); // camOffsetX in meters from left edge of the screen

    y += -(faceData->faceTranslation[1] + camOffsetY); // camOffsetY in meters from top edge of the screen


Need to insert links to relevant API parts in text and/or as “See also” section.

Can images of crowds be processed?

visage|SDK can be used to locate and track faces in group/crowd images and also to perform face recognition (identity) and face analysis (age, gender, emotion estimation). Such use requires particular care related to performance issues since there may be many faces to process. Some initial guidelines:

I've seen the tiger mask in your demo - how I can build my own masks?

Our sample projects give you a good starting point for implementing your own masks and other effects using powerful mainstream graphics applications (such as Blender, Photoshop, Unity 3D and others). Specifically:

Showcase Demo

This demo, available as sample project with full source code, includes a basic face mask (the tiger mask) effect. It is implemented by creating a face mesh during run-time, based on data provided by VisageTracker through FaceData::faceModel* class members, applying a tiger texture and rendering it with OpenGL.

The mesh uses static texture coordinates so it is fairly simple to replace the texture image and use other themes instead of the tiger mask. We provide the texture image in a form that makes it fairly easy to create other textures in Photoshop, and use these textures as a face mask. This is the template texture file (jk_300_textureTemplate.png) found in visageSDK\Samples\data\ directory. You can simply create a texture image with facial features (mouth, nose etc.) placed according to the template image, and use this texture instead of the tiger. You can modify texture in Showcase Demo sample by changing the texture file which is set in line 331 of ShowcaseDemo.xaml.cs source file:

331: gVisageRendering.SetTextureImage(LoadImage(@"..\Samples\OpenGL\data\ShowcaseDemo\tiger_texture.png"));

Visage Tracker Unity Demo

This sample project is based on Unity 3D. It includes the tiger mask effect and a 3D model (glasses) superimposed on the face. Unity 3D is an extremely powerful game/3D engine that gives you much more choices and freedom in implementing your effects, while starting from the basic ones provided in our project. For more information on the sample project, see Samples – Unity 3D – Visage Tracker Unity Demo in the Documentation. Furthermore, the “Animation and AR modeling guide” document, available in the Documentation under the link “References”, explains how to create and import a 3D model to overlay on the face, which may also be of interest to you.

In Visage Tracker Unity Demo, the tiger face mask effect is achieved using the same principles as in Showcase Demo. Details of implementation can be found in Tracker.cs file (located in visageSDK\Samples\Unity\VisageTrackerUnityDemo\Assets\Scripts\ directory) by searching for keyword "tiger".

Troubleshooting

I am using visage|SDK FaceRecognition gallery with a large number of descriptors (100.000+) and it takes 2 minutes to load the gallery. What can I do about it?

visage|SDK FaceRecognition simple gallery implementation was not designed for a use case with a large number of descriptors.

Use API functions that provide raw descriptor output (extractDescritor) and descriptor similarity comparison function (descriptorSimilarity) to implement your own gallery solution in technology of your choice is appropriate for your use case.

Need to insert links to relevant API parts in text and/or as “See also” section.

I want to change the camera resolution in Unity application VisageTrackerDemo. Is this supported and how can I do this?

Depending on the platform, it’s already possible, out of the box.

On Windows and Android, the camera resolution can be changed via Tracker object properties defaultCameraWidth and defaultCameraHeight within the Unity Editor. When the default value -1 is used, the resolution is set to 800 x 600 in the native VisageTrackerUnityPlugin.

On iOS it’s not possible to change the resolution out of the box from the demo application. The camera resolution is hard-coded to 480 x 600 within the native VisageTrackerUnityPlugin.

VisageTrackerUnityPlugin is provided with full source code within the package distribution.

I am getting EntryPointNotFoundException when attempting to run a Unity application in the Editor. Why does my Unity application does not work?

Make sure that you had followed all the steps from the documentation Building and running Unity application.

Need to insert links to relevant API parts in text and/or as “See also” section.

Verify that the build target and visage|SDK platform match. For example, running visage|SDK for Windows inside the Unity Editor and for a Standalone application will work since both are run on the same platform. Attempting to run visage|SDK for iOS inside the Unity Editor on a MacOS will output an error because iOS architecture does not match MacOS architecture.

When working with large resolution videos (>2K), video FPS significantly drops, why?

It seems that the slowdown is the result of not optimal frame mirroring (our native Windows plugin mirrors the image). Track function itself seem to be good enough. There are further optimizations that can be implemented. However, for a quick fix solution, try to turn off frame mirroring in Unity project by setting Mirrored property to 0 in the Unity Editor Property page for the Tracker object.

To elaborate, _grabFrame function has two working modes:

  1. The cameraOrientation and cameraMirror values are equal to 0

  2. The cameraOrientation and cameraMirror value are different from 0

First one will just copy pixels to another buffer, and the second one will go to the pixels manipulation process to prepare pixels for the _track() function.

Pixels manipulation is an expensive operation. To avoid it, please turn off isMirrored value which is by default set to 1 and adjust the mirroring property in the setting of camera itself if needed.

This will result in significantly faster execution of the _grabframe() function.

Important! This refers to visage|SDK 8.7.b1 and older versions. On newer versions, isMirrored value is turned off by default.


Need to insert links to relevant API parts in text and/or as “See also” section.

Troubleshooting - Licensing Errors

The following articles describe the various error codes produced by the Visage Technologies licensing system, and what may be done to remedy each error. They are valid for visage|SDK version 8.6b1 and higher.

Error code 0x00000001 (VS_ERROR_INVALID_LICENSE)

The error you received indicates that the license is not valid. The error occurs when the BundleID is not the same as the one in your application, or when the license that is registered to one product is used with another product. Please check if you’re using the correct license.

Error code 0x00000002 (VS_ERROR_EXPIRED_LICENSE)

The error you received indicates that the license has expired. Please consider renewing your license. Your Visage Technologies contact person may advise you on the options.

Error code 0x00000004 (VS_ERROR_EARLIER_VERSION_LICENSE)

The error you received indicates that the license version you are using is out of date, so you need to update to the newest available version. Please consider upgrading your license. Your Visage Technologies contact person may advise you on the options.

Error code 0x00000008 (VS_ERROR_MISSING_KEYFILE)

The error you received indicates that the application cannot locate the license key file. Please verify that the license key file is present in the folder used as a path to initialize license manager. For more details, please follow the instructions from Documentation -> Licensing.

Error code 0x00000010 (VS_ERROR_NO_LICENSE)

The error you received indicates that there is currently no license available. Please follow the instructions from Documentation -> Licensing on how to correctly use the license key in your application.

Error code 0x00000020 (VS_ERROR_CORRUPT_VERSION_STRING)

The error you received indicates that the license key file was modified. Please try using a clean copy of the license key file that was sent to you, and see if the error still occurs.

Error code 0x00000040 (VS_ERROR_LICENSE_VALIDATION_FAILURE)

The error you received indicates that the server has rejected the license. Please get in touch with your Visage Technologies contact person, who will investigate the matter further and get back to you.

[Internal - for Visage Technologies contact person] - Check on the VTLS server for the reason why license was rejected. It can be one of the following (the most common being -6):

  • -1 - License Key sent to VTLS server for validation was malformed

  • -2 - Device ID sent to VTLS server for validation was malformed

  • -3 - License does not exist on VTLS server

  • -4 - License is blocked on VTLS server

  • -5 - License expired

  • -6 - Installations limit reached

  • -7 - Concurrent users limit reached

Error code 0x00000080 (VS_ERROR_NC_CONNECTION_FAILED)

The error you received indicates that there was a failure in connection to our licensing server for registering your license. Please make sure that the device on which you are using the software is connected to the internet.

Error code 0x00000100 (VS_ERROR_TEMPERED_KEYFILE)

The error you received indicates that the license key file was modified. Please try using a clean copy of the license key file that was sent to you, and see if the error still occurs.

Error code 0x00000200 (VS_ERROR_TEMPERED_KEYSTRING)

The error you received indicates that the license key file was modified. Please try using a clean copy of the license key file that was sent to you, and see if the error still occurs.

Error code 0x00000400 (VS_ERROR_TEMPERED_DATE)

The error you received indicates that the date on the computer was modified. Please make sure that the date on the computer is correct.

Error code 0x00000800 (VS_ERROR_UNREADABLE_KEYSTRING)

The error you received indicates that the license key file was modified. Please try using a clean copy of the license key file that was sent to you, and see if the error still occurs.

Error code 0x00001000 (VS_ERROR_INVALID_OS)

The error you received indicates that your license key does not support the platform (operating system) on which you are trying to use it.

Error code 0x00002000 (VS_ERROR_INVALID_URL)

The error you received indicates that the license was issued for a different domain (URL) than the one on which it is used. Please confirm that the domain name for which you have licensed visage|SDK matches the domain (URL) on which you are using it.