You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
323 lines
13 KiB
323 lines
13 KiB
/**
|
|
* @file IDetector.h
|
|
* @brief Face detector interfaces.
|
|
* @copyright VisionLabs LLC
|
|
* @date 16.02.2017
|
|
* */
|
|
|
|
#pragma once
|
|
|
|
#include "FSDKError.h"
|
|
#include "IFaceDetectionBatch.h"
|
|
#include "IObject.h"
|
|
#include "Types.h"
|
|
#include "Types/Face.h"
|
|
|
|
#include <fsdk/vlc/future.h>
|
|
|
|
#include <functional>
|
|
|
|
namespace fsdk {
|
|
|
|
#ifndef DOXYGEN_SHOULD_SKIP_THIS
|
|
DECLARE_SMARTPTR(IDetector);
|
|
#endif
|
|
|
|
/**
|
|
* @brief Sensor type structure.
|
|
* Determines which type of camera sensor is used to perform face recognition.
|
|
* */
|
|
enum class SensorType {
|
|
Visible = 0, //!< Visible sensor type.
|
|
NIR //!< NIR sensor type.
|
|
};
|
|
|
|
/**
|
|
* @defgroup DetectorGroup Face detector.
|
|
* @brief Face detector public interfaces and related types and structures.
|
|
* @{
|
|
* */
|
|
|
|
/**
|
|
* @brief Object detector type enumeration.
|
|
* */
|
|
enum ObjectDetectorClassType {
|
|
FACE_DET_DEFAULT = 0, //!< Default detector cpecified in config file.
|
|
FACE_DET_V1 = 4, //!< Detector type 1.
|
|
FACE_DET_V2 = 5, //!< Detector type 2.
|
|
FACE_DET_V3 = 6, //!< Detector type 3.
|
|
FACE_DET_COUNT = 7, //!< Detector type count.
|
|
};
|
|
|
|
/**
|
|
* @brief Strategy of BestDetections comparer.
|
|
*/
|
|
enum DetectionComparerType {
|
|
DCT_CONFIDENCE = 0, //!< BestDetection - detections with highest score.
|
|
DCT_CENTER, //!< BestDetection - most centered detection.
|
|
DCT_CENTER_AND_CONFIDENCE, //!< bestDetection - most centered with high score.
|
|
DCT_SIZE, //!< bestDetection - the largest detection.
|
|
DCT_COUNT
|
|
};
|
|
|
|
/**
|
|
* @brief Detection type enumeration.
|
|
* */
|
|
enum DetectionType {
|
|
DT_BBOX = 0, //!< Get bounding boxes of faces.
|
|
DT_LANDMARKS5 = 1<<0, //!< Get bounding boxes and 5 facial landmarks.
|
|
DT_LANDMARKS68 = 1<<1, //!< Get bounding boxes and 68 facial landmarks.
|
|
DT_ALL = 0xffff //!< Get all supported parameters.
|
|
};
|
|
|
|
inline DetectionType operator | (DetectionType a, DetectionType b)
|
|
{ return static_cast<DetectionType>(static_cast<int>(a) | static_cast<int>(b)); }
|
|
|
|
/**
|
|
* @brief Interface of BestDetection comparer. Implement it if you want to use own BestDetection strategy.
|
|
*/
|
|
class IDetectionComparer {
|
|
public:
|
|
virtual bool compare(const Image& img, const Detection& a, const Detection& b) const = 0;
|
|
virtual ~IDetectionComparer() = default;
|
|
};
|
|
|
|
/**
|
|
* @brief Syntax sugar, allows you to use lambdas to define a BestDetection comparer.
|
|
*/
|
|
class FunctionDetectionComparer : public IDetectionComparer {
|
|
public:
|
|
typedef std::function<bool(const Image& img, const Detection&, const Detection&)> Function;
|
|
explicit FunctionDetectionComparer(const Function& function) : func(function)
|
|
{}
|
|
bool compare(const Image& img, const Detection& a, const Detection& b) const
|
|
{ return func(img, a, b); }
|
|
private:
|
|
Function func;
|
|
};
|
|
|
|
/**
|
|
* @brief face detector interface.
|
|
* */
|
|
struct IDetector : IRefCounted {
|
|
/**
|
|
* @brief Detect faces and their parameters on multiple images.
|
|
* @param [in] images span of source images.
|
|
* @param [in] rectangles input rectangles of interest (ROI) span.
|
|
* @param [in] perImageNum the max number of detections per input image.
|
|
* @param [in] type type of the detection.
|
|
* @return ResultValue with error code and IFaceDetectionBatch object.
|
|
* @see Ref, Span, Image, Rect, DetectionType, IFaceDetectionBatch, ResultValue and FSDKError for details.
|
|
* @note images format must be R8G8B8, @see Format.
|
|
* @note all spans should be based on user owned continuous collections.
|
|
* @note all spans should be equal size.
|
|
* */
|
|
virtual ResultValue<FSDKError, Ref<IFaceDetectionBatch>>
|
|
detect(
|
|
Span<const Image> images,
|
|
Span<const Rect> ROIs,
|
|
uint32_t perImageNum,
|
|
DetectionType type = DT_BBOX
|
|
) noexcept = 0;
|
|
|
|
/**
|
|
* @brief Light function to get just one best detection from single input image.
|
|
* @param [in] image source image.
|
|
* @param [in] rect rectangle of interest in the image.
|
|
* @param [in] type type of detection: BBox, 5landmarks or 68landmarks.
|
|
* @return ResultValue with error code and a Face object (detection bbox, landmarks, etc).
|
|
* @see Face, Image, Rect, DetectionType, ResultValue and FSDKError for details.
|
|
* @note image format must be R8G8B8, @see Format.
|
|
*/
|
|
virtual ResultValue<FSDKError, Face>
|
|
detectOne(
|
|
const Image& image,
|
|
const Rect& rect,
|
|
DetectionType type = DT_BBOX) noexcept = 0;
|
|
|
|
/**
|
|
* @brief Batched redetect faces on multiple images.
|
|
* based on the detection results for the previous frames.
|
|
* @param [in] images span of source images.
|
|
* @param [in] detectionBatch result of detection on the previous frames -
|
|
* Ref with an IFaceDetectionBatch object.
|
|
* @param [in] type type of redetection.
|
|
* @return ResultValue with error code and IFaceDetectionBatch object.
|
|
* @see Ref, Span, Image, DetectionType, IFaceDetectionBatch, ResultValue and FSDKError for details.
|
|
* @note images format must be R8G8B8, @see Format.
|
|
* @note all spans should be based on user owned continuous collections.
|
|
* @note images span should be the same size with detectionBatch size.
|
|
* @note In case if some face from the input detectionBatch was not found
|
|
* the corresponding detection in the output IFaceDetectionBatch object
|
|
* will be invalid.
|
|
*/
|
|
virtual ResultValue<FSDKError, Ref<IFaceDetectionBatch>>
|
|
redetect(
|
|
Span<const Image> images,
|
|
Ref<IFaceDetectionBatch> detectionBatch,
|
|
DetectionType type = DT_BBOX
|
|
) noexcept = 0;
|
|
|
|
/**
|
|
* @brief Batched redetect faces on multiple images.
|
|
* based on the detection results for the previous frames.
|
|
* @param [in] images span of source images.
|
|
* @param [in] detections span of detection coordinates in corresponding source images space
|
|
* from the previous frames. It is a two dimensional Span. There is one Span of the rectangles for each image.
|
|
* @param [in] type type of redetection.
|
|
* @return ResultValue with error code and IFaceDetectionBatch object.
|
|
* @see Ref, Span, Image, DetectionType, Detection, IFaceDetectionBatch, ResultValue and FSDKError for details.
|
|
* @note images format must be R8G8B8, @see Format.
|
|
* @note all spans should be based on user owned continuous collections.
|
|
* @note all spans should be equal size.
|
|
* @note If for some of the input detections the redetected face will not be found the
|
|
* appropriate detection in the IFaceDetectionBatch object will be invalid.
|
|
*/
|
|
virtual ResultValue<FSDKError, Ref<IFaceDetectionBatch>>
|
|
redetect(
|
|
Span<const Image> images,
|
|
Span<Span<const Detection>> detections,
|
|
DetectionType type = DT_BBOX
|
|
) noexcept = 0;
|
|
|
|
/**
|
|
* @brief Redetect face.
|
|
* @param [in] image source image. Format must be R8G8B8.
|
|
* @param [in] detection detection coordinates in image space from the previous frame to make redetect.
|
|
* @param [in] type type of detection: BBox, 5landmarks or 68landmarks.
|
|
* @return ResultValue with error code and Face.
|
|
* @see Face, Image, DetectionType, Detection, ResultValue and FSDKError for details.
|
|
* @note image format must be R8G8B8, @see Format.
|
|
* */
|
|
virtual ResultValue<FSDKError, Face>
|
|
redetectOne(
|
|
const Image& image,
|
|
const Detection& detection,
|
|
DetectionType type = DT_BBOX) noexcept = 0;
|
|
|
|
/**
|
|
* @brief Set detection comparer from SDK defined list.
|
|
* @param [in] comparerType type of the comparer for detections.
|
|
* @see DetectionComparerType for details.
|
|
*/
|
|
virtual void setDetectionComparer(DetectionComparerType comparerType) noexcept = 0;
|
|
|
|
/**
|
|
* @brief Set custom detection comparer object.
|
|
* @param [in] comparer pointer to user defined comparer object.
|
|
* @see IDetectionComparer for details.
|
|
* @note Client code still owns comparer object
|
|
*/
|
|
virtual void setCustomDetectionComparer(const IDetectionComparer* comparer) noexcept = 0;
|
|
|
|
/**
|
|
* @brief Validate input of multiple frames in a single function call.
|
|
* @param [in] images span of source images.
|
|
* @param [in] detections span of detection coordinates in corresponding source images space
|
|
* from the previous frames. It is a two dimensional Span. There is one Span of Detections for each image.
|
|
* @param [out] errors output span of errors for each image.
|
|
* It is a two dimensional Span. There is one Span of the errors for each image.
|
|
* @return Result with error code.
|
|
* @see Span, Image, Detection, Result and FSDKError for details.
|
|
* @note images format must be R8G8B8, @see Format.
|
|
* @note all spans should be based on user owned continuous collections.
|
|
* @note all spans should be equal size.
|
|
* */
|
|
virtual Result<FSDKError>
|
|
validate(
|
|
Span<const Image> images,
|
|
Span<Span<const Detection>> detections,
|
|
Span<Span<Result<FSDKError>>> errors) const noexcept = 0;
|
|
|
|
/**
|
|
* @brief Validate input of multiple frames in a single function call.
|
|
* @param [in] images span of source images.
|
|
* @param [in] rects span of rectangle coordinates of corresponding source images.
|
|
* @param [in] detectionPerImageNum max number of detections per input image.
|
|
* @param [out] errors output span of errors for each image.
|
|
* @return Result with error code.
|
|
* @see Span, Image, Rect, Result and FSDKError for details.
|
|
* @note images format must be R8G8B8, @see Format.
|
|
* @note all spans should be based on user owned continuous collections.
|
|
* @note all spans should be equal size.
|
|
* */
|
|
virtual Result<FSDKError>
|
|
validate(
|
|
Span<const Image> images,
|
|
Span<const Rect> rects,
|
|
uint32_t detectionPerImageNum,
|
|
Span<Result<FSDKError>> outErrors) const noexcept = 0;
|
|
|
|
/**
|
|
* @brief Validate input of multiple frames in a single function call.
|
|
* @param [in] images span of source images.
|
|
* @param [in] detectionBatch result of detection on the previous frames -
|
|
* Ref with an IFaceDetectionBatch object.
|
|
* @param [out] errors output span of errors for each image.
|
|
* @return Result with error code.
|
|
* @see Ref, Span, Image, IFaceDetectionBatch, Result and FSDKError for details.
|
|
* @note images format must be R8G8B8, @see Format.
|
|
* @note all spans should be based on user owned continuous collections.
|
|
* @note all spans should be equal size.
|
|
* */
|
|
virtual Result<FSDKError>
|
|
validate(
|
|
Span<const Image> images,
|
|
Ref<IFaceDetectionBatch> detectionBatch,
|
|
Span<Result<FSDKError>> outErrors) const noexcept = 0;
|
|
|
|
/**
|
|
* @brief Common aliases for IDetector asynchronous interface.
|
|
* */
|
|
using FaceBatchResult = ResultValue<FSDKError, IFaceDetectionBatchPtr>;
|
|
using FaceBatchFuture = vlc::future<IFaceDetectionBatchPtr>;
|
|
|
|
/**
|
|
* @brief Asynchronously detect faces and their parameters on multiple images.
|
|
* @param [in] images span of source images.
|
|
* @param [in] rectangles input rectangles of interest (ROI) span.
|
|
* @param [in] perImageNum the max number of detections per input image.
|
|
* @param [in] type type of the detection.
|
|
* @return Future ResultValue with error code and IFaceDetectionBatch object.
|
|
* @see Ref, Span, Image, Rect, DetectionType, IFaceDetectionBatch,
|
|
* ResultValue, FSDKError and vlc::future for details.
|
|
* @note images format must be R8G8B8, @see Format.
|
|
* @note all spans should be based on user owned continuous collections.
|
|
* @note all spans should be equal size.
|
|
* @note this method is experimental and interface may be changed in the future.
|
|
* @note this method is not marked as noexcept and may throw an exception.
|
|
* */
|
|
virtual FaceBatchFuture detectAsync(
|
|
Span<const Image> images,
|
|
Span<const Rect> rectangles,
|
|
uint32_t perImageNum,
|
|
DetectionType type = DT_BBOX) const = 0;
|
|
|
|
/**
|
|
* @brief Asynchronously redetect faces on multiple images.
|
|
* based on the detection results for the previous frames.
|
|
* @param [in] images span of source images.
|
|
* @param [in] detectionBatch result of detection on the previous frames -
|
|
* Ref with an IFaceDetectionBatch object.
|
|
* @param [in] type type of redetection.
|
|
* @return Future ResultValue with error code and IFaceDetectionBatch object.
|
|
* @see Ref, Span, Image, DetectionType, IFaceDetectionBatch,
|
|
* ResultValue, FSDKError and vlc::future for details.
|
|
* @note images format must be R8G8B8, @see Format.
|
|
* @note all spans should be based on user owned continuous collections.
|
|
* @note images span should be the same size with detectionBatch size.
|
|
* @note In case if some face from the input detectionBatch was not found
|
|
* the corresponding detection in the output IFaceDetectionBatch object
|
|
* will be invalid.
|
|
* @note this method is experimental and interface may be changed in the future.
|
|
* @note this method is not marked as noexcept and may throw an exception.
|
|
* */
|
|
virtual FaceBatchFuture redetectAsync(
|
|
Span<const Image> images,
|
|
IFaceDetectionBatchPtr detectionBatch,
|
|
DetectionType type = DT_BBOX) const = 0;
|
|
};
|
|
|
|
/** @} */
|
|
|
|
}
|