| Face Engine SDK 4.9.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 DesctiptorType {
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 = 101
76 };
77
82 struct IDescriptor : IDataStorageObject {
83
88 virtual uint32_t getModelVersion() const noexcept = 0;
89
94 virtual DesctiptorType getDescriptorType() const noexcept = 0;
95
101 virtual uint32_t getDescriptorLength() const noexcept = 0;
102
110 virtual bool getDescriptor(uint8_t* buffer) const noexcept = 0;
111
116 virtual void setDescriptor(const uint8_t* buffer) noexcept = 0;
117 };
118
130 struct IDescriptorBatch : IDataStorageObject {
131
136 enum class Error : uint32_t {
137 Ok,
138 InvalidInput,
139 BatchFull,
140 Incompatible,
141 Internal,
142 IoError,
143 OutOfRange,
144 };
145
153 virtual Result<Error> add(IDescriptor* descriptor) noexcept = 0;
154
170 virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset = 0) noexcept = 0;
171
186 virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset, uint32_t count) noexcept = 0;
187
194 virtual Result<Error> removeFast(int index) noexcept = 0;
195
202 virtual Result<Error> removeSlow(int index) noexcept = 0;
203
212 virtual Result<MultiError<ISerializableObject::Error,Error>> loadAndAdd(IArchive* archive) = 0;
213
218 virtual uint32_t getMaxCount() const noexcept = 0;
219
224 virtual uint32_t getCount() const noexcept = 0;
225
232 virtual uint32_t getModelVersion() const noexcept = 0;
233
239 virtual DesctiptorType getDescriptorType() const noexcept = 0;
240
245 virtual uint32_t getDescriptorSize() const noexcept = 0;
246
252 virtual IDescriptor* getDescriptorSlow(uint32_t index) const noexcept = 0;
253
260 virtual IDescriptor* getDescriptorFast(uint32_t index) noexcept = 0;
261 };
262
266 template<>
267 struct ErrorTraits<IDescriptorBatch::Error> {
268
269 static bool isOk(IDescriptorBatch::Error error) noexcept {
270 return error == IDescriptorBatch::Error::Ok;
271 }
272
273 static const char* toString (IDescriptorBatch::Error error) noexcept {
274 switch(error) {
275 case IDescriptorBatch::Error::Ok: return "Ok";
276 case IDescriptorBatch::Error::IoError: return "Error during reading/writing";
277 case IDescriptorBatch::Error::Internal: return "Internal error";
278 case IDescriptorBatch::Error::BatchFull: return "Batch is full";
279 case IDescriptorBatch::Error::OutOfRange: return "Descriptor out of range";
280 case IDescriptorBatch::Error::Incompatible: return "Incompatible descriptor";
281 case IDescriptorBatch::Error::InvalidInput: return "Invalid input";
282 default: return "Unknown error";
283 }
284 }
285 };
286
291 struct IDescriptorExtractor : IRefCounted {
308 virtual ResultValue<FSDKError, float>
309 FSDK_DEPRECATED("IDescriptorExtractor::extract is deprecated. Use IDescriptorExtractor::extractFromWarpedImage method")
310 extract(Image& image,
311 const Detection& detection,
312 const Landmarks5& landmarks,
313 IDescriptor* descriptor) const noexcept = 0;
314
327 virtual ResultValue<FSDKError, float>
328 extractFromWarpedImage(
329 const Image& image,
330 IDescriptor* descriptor) const noexcept = 0;
331
350 virtual ResultValue<FSDKError, float>
351 extractFromWarpedImageBatch(
352 const Image* warpsBatch,
353 IDescriptorBatch* descriptorBatch,
354 IDescriptor* aggregation,
355 float* garbageScoreBatch,
356 int batchSize) const noexcept = 0;
357
374 virtual Result<FSDKError>
375 extractFromWarpedImageBatch(
376 const Image* warpsBatch,
377 IDescriptorBatch* descriptorBatch,
378 float* garbageScoreBatch,
379 int batchSize) const noexcept = 0;
380
385 virtual uint32_t getModelVersion() const noexcept = 0;
386
391 virtual DesctiptorType getDescriptorType() const noexcept = 0;
392 };
393
407 struct IDescriptorMatcher : IRefCounted {
408
416 virtual ResultValue<
417 FSDKError,
418 MatchingResult>
419 match(
420 const IDescriptor* first,
421 const IDescriptor* second) noexcept = 0;
422
435 virtual Result<FSDKError>
436 match(
437 const IDescriptor* reference,
438 const IDescriptorBatch* candidates,
439 MatchingResult* results) noexcept = 0;
440
445 virtual uint32_t getModelVersion() const noexcept = 0;
446 };
448 }
fsdk::IDescriptor::getModelVersion
virtual uint32_t getModelVersion() const noexcept=0
Get algorithm model version this descriptor was created with.
fsdk::DesctiptorType
DesctiptorType
Descriptor type enum. Determines which type of descriptor to use.
Definition: IDescriptor.h:64
fsdk::DescriptorVersion
DescriptorVersion
Minimum descriptor model version. Determines which minimum version of descriptor to use...
Definition: IDescriptor.h:73
fsdk::IDescriptor::getDescriptor
virtual bool getDescriptor(uint8_t *buffer) const noexcept=0
Copy descriptor data to user provided buffer.
DECLARE_SMARTPTR
#define DECLARE_SMARTPTR(X)
Smart ptr declaration helper macro.
Definition: Def.h:59
fsdk
SDK namespace.
Definition: IAGSEstimator.h:8
fsdk::IDescriptorBatch::Error::Internal
An internal processing error (Ex: memopry allocation or misalignment).
fsdk::Result
A structure that encapsulates an action result enumeration.
Definition: Result.h:29
Types.h
Common data types and structures.
fsdk::IDescriptorBatch::Error::Ok
No error.
fsdk::Landmarks
Face landmarks template structure.
Definition: Landmarks.h:18
fsdk::MultiError
An error structure designed for functions which can return errors from different enum classes...
Definition: MultiError.h:17
fsdk::IDescriptorBatch::Error
Error
Descriptor batch error enumeration.
Definition: IDescriptor.h:136
fsdk::IDescriptorBatch::getDescriptorSize
virtual uint32_t getDescriptorSize() const noexcept=0
Get length of one descriptor. Specified by version of descriptors in batch.
fsdk::IDescriptorBatch
Descriptor batch interface.
Definition: IDescriptor.h:130
fsdk::IDescriptorBatch::getDescriptorSlow
virtual IDescriptor * getDescriptorSlow(uint32_t index) const noexcept=0
Create descriptor from batch by index with copying.
IObject.h
Object system types and interfaces.
fsdk::IDescriptorBatch::loadAndAdd
virtual Result< MultiError< ISerializableObject::Error, Error > > loadAndAdd(IArchive *archive)=0
Load a descriptor/descriptors from archive and add it to the batch.
fsdk::IDescriptor::getDescriptorLength
virtual uint32_t getDescriptorLength() const noexcept=0
return size of descriptor in bytes.
FSDKError.h
Common SDK error codes.
fsdk::ISerializableObject
Serializable object interface.
Definition: IObject.h:68
fsdk::IDescriptorBatch::add
virtual Result< Error > add(IDescriptor *descriptor) noexcept=0
Add a descriptor to the batch.
fsdk::ErrorTraits
Definition: Result.h:9
fsdk::IDescriptorBatch::Error::Incompatible
Trying to add an incompatible descriptor.
fsdk::IRefCounted
Base strong reference counted object interface.
Definition: IRefCounted.h:36
fsdk::IDescriptorBatch::getMaxCount
virtual uint32_t getMaxCount() const noexcept=0
Get maximum number of descriptors in this batch.
fsdk::IDescriptorMatcher
Descriptor matcher interface.
Definition: IDescriptor.h:407
fsdk::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::IDescriptorBatch::Error::OutOfRange
Error while accessing descriptor out of range.
fsdk::MatchingResult::similarity
float similarity
similarity (normalized in [0..1] range).
Definition: IDescriptor.h:37
fsdk::IDescriptorBatch::getDescriptorType
virtual DesctiptorType getDescriptorType() const noexcept=0
Get type of descriptor.
fsdk::ResultValue
Addon for Result to output some value aside the result. Specialization for copiable types...
Definition: ResultValue.h:21
IDetector.h
Face detector interfaces.
fsdk::IDescriptorBatch::getModelVersion
virtual uint32_t getModelVersion() const noexcept=0
Get algorithm model version the descriptors in this batch were created with.
fsdk::IDescriptorBatch::getCount
virtual uint32_t getCount() const noexcept=0
Get actual number of descriptors in this batch.
fsdk::IDescriptorExtractor
Descriptor extractor interface.
Definition: IDescriptor.h:291
fsdk::DT_HUMAN
human descriptor
Definition: IDescriptor.h:66
fsdk::MatchingResult::MatchingResult
MatchingResult(void) noexcept
Initializes result to default values.
Definition: IDescriptor.h:42
fsdk::Image
Image.
Definition: Image.h:38
fsdk::MatchingResult
Result of descriptor matching.
Definition: IDescriptor.h:34
fsdk::IDescriptorBatch::getDescriptorFast
virtual IDescriptor * getDescriptorFast(uint32_t index) noexcept=0
Create descriptor from batch by index without copying.
fsdk::IDescriptor::getDescriptorType
virtual DesctiptorType getDescriptorType() const noexcept=0
Get type of descriptor.
fsdk::IDescriptor
Descriptor interface.
Definition: IDescriptor.h:82
fsdk::IDataStorageObject
Data storage object interface helper.
Definition: IObject.h:157
fsdk::DV_MIN_FACE_DESCRIPTOR_VERSION
face descriptor
Definition: IDescriptor.h:74
fsdk::IDescriptorBatch::Error::BatchFull
Batch is full.
fsdk::IDescriptorBatch::removeSlow
virtual Result< Error > removeSlow(int index) noexcept=0
Remove a descriptor from batch.
fsdk::IDescriptorBatch::Error::IoError
Error while trying open/read/write file.
fsdk::IArchive
Archive interface.
Definition: IObject.h:37
fsdk::IDescriptorBatch::removeFast
virtual Result< Error > removeFast(int index) noexcept=0
Remove a descriptor from batch.
fsdk::FSDKError
FSDKError
Common SDK error codes.
Definition: FSDKError.h:17
fsdk::DV_MIN_HUMAN_DESCRIPTOR_VERSION
human descriptor
Definition: IDescriptor.h:75
fsdk::MatchingResult::distance
float distance
distance between descriptor vectors.
Definition: IDescriptor.h:36
fsdk::IDescriptorBatch::Error::InvalidInput
Invalid input (Ex: null pointer while a valid objects is expected).
fsdk::MatchingResult::MatchingResult
MatchingResult(float distance, float similarity) noexcept
Initializes result.
Definition: IDescriptor.h:52
fsdk::BaseDetection
Face detection. Stores a detected face bounding box within a source image frame as well as detection...
Definition: Detection.h:10