JeVoisBase  1.0
JeVois Smart Embedded Machine Vision Toolkit Base Modules
ObjectMatcher.H
Go to the documentation of this file.
1 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2 //
3 // JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 2016 by Laurent Itti, the University of Southern
4 // California (USC), and iLab at USC. See http://iLab.usc.edu and http://jevois.org for information about this project.
5 //
6 // This file is part of the JeVois Smart Embedded Machine Vision Toolkit. This program is free software; you can
7 // redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software
8 // Foundation, version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
9 // without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
10 // License for more details. You should have received a copy of the GNU General Public License along with this program;
11 // if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
12 //
13 // Contact information: Laurent Itti - 3641 Watt Way, HNB-07A - Los Angeles, CA 90089-2520 - USA.
14 // Tel: +1 213 740 3527 - itti@pollux.usc.edu - http://iLab.usc.edu - http://jevois.org
15 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
16 /*! \file */
17 
18 #pragma once
19 
21 #include <opencv2/core/core.hpp>
22 #include <opencv2/features2d.hpp>
23 
24 namespace objectmatcher
25 {
26  static jevois::ParameterCategory const ParamCateg("Object Matcher Options");
27 
28  //! Parameter \relates ObjectMatcher
29  JEVOIS_DECLARE_PARAMETER(hessian, double, "Hessian threshold", 800.0, ParamCateg);
30 
31  //! Parameter \relates ObjectMatcher
32  JEVOIS_DECLARE_PARAMETER(traindir, std::string, "Directory where training images are", "images", ParamCateg);
33 
34  //! Parameter \relates ObjectMatcher
35  JEVOIS_DECLARE_PARAMETER(goodpts, jevois::Range<size_t>, "Number range of good matches considered",
36  jevois::Range<size_t>(15, 100), ParamCateg);
37 
38  //! Parameter \relates ObjectMatcher
39  JEVOIS_DECLARE_PARAMETER(distthresh, double, "Maximum distance for a match to be considered good",
40  0.2, ParamCateg);
41 }
42 
43 //! Object matching using OpenCV keypoint detection and matching
44 /*! See tutorial at http://docs.opencv.org/3.0-beta/doc/py_tutorials/py_feature2d/py_surf_intro/py_surf_intro.html
45  \ingroup components */
47  public jevois::Parameter<objectmatcher::hessian, objectmatcher::traindir,
48  objectmatcher::goodpts, objectmatcher::distthresh>
49 {
50  public:
51  //! Default inherited constructor ok
53 
54  //! Destructor
56 
57  //! Process a greyscale image, returns match score, object index, and bounding box corners for best match object
58  /*! If return value is 1.0e30, then no good object match was found. This runs detect(), then compute() and then
59  match(). One may also want to run those separately in some cases. */
60  double process(cv::Mat const & img, size_t & trainidx, std::vector<cv::Point2f> & corners);
61 
62  //! Process a greyscale image, returns match score, object index
63  /*! If return value is 1.0e30, then no good object match was found. This runs detect(), then compute() and then
64  match(). One may also want to run those separately in some cases. */
65  double process(cv::Mat const & img, size_t & trainidx);
66 
67  //! Load training images and compute keypoints and descriptors
68  void postInit() override;
69 
70  //! Get number of training images
71  size_t numtrain() const;
72 
73  //! Detect keypoints
74  void detect(cv::Mat const & img, std::vector<cv::KeyPoint> & keypoints);
75 
76  //! Compute descriptors for given keypoints
77  /*! \note keypoints is an input argument but opencv wants a non-const ref to it for some reason. */
78  void compute(cv::Mat const & img, std::vector<cv::KeyPoint> & keypoints, cv::Mat & descriptors);
79 
80  //! Match given descriptors against those of our training images, return best match distance
81  double match(std::vector<cv::KeyPoint> const & keypoints, cv::Mat const & descriptors,
82  size_t & trainidx, std::vector<cv::Point2f> & corners);
83 
84  //! Match given descriptors against those of our training images, return best match distance
85  double match(std::vector<cv::KeyPoint> const & keypoints, cv::Mat const & descriptors, size_t & trainidx);
86 
87  //! Training data structure for ObjectMatcher
88  /*! \relates ObjectMatcher */
89  struct TrainData
90  {
91  std::string name;
92  cv::Mat image;
93  std::vector<cv::KeyPoint> keypoints;
94  cv::Mat descriptors;
95  };
96 
97  //! Get the training data for a given index
98  TrainData const & traindata(size_t idx) const;
99 
100  private:
101  struct MatchData
102  {
103  double avgdist;
104  size_t trainidx;
105  std::vector<cv::Point2f> corners;
106  };
107 
108  MatchData matchcore(size_t corenum, std::vector<cv::KeyPoint> const & keypoints, cv::Mat const & descriptors,
109  size_t minidx, size_t maxidx, bool do_corners);
110 
111  cv::Ptr<cv::Feature2D> itsFeatureDetector;
112  std::vector<cv::Ptr<cv::DescriptorMatcher> > itsMatcher; // one matcher per core
113  std::vector<TrainData> itsTrainData;
114 };
115 
double match(std::vector< cv::KeyPoint > const &keypoints, cv::Mat const &descriptors, size_t &trainidx, std::vector< cv::Point2f > &corners)
Match given descriptors against those of our training images, return best match distance.
~ObjectMatcher()
Destructor.
Definition: ObjectMatcher.C:35
Training data structure for ObjectMatcher.
Definition: ObjectMatcher.H:89
JEVOIS_DECLARE_PARAMETER(thresh1, double,"First threshold for hysteresis", 50.0, ParamCateg)
void detect(cv::Mat const &img, std::vector< cv::KeyPoint > &keypoints)
Detect keypoints.
void compute(cv::Mat const &img, std::vector< cv::KeyPoint > &keypoints, cv::Mat &descriptors)
Compute descriptors for given keypoints.
size_t numtrain() const
Get number of training images.
TrainData const & traindata(size_t idx) const
Get the training data for a given index.
void postInit() override
Load training images and compute keypoints and descriptors.
Definition: ObjectMatcher.C:39
std::vector< cv::KeyPoint > keypoints
Definition: ObjectMatcher.H:93
friend friend class Component
double process(cv::Mat const &img, size_t &trainidx, std::vector< cv::Point2f > &corners)
Process a greyscale image, returns match score, object index, and bounding box corners for best match...
Definition: ObjectMatcher.C:87
Object matching using OpenCV keypoint detection and matching.
Definition: ObjectMatcher.H:46