Face Engine SDK  5.21.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
55  }
56  };
57 
64  DT_HUMAN
65  };
66 
71  enum DescriptorVersion : uint32_t {
74  };
75 
80  enum HumanDescriptorVersion : uint32_t {
91  HDV_REGULAR_V4 = 113
92  };
93 
103  virtual uint32_t getModelVersion() const noexcept = 0;
104 
110  virtual DescriptorType getDescriptorType() const noexcept = 0;
111 
117  virtual uint32_t getDescriptorLength() const noexcept = 0;
118 
126  virtual bool getDescriptor(uint8_t* buffer) const noexcept = 0;
127 
132  virtual void setDescriptor(const uint8_t* buffer) noexcept = 0;
133  };
134 
151  enum class Error : uint32_t {
152  Ok,
153  InvalidInput,
154  BatchFull,
155  Incompatible,
156  Internal,
157  IoError,
158  OutOfRange,
159  };
160 
168  virtual Result<Error> add(IDescriptor* descriptor) noexcept = 0;
169 
186  virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset = 0) noexcept = 0;
187 
203  virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset, uint32_t count) noexcept = 0;
204 
213  virtual Result<Error> removeFast(uint32_t index) noexcept = 0;
214 
223  virtual Result<Error> removeSlow(uint32_t index) noexcept = 0;
224 
233  virtual Result<MultiError<ISerializableObject::Error, Error>> loadAndAdd(IArchive* archive) = 0;
234 
239  virtual uint32_t getMaxCount() const noexcept = 0;
240 
245  virtual uint32_t getCount() const noexcept = 0;
246 
253  virtual uint32_t getModelVersion() const noexcept = 0;
254 
261  virtual DescriptorType getDescriptorType() const noexcept = 0;
262 
267  virtual uint32_t getDescriptorLength() const noexcept = 0;
268 
275  virtual ResultValue<FSDKError, IDescriptorPtr> getDescriptorSlow(uint32_t index) const noexcept = 0;
276 
284  virtual ResultValue<FSDKError, IDescriptorPtr> getDescriptorFast(uint32_t index) noexcept = 0;
285  };
286 
290  template <>
292  static bool isOk(IDescriptorBatch::Error error) noexcept {
293  return error == IDescriptorBatch::Error::Ok;
294  }
295 
296  static const char* toString(IDescriptorBatch::Error error) noexcept {
297  switch(error) {
299  return "Ok";
301  return "Error during reading/writing";
303  return "Internal error";
305  return "Batch is full";
307  return "Descriptor out of range";
309  return "Incompatible descriptor";
311  return "Invalid input";
312  default:
313  return "Unknown error";
314  }
315  }
316  };
317 
336  extractFromWarpedImage(const Image& warp, IDescriptor* descriptor) const noexcept = 0;
337 
356  Span<const Image> warps,
357  IDescriptorBatch* descriptorBatch,
358  IDescriptor* aggregation,
359  Span<float> garbageScoreBatch) const noexcept = 0;
360 
377  Span<const Image> warps,
378  IDescriptorBatch* descriptorBatch,
379  Span<float> garbageScoreBatch) const noexcept = 0;
380 
391  virtual Result<FSDKError>
392  validate(Span<const Image> warps, Span<Result<FSDKError>> errors) const noexcept = 0;
393 
398  virtual uint32_t getModelVersion() const noexcept = 0;
399 
404  virtual DescriptorType getDescriptorType() const noexcept = 0;
405 
409  using FutureResult = vlc::future<float>;
410 
429  virtual FutureResult extractFromWarpedImageBatchAsync(
430  Span<const Image> warps,
431  IDescriptorBatch* descriptorBatch,
432  IDescriptor* aggregation,
433  Span<float> garbageScoreBatch) const = 0;
434  };
435 
458  match(const IDescriptor* first, const IDescriptor* second) noexcept = 0;
459 
474  const IDescriptor* reference,
475  const IDescriptorBatch* candidates,
476  Span<MatchingResult> results) noexcept = 0;
477 
482  virtual uint32_t getModelVersion() const noexcept = 0;
483 
493  virtual Result<FSDKError> calcSimilarity(Span<MatchingResult> distances) const noexcept = 0;
494 
504  virtual Result<FSDKError> calcDistance(Span<MatchingResult> similarities) const noexcept = 0;
505  };
506 
508 } // namespace fsdk
fsdk::Span
Span. @detail Not owning data view. It incapsulated pointer to the continuous array with one or more ...
Definition: Span.h:14
fsdk::IDataStorageObject
Data storage object interface helper.
Definition: IObject.h:167
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.
fsdk::IDescriptorMatcher::match
virtual ResultValue< FSDKError, MatchingResult > match(const IDescriptor *first, const IDescriptor *second) noexcept=0
Match descriptors 1:1.
DECLARE_SMARTPTR
#define DECLARE_SMARTPTR(X)
Smart ptr declaration helper macro.
Definition: Def.h:56
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:14
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::HDV_REGULAR_V4
@ HDV_REGULAR_V4
regular human descriptor.
Definition: IDescriptor.h:91
fsdk::DescriptorType
DescriptorType
Descriptor type enum. Determines which type of descriptor to use.
Definition: IDescriptor.h:62
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.
fsdk::HDV_TRACKER_V2
@ HDV_TRACKER_V2
human tracking descriptor, light and fast version.
Definition: IDescriptor.h:84
fsdk::ISerializableObject::Error::Ok
@ Ok
Ok.
fsdk::IDescriptorBatch
Descriptor batch interface.
Definition: IDescriptor.h:146
fsdk::HDV_PRECISE_HUMAN_DESCRIPTOR_VERSION
@ HDV_PRECISE_HUMAN_DESCRIPTOR_VERSION
precise human descriptor, heavy and slow.
Definition: IDescriptor.h:82
fsdk::IDescriptorMatcher
Descriptor matcher interface.
Definition: IDescriptor.h:449
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 tracking descriptor, light and fast version.
Definition: IDescriptor.h:81
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:98
fsdk::ISerializableObject::Error
Error
Serialization nerror codes.
Definition: IObject.h:76
fsdk::MatchingResult::MatchingResult
MatchingResult(float distance, float similarity) noexcept
Initializes result.
Definition: IDescriptor.h:52
fsdk::MatchingResult
Result of descriptor matching.
Definition: IDescriptor.h:35
fsdk::ISerializableObject
Serializable object interface.
Definition: IObject.h:71
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:64
fsdk::HumanDescriptorVersion
HumanDescriptorVersion
Human descriptor model versions. Determines which version of human descriptor to use.
Definition: IDescriptor.h:80
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:409
fsdk::IArchive
Archive interface.
Definition: IObject.h:38
fsdk::IDescriptor::getDescriptorType
virtual DescriptorType getDescriptorType() const noexcept=0
Get type of descriptor.
fsdk::ErrorTraits
Definition: Result.h:8
fsdk::IDescriptorMatcher::match
virtual Result< FSDKError > match(const IDescriptor *reference, const IDescriptorBatch *candidates, Span< MatchingResult > results) noexcept=0
Match descriptors 1:M.
fsdk::HDV_REGULAR_V3
@ HDV_REGULAR_V3
regular human descriptor.
Definition: IDescriptor.h:89
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:151
fsdk::DescriptorVersion
DescriptorVersion
Minimum descriptor model version. Determines which minimum version of descriptor to use.
Definition: IDescriptor.h:71
fsdk::Result
A structure that encapsulates an action result enumeration.
Definition: Result.h:27
fsdk::IDescriptorExtractor
Descriptor extractor interface.
Definition: IDescriptor.h:322
fsdk::HDV_PRECISE_V4
@ HDV_PRECISE_V4
precise human descriptor, heavy and slow.
Definition: IDescriptor.h:90
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:83
fsdk::DV_MIN_FACE_DESCRIPTOR_VERSION
@ DV_MIN_FACE_DESCRIPTOR_VERSION
face descriptor.
Definition: IDescriptor.h:72
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::HDV_PRECISE_V2
@ HDV_PRECISE_V2
precise human descriptor, heavy and slow.
Definition: IDescriptor.h:85
fsdk::DV_MIN_HUMAN_DESCRIPTOR_VERSION
@ DV_MIN_HUMAN_DESCRIPTOR_VERSION
human descriptor.
Definition: IDescriptor.h:73
fsdk::IDescriptorBatch::Error::Ok
@ Ok
No error.
fsdk::DT_FACE
@ DT_FACE
face descriptor.
Definition: IDescriptor.h:63
fsdk::IDescriptor::setDescriptor
virtual void setDescriptor(const uint8_t *buffer) noexcept=0
Copy descriptor from user providedbuffer.
fsdk::HDV_TRACKER_V3
@ HDV_TRACKER_V3
human tracking descriptor, light and fast version.
Definition: IDescriptor.h:87
fsdk::HDV_REGULAR_V2
@ HDV_REGULAR_V2
regular human descriptor.
Definition: IDescriptor.h:86
fsdk::IRefCounted
Base strong reference counted object interface.
Definition: IRefCounted.h:37
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::HDV_PRECISE_V3
@ HDV_PRECISE_V3
precise human descriptor, heavy and slow.
Definition: IDescriptor.h:88
fsdk::ResultValue
Addon for Result to output some value aside the result. Specialization for copiable types.
Definition: ResultValue.h:21