luna_mobile_online/include/bsmobile/IBestShotMobile.h

#pragma once

#include "BestShotMobileDefs.h"

#include <fsdk/FaceEngine.h>
#include <tsdk/ITrackEngine.h>

namespace mobile {

	/** @brief Supported liveness methods enum
	 *	@note LivenessType::Offline supported in the Complete edition only!
	 */
	enum class LivenessType {
		None        = 0,      //!< No liveness check at all
		Online      = 1,      //!< Online liveness check. Liveness processing on the backend.
		Offline     = 2,      //!< Offline liveness check. Liveness processing on the device.
		Offline_OSL = 3       //!< Offline liveness check with OneShot Liveness.
		                      //!< Liveness processing on the device.
	};

	/** @brief Current liveness state.
	 */
	enum class LivenessState {
		Alive,                    //!< Face was estimated as alive.
		Fake,                     //!< Face was estimated as not alive.
		None,                     //!< No liveness check at all.
		NotReady,                 //!< Liveness check not ready for now. Need more frames to handle.
		BadHeadPose,              //!< Head angles bigger than thresholds.
		BadQuality,               //!< Image quality is less than threshold.
		FaceNotFound,             //!< Face was not found.
		FaceTooClose,             //!< Face is too close to the camera.
		FaceCloseToBorder,        //!< Face is too close to the frame border.
		FaceTooSmall,             //!< Face is too small.
		TooManyFaces,             //!< There are more than one face in the frame.
		Timeout,                  //!< Liveness timeout.
		CriticalError             //!< Critical during liveness processing.
	};

	/** @brief Current best shot state.
	 */
	enum class BestShotState {
		Ok,                       //!< Nice best shot. It can be used for the recognition
		BadQuality,               //!< Quality is less than threshold.
		BadHeadPose,              //!< Head angles bigger than thresholds.
		Error                     //!< Error during the best shot processing.
	};

	struct BestShotInfo {
		//! State of this frame
		BestShotState state;

		//! Source image
		fsdk::Image image;
		//! Detection with face
		fsdk::Detection detection;
		//! Face landmarks
		fsdk::Landmarks5 landmarks;

		//! Estimation of the head position. 
		//! This parameter could help to show notification to the user in case of bad angles.
		fsdk::HeadPoseEstimation headPoseEstimation;
		//! AGS estimation result.
		//! This parameter could help to show notification to the user in case of bad quality.
		float agsEstimation;

		//! Index of the frame
		tsdk::FrameId frameIndex;
		//! Index of the track
		tsdk::TrackId trackId;
	};

	struct IBestShotMobileObserver {
		/** 
		* @brief Bestshot notification.
		* @param bestShotInfo bestshot information, @see BestShotInfo.
		* @note If liveness check is not nedded (LivenessType::None), this callback
		* could be used to take a bestshot.
		*/
		BESTSHOT_MOBILE_API virtual void bestShot(
			const BestShotInfo& bestShotInfo) = 0;

		/** 
		* @brief Liveness check notification.
		* @param state liveness state for the bestshot. @see LivenessState.
		* @param bestShotInfo bestshot information, @see BestShotInfo.
		* @note For the liveness type LivenessType::None this callback will not be called!
		*/
		BESTSHOT_MOBILE_API virtual void liveness(
			const LivenessState livenessState,
			const BestShotInfo& bestShotInfo) = 0;

		/** 
		* @brief End of a track notification
		* @param trackId id of the track. @see tsdk::TrackId.
		*/
		BESTSHOT_MOBILE_API virtual void trackEnd(
			const tsdk::TrackId& trackId) = 0;
	};

	/** @brief IBestShotMobile interface class.
	 *	@note This interface is not thread-safe!
	 */
	struct IBestShotMobile {

		virtual ~IBestShotMobile() = default;

		/** @brief Pushes a single frame to the buffer.
		*	@note You should pass consequent frames for reasonble results 
		*	(thing video frames).
		*	Calls face detector and tracker, then triggers the callback for 
		*	processed faces.
		*	@param frame input frame image. Format must be R8G8B8. 
		*	@param frameId unique identifier for frames sequence.
		*	@param data is any additional data that a developer wants to receive 
		*	in callbacks-realization. 
		*	Do not use the delete-operator. The garbage collector is implemented 
		*	inside for this param.
		*	@return true if frame was appended to the queue for processing,
		*	false otherwise - frame was skipped because of full queue.
		*/
		BESTSHOT_MOBILE_API virtual bool pushFrame(
			const fsdk::Image &frame,
			uint32_t frameId) = 0;

		/** @brief Sets a bestshot observer.
		*	@param observer pointer to the observer object, @see IBestShotMobileObserver
		*/
		BESTSHOT_MOBILE_API virtual void setBestShotMobileObserver(
			IBestShotMobileObserver* observer) = 0;

		/** @brief Blocks current thread until all frames in this Stream will be handled
		 *	and all callbacks will be executed.
		 *	@note Stream could not be used after join.
		 *	@see setBestShotObserver, setVisualObserver, setDebugObserver and
		 *	setBestShotPredicate
		 */
		BESTSHOT_MOBILE_API virtual void join() = 0;

		/** @brief Returns current liveness type.
		 *	@see LivenessType for details.
		 *	return current liveness type.
		 */
		BESTSHOT_MOBILE_API virtual LivenessType getLivenessType() = 0;
	};

	/** @brief Creates an IBesthoMobile object.
	 *	@param faceEngine faceEngine object.
	 *	@param trackEngine trackEngine object.
	 *	@param settings settings.
	 *	@return IBestShotMobile object if succeeded, nullptr if failed.
	 */
	IBestShotMobile* createBestShotMobile(
		fsdk::FaceEngineType* faceEngine,
		tsdk::ITrackEngine* trackEngine,
		fsdk::ISettingsProvider* settings
	);

	/** @brief Creates an IBesthoMobile object.
	 *	@param faceEngine faceEngine object.
	 *	@param trackEngine trackEngine object.
	 *	@param configPath path to the configuration file bestshotmobile.conf.
	 *	@return IBestShotMobile object if succeeded, nullptr if failed.
	 */
	IBestShotMobile* createBestShotMobile(
		fsdk::FaceEngineType* faceEngine,
		tsdk::ITrackEngine* trackEngine,
		const char * configPath
	);

} // namespace mobile