| Face Engine SDK 5.2.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
36 float distance;
37 float similarity;
38
42 MatchingResult(void) noexcept
43 : distance(std::numeric_limits<float>::infinity())
44 , similarity(0.f)
45 {}
46
52 MatchingResult(
53 float distance,
54 float similarity) noexcept
55 : distance(distance)
56 , similarity(similarity)
57 {}
58 };
59
64 enum DescriptorType {
65 DT_FACE,
66 DT_HUMAN
67 };
68
73 enum DescriptorVersion : uint32_t {
74 DV_MIN_FACE_DESCRIPTOR_VERSION = 46,
75 DV_MIN_HUMAN_DESCRIPTOR_VERSION = 102
76 };
77
82 enum HumanDescriptorVersion : uint32_t {
83 HDV_TRACKER_HUMAN_DESCRIPTOR_VERSION = 102,
84 HDV_PRECISE_HUMAN_DESCRIPTOR_VERSION = 103,
85 HDV_REGULAR_HUMAN_DESCRIPTOR_VERSION = 104,
86 };
87
92 struct IDescriptor : IDataStorageObject {
93
98 virtual uint32_t getModelVersion() const noexcept = 0;
99
104 virtual DescriptorType getDescriptorType() const noexcept = 0;
105
111 virtual uint32_t getDescriptorLength() const noexcept = 0;
112
120 virtual bool getDescriptor(uint8_t* buffer) const noexcept = 0;
121
126 virtual void setDescriptor(const uint8_t* buffer) noexcept = 0;
127 };
128
140 struct IDescriptorBatch : IDataStorageObject {
141
146 enum class Error : uint32_t {
147 Ok,
148 InvalidInput,
149 BatchFull,
150 Incompatible,
151 Internal,
152 IoError,
153 OutOfRange,
154 };
155
163 virtual Result<Error> add(IDescriptor* descriptor) noexcept = 0;
164
180 virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset = 0) noexcept = 0;
181
196 virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset, uint32_t count) noexcept = 0;
197
204 virtual Result<Error> removeFast(uint32_t index) noexcept = 0;
205
212 virtual Result<Error> removeSlow(uint32_t index) noexcept = 0;
213
222 virtual Result<MultiError<ISerializableObject::Error,Error>> loadAndAdd(IArchive* archive) = 0;
223
228 virtual uint32_t getMaxCount() const noexcept = 0;
229
234 virtual uint32_t getCount() const noexcept = 0;
235
242 virtual uint32_t getModelVersion() const noexcept = 0;
243
249 virtual DescriptorType getDescriptorType() const noexcept = 0;
250
255 virtual uint32_t getDescriptorLength() const noexcept = 0;
256
263 virtual ResultValue<FSDKError, IDescriptorPtr> getDescriptorSlow(uint32_t index) const noexcept = 0;
264
272 virtual ResultValue<FSDKError, IDescriptorPtr> getDescriptorFast(uint32_t index) noexcept = 0;
273 };
274
278 template<>
279 struct ErrorTraits<IDescriptorBatch::Error> {
280
281 static bool isOk(IDescriptorBatch::Error error) noexcept {
282 return error == IDescriptorBatch::Error::Ok;
283 }
284
285 static const char* toString (IDescriptorBatch::Error error) noexcept {
286 switch(error) {
287 case IDescriptorBatch::Error::Ok: return "Ok";
288 case IDescriptorBatch::Error::IoError: return "Error during reading/writing";
289 case IDescriptorBatch::Error::Internal: return "Internal error";
290 case IDescriptorBatch::Error::BatchFull: return "Batch is full";
291 case IDescriptorBatch::Error::OutOfRange: return "Descriptor out of range";
292 case IDescriptorBatch::Error::Incompatible: return "Incompatible descriptor";
293 case IDescriptorBatch::Error::InvalidInput: return "Invalid input";
294 default: return "Unknown error";
295 }
296 }
297 };
298
303 struct IDescriptorExtractor : IRefCounted {
316 virtual ResultValue<FSDKError, float>
317 extractFromWarpedImage(
318 const Image& image,
319 IDescriptor* descriptor) const noexcept = 0;
320
337 virtual ResultValue<FSDKError, float>
338 extractFromWarpedImageBatch(
339 Span<const Image> warpsBatch,
340 IDescriptorBatch* descriptorBatch,
341 IDescriptor* aggregation,
342 Span<float> garbageScoreBatch) const noexcept = 0;
343
358 virtual Result<FSDKError>
359 extractFromWarpedImageBatch(
360 Span<const Image> warpsBatch,
361 IDescriptorBatch* descriptorBatch,
362 Span<float> garbageScoreBatch) const noexcept = 0;
363
371 virtual Result<FSDKError>
372 validate(
373 Span<const Image> warps,
374 Span<Result<FSDKError>> errors) const noexcept = 0;
375
380 virtual uint32_t getModelVersion() const noexcept = 0;
381
386 virtual DescriptorType getDescriptorType() const noexcept = 0;
387 };
388
402 struct IDescriptorMatcher : IRefCounted {
403
411 virtual ResultValue<
412 FSDKError,
413 MatchingResult>
414 match(
415 const IDescriptor* first,
416 const IDescriptor* second) noexcept = 0;
417
430 virtual Result<FSDKError>
431 match(
432 const IDescriptor* reference,
433 const IDescriptorBatch* candidates,
434 Span<MatchingResult> results) noexcept = 0;
435
440 virtual uint32_t getModelVersion() const noexcept = 0;
441
450 virtual Result<FSDKError> calcSimilarity(Span<MatchingResult> distances) const noexcept = 0;
451
460 virtual Result<FSDKError> calcDistance(Span<MatchingResult> similarities) const noexcept = 0;
461 };
463 }
fsdk::Span
Span. @detail Not owning data view. It incapsulated pointer to the continuous array with one or more ...
Definition: Span.h:15
fsdk::IDescriptorExtractor::extractFromWarpedImageBatch
virtual Result< FSDKError > extractFromWarpedImageBatch(Span< const Image > warpsBatch, IDescriptorBatch *descriptorBatch, Span< float > garbageScoreBatch) const noexcept=0
Extract batch of descriptors from a batch of images.
fsdk::IDescriptorExtractor::extractFromWarpedImageBatch
virtual ResultValue< FSDKError, float > extractFromWarpedImageBatch(Span< const Image > warpsBatch, IDescriptorBatch *descriptorBatch, IDescriptor *aggregation, Span< float > garbageScoreBatch) const noexcept=0
Extract batch of descriptors from a batch of images and perform aggregation.
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 descriptor batch content to the batch. Descriptors to copy from the source bath are selected ba...
fsdk::DescriptorType
DescriptorType
Descriptor type enum. Determines which type of descriptor to use.
Definition: IDescriptor.h:64
IObject.h
Object system types and interfaces.
fsdk::ISerializableObject::Error::Ok
@ Ok
Ok.
fsdk::IDescriptorBatch
Descriptor batch interface.
Definition: IDescriptor.h:140
fsdk::HDV_PRECISE_HUMAN_DESCRIPTOR_VERSION
@ HDV_PRECISE_HUMAN_DESCRIPTOR_VERSION
precise human descriptor, heavy and slow
Definition: IDescriptor.h:84
fsdk::IDescriptorMatcher
Descriptor matcher interface.
Definition: IDescriptor.h:402
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:83
fsdk::IDescriptor
Descriptor interface.
Definition: IDescriptor.h:92
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:52
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 objects is expected).
fsdk::IDescriptorExtractor::extractFromWarpedImage
virtual ResultValue< FSDKError, float > extractFromWarpedImage(const Image &image, IDescriptor *descriptor) const noexcept=0
Extract descriptor from a warped image.
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:66
fsdk::HumanDescriptorVersion
HumanDescriptorVersion
Human descriptor model versions. Determines which version of human descriptor to use.
Definition: IDescriptor.h:82
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::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:146
fsdk::DescriptorVersion
DescriptorVersion
Minimum descriptor model version. Determines which minimum version of descriptor to use.
Definition: IDescriptor.h:73
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:303
fsdk::MatchingResult::similarity
float similarity
similarity (normalized in [0..1] range).
Definition: IDescriptor.h:37
fsdk::HDV_REGULAR_HUMAN_DESCRIPTOR_VERSION
@ HDV_REGULAR_HUMAN_DESCRIPTOR_VERSION
regular human descriptor
Definition: IDescriptor.h:85
fsdk::DV_MIN_FACE_DESCRIPTOR_VERSION
@ DV_MIN_FACE_DESCRIPTOR_VERSION
face descriptor
Definition: IDescriptor.h:74
fsdk::Image
Image.
Definition: Image.h:37
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:75
fsdk::IDescriptorBatch::Error::Ok
@ Ok
No error.
fsdk::DT_FACE
@ DT_FACE
face descriptor
Definition: IDescriptor.h:65
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:36
fsdk::MatchingResult::MatchingResult
MatchingResult(void) noexcept
Initializes result to default values.
Definition: IDescriptor.h:42
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:21