Face Engine SDK  5.14.0
A face detection, recognition and tracking engine.
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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 
53  float distance,
54  float similarity) noexcept
57  {}
58  };
59 
67  };
68 
73  enum DescriptorVersion : uint32_t {
76  };
77 
82  enum HumanDescriptorVersion : uint32_t {
89  };
90 
100  virtual uint32_t getModelVersion() const noexcept = 0;
101 
107  virtual DescriptorType getDescriptorType() const noexcept = 0;
108 
114  virtual uint32_t getDescriptorLength() const noexcept = 0;
115 
123  virtual bool getDescriptor(uint8_t* buffer) const noexcept = 0;
124 
129  virtual void setDescriptor(const uint8_t* buffer) noexcept = 0;
130  };
131 
148  enum class Error : uint32_t {
149  Ok,
150  InvalidInput,
151  BatchFull,
152  Incompatible,
153  Internal,
154  IoError,
155  OutOfRange,
156  };
157 
165  virtual Result<Error> add(IDescriptor* descriptor) noexcept = 0;
166 
183  virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset = 0) noexcept = 0;
184 
200  virtual Result<Error> add(IDescriptorBatch* batch, uint32_t offset, uint32_t count) noexcept = 0;
201 
209  virtual Result<Error> removeFast(uint32_t index) noexcept = 0;
210 
218  virtual Result<Error> removeSlow(uint32_t index) noexcept = 0;
219 
228  virtual Result<MultiError<ISerializableObject::Error,Error>> loadAndAdd(IArchive* archive) = 0;
229 
234  virtual uint32_t getMaxCount() const noexcept = 0;
235 
240  virtual uint32_t getCount() const noexcept = 0;
241 
248  virtual uint32_t getModelVersion() const noexcept = 0;
249 
256  virtual DescriptorType getDescriptorType() const noexcept = 0;
257 
262  virtual uint32_t getDescriptorLength() const noexcept = 0;
263 
270  virtual ResultValue<FSDKError, IDescriptorPtr> getDescriptorSlow(uint32_t index) const noexcept = 0;
271 
279  virtual ResultValue<FSDKError, IDescriptorPtr> getDescriptorFast(uint32_t index) noexcept = 0;
280  };
281 
285  template<>
286  struct ErrorTraits<IDescriptorBatch::Error> {
287  static bool isOk(IDescriptorBatch::Error error) noexcept {
288  return error == IDescriptorBatch::Error::Ok;
289  }
290 
291  static const char* toString (IDescriptorBatch::Error error) noexcept {
292  switch(error) {
293  case IDescriptorBatch::Error::Ok: return "Ok";
294  case IDescriptorBatch::Error::IoError: return "Error during reading/writing";
295  case IDescriptorBatch::Error::Internal: return "Internal error";
296  case IDescriptorBatch::Error::BatchFull: return "Batch is full";
297  case IDescriptorBatch::Error::OutOfRange: return "Descriptor out of range";
298  case IDescriptorBatch::Error::Incompatible: return "Incompatible descriptor";
299  case IDescriptorBatch::Error::InvalidInput: return "Invalid input";
300  default: return "Unknown error";
301  }
302  }
303  };
304 
323  extractFromWarpedImage(
324  const Image& warp,
325  IDescriptor* descriptor) const noexcept = 0;
326 
345  extractFromWarpedImageBatch(
346  Span<const Image> warps,
347  IDescriptorBatch* descriptorBatch,
348  IDescriptor* aggregation,
349  Span<float> garbageScoreBatch) const noexcept = 0;
350 
366  virtual Result<FSDKError>
367  extractFromWarpedImageBatch(
368  Span<const Image> warps,
369  IDescriptorBatch* descriptorBatch,
370  Span<float> garbageScoreBatch) const noexcept = 0;
371 
382  virtual Result<FSDKError>
383  validate(
384  Span<const Image> warps,
385  Span<Result<FSDKError>> errors) const noexcept = 0;
386 
391  virtual uint32_t getModelVersion() const noexcept = 0;
392 
397  virtual DescriptorType getDescriptorType() const noexcept = 0;
398 
402  using FutureResult = vlc::future<float>;
403 
422  virtual FutureResult extractFromWarpedImageBatchAsync(
423  Span<const Image> warps,
424  IDescriptorBatch* descriptorBatch,
425  IDescriptor* aggregation,
426  Span<float> garbageScoreBatch) const = 0;
427  };
428 
450  virtual ResultValue<
451  FSDKError,
453  match(
454  const IDescriptor* first,
455  const IDescriptor* second) noexcept = 0;
456 
470  virtual Result<FSDKError>
471  match(
472  const IDescriptor* reference,
473  const IDescriptorBatch* candidates,
474  Span<MatchingResult> results) noexcept = 0;
475 
480  virtual uint32_t getModelVersion() const noexcept = 0;
481 
491  virtual Result<FSDKError> calcSimilarity(Span<MatchingResult> distances) const noexcept = 0;
492 
502  virtual Result<FSDKError> calcDistance(Span<MatchingResult> similarities) const noexcept = 0;
503  };
505 }
virtual uint32_t getModelVersion() const noexcept=0
Get algorithm model version this descriptor was created with.
DescriptorVersion
Minimum descriptor model version. Determines which minimum version of descriptor to use...
Definition: IDescriptor.h:73
virtual bool getDescriptor(uint8_t *buffer) const noexcept=0
Copy descriptor data to user provided buffer.
#define DECLARE_SMARTPTR(X)
Smart ptr declaration helper macro.
Definition: Def.h:59
An internal processing error (Ex: memopry allocation or misalignment).
A structure that encapsulates an action result enumeration.
Definition: Result.h:29
Common data types and structures.
An error structure designed for functions which can return errors from different enum classes...
Definition: MultiError.h:17
Error
Descriptor batch error enumeration.
Definition: IDescriptor.h:148
virtual ResultValue< FSDKError, IDescriptorPtr > getDescriptorFast(uint32_t index) noexcept=0
Get descriptor from batch by index without copying.
precise human descriptor, heavy and slow.
Definition: IDescriptor.h:84
HumanDescriptorVersion
Human descriptor model versions. Determines which version of human descriptor to use.
Definition: IDescriptor.h:82
Descriptor batch interface.
Definition: IDescriptor.h:143
human descriptor for tracking of people, light and fast version.
Definition: IDescriptor.h:86
Object system types and interfaces.
virtual Result< MultiError< ISerializableObject::Error, Error > > loadAndAdd(IArchive *archive)=0
Load a descriptor/descriptors from archive and add it to the batch.
virtual uint32_t getDescriptorLength() const noexcept=0
return size of descriptor in bytes.
Common SDK error codes.
Serializable object interface.
Definition: IObject.h:68
virtual Result< Error > add(IDescriptor *descriptor) noexcept=0
Add a descriptor to the batch.
Definition: Result.h:9
Trying to add an incompatible descriptor.
human descriptor for tracking of people, light and fast version.
Definition: IDescriptor.h:83
Base strong reference counted object interface.
Definition: IRefCounted.h:36
virtual Result< Error > removeFast(uint32_t index) noexcept=0
Remove a descriptor from batch.
virtual uint32_t getMaxCount() const noexcept=0
Get maximum number of descriptors in this batch.
Descriptor matcher interface.
Definition: IDescriptor.h:442
virtual void setDescriptor(const uint8_t *buffer) noexcept=0
Copy descriptor from user providedbuffer.
human descriptor.
Definition: IDescriptor.h:66
virtual DescriptorType getDescriptorType() const noexcept=0
Get type of descriptor.
Error while accessing descriptor out of range.
float similarity
similarity (normalized in [0..1] range).
Definition: IDescriptor.h:37
virtual ResultValue< FSDKError, IDescriptorPtr > getDescriptorSlow(uint32_t index) const noexcept=0
Get descriptor from batch by index with copying.
Addon for Result to output some value aside the result. Specialization for copiable types...
Definition: ResultValue.h:25
Face detector interfaces.
virtual uint32_t getModelVersion() const noexcept=0
Get algorithm model version the descriptors in this batch were created with.
virtual uint32_t getDescriptorLength() const noexcept=0
Get length of one descriptor. Specified by version of descriptors in batch.
virtual uint32_t getCount() const noexcept=0
Get actual number of descriptors in this batch.
Descriptor extractor interface.
Definition: IDescriptor.h:309
MatchingResult(void) noexcept
Initializes result to default values.
Definition: IDescriptor.h:42
virtual Result< Error > removeSlow(uint32_t index) noexcept=0
Remove a descriptor from batch.
Image.
Definition: Image.h:39
Result of descriptor matching.
Definition: IDescriptor.h:35
Descriptor interface.
Definition: IDescriptor.h:95
Data storage object interface helper.
Definition: IObject.h:157
face descriptor.
Definition: IDescriptor.h:74
regular human descriptor.
Definition: IDescriptor.h:85
Error while trying open/read/write file.
Archive interface.
Definition: IObject.h:37
precise human descriptor, heavy and slow.
Definition: IDescriptor.h:87
FSDKError
Common SDK error codes.
Definition: FSDKError.h:17
human descriptor.
Definition: IDescriptor.h:75
float distance
distance between descriptor vectors.
Definition: IDescriptor.h:36
DescriptorType
Descriptor type enum. Determines which type of descriptor to use.
Definition: IDescriptor.h:64
Invalid input (Ex: null pointer while a valid object is expected).
MatchingResult(float distance, float similarity) noexcept
Initializes result.
Definition: IDescriptor.h:52
vlc::future< float > FutureResult
Common aliases for BestShotQuality asynchronous interface.
Definition: IDescriptor.h:402
Span. Not owning data view. It incapsulated pointer to the continuous array with one or more T objec...
Definition: Span.h:14
face descriptor.
Definition: IDescriptor.h:65
virtual DescriptorType getDescriptorType() const noexcept=0
Get type of descriptor.
regular human descriptor.
Definition: IDescriptor.h:88