How to use#
Follow the next steps to use the BestShotMobile library :
-
Implement the IBestShotMobileObserver interface. All virtual methods should be implemented.
-
Create FaceEngine and TrackEngine instances. See the "FaceEngine_Handbook" and the "TrackEngine_Handbook" for details.
-
Create BestShotMobile instance.
-
Create an instance of the callbacks implementation class.
-
Pass a pointer to the callbacks implementation class to the setBestShotMobileObserver method of the BestShotMobile instance.
-
Push all needed frames to the pushFrame method of the BestShotMobile instance.
-
Receive and handle all needed callbacks.
-
Wait until the end of processing by calling the blocking method join of the BestShotMobile instance.
See the next code example:
#include <bsmobile/IBestShotMobile.h>
#include <iostream>
struct BestShotMobileObserver : mobile::IBestShotMobileObserver {
void bestShot(const mobile::BestShotInfo& bestShotInfo) override {
std::cout << "This is just an example of the bestShot callback implementation!" << std::endl;
}
void liveness(const mobile::LivenessState livenessSate,
const mobile::BestShotInfo& bestShotInfo) override {
std::cout << "This is just an example of the liveness callback implementation!" << std::endl;
}
void trackEnd(const tsdk::TrackId& trackId) override {
std::cout << "This is just an example of the trackEnd callback implementation!" << std::endl;
}
};
fsdk::Image takeNextFrame() {
// some implementation of the frame capturing here
return fsdk::Image{};
}
int main() {
// Create the FaceEngine instance based on the configuration file
// (../Imgs/Install/data/faceengine.conf by default)
auto resFaceEngine = fsdk::createFaceEngineMobile("./data");
if (!resFaceEngine) {
std::cout << "Failed to create FaceEngineMobile instance! " << resFaceEngine.what() << std::endl;
return -1;
}
fsdk::Ref<fsdk::FaceEngineType> faceEngine = resFaceEngine.getValue();
// Take license object
fsdk::ILicense* license = faceEngine->getLicense();
if (!license) return -1;
// Make activation with license configuration file (../Imgs/Install/data/license.conf by default)
auto resActivate = fsdk::activateLicense(license, "./data/license.conf");
if (!resActivate) {
std::cout << "Failed to activate license! " << resActivate.what() << std::endl;
return -1;
}
// Create the TrackEngine settings instance and read parameters
// from the config (../Imgs/Install/data/trackengine.conf by default)
auto resTrackEngineSettings = fsdk::createSettingsProvider("./data/trackengine.conf");
if (!resTrackEngineSettings) {
std::cout << "Failed to parse trackengine settings! " << resTrackEngineSettings.what() << std::endl;
return -1;
}
fsdk::Ref<fsdk::ISettingsProvider> trackEngineSettings = resTrackEngineSettings.getValue();
// Create the TrackEngine instance.
auto resTrackEngine = tsdk::createTrackEngine(
faceEngine,
trackEngineSettings
);
if (!resTrackEngine) {
std::cout << "Failed to build TrackEngine instance! " << resTrackEngine.what() << std::endl;
return -1;
}
fsdk::Ref<tsdk::ITrackEngine> trackEngine = resTrackEngine.getValue();
// Create the BestShotMobile settings instance and read parameters
// from the config (../Imgs/Install/data/bestshotmobile.conf by default)
auto resBestShotMobileSettings = fsdk::createSettingsProvider("./data/bestshotmobile.conf");
if (!resBestShotMobileSettings) {
std::cout << "Failed to parse bestshotmobile settings! " << resBestShotMobileSettings.what() << std::endl;
return -1;
}
fsdk::Ref<fsdk::ISettingsProvider> bestShotMobileSettings = resBestShotMobileSettings.getValue();
// Check the liveness type. Online in this example.
bestShotMobileSettings->setValue(
"BestShotMobile::Settings",
"LivenessType",
1
);
// Online liveness use a backend server.
// So, need to set the URL to the Liveness API
bestShotMobileSettings->setValue(
"LivenessOnline::Settings",
"URL",
"http://example.com:12345/5/liveness"
);
// And need to set the Account-Id
bestShotMobileSettings->setValue(
"LivenessOnline::Settings",
"Luna-Account-Id",
"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
);
// Create the BestShotMobile instance
std::unique_ptr<mobile::IBestShotMobile> bsmobile {
mobile::createBestShotMobile(
faceEngine,
trackEngine,
bestShotMobileSettings
)
};
if (!bsmobile) {
std::cout << "Failed to create BestShotMobile!" << std::endl;
return -1;
}
// Create the user defined BestShotMobileObserver class instance.
BestShotMobileObserver bestShotMobileObserver;
// Set this instance as an observer into the BestShotMobile instance.
bsmobile->setBestShotMobileObserver(&bestShotMobileObserver);
// Just for example
size_t maxFramesCount = 100;
for (size_t frameIndex = 0; frameIndex < maxFramesCount; /*empty*/) {
fsdk::Image nextFrame = takeNextFrame();
// If the internal queue of the BestShotMobile has a free place, the frame
// will be taken into the processing and the ```pushFrame``` will return true.
if (bsmobile->pushFrame(nextFrame, frameIndex))
++frameIndex;
}
// Wait all processing finish.
bsmobile->join();
return 0;
}
Configuration file description#
The configuration file has a module-based structure. Each liveness algorithm has its own parameters.
There is also a common section with the BestShotMobile parametes.
BestShotMobile parameters
Parameter | Description | Type | Default value |
---|---|---|---|
LivenessType | Default liveness algorithm | "Value::Int1" |
0 |
Liveness None parameters
Parameter | Description | Type | Default value |
---|---|---|---|
AGSThreshold | Threshold for the quality (AGS) check | "Value::Float1" |
0.5 |
HeadPoseThreshold | Thresholds for the head pose check. Pitch, yaw, roll angles. | "Value::Float3" |
x="20.0" y="20.0" z="30.0" |
Liveness Online parameters
Parameter | Description | Type | Default value |
---|---|---|---|
AGSThreshold | Threshold for the quality (AGS) check | "Value::Float1" |
0.5 |
HeadPoseThreshold | Thresholds for the head pose check. Pitch, yaw, roll angles. | "Value::Float3" |
x="20.0" y="20.0" z="30.0" |
MinFaceSIze | Minimum face size to check | "Value:Int1" |
220 |
MinFrameSize | Minimum frame size to check | "Value:Int1" |
480 |
URL | Backend API URL | "Value::String" |
"" (empty) |
Luna-Account-Id | Account-id to work with backend API | "Value::String" |
"" (empty) |
Liveness Offline parameters
Parameter | Description | Type | Default value |
---|---|---|---|
AGSThreshold | Threshold for the quality (AGS) check | "Value::Float1" |
0.5 |
HeadPoseThreshold | Thresholds for the head pose check. Pitch, yaw, roll angles. | "Value::Float3" |
x="20.0" y="20.0" z="30.0" |
MinCheckCount | Minimum best shots count to check | "Value::Int1" |
3 |
Liveness Offline OSL parameters
Parameter | Description | Type | Default value |
---|---|---|---|
AGSThreshold | Threshold for the quality (AGS) check | "Value::Float1" |
0.2 |
HeadPoseThreshold | Thresholds for the head pose check. Pitch, yaw, roll angles. | "Value::Float3" |
x="25.0" y="25.0" z="25.0" |
MinFaceSize | Minimum face size to check | "Value:Int1" |
200 |
MinBorderPaddings | Minimum distance between face rect and image borders | "Value:Int1" |
10 |