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 parameters.

BestShotMobile parameters

Parameter	Description	Default value
`LivenessType`	Default liveness algorithm.	`0`
	Possible values: `0` - `LivenessNone` `1` - `LivenessOnline` `2` - `LivenessOffline`
	Type: `Value::Int1`

LivenessNone parameters

Parameter	Description	Default value
`AGSThreshold`	Threshold for the quality (AGS) check. Type: `Value::Float1`	`0.2`
`HeadPoseThreshold`	Thresholds for the head pose check. Pitch, yaw, roll angles. Type: `Value::Float3`	`x="20.0" y="20.0" z="30.0"`

LivenessOnline parameters

Parameter	Description	Default value
`AGSThreshold`	Threshold for the quality (AGS) check. Type: `Value::Float1`	`0.2`
`HeadPoseThreshold`	Thresholds for the head pose check. Pitch, yaw, roll angles. Type: `Value::Float3`	`x="20.0" y="20.0" z="30.0"`
`MinFaceSize`	Minimum face size to check. Type: `Value:Int1`	`220`
`MinFrameSize`	Minimum frame size to check. Type: `Value:Int1`	`480`
`MinBorderPaddings`	Minimum distance between face rect and image borders. Type: `Value:Int1`	`25`
`URL`	Backend API URL. Type: `Value::String`	`""` (empty)
`Luna-Account-Id`	Account ID to work with backend API. Type: `Value::String`	`""` (empty)

LivenessOffline parameters

Parameter	Description	Default value
`AGSThreshold`	Threshold for the quality (AGS) check. Type: `Value::Float1`	`0.2`
`HeadPoseThreshold`	Thresholds for the head pose check. Pitch, yaw, roll angles. Type: `Value::Float3`	`x="20.0" y="20.0" z="30.0"`
`MinCheckCount`	Minimum best shots count to check. Type: `Value::Int`	`3`

LivenessOfflineOSL parameters

Parameter	Description	Default value
`AGSThreshold`	Threshold for the quality (AGS) check. Type: `Value::Float1`	`0.2`
`HeadPoseThreshold`	Thresholds for the head pose check. Pitch, yaw, roll angles. Type: `Value::Float3`	`x="25.0" y="25.0" z="35.0"`
`MinFaceSize`	Minimum face size to check. Type: `Value:Int1`	`200`
`MinBorderPaddings`	Minimum distance between face rect and image borders. Type: `Value:Int1`	`10`