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

IDescriptor.h
Go to the documentation of this file.
1
8 #pragma once
9
10 #include <fsdk/IObject.h>
11 #include <fsdk/IDetector.h>
12 #include <fsdk/FSDKError.h>
13 #include <fsdk/Types.h>
14
15 #include <limits>
16
17 namespace fsdk {
18
19 #ifndef DOXYGEN_SHOULD_SKIP_THIS
20 DECLARE_SMARTPTR(IDescriptor);
21 DECLARE_SMARTPTR(IDescriptorBatch);
22 DECLARE_SMARTPTR(IDescriptorMatcher);
23 DECLARE_SMARTPTR(IDescriptorExtractor);
24 #endif
25
35 struct MatchingResult {
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(float distance, float similarity) noexcept
53 : distance(distance)
54 , similarity(similarity) {
55 }
56 };
57
62 enum DescriptorType {
63 DT_FACE,
64 DT_HUMAN
65 };
66
71 enum DescriptorVersion : uint32_t {
72 DV_MIN_FACE_DESCRIPTOR_VERSION = 54,
73 DV_MIN_HUMAN_DESCRIPTOR_VERSION = 102
74 };
75
80 enum HumanDescriptorVersion : uint32_t {
81 HDV_TRACKER_HUMAN_DESCRIPTOR_VERSION = 102,
82 HDV_PRECISE_HUMAN_DESCRIPTOR_VERSION = 103,
83 HDV_REGULAR_HUMAN_DESCRIPTOR_VERSION = 104,
84 HDV_TRACKER_V2 = 105,
85 HDV_PRECISE_V2 = 106,
86 HDV_REGULAR_V2 = 107,
87 HDV_TRACKER_V3 = 108,
88 HDV_PRECISE_V3 = 109,
89 HDV_REGULAR_V3 = 110,
90 HDV_PRECISE_V4 = 112,
91 HDV_REGULAR_V4 = 113,
92 HDV_PRECISE_V5 = 115,
93 HDV_REGULAR_V5 = 116
94 };
95
100 struct IDescriptor : IDataStorageObject {
105 virtual uint32_t getModelVersion() const noexcept = 0;
106
112 virtual DescriptorType getDescriptorType() const noexcept = 0;
113
119 virtual uint32_t getDescriptorLength() const noexcept = 0;
120
128 virtual bool getDescriptor(uint8_t* buffer) const noexcept = 0;
129
134 virtual void setDescriptor(const uint8_t* buffer) noexcept = 0;
135 };
136
148 struct IDescriptorBatch : IDataStorageObject {
153 enum class Error : uint32_t {
154 Ok,
155 InvalidInput,
156 BatchFull,
157 Incompatible,
158 Internal,
159 IoError,
160 OutOfRange,
161 };
162
170 virtual Result<Error> add(IDescriptor* descriptor) noexcept = 0;
171
188 virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset = 0) noexcept = 0;
189
205 virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset, uint32_t count) noexcept = 0;
206
215 virtual Result<Error> removeFast(uint32_t index) noexcept = 0;
216
225 virtual Result<Error> removeSlow(uint32_t index) noexcept = 0;
226
235 virtual Result<MultiError<ISerializableObject::Error, Error>> loadAndAdd(IArchive* archive) = 0;
236
241 virtual uint32_t getMaxCount() const noexcept = 0;
242
247 virtual uint32_t getCount() const noexcept = 0;
248
255 virtual uint32_t getModelVersion() const noexcept = 0;
256
263 virtual DescriptorType getDescriptorType() const noexcept = 0;
264
269 virtual uint32_t getDescriptorLength() const noexcept = 0;
270
277 virtual ResultValue<FSDKError, IDescriptorPtr> getDescriptorSlow(uint32_t index) const noexcept = 0;
278
286 virtual ResultValue<FSDKError, IDescriptorPtr> getDescriptorFast(uint32_t index) noexcept = 0;
287 };
288
292 template <>
293 struct ErrorTraits<IDescriptorBatch::Error> {
294 static bool isOk(IDescriptorBatch::Error error) noexcept {
295 return error == IDescriptorBatch::Error::Ok;
296 }
297
298 static const char* toString(IDescriptorBatch::Error error) noexcept {
299 switch(error) {
300 case IDescriptorBatch::Error::Ok:
301 return "Ok";
302 case IDescriptorBatch::Error::IoError:
303 return "Error during reading/writing";
304 case IDescriptorBatch::Error::Internal:
305 return "Internal error";
306 case IDescriptorBatch::Error::BatchFull:
307 return "Batch is full";
308 case IDescriptorBatch::Error::OutOfRange:
309 return "Descriptor out of range";
310 case IDescriptorBatch::Error::Incompatible:
311 return "Incompatible descriptor";
312 case IDescriptorBatch::Error::InvalidInput:
313 return "Invalid input";
314 default:
315 return "Unknown error";
316 }
317 }
318 };
319
324 struct IDescriptorExtractor : IRefCounted {
337 virtual ResultValue<FSDKError, float>
338 extractFromWarpedImage(const Image& warp, IDescriptor* descriptor) const noexcept = 0;
339
357 virtual ResultValue<FSDKError, float> extractFromWarpedImageBatch(
358 Span<const Image> warps,
359 IDescriptorBatch* descriptorBatch,
360 IDescriptor* aggregation,
361 Span<float> garbageScoreBatch) const noexcept = 0;
362
378 virtual Result<FSDKError> extractFromWarpedImageBatch(
379 Span<const Image> warps,
380 IDescriptorBatch* descriptorBatch,
381 Span<float> garbageScoreBatch) const noexcept = 0;
382
393 virtual Result<FSDKError>
394 validate(Span<const Image> warps, Span<Result<FSDKError>> errors) const noexcept = 0;
395
400 virtual uint32_t getModelVersion() const noexcept = 0;
401
406 virtual DescriptorType getDescriptorType() const noexcept = 0;
407
411 using FutureResult = vlc::future<float>;
412
431 virtual FutureResult extractFromWarpedImageBatchAsync(
432 Span<const Image> warps,
433 IDescriptorBatch* descriptorBatch,
434 IDescriptor* aggregation,
435 Span<float> garbageScoreBatch) const = 0;
436 };
437
451 struct IDescriptorMatcher : IRefCounted {
459 virtual ResultValue<FSDKError, MatchingResult>
460 match(const IDescriptor* first, const IDescriptor* second) noexcept = 0;
461
475 virtual Result<FSDKError> match(
476 const IDescriptor* reference,
477 const IDescriptorBatch* candidates,
478 Span<MatchingResult> results) noexcept = 0;
479
484 virtual uint32_t getModelVersion() const noexcept = 0;
485
495 virtual Result<FSDKError> calcSimilarity(Span<MatchingResult> distances) const noexcept = 0;
496
506 virtual Result<FSDKError> calcDistance(Span<MatchingResult> similarities) const noexcept = 0;
507 };
508
510 } // namespace fsdk
fsdk::IDescriptor::getModelVersion
virtual uint32_t getModelVersion() const noexcept=0
Get algorithm model version this descriptor was created with.
fsdk::DescriptorVersion
DescriptorVersion
Minimum descriptor model version. Determines which minimum version of descriptor to use...
Definition: IDescriptor.h:71
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:70
fsdk
SDK namespace.
Definition: IAGSEstimator.h:8
fsdk::HDV_REGULAR_V4
regular human descriptor.
Definition: IDescriptor.h:91
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:27
Types.h
Common data types and structures.
fsdk::IDescriptorBatch::Error::Ok
No error.
fsdk::MultiError
An error structure designed for functions which can return errors from different enum classes...
Definition: MultiError.h:14
fsdk::IDescriptorBatch::Error
Error
Descriptor batch error enumeration.
Definition: IDescriptor.h:153
fsdk::IDescriptorBatch::getDescriptorFast
virtual ResultValue< FSDKError, IDescriptorPtr > getDescriptorFast(uint32_t index) noexcept=0
Get descriptor from batch by index without copying.
fsdk::HDV_PRECISE_HUMAN_DESCRIPTOR_VERSION
precise human descriptor, heavy and slow.
Definition: IDescriptor.h:82
fsdk::HumanDescriptorVersion
HumanDescriptorVersion
Human descriptor model versions. Determines which version of human descriptor to use.
Definition: IDescriptor.h:80
fsdk::IDescriptorBatch
Descriptor batch interface.
Definition: IDescriptor.h:148
fsdk::HDV_TRACKER_V2
human tracking descriptor, light and fast version.
Definition: IDescriptor.h:84
IObject.h
Object system types and interfaces.
fsdk::HDV_PRECISE_V5
precise human descriptor, heavy and slow.
Definition: IDescriptor.h:92
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:71
fsdk::IDescriptorBatch::add
virtual Result< Error > add(IDescriptor *descriptor) noexcept=0
Add a descriptor to the batch.
fsdk::ErrorTraits
Definition: Result.h:8
fsdk::IDescriptorBatch::Error::Incompatible
Trying to add an incompatible descriptor.
fsdk::HDV_TRACKER_HUMAN_DESCRIPTOR_VERSION
human tracking descriptor, light and fast version.
Definition: IDescriptor.h:81
fsdk::IRefCounted
Base strong reference counted object interface.
Definition: IRefCounted.h:37
fsdk::IDescriptorBatch::removeFast
virtual Result< Error > removeFast(uint32_t index) noexcept=0
Remove a descriptor from batch.
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:451
fsdk::IDescriptor::setDescriptor
virtual void setDescriptor(const uint8_t *buffer) noexcept=0
Copy descriptor from user providedbuffer.
fsdk::DT_HUMAN
human descriptor.
Definition: IDescriptor.h:64
fsdk::IDescriptorBatch::getDescriptorType
virtual DescriptorType getDescriptorType() const noexcept=0
Get type of descriptor.
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::getDescriptorSlow
virtual ResultValue< FSDKError, IDescriptorPtr > getDescriptorSlow(uint32_t index) const noexcept=0
Get descriptor from batch by index with copying.
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::getDescriptorLength
virtual uint32_t getDescriptorLength() const noexcept=0
Get length of one descriptor. Specified by version of descriptors in batch.
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:324
fsdk::MatchingResult::MatchingResult
MatchingResult(void) noexcept
Initializes result to default values.
Definition: IDescriptor.h:42
fsdk::IDescriptorBatch::removeSlow
virtual Result< Error > removeSlow(uint32_t index) noexcept=0
Remove a descriptor from batch.
fsdk::Image
Image.
Definition: Image.h:38
fsdk::HDV_PRECISE_V4
precise human descriptor, heavy and slow.
Definition: IDescriptor.h:90
fsdk::MatchingResult
Result of descriptor matching.
Definition: IDescriptor.h:35
fsdk::HDV_REGULAR_V3
regular human descriptor.
Definition: IDescriptor.h:89
fsdk::IDescriptor
Descriptor interface.
Definition: IDescriptor.h:100
fsdk::IDataStorageObject
Data storage object interface helper.
Definition: IObject.h:167
fsdk::DV_MIN_FACE_DESCRIPTOR_VERSION
face descriptor.
Definition: IDescriptor.h:72
fsdk::HDV_REGULAR_HUMAN_DESCRIPTOR_VERSION
regular human descriptor.
Definition: IDescriptor.h:83
fsdk::IDescriptorBatch::Error::BatchFull
Batch is full.
fsdk::IDescriptorBatch::Error::IoError
Error while trying open/read/write file.
fsdk::IArchive
Archive interface.
Definition: IObject.h:38
fsdk::toString
const char * toString(Image::MemoryResidence residence)
Returns a string representation of a MemoryResidence type.
fsdk::HDV_PRECISE_V2
precise human descriptor, heavy and slow.
Definition: IDescriptor.h:85
fsdk::FSDKError
FSDKError
Common SDK error codes.
Definition: FSDKError.h:17
fsdk::DV_MIN_HUMAN_DESCRIPTOR_VERSION
human descriptor.
Definition: IDescriptor.h:73
fsdk::MatchingResult::distance
float distance
distance between descriptor vectors.
Definition: IDescriptor.h:36
fsdk::DescriptorType
DescriptorType
Descriptor type enum. Determines which type of descriptor to use.
Definition: IDescriptor.h:62
fsdk::HDV_REGULAR_V5
regular human descriptor.
Definition: IDescriptor.h:93
fsdk::IDescriptorBatch::Error::InvalidInput
Invalid input (Ex: null pointer while a valid object is expected).
fsdk::MatchingResult::MatchingResult
MatchingResult(float distance, float similarity) noexcept
Initializes result.
Definition: IDescriptor.h:52
fsdk::IDescriptorExtractor::FutureResult
vlc::future< float > FutureResult
Common aliases for BestShotQuality asynchronous interface.
Definition: IDescriptor.h:411
fsdk::HDV_PRECISE_V3
precise human descriptor, heavy and slow.
Definition: IDescriptor.h:88
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::Span
Span. Not owning data view. It incapsulated pointer to the continuous array with one or more T objec...
Definition: Span.h:14
fsdk::DT_FACE
face descriptor.
Definition: IDescriptor.h:63
fsdk::IDescriptor::getDescriptorType
virtual DescriptorType getDescriptorType() const noexcept=0
Get type of descriptor.
fsdk::HDV_TRACKER_V3
human tracking descriptor, light and fast version.
Definition: IDescriptor.h:87
fsdk::HDV_REGULAR_V2
regular human descriptor.
Definition: IDescriptor.h:86