3DiVi Face SDK  3.24.1
 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 
453  TemplatesIndex::Ptr createResizableIndex(
454  const uint64_t templates_count,
455  const int search_threads_count = 1,
456  const int reserve_queries_count = 0) const;
457 
458 
502  std::vector<SearchResult> search(
503  const pbio::Template &query_template,
504  const pbio::TemplatesIndex &templates_index,
505  const size_t k,
506  const SearchAccelerationType acceleration = SEARCH_ACCELERATION_1) const;
507 
508 
554  std::vector<std::vector<SearchResult> > search(
555  const std::vector<pbio::Template::Ptr> &queries_templates,
556  const pbio::TemplatesIndex &templates_index,
557  const size_t k,
558  const SearchAccelerationType acceleration = SEARCH_ACCELERATION_1) const;
559 
560 
594  std::vector<size_t> chooseRepresentativeTemplatesSet(
595  const size_t set_size,
596  const std::vector<pbio::Template::Ptr> &templates,
597  const std::vector<size_t> &inviolable_templates_indexes = std::vector<size_t>());
598 
599 private:
600 
601  Recognizer(
602  const DHPtr &dll_handle,
603  void* impl);
604 
605  friend class FacerecService;
606  friend class object_with_ref_counter<Recognizer>;
607 };
608 
609 } // pbio namespace
610 
611 
612 
616 
617 namespace pbio
618 {
619 
620 inline
621 Recognizer::Recognizer(
622  const DHPtr &dll_handle,
623  void* impl):
624 ComplexObject(dll_handle, impl)
625 {
626  // nothing else
627 }
628 
629 
630 inline
631 std::string Recognizer::getMethodName() const
632 {
633  std::ostringstream name_stream;
634  pbio::stl_wraps::WrapOStreamImpl name_stream_wrap(name_stream);
635 
636  void* exception = NULL;
637 
638  _dll_handle->Recognizer_getMethodName(
639  _impl,
640  &name_stream_wrap,
641  pbio::stl_wraps::WrapOStream::write_func,
642  &exception);
643 
644  checkException(exception, *_dll_handle);
645 
646  return name_stream.str();
647 }
648 
649 
650 inline
652  const RawSample &sample) const
653 {
654  void* exception = NULL;
655 
656  void* const result_impl = _dll_handle->Recognizer_processing(
657  _impl,
658  (const pbio::facerec::RawSampleImpl*) sample._impl,
659  &exception);
660 
661  checkException(exception, *_dll_handle);
662 
663  return Template::Ptr::make(_dll_handle, result_impl);
664 }
665 
666 
667 inline
668 Template::Ptr Recognizer::loadTemplate(std::istream &binary_stream) const
669 {
670  pbio::stl_wraps::WrapIStreamImpl binary_stream_wrap(binary_stream);
671 
672  return loadTemplate(binary_stream_wrap);
673 }
674 
675 inline
676 Template::Ptr Recognizer::loadTemplate(pbio::stl_wraps::WrapIStream &binary_stream) const
677 {
678  void* exception = NULL;
679 
680  void* const result_impl = _dll_handle->Recognizer_loadTemplate(
681  _impl,
682  &binary_stream,
683  pbio::stl_wraps::WrapIStream::read_func,
684  &exception);
685 
686  checkException(exception, *_dll_handle);
687 
688  return Template::Ptr::make(_dll_handle, result_impl);
689 }
690 
691 
692 inline
694  const void* const data,
695  const int size) const
696 {
697  void* exception = NULL;
698 
699  pbio::stl_wraps::WrapIStreamBufferImpl input_stream((const char*) data, size);
700 
701  void* const result_impl = _dll_handle->Recognizer_loadTemplate(
702  _impl,
703  &input_stream,
704  pbio::stl_wraps::WrapIStream::read_func,
705  &exception);
706 
707  checkException(exception, *_dll_handle);
708 
709  return Template::Ptr::make(_dll_handle, result_impl);
710 }
711 
712 
713 inline
715  const Template &template1,
716  const Template &template2) const
717 {
718  MatchResult result;
719 
720  void* exception = NULL;
721 
722  _dll_handle->Recognizer_verifyMatch_v2(
723  _impl,
724  (const pbio::facerec::TemplateImpl*) template1._impl,
725  (const pbio::facerec::TemplateImpl*) template2._impl,
726  &result.distance,
727  &result.fa_r,
728  &result.fr_r,
729  &result.score,
730  &exception);
731 
732  checkException(exception, *_dll_handle);
733 
734  return result;
735 }
736 
737 inline
739  const std::vector<pbio::Template::Ptr> &templates,
740  const int search_threads_count,
741  const int reserve_queries_count) const
742 {
743  std::vector<const pbio::facerec::TemplateImpl*> templates_impls(templates.size());
744 
745  for(size_t i = 0; i < templates.size(); ++i)
746  templates_impls[i] = (const pbio::facerec::TemplateImpl*) templates[i]->_impl;
747 
748  void* exception = NULL;
749 
750  void* const result_impl =
751  _dll_handle->Recognizer_createIndex(
752  _impl,
753  templates.size(),
754  &templates_impls[0],
755  search_threads_count,
756  &exception);
757 
758  checkException(exception, *_dll_handle);
759 
760  const TemplatesIndex::Ptr result = TemplatesIndex::Ptr::make(_dll_handle, result_impl);
761 
762  result->reserveSearchMemory(reserve_queries_count);
763 
764  return result;
765 }
766 
767 
768 inline TemplatesIndex::Ptr Recognizer::createResizableIndex(
769  const uint64_t templates_count,
770  const int search_threads_count,
771  const int reserve_queries_count) const
772 {
773  void* exception = NULL;
774 
775  void* const result_impl =
776  _dll_handle->Recognizer_createResizableIndex(
777  _impl,
778  templates_count,
779  search_threads_count,
780  &exception);
781 
782  checkException(exception, *_dll_handle);
783 
784  const TemplatesIndex::Ptr result = TemplatesIndex::Ptr::make(_dll_handle, result_impl);
785 
786  result->reserveSearchMemory(reserve_queries_count);
787 
788  return result;
789 }
790 
791 
792 inline
793 std::vector<Recognizer::SearchResult> Recognizer::search(
794  const pbio::Template &query_template,
795  const pbio::TemplatesIndex &templates_index,
796  const size_t k,
797  const SearchAccelerationType acceleration) const
798 {
799  std::vector<int64_t> result_i(k);
800  std::vector<float> result_distance(k);
801  std::vector<float> result_far(k);
802  std::vector<float> result_frr(k);
803  std::vector<float> result_score(k);
804 
805  void* exception = NULL;
806 
807  _dll_handle->Recognizer_search_v2(
808  _impl,
809  acceleration,
810  1, // queries_count
811  (const pbio::facerec::TemplateImpl* const*) &query_template._impl,
812  (const pbio::facerec::TemplatesIndexImpl*) templates_index._impl,
813  k,
814  &result_i[0],
815  &result_distance[0],
816  &result_far[0],
817  &result_frr[0],
818  &result_score[0],
819  &exception);
820 
821  checkException(exception, *_dll_handle);
822 
823  std::vector<SearchResult> result(k);
824  result.reserve(k);
825 
826  for(size_t i = 0; i < k; ++i)
827  {
828  if(result_i[i] < 0)
829  {
830  result.resize(i);
831  break;
832  }
833 
834  result[i].i = result_i[i];
835  result[i].match_result.distance = result_distance[i];
836  result[i].match_result.fa_r = result_far[i];
837  result[i].match_result.fr_r = result_frr[i];
838  result[i].match_result.score = result_score[i];
839  }
840 
841  return result;
842 }
843 
844 
845 inline
846 std::vector<std::vector<Recognizer::SearchResult> > Recognizer::search(
847  const std::vector<pbio::Template::Ptr> &queries_templates,
848  const pbio::TemplatesIndex &templates_index,
849  const size_t k,
850  const SearchAccelerationType acceleration) const
851 {
852  const size_t queries_count = queries_templates.size();
853 
854  std::vector<const pbio::facerec::TemplateImpl*> queries_impls(queries_count);
855 
856  for(size_t i = 0; i < queries_count; ++i)
857  {
858  queries_impls[i] = (const pbio::facerec::TemplateImpl*) queries_templates[i]->_impl;
859  }
860 
861  std::vector<int64_t> result_i(k * queries_count);
862  std::vector<float> result_distance(k * queries_count);
863  std::vector<float> result_far(k * queries_count);
864  std::vector<float> result_frr(k * queries_count);
865  std::vector<float> result_score(k * queries_count);
866 
867  void* exception = NULL;
868 
869  _dll_handle->Recognizer_search_v2(
870  _impl,
871  acceleration,
872  queries_count,
873  &queries_impls[0],
874  (const pbio::facerec::TemplatesIndexImpl*) templates_index._impl,
875  k,
876  &result_i[0],
877  &result_distance[0],
878  &result_far[0],
879  &result_frr[0],
880  &result_score[0],
881  &exception);
882 
883  checkException(exception, *_dll_handle);
884 
885  std::vector<std::vector<SearchResult> > result(
886  queries_count,
887  std::vector<SearchResult>(k));
888 
889  for(size_t i = 0; i < queries_count; ++i)
890  {
891  for(size_t j = 0; j < k; ++j)
892  {
893  const size_t h = i * k + j;
894 
895  if(result_i[h] < 0)
896  {
897  result[i].resize(j);
898  break;
899  }
900 
901  result[i][j].i = result_i[h];
902  result[i][j].match_result.distance = result_distance[h];
903  result[i][j].match_result.fa_r = result_far[h];
904  result[i][j].match_result.fr_r = result_frr[h];
905  result[i][j].match_result.score = result_score[h];
906  }
907  }
908 
909  return result;
910 }
911 
912 
913 
914 
915 
916 inline
918  const double distance_threshold) const
919 {
920  MatchResult result;
921 
922  void* exception = NULL;
923 
924  _dll_handle->Recognizer_getROCCurvePointByDistanceThreshold_v2(
925  _impl,
926  distance_threshold,
927  &result.distance,
928  &result.fa_r,
929  &result.fr_r,
930  &result.score,
931  &exception);
932 
933  checkException(exception, *_dll_handle);
934 
935  return result;
936 }
937 
938 inline
940  const double desired_far) const
941 {
942  MatchResult result;
943 
944  void* exception = NULL;
945 
946  _dll_handle->Recognizer_getROCCurvePointByFAR_v2(
947  _impl,
948  desired_far,
949  &result.distance,
950  &result.fa_r,
951  &result.fr_r,
952  &result.score,
953  &exception);
954 
955  checkException(exception, *_dll_handle);
956 
957  return result;
958 }
959 
960 inline
962  const double desired_frr) const
963 {
964  MatchResult result;
965 
966  void* exception = NULL;
967 
968  _dll_handle->Recognizer_getROCCurvePointByFRR_v2(
969  _impl,
970  desired_frr,
971  &result.distance,
972  &result.fa_r,
973  &result.fr_r,
974  &result.score,
975  &exception);
976 
977  checkException(exception, *_dll_handle);
978 
979  return result;
980 }
981 
982 
983 inline
985  const double score_threshold) const
986 {
987  MatchResult result;
988 
989  void* exception = NULL;
990 
991  _dll_handle->Recognizer_getROCCurvePointByScoreThreshold(
992  _impl,
993  score_threshold,
994  &result.distance,
995  &result.fa_r,
996  &result.fr_r,
997  &result.score,
998  &exception);
999 
1000  checkException(exception, *_dll_handle);
1001 
1002  return result;
1003 }
1004 
1005 inline
1007  const size_t set_size,
1008  const std::vector<pbio::Template::Ptr> &templates,
1009  const std::vector<size_t> &inviolable_templates_indexes)
1010 {
1011  std::vector<pbio::facerec::TemplateImpl const*> template_impls(templates.size());
1012 
1013  for(size_t i = 0; i < templates.size(); ++i)
1014  template_impls[i] = (pbio::facerec::TemplateImpl const*) templates[i]->_impl;
1015 
1016  std::vector<int8_t> inv_flags_8(templates.size(), 0);
1017 
1018  for(size_t i = 0; i < inviolable_templates_indexes.size(); ++i)
1019  {
1020  const size_t j = inviolable_templates_indexes[i];
1021 
1022  if(j >= templates.size())
1023  throw pbio::Error(
1024  0x63156958,
1025  "Error: bad index in chooseRepresentativeTemplatesSet, error code: 0x63156958");
1026 
1027  inv_flags_8[j] = 1;
1028  }
1029 
1030  std::vector<int32_t> result(set_size);
1031 
1032  void* exception = NULL;
1033 
1034  _dll_handle->Recognizer_chooseRepresentativeTemplatesSet(
1035  _impl,
1036  template_impls.empty() ? NULL : template_impls.data(),
1037  inv_flags_8.empty() ? NULL : inv_flags_8.data(),
1038  templates.size(),
1039  result.empty() ? NULL : result.data(),
1040  set_size,
1041  &exception);
1042 
1043  checkException(exception, *_dll_handle);
1044 
1045  return std::vector<size_t>(result.begin(), result.end());
1046 }
1047 
1048 
1049 } // pbio namespace
1050 
1051 
1052 #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:984
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:668
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:738
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:37
std::string getMethodName() const
Get a method name. Thread-safe.
Definition: Recognizer.h:631
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:46
Template::Ptr processing(const RawSample &sample) const
Create a template.
Definition: Recognizer.h:651
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:1006
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:793
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:961
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:714
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:917
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:939
double fr_r
False rejection rate corresponding to the distance value taken as a threshold at the extended LFW tes...
Definition: Recognizer.h:82