| Face Engine SDK 5.7.0 A face detection, recognition and tracking engine.

IDescriptor.h
Go to the documentation of this file.
1
8 #pragma once
9
10 #include "IObject.h"
11 #include "IDetector.h"
12 #include "FSDKError.h"
13 #include "Types.h"
14 #include <limits>
15
16 namespace fsdk {
17
18 #ifndef DOXYGEN_SHOULD_SKIP_THIS
19 DECLARE_SMARTPTR(IDescriptor);
20 DECLARE_SMARTPTR(IDescriptorBatch);
21 DECLARE_SMARTPTR(IDescriptorMatcher);
22 DECLARE_SMARTPTR(IDescriptorExtractor);
23 #endif
24
34 struct MatchingResult {
35 float distance;
36 float similarity;
37
41 MatchingResult(void) noexcept
42 : distance(std::numeric_limits<float>::infinity())
43 , similarity(0.f)
44 {}
45
51 MatchingResult(
52 float distance,
53 float similarity) noexcept
54 : distance(distance)
55 , similarity(similarity)
56 {}
57 };
58
63 enum DescriptorType {
64 DT_FACE,
65 DT_HUMAN
66 };
67
72 enum DescriptorVersion : uint32_t {
73 DV_MIN_FACE_DESCRIPTOR_VERSION = 46,
74 DV_MIN_HUMAN_DESCRIPTOR_VERSION = 102
75 };
76
81 enum HumanDescriptorVersion : uint32_t {
82 HDV_TRACKER_HUMAN_DESCRIPTOR_VERSION = 102,
83 HDV_PRECISE_HUMAN_DESCRIPTOR_VERSION = 103,
84 HDV_REGULAR_HUMAN_DESCRIPTOR_VERSION = 104,
85 };
86
91 struct IDescriptor : IDataStorageObject {
96 virtual uint32_t getModelVersion() const noexcept = 0;
97
103 virtual DescriptorType getDescriptorType() const noexcept = 0;
104
110 virtual uint32_t getDescriptorLength() const noexcept = 0;
111
119 virtual bool getDescriptor(uint8_t* buffer) const noexcept = 0;
120
125 virtual void setDescriptor(const uint8_t* buffer) noexcept = 0;
126 };
127
139 struct IDescriptorBatch : IDataStorageObject {
144 enum class Error : uint32_t {
145 Ok,
146 InvalidInput,
147 BatchFull,
148 Incompatible,
149 Internal,
150 IoError,
151 OutOfRange,
152 };
153
161 virtual Result<Error> add(IDescriptor* descriptor) noexcept = 0;
162
179 virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset = 0) noexcept = 0;
180
196 virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset, uint32_t count) noexcept = 0;
197
205 virtual Result<Error> removeFast(uint32_t index) noexcept = 0;
206
214 virtual Result<Error> removeSlow(uint32_t index) noexcept = 0;
215
224 virtual Result<MultiError<ISerializableObject::Error,Error>> loadAndAdd(IArchive* archive) = 0;
225
230 virtual uint32_t getMaxCount() const noexcept = 0;
231
236 virtual uint32_t getCount() const noexcept = 0;
237
244 virtual uint32_t getModelVersion() const noexcept = 0;
245
252 virtual DescriptorType getDescriptorType() const noexcept = 0;
253
258 virtual uint32_t getDescriptorLength() const noexcept = 0;
259
266 virtual ResultValue<FSDKError, IDescriptorPtr> getDescriptorSlow(uint32_t index) const noexcept = 0;
267
275 virtual ResultValue<FSDKError, IDescriptorPtr> getDescriptorFast(uint32_t index) noexcept = 0;
276 };
277
281 template<>
282 struct ErrorTraits<IDescriptorBatch::Error> {
283 static bool isOk(IDescriptorBatch::Error error) noexcept {
284 return error == IDescriptorBatch::Error::Ok;
285 }
286
287 static const char* toString (IDescriptorBatch::Error error) noexcept {
288 switch(error) {
289 case IDescriptorBatch::Error::Ok: return "Ok";
290 case IDescriptorBatch::Error::IoError: return "Error during reading/writing";
291 case IDescriptorBatch::Error::Internal: return "Internal error";
292 case IDescriptorBatch::Error::BatchFull: return "Batch is full";
293 case IDescriptorBatch::Error::OutOfRange: return "Descriptor out of range";
294 case IDescriptorBatch::Error::Incompatible: return "Incompatible descriptor";
295 case IDescriptorBatch::Error::InvalidInput: return "Invalid input";
296 default: return "Unknown error";
297 }
298 }
299 };
300
305 struct IDescriptorExtractor : IRefCounted {
318 virtual ResultValue<FSDKError, float>
319 extractFromWarpedImage(
320 const Image& warp,
321 IDescriptor* descriptor) const noexcept = 0;
322
340 virtual ResultValue<FSDKError, float>
341 extractFromWarpedImageBatch(
342 Span<const Image> warps,
343 IDescriptorBatch* descriptorBatch,
344 IDescriptor* aggregation,
345 Span<float> garbageScoreBatch) const noexcept = 0;
346
362 virtual Result<FSDKError>
363 extractFromWarpedImageBatch(
364 Span<const Image> warps,
365 IDescriptorBatch* descriptorBatch,
366 Span<float> garbageScoreBatch) const noexcept = 0;
367
378 virtual Result<FSDKError>
379 validate(
380 Span<const Image> warps,
381 Span<Result<FSDKError>> errors) const noexcept = 0;
382
387 virtual uint32_t getModelVersion() const noexcept = 0;
388
393 virtual DescriptorType getDescriptorType() const noexcept = 0;
394
398 using FutureResult = vlc::future<float>;
399
418 virtual FutureResult extractFromWarpedImageBatchAsync(
419 Span<const Image> warps,
420 IDescriptorBatch* descriptorBatch,
421 IDescriptor* aggregation,
422 Span<float> garbageScoreBatch) const = 0;
423 };
424
438 struct IDescriptorMatcher : IRefCounted {
446 virtual ResultValue<
447 FSDKError,
448 MatchingResult>
449 match(
450 const IDescriptor* first,
451 const IDescriptor* second) noexcept = 0;
452
466 virtual Result<FSDKError>
467 match(
468 const IDescriptor* reference,
469 const IDescriptorBatch* candidates,
470 Span<MatchingResult> results) noexcept = 0;
471
476 virtual uint32_t getModelVersion() const noexcept = 0;
477
487 virtual Result<FSDKError> calcSimilarity(Span<MatchingResult> distances) const noexcept = 0;
488
498 virtual Result<FSDKError> calcDistance(Span<MatchingResult> similarities) const noexcept = 0;
499 };
501 }
fsdk::Span
Span. @detail Not owning data view. It incapsulated pointer to the continuous array with one or more ...
Definition: Span.h:15
fsdk::IDataStorageObject
Data storage object interface helper.
Definition: IObject.h:157
fsdk::FSDKError
FSDKError
Common SDK error codes.
Definition: FSDKError.h:17
fsdk::FutureError::Ok
@ Ok
All good.
fsdk::IDescriptorBatch::Error::OutOfRange
@ OutOfRange
Error while accessing descriptor out of range.
fsdk::IDescriptor::getModelVersion
virtual uint32_t getModelVersion() const noexcept=0
Get algorithm model version this descriptor was created with.
DECLARE_SMARTPTR
#define DECLARE_SMARTPTR(X)
Smart ptr declaration helper macro.
Definition: Def.h:59
fsdk::IDescriptorBatch::Error::IoError
@ IoError
Error while trying open/read/write file.
fsdk::MultiError
An error structure designed for functions which can return errors from different enum classes.
Definition: MultiError.h:17
fsdk::IDescriptorBatch::add
virtual Result< Error > add(IDescriptorBatch *batch, uint32_t offset=0) noexcept=0
Add a given descriptor batch content to the current batch. Descriptors to copy from the source batch ...
fsdk::DescriptorType
DescriptorType
Descriptor type enum. Determines which type of descriptor to use.
Definition: IDescriptor.h:63
fsdk::IDescriptorExtractor::extractFromWarpedImageBatch
virtual ResultValue< FSDKError, float > extractFromWarpedImageBatch(Span< const Image > warps, IDescriptorBatch *descriptorBatch, IDescriptor *aggregation, Span< float > garbageScoreBatch) const noexcept=0
Extract batch of descriptors from a batch of images and perform aggregation.
IObject.h
Object system types and interfaces.
fsdk::ISerializableObject::Error::Ok
@ Ok
Ok.
fsdk::IDescriptorBatch
Descriptor batch interface.
Definition: IDescriptor.h:139
fsdk::HDV_PRECISE_HUMAN_DESCRIPTOR_VERSION
@ HDV_PRECISE_HUMAN_DESCRIPTOR_VERSION
precise human descriptor, heavy and slow.
Definition: IDescriptor.h:83
fsdk::IDescriptorMatcher
Descriptor matcher interface.
Definition: IDescriptor.h:438
fsdk::IDescriptorMatcher::getModelVersion
virtual uint32_t getModelVersion() const noexcept=0
Get algorithm model version this matcher works with.
fsdk
SDK namespace.
Definition: IAGSEstimator.h:8
fsdk::IDescriptor::getDescriptorLength
virtual uint32_t getDescriptorLength() const noexcept=0
return size of descriptor in bytes.
fsdk::HDV_TRACKER_HUMAN_DESCRIPTOR_VERSION
@ HDV_TRACKER_HUMAN_DESCRIPTOR_VERSION
human descriptor for tracking of people, light and fast version.
Definition: IDescriptor.h:82
fsdk::IDescriptorExtractor::extractFromWarpedImageBatch
virtual Result< FSDKError > extractFromWarpedImageBatch(Span< const Image > warps, IDescriptorBatch *descriptorBatch, Span< float > garbageScoreBatch) const noexcept=0
Extract batch of descriptors from a batch of images.
fsdk::IDescriptor
Descriptor interface.
Definition: IDescriptor.h:91
fsdk::ISerializableObject::Error
Error
Serialization nerror codes.
Definition: IObject.h:73
fsdk::MatchingResult::MatchingResult
MatchingResult(float distance, float similarity) noexcept
Initializes result.
Definition: IDescriptor.h:51
fsdk::MatchingResult
Result of descriptor matching.
Definition: IDescriptor.h:34
fsdk::ISerializableObject
Serializable object interface.
Definition: IObject.h:68
fsdk::IDescriptorBatch::Error::InvalidInput
@ InvalidInput
Invalid input (Ex: null pointer while a valid object is expected).
fsdk::IDescriptorExtractor::getModelVersion
virtual uint32_t getModelVersion() const noexcept=0
Get algorithm model version this extractor works with.
fsdk::IDescriptorBatch::add
virtual Result< Error > add(IDescriptor *descriptor) noexcept=0
Add a descriptor to the batch.
fsdk::IDescriptorBatch::Error::Incompatible
@ Incompatible
Trying to add an incompatible descriptor.
fsdk::IDescriptorBatch::Error::Internal
@ Internal
An internal processing error (Ex: memopry allocation or misalignment).
fsdk::DT_HUMAN
@ DT_HUMAN
human descriptor.
Definition: IDescriptor.h:65
fsdk::HumanDescriptorVersion
HumanDescriptorVersion
Human descriptor model versions. Determines which version of human descriptor to use.
Definition: IDescriptor.h:81
IDetector.h
Face detector interfaces.
fsdk::IDescriptorExtractor::validate
virtual Result< FSDKError > validate(Span< const Image > warps, Span< Result< FSDKError >> errors) const noexcept=0
Validate input of multiple frames in a single function call.
fsdk::IDescriptorExtractor::FutureResult
vlc::future< float > FutureResult
Common aliases for BestShotQuality asynchronous interface.
Definition: IDescriptor.h:398
fsdk::IArchive
Archive interface.
Definition: IObject.h:37
fsdk::IDescriptor::getDescriptorType
virtual DescriptorType getDescriptorType() const noexcept=0
Get type of descriptor.
fsdk::ErrorTraits
Definition: Result.h:10
Types.h
Common data types and structures.
fsdk::IDescriptorMatcher::match
virtual Result< FSDKError > match(const IDescriptor *reference, const IDescriptorBatch *candidates, Span< MatchingResult > results) noexcept=0
Match descriptors 1:M.
fsdk::IDescriptor::getDescriptor
virtual bool getDescriptor(uint8_t *buffer) const noexcept=0
Copy descriptor data to user provided buffer.
fsdk::IDescriptorBatch::Error
Error
Descriptor batch error enumeration.
Definition: IDescriptor.h:144
fsdk::DescriptorVersion
DescriptorVersion
Minimum descriptor model version. Determines which minimum version of descriptor to use.
Definition: IDescriptor.h:72
fsdk::Result
A structure that encapsulates an action result enumeration.
Definition: Result.h:30
FSDKError.h
Common SDK error codes.
fsdk::IDescriptorExtractor
Descriptor extractor interface.
Definition: IDescriptor.h:305
fsdk::MatchingResult::similarity
float similarity
similarity (normalized in [0..1] range).
Definition: IDescriptor.h:36
fsdk::HDV_REGULAR_HUMAN_DESCRIPTOR_VERSION
@ HDV_REGULAR_HUMAN_DESCRIPTOR_VERSION
regular human descriptor.
Definition: IDescriptor.h:84
fsdk::DV_MIN_FACE_DESCRIPTOR_VERSION
@ DV_MIN_FACE_DESCRIPTOR_VERSION
face descriptor.
Definition: IDescriptor.h:73
fsdk::Image
Image.
Definition: Image.h:38
fsdk::IDescriptorExtractor::extractFromWarpedImage
virtual ResultValue< FSDKError, float > extractFromWarpedImage(const Image &warp, IDescriptor *descriptor) const noexcept=0
Extract descriptor from a warped image.
fsdk::IDescriptorMatcher::match
virtual ResultValue< FSDKError, MatchingResult > match(const IDescriptor *first, const IDescriptor *second) noexcept=0
Match descriptors 1:1.
fsdk::DV_MIN_HUMAN_DESCRIPTOR_VERSION
@ DV_MIN_HUMAN_DESCRIPTOR_VERSION
human descriptor.
Definition: IDescriptor.h:74
fsdk::IDescriptorBatch::Error::Ok
@ Ok
No error.
fsdk::DT_FACE
@ DT_FACE
face descriptor.
Definition: IDescriptor.h:64
fsdk::IDescriptor::setDescriptor
virtual void setDescriptor(const uint8_t *buffer) noexcept=0
Copy descriptor from user providedbuffer.
fsdk::IRefCounted
Base strong reference counted object interface.
Definition: IRefCounted.h:36
fsdk::MatchingResult::distance
float distance
distance between descriptor vectors.
Definition: IDescriptor.h:35
fsdk::MatchingResult::MatchingResult
MatchingResult(void) noexcept
Initializes result to default values.
Definition: IDescriptor.h:41
fsdk::IDescriptorBatch::Error::BatchFull
@ BatchFull
Batch is full.
fsdk::ResultValue
Addon for Result to output some value aside the result. Specialization for copiable types.
Definition: ResultValue.h:25