3DiVi Face SDK  3.24.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Groups
Recognizer.h
1 
9 #ifndef __PBIO_API__PBIO__RECOGNIZER_H_
10 #define __PBIO_API__PBIO__RECOGNIZER_H_
11 
12 
13 #include <istream>
14 #include <sstream>
15 #include <vector>
16 
17 #include "ComplexObject.h"
18 #include "Error.h"
19 #include "RawSample.h"
20 #include "SmartPtr.h"
21 #include "Template.h"
22 #include "TemplatesIndex.h"
23 #include "stl_wraps_impls/WrapIStreamBufferImpl.h"
24 #include "stl_wraps_impls/WrapIStreamImpl.h"
25 #include "stl_wraps_impls/WrapOStreamImpl.h"
26 
27 namespace pbio
28 {
29 
30 class FacerecService;
31 
37 class Recognizer : public ComplexObject
38 {
39 public:
40 
46  typedef LightSmartPtr<Recognizer>::tPtr Ptr;
47 
53  struct MatchResult
54  {
60  double distance;
61 
71  double fa_r;
72 
82  double fr_r;
83 
89  double score;
90  };
91 
97  struct SearchResult
98  {
104  size_t i;
105 
112  };
113 
120  {
131 
144  };
145 
146 
164  std::string getMethodName() const;
165 
166 
184  MatchResult getROCCurvePointByDistanceThreshold(const double distance_threshold) const;
185 
186 
204  MatchResult getROCCurvePointByFAR(const double desired_far) const;
205 
206 
224  MatchResult getROCCurvePointByFRR(const double desired_frr) const;
225 
226 
244  MatchResult getROCCurvePointByScoreThreshold(const double score_threshold) const;
245 
246 
270  Template::Ptr processing(const RawSample &sample) const;
271 
272 
302  Template::Ptr loadTemplate(std::istream &binary_stream) const;
303 
333  Template::Ptr loadTemplate(pbio::stl_wraps::WrapIStream &binary_stream) const;
334 
335 
370  const void* const data,
371  const int size) const;
372 
373 
408  const Template &template1,
409  const Template &template2) const;
410 
411 
448  const std::vector<pbio::Template::Ptr> &templates,
449  const int search_threads_count = 1,
450  const int reserve_queries_count = 0) const;
451 
452 
496  std::vector<SearchResult> search(
497  const pbio::Template &query_template,
498  const pbio::TemplatesIndex &templates_index,
499  const size_t k,
500  const SearchAccelerationType acceleration = SEARCH_ACCELERATION_1) const;
501 
502 
548  std::vector<std::vector<SearchResult> > search(
549  const std::vector<pbio::Template::Ptr> &queries_templates,
550  const pbio::TemplatesIndex &templates_index,
551  const size_t k,
552  const SearchAccelerationType acceleration = SEARCH_ACCELERATION_1) const;
553 
554 
588  std::vector<size_t> chooseRepresentativeTemplatesSet(
589  const size_t set_size,
590  const std::vector<pbio::Template::Ptr> &templates,
591  const std::vector<size_t> &inviolable_templates_indexes = std::vector<size_t>());
592 
593 private:
594 
595  Recognizer(
596  const DHPtr &dll_handle,
597  void* impl);
598 
599  friend class FacerecService;
600  friend class object_with_ref_counter<Recognizer>;
601 };
602 
603 } // pbio namespace
604 
605 
606 
610 
611 namespace pbio
612 {
613 
614 inline
615 Recognizer::Recognizer(
616  const DHPtr &dll_handle,
617  void* impl):
618 ComplexObject(dll_handle, impl)
619 {
620  // nothing else
621 }
622 
623 
624 inline
625 std::string Recognizer::getMethodName() const
626 {
627  std::ostringstream name_stream;
628  pbio::stl_wraps::WrapOStreamImpl name_stream_wrap(name_stream);
629 
630  void* exception = NULL;
631 
632  _dll_handle->Recognizer_getMethodName(
633  _impl,
634  &name_stream_wrap,
635  pbio::stl_wraps::WrapOStream::write_func,
636  &exception);
637 
638  checkException(exception, *_dll_handle);
639 
640  return name_stream.str();
641 }
642 
643 
644 inline
646  const RawSample &sample) const
647 {
648  void* exception = NULL;
649 
650  void* const result_impl = _dll_handle->Recognizer_processing(
651  _impl,
652  (const pbio::facerec::RawSampleImpl*) sample._impl,
653  &exception);
654 
655  checkException(exception, *_dll_handle);
656 
657  return Template::Ptr::make(_dll_handle, result_impl);
658 }
659 
660 
661 inline
662 Template::Ptr Recognizer::loadTemplate(std::istream &binary_stream) const
663 {
664  pbio::stl_wraps::WrapIStreamImpl binary_stream_wrap(binary_stream);
665 
666  return loadTemplate(binary_stream_wrap);
667 }
668 
669 inline
670 Template::Ptr Recognizer::loadTemplate(pbio::stl_wraps::WrapIStream &binary_stream) const
671 {
672  void* exception = NULL;
673 
674  void* const result_impl = _dll_handle->Recognizer_loadTemplate(
675  _impl,
676  &binary_stream,
677  pbio::stl_wraps::WrapIStream::read_func,
678  &exception);
679 
680  checkException(exception, *_dll_handle);
681 
682  return Template::Ptr::make(_dll_handle, result_impl);
683 }
684 
685 
686 inline
688  const void* const data,
689  const int size) const
690 {
691  void* exception = NULL;
692 
693  pbio::stl_wraps::WrapIStreamBufferImpl input_stream((const char*) data, size);
694 
695  void* const result_impl = _dll_handle->Recognizer_loadTemplate(
696  _impl,
697  &input_stream,
698  pbio::stl_wraps::WrapIStream::read_func,
699  &exception);
700 
701  checkException(exception, *_dll_handle);
702 
703  return Template::Ptr::make(_dll_handle, result_impl);
704 }
705 
706 
707 inline
709  const Template &template1,
710  const Template &template2) const
711 {
712  MatchResult result;
713 
714  void* exception = NULL;
715 
716  _dll_handle->Recognizer_verifyMatch_v2(
717  _impl,
718  (const pbio::facerec::TemplateImpl*) template1._impl,
719  (const pbio::facerec::TemplateImpl*) template2._impl,
720  &result.distance,
721  &result.fa_r,
722  &result.fr_r,
723  &result.score,
724  &exception);
725 
726  checkException(exception, *_dll_handle);
727 
728  return result;
729 }
730 
731 inline
733  const std::vector<pbio::Template::Ptr> &templates,
734  const int search_threads_count,
735  const int reserve_queries_count) const
736 {
737  std::vector<const pbio::facerec::TemplateImpl*> templates_impls(templates.size());
738 
739  for(size_t i = 0; i < templates.size(); ++i)
740  templates_impls[i] = (const pbio::facerec::TemplateImpl*) templates[i]->_impl;
741 
742  void* exception = NULL;
743 
744  void* const result_impl =
745  _dll_handle->Recognizer_createIndex(
746  _impl,
747  templates.size(),
748  &templates_impls[0],
749  search_threads_count,
750  &exception);
751 
752  checkException(exception, *_dll_handle);
753 
754  const TemplatesIndex::Ptr result = TemplatesIndex::Ptr::make(_dll_handle, result_impl);
755 
756  result->reserveSearchMemory(reserve_queries_count);
757 
758  return result;
759 }
760 
761 
762 inline
763 std::vector<Recognizer::SearchResult> Recognizer::search(
764  const pbio::Template &query_template,
765  const pbio::TemplatesIndex &templates_index,
766  const size_t k,
767  const SearchAccelerationType acceleration) const
768 {
769  std::vector<int64_t> result_i(k);
770  std::vector<float> result_distance(k);
771  std::vector<float> result_far(k);
772  std::vector<float> result_frr(k);
773  std::vector<float> result_score(k);
774 
775  void* exception = NULL;
776 
777  _dll_handle->Recognizer_search_v2(
778  _impl,
779  acceleration,
780  1, // queries_count
781  (const pbio::facerec::TemplateImpl* const*) &query_template._impl,
782  (const pbio::facerec::TemplatesIndexImpl*) templates_index._impl,
783  k,
784  &result_i[0],
785  &result_distance[0],
786  &result_far[0],
787  &result_frr[0],
788  &result_score[0],
789  &exception);
790 
791  checkException(exception, *_dll_handle);
792 
793  std::vector<SearchResult> result(k);
794  result.reserve(k);
795 
796  for(size_t i = 0; i < k; ++i)
797  {
798  if(result_i[i] < 0)
799  {
800  result.resize(i);
801  break;
802  }
803 
804  result[i].i = result_i[i];
805  result[i].match_result.distance = result_distance[i];
806  result[i].match_result.fa_r = result_far[i];
807  result[i].match_result.fr_r = result_frr[i];
808  result[i].match_result.score = result_score[i];
809  }
810 
811  return result;
812 }
813 
814 
815 inline
816 std::vector<std::vector<Recognizer::SearchResult> > Recognizer::search(
817  const std::vector<pbio::Template::Ptr> &queries_templates,
818  const pbio::TemplatesIndex &templates_index,
819  const size_t k,
820  const SearchAccelerationType acceleration) const
821 {
822  const size_t queries_count = queries_templates.size();
823 
824  std::vector<const pbio::facerec::TemplateImpl*> queries_impls(queries_count);
825 
826  for(size_t i = 0; i < queries_count; ++i)
827  {
828  queries_impls[i] = (const pbio::facerec::TemplateImpl*) queries_templates[i]->_impl;
829  }
830 
831  std::vector<int64_t> result_i(k * queries_count);
832  std::vector<float> result_distance(k * queries_count);
833  std::vector<float> result_far(k * queries_count);
834  std::vector<float> result_frr(k * queries_count);
835  std::vector<float> result_score(k * queries_count);
836 
837  void* exception = NULL;
838 
839  _dll_handle->Recognizer_search_v2(
840  _impl,
841  acceleration,
842  queries_count,
843  &queries_impls[0],
844  (const pbio::facerec::TemplatesIndexImpl*) templates_index._impl,
845  k,
846  &result_i[0],
847  &result_distance[0],
848  &result_far[0],
849  &result_frr[0],
850  &result_score[0],
851  &exception);
852 
853  checkException(exception, *_dll_handle);
854 
855  std::vector<std::vector<SearchResult> > result(
856  queries_count,
857  std::vector<SearchResult>(k));
858 
859  for(size_t i = 0; i < queries_count; ++i)
860  {
861  for(size_t j = 0; j < k; ++j)
862  {
863  const size_t h = i * k + j;
864 
865  if(result_i[h] < 0)
866  {
867  result[i].resize(j);
868  break;
869  }
870 
871  result[i][j].i = result_i[h];
872  result[i][j].match_result.distance = result_distance[h];
873  result[i][j].match_result.fa_r = result_far[h];
874  result[i][j].match_result.fr_r = result_frr[h];
875  result[i][j].match_result.score = result_score[h];
876  }
877  }
878 
879  return result;
880 }
881 
882 
883 
884 
885 
886 inline
888  const double distance_threshold) const
889 {
890  MatchResult result;
891 
892  void* exception = NULL;
893 
894  _dll_handle->Recognizer_getROCCurvePointByDistanceThreshold_v2(
895  _impl,
896  distance_threshold,
897  &result.distance,
898  &result.fa_r,
899  &result.fr_r,
900  &result.score,
901  &exception);
902 
903  checkException(exception, *_dll_handle);
904 
905  return result;
906 }
907 
908 inline
910  const double desired_far) const
911 {
912  MatchResult result;
913 
914  void* exception = NULL;
915 
916  _dll_handle->Recognizer_getROCCurvePointByFAR_v2(
917  _impl,
918  desired_far,
919  &result.distance,
920  &result.fa_r,
921  &result.fr_r,
922  &result.score,
923  &exception);
924 
925  checkException(exception, *_dll_handle);
926 
927  return result;
928 }
929 
930 inline
932  const double desired_frr) const
933 {
934  MatchResult result;
935 
936  void* exception = NULL;
937 
938  _dll_handle->Recognizer_getROCCurvePointByFRR_v2(
939  _impl,
940  desired_frr,
941  &result.distance,
942  &result.fa_r,
943  &result.fr_r,
944  &result.score,
945  &exception);
946 
947  checkException(exception, *_dll_handle);
948 
949  return result;
950 }
951 
952 
953 inline
955  const double score_threshold) const
956 {
957  MatchResult result;
958 
959  void* exception = NULL;
960 
961  _dll_handle->Recognizer_getROCCurvePointByScoreThreshold(
962  _impl,
963  score_threshold,
964  &result.distance,
965  &result.fa_r,
966  &result.fr_r,
967  &result.score,
968  &exception);
969 
970  checkException(exception, *_dll_handle);
971 
972  return result;
973 }
974 
975 inline
977  const size_t set_size,
978  const std::vector<pbio::Template::Ptr> &templates,
979  const std::vector<size_t> &inviolable_templates_indexes)
980 {
981  std::vector<pbio::facerec::TemplateImpl const*> template_impls(templates.size());
982 
983  for(size_t i = 0; i < templates.size(); ++i)
984  template_impls[i] = (pbio::facerec::TemplateImpl const*) templates[i]->_impl;
985 
986  std::vector<int8_t> inv_flags_8(templates.size(), 0);
987 
988  for(size_t i = 0; i < inviolable_templates_indexes.size(); ++i)
989  {
990  const size_t j = inviolable_templates_indexes[i];
991 
992  if(j >= templates.size())
993  throw pbio::Error(
994  0x63156958,
995  "Error: bad index in chooseRepresentativeTemplatesSet, error code: 0x63156958");
996 
997  inv_flags_8[j] = 1;
998  }
999 
1000  std::vector<int32_t> result(set_size);
1001 
1002  void* exception = NULL;
1003 
1004  _dll_handle->Recognizer_chooseRepresentativeTemplatesSet(
1005  _impl,
1006  template_impls.empty() ? NULL : template_impls.data(),
1007  inv_flags_8.empty() ? NULL : inv_flags_8.data(),
1008  templates.size(),
1009  result.empty() ? NULL : result.data(),
1010  set_size,
1011  &exception);
1012 
1013  checkException(exception, *_dll_handle);
1014 
1015  return std::vector<size_t>(result.begin(), result.end());
1016 }
1017 
1018 
1019 } // pbio namespace
1020 
1021 
1022 #endif // __PBIO_API__PBIO__RECOGNIZER_H_
MatchResult getROCCurvePointByScoreThreshold(const double score_threshold) const
Get a point on the ROC curve with a given similarity score threshold. Thread-safe.
Definition: Recognizer.h:954
Template::Ptr loadTemplate(std::istream &binary_stream) const
Load the template. The format is platform-independent. Only the templates that were created with the ...
Definition: Recognizer.h:662
Result of template matching.
Definition: Recognizer.h:15
Interface object for creating other interface objects.
Definition: FacerecService.h:64
TemplatesIndex::Ptr createIndex(const std::vector< pbio::Template::Ptr > &templates, const int search_threads_count=1, const int reserve_queries_count=0) const
Create the TemplatesIndex for quick search. The total size of all indexes is limited by the license...
Definition: Recognizer.h:732
MatchResult match_result
Result of matching the query Template with the i-th Template from the TemplatesIndex.
Definition: Recognizer.h:111
Interface object that stores a captured face sample.
Definition: RawSample.h:49
Interface object for saving the face template.
Definition: Template.h:37
double score
Score of templates similarity - real number from 0 to 1.
Definition: Recognizer.h:89
double distance
Distance between the templates.
Definition: Recognizer.h:60
Interface object for working with the template index.
Definition: TemplatesIndex.h:35
std::string getMethodName() const
Get a method name. Thread-safe.
Definition: Recognizer.h:625
Heuristically accelerated linear search. Heuristics reduces TAR (true acceptance rate) on the 1:N tes...
Definition: Recognizer.h:143
Interface object for creating and matching templates.
Definition: Recognizer.h:37
LightSmartPtr< Template >::tPtr Ptr
Alias for the type of a smart pointer to Template.
Definition: Template.h:46
LightSmartPtr< TemplatesIndex >::tPtr Ptr
Alias for the type of a smart pointer to TemplatesIndex.
Definition: TemplatesIndex.h:44
Template::Ptr processing(const RawSample &sample) const
Create a template.
Definition: Recognizer.h:645
Error - the class of exceptions thrown when errors occur.
SearchAccelerationType
Types of search acceleration.
Definition: Recognizer.h:119
Result of template matching.
Definition: Recognizer.h:53
std::vector< size_t > chooseRepresentativeTemplatesSet(const size_t set_size, const std::vector< pbio::Template::Ptr > &templates, const std::vector< size_t > &inviolable_templates_indexes=std::vector< size_t >())
Choose templates set that best represent original templates.
Definition: Recognizer.h:976
Result of searching the Template query in the TemplatesIndex.
Definition: Recognizer.h:97
std::vector< SearchResult > search(const pbio::Template &query_template, const pbio::TemplatesIndex &templates_index, const size_t k, const SearchAccelerationType acceleration=SEARCH_ACCELERATION_1) const
Search for the k nearest Templates in the TemplatesIndex. The search time depends on k and the size o...
Definition: Recognizer.h:763
LightSmartPtr< Recognizer >::tPtr Ptr
Alias for the type of a smart pointer to Recognizer.
Definition: Recognizer.h:46
The class of exceptions thrown when errors occur.
Definition: Error.h:26
double fa_r
False acceptance rate corresponding to the distance value taken as a threshold at the extended LFW te...
Definition: Recognizer.h:71
MatchResult getROCCurvePointByFRR(const double desired_frr) const
Get a point on the ROC curve with a given false rejection rate (FRR). Thread-safe.
Definition: Recognizer.h:931
TemplatesIndex - Interface object for working with the template index.
MatchResult verifyMatch(const Template &template1, const Template &template2) const
Compare two templates. The order of templates does not matter. Only the templates that were created w...
Definition: Recognizer.h:708
size_t i
Index in the TemplatesIndex.
Definition: Recognizer.h:104
MatchResult getROCCurvePointByDistanceThreshold(const double distance_threshold) const
Get a point on the ROC curve with a given distance threshold. Thread-safe.
Definition: Recognizer.h:887
SmartPtr.
No acceleration, a standard line search. The result is identical to N calls of Recognizer::verifyMatc...
Definition: Recognizer.h:130
Definition: FacerecService.mm:79
MatchResult getROCCurvePointByFAR(const double desired_far) const
Get a point on the ROC curve with a given false acceptance rate (FAR). Thread-safe.
Definition: Recognizer.h:909
double fr_r
False rejection rate corresponding to the distance value taken as a threshold at the extended LFW tes...
Definition: Recognizer.h:82