How to use

Follow the next steps to use the BestShotMobile library :

1. Implement the IBestShotMobileObserver interface. All virtual methods should be implemented.

2. Create FaceEngine and TrackEngine instances. See the "FaceEngine_Handbook" and the "TrackEngine_Handbook" for details.

3. Create BestShotMobile instance.

4. Create an instance of the callbacks implementation class.

5. Pass a pointer to the callbacks implementation class to the setBestShotMobileObserver method of the BestShotMobile instance.

6. Push all needed frames to the pushFrame method of the BestShotMobile instance.

7. Receive and handle all needed callbacks.

8. Wait until the end of processing by calling the blocking method join of the BestShotMobile instance.

See the next code example:

#include <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/faceengine.conf");
    if (!resFaceEgnine) {
        ...
    }
    fsdk::Ref<fsdk::FaceEngineType> faceEngine = resFaceEgnine.getValue();
    if (!faceEngine) return -1;

    // 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)
    if (!fsdk::activateLicense(license, "./data/license.conf"))
        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) 
        return -1;
    fsdk::Ref<fsdk::ISettingsProvider> trackEngineSettings = resTrackEngineSettings.getValue();

    // Create the TrackEngine instance.
    fsdk::Ref<tsdk::ITrackEngine> trackEngine = 
        fsdk::acquire(
            tsdk::createTrackEngine(
                faceEngine,
                trackEngineSettings
            )
        );
    if (!trackEngine) return -1;

    // 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) 
        return -1;
    bestShotMobileSettings = bestShotMobileSettings.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) 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();

        // Is 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