Main MRPT website > C++ reference
MRPT logo
vision/include/mrpt/vision/utils.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | The Mobile Robot Programming Toolkit (MRPT) C++ library |
3  | |
4  | http://www.mrpt.org/ |
5  | |
6  | Copyright (C) 2005-2012 University of Malaga |
7  | |
8  | This software was written by the Machine Perception and Intelligent |
9  | Robotics Lab, University of Malaga (Spain). |
10  | Contact: Jose-Luis Blanco <jlblanco@ctima.uma.es> |
11  | |
12  | This file is part of the MRPT project. |
13  | |
14  | MRPT is free software: you can redistribute it and/or modify |
15  | it under the terms of the GNU General Public License as published by |
16  | the Free Software Foundation, either version 3 of the License, or |
17  | (at your option) any later version. |
18  | |
19  | MRPT is distributed in the hope that it will be useful, |
20  | but WITHOUT ANY WARRANTY; without even the implied warranty of |
21  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
22  | GNU General Public License for more details. |
23  | |
24  | You should have received a copy of the GNU General Public License |
25  | along with MRPT. If not, see <http://www.gnu.org/licenses/>. |
26  | |
27  +---------------------------------------------------------------------------+ */
28 
29 #ifndef mrpt_vision_utils_H
30 #define mrpt_vision_utils_H
31 
32 #include <mrpt/vision/CFeature.h>
33 #include <mrpt/utils/CImage.h>
34 #include <mrpt/math/utils.h>
35 #include <mrpt/utils/CLoadableOptions.h>
36 #include <mrpt/utils/TMatchingPair.h>
37 #include <mrpt/poses/CPose3D.h>
38 #include <mrpt/poses/CPoint2D.h>
39 #include <mrpt/poses/CPoint3D.h>
40 
41 #include <mrpt/vision/types.h>
42 #include <mrpt/vision/chessboard_camera_calib.h>
43 
44 #include <mrpt/vision/link_pragmas.h>
45 
46 namespace mrpt
47 {
48  namespace slam
49  {
50  class CObservationStereoImages;
51  class CObservationBearingRange;
52  class CLandmarksMap;
53  class CObservationVisualLandmarks;
54  }
55 
56  /** Classes for computer vision, detectors, features, etc. \ingroup mrpt_vision_grp
57  */
58  namespace vision
59  {
60  using std::vector;
61  using namespace mrpt::slam;
62  using namespace mrpt::math;
63  using namespace mrpt::utils;
64 
65  /** \addtogroup mrpt_vision_grp
66  * @{ */
67 
68  /** Computes the correlation between this image and another one, encapsulating the openCV function cvMatchTemplate
69  * This implementation reduced computation time.
70  * \param img [IN] The imput image. This function supports gray-scale (1 channel only) images.
71  * \param patch_img [IN] The "patch" image, which must be equal, or smaller than "this" image. This function supports gray-scale (1 channel only) images.
72  * \param x_max [OUT] The x coordinate where it was found the maximun cross correlation value.
73  * \param y_max [OUT] The y coordinate where it was found the maximun cross correlation value.
74  * \param max_val [OUT] The maximun value of cross correlation which we can find
75  * \param x_search_ini [IN] The "x" coordinate of the search window.
76  * \param y_search_ini [IN] The "y" coordinate of the search window.
77  * \param x_search_size [IN] The width of the search window.
78  * \param y_search_size [IN] The height of the search window.
79  * Note: By default, the search area is the whole (this) image.
80  * \sa cross_correlation
81  */
82  void VISION_IMPEXP openCV_cross_correlation(
83  const CImage & img,
84  const CImage & patch_img,
85  size_t & x_max,
86  size_t & y_max,
87  double & max_val,
88  int x_search_ini=-1,
89  int y_search_ini=-1,
90  int x_search_size=-1,
91  int y_search_size=-1);
92 
93  /** Invert an image using OpenCV function
94  *
95  */
96  void VISION_IMPEXP flip(
97  CImage & img);
98 
99  /** Extract a UNITARY 3D vector in the direction of a 3D point, given from its (x,y) pixels coordinates, and the camera intrinsic coordinates.
100  * \param xy [IN] Pixels coordinates, from the top-left corner of the image.
101  * \param A [IN] The 3x3 intrinsic parameters matrix for the camera.
102  * \return The TPoint3D containing the output unitary vector.
103  * \sa buildIntrinsicParamsMatrix, defaultIntrinsicParamsMatrix, TPixelCoordf
104  */
105  TPoint3D VISION_IMPEXP pixelTo3D(
106  const TPixelCoordf & xy,
107  const CMatrixDouble33 & A);
108 
109  /** Builds the intrinsic parameters matrix A from parameters:
110  * \param focalLengthX [IN] The focal length, in X (horizontal) pixels
111  * \param focalLengthY [IN] The focal length, in Y (vertical) pixels
112  * \param centerX [IN] The image center, horizontal, in pixels
113  * \param centerY [IN] The image center, vertical, in pixels
114  *
115  * <br>This method returns the matrix:
116  <table>
117  <tr><td>f_x</td><td>0</td><td>cX</td> </tr>
118  <tr><td>0</td><td>f_y</td><td>cY</td> </tr>
119  <tr><td>0</td><td>0</td><td>1</td> </tr>
120  </table>
121  * See also the tutorial discussing the <a rhref="http://www.mrpt.org/Camera_Parameters">camera model parameters</a>.
122  * \sa defaultIntrinsicParamsMatrix, pixelTo3D
123  */
124  CMatrixDouble33 VISION_IMPEXP buildIntrinsicParamsMatrix(
125  const double focalLengthX,
126  const double focalLengthY,
127  const double centerX,
128  const double centerY);
129 
130  /** Returns the stored, default intrinsic params matrix for a given camera:
131  * \param camIndex [IN] Posible values are listed next.
132  * \param resolutionX [IN] The number of pixel columns
133  * \param resolutionY [IN] The number of pixel rows
134  *
135  * The matrix is generated for the indicated camera resolution configuration.
136  * The following table summarizes the current supported cameras and the values as
137  * ratios of the corresponding horz. or vert. resolution:<br>
138 
139  <center><table>
140  <tr>
141  <td><center><b>camIndex</b></center></td>
142  <td><center><b>Manufacturer</b></center></td>
143  <td><center><b>Camera model</b></center></td>
144  <td><center><b>fx</b></center></td>
145  <td><center><b>fy</b></center></td>
146  <td><center><b>cx</b></center></td>
147  <td><center><b>cy</b></center></td>
148  </tr>
149 
150  <tr>
151  <td><center>0</center></td>
152  <td><center>Point Grey Research</center></td>
153  <td><center>Bumblebee</center></td>
154  <td><center>0.79345</center></td>
155  <td><center>1.05793</center></td>
156  <td><center>0.55662</center></td>
157  <td><center>0.52692</center></td>
158  </tr>
159 
160  <tr>
161  <td><center>1</center></td>
162  <td><center>Sony</center></td>
163  <td><center>???</center></td>
164  <td><center>0.95666094</center></td>
165  <td><center>1.3983423f</center></td>
166  <td><center>0.54626328f</center></td>
167  <td><center>0.4939191f</center></td>
168  </tr>
169  </table>
170  </center>
171 
172  * \sa buildIntrinsicParamsMatrix, pixelTo3D
173  */
174  CMatrixDouble33 VISION_IMPEXP defaultIntrinsicParamsMatrix(
175  unsigned int camIndex = 0,
176  unsigned int resolutionX = 320,
177  unsigned int resolutionY = 240 );
178 
179  /** Explore the feature list and removes features which are in the same coordinates
180  * \param list [IN] The list of features.
181  */
182  void VISION_IMPEXP deleteRepeatedFeats(
183  CFeatureList & list );
184 
185  /** Search for correspondences which are not in the same row and deletes them
186  * \param leftList [IN/OUT] The left list of matched features.
187  * \param rightList [IN/OUT] The right list of matched features.
188  * \param threshold [IN] The tolerance value for the row checking: valid matched are within this threshold.
189  */
190  void VISION_IMPEXP rowChecking(
191  CFeatureList & leftList,
192  CFeatureList & rightList,
193  float threshold = 1.0);
194 
195  /** Computes the dispersion of the features in the image
196  * \param list [IN] Input list of features
197  * \param std [OUT] 2 element vector containing the standard deviations in the 'x' and 'y' coordinates.
198  * \param mean [OUT] 2 element vector containing the mean in the 'x' and 'y' coordinates.
199  */
200  void VISION_IMPEXP getDispersion(
201  const CFeatureList & list,
202  vector_float & std,
203  vector_float & mean );
204 
205  /** Returns a new image where distortion has been removed.
206  * \param A The 3x3 intrinsic parameters matrix
207  * \param dist_coeffs The 1x4 (or 1x5) vector of distortion coefficients
208  */
209  inline void correctDistortion(
210  const CImage & in_img,
211  CImage & out_img,
212  const CMatrixDouble33 & A,
213  const vector_double & dist_coeffs )
214  {
215  in_img.rectifyImage( out_img, A, dist_coeffs);
216  }
217 
218 
219  /** Computes the mean squared distance between a set of 3D correspondences
220  * ...
221  */
222  double VISION_IMPEXP computeMsd(
223  const TMatchingPairList & list,
224  const poses::CPose3D & Rt );
225 
226  /** Transform two clouds of 3D points into a matched list of points
227  * ...
228  */
229  void VISION_IMPEXP cloudsToMatchedList(
230  const CObservationVisualLandmarks & cloud1,
231  const CObservationVisualLandmarks & cloud2,
232  TMatchingPairList & outList);
233 
234  /** Computes the main orientation of a set of points with an image (for using in SIFT-based algorithms)
235  * \param image [IN] The input image.
236  * \param x [IN] A vector containing the 'x' coordinates of the image points.
237  * \param y [IN] A vector containing the 'y' coordinates of the image points.
238  * \return The main orientation of the image point.
239  */
240  float VISION_IMPEXP computeMainOrientation(
241  const CImage & image,
242  unsigned int x,
243  unsigned int y );
244 
245  /** Normalizes the brigthness and contrast of an image by setting its mean value to zero and its standard deviation to unit.
246  * \param image [IN] The input image.
247  * \param nimage [OUTPUT] The new normalized image.
248  */
249  void VISION_IMPEXP normalizeImage(
250  const CImage & image,
251  CImage & nimage );
252 
253  /** Find the matches between two lists of features which must be of the same type.
254  * \param list1 [IN] One list.
255  * \param list2 [IN] Other list.
256  * \param matches [OUT] A vector of pairs of correspondences.
257  * \param options [IN] A struct containing matching options
258  * \return Returns the number of matched pairs of features.
259  */
260  size_t VISION_IMPEXP matchFeatures(
261  const CFeatureList & list1,
262  const CFeatureList & list2,
263  CMatchedFeatureList & matches,
264  const TMatchingOptions & options = TMatchingOptions(),
265  const TStereoSystemParams & params = TStereoSystemParams() );
266 
267  /** Calculates the Sum of Absolutes Differences (range [0,1]) between two patches. Both patches must have the same size.
268  * \param mList [IN] The list of matched features.
269  * \param mask1 [OUT] The output mask for left features.
270  * \param mask2 [OUT] The output mask for right features.
271  * \param wSize [IN] The value of the masking window for each features.
272  * \exception if mList.size() = 0
273  */
274  void VISION_IMPEXP generateMask(
275  const CMatchedFeatureList & mList,
276  CMatrixBool & mask1,
277  CMatrixBool & mask2,
278  int wSize = 10 );
279 
280  /** Calculates the Sum of Absolutes Differences (range [0,1]) between two patches. Both patches must have the same size.
281  * \param patch1 [IN] One patch.
282  * \param patch2 [IN] The other patch.
283  * \return The value of computed SAD normalized to [0,1]
284  */
285  double VISION_IMPEXP computeSAD(
286  const CImage & patch1,
287  const CImage & patch2 );
288 
289  /** Draw rectangles around each of the features on a copy of the input image.
290  * \param inImg [IN] The input image where to draw the features.
291  * \param theList [IN] The list of features.
292  * \param outImg [OUT] The copy of the input image with the marked features.
293  */
294  void VISION_IMPEXP addFeaturesToImage(
295  const CImage & inImg,
296  const CFeatureList & theList,
297  CImage & outImg );
298 
299  /** Computes the 3D position of a set of matched features from their coordinates in the images. The list have to be matched in order, e.g. leftList[0]<->rightList[0]
300  * \param leftList [IN] The left list of features.
301  * \param rightList [IN] The right list of features.
302  * \param vP3D [OUT] A vector of TPoint3D containing the 3D positions of the projected points.
303  * \param params [IN] The intrinsic and extrinsic parameters of the stereo pair.
304  */
305  void VISION_IMPEXP projectMatchedFeatures(
306  const CFeatureList & leftList,
307  const CFeatureList & rightList,
308  vector<TPoint3D> & vP3D,
309  const TStereoSystemParams & params = TStereoSystemParams() );
310 
311  /** Computes the 3D position of a particular matched feature.
312  * \param leftList [IN] The left feature.
313  * \param rightList [IN] The right feature.
314  * \param vP3D [OUT] The 3D position of the projected point.
315  * \param params [IN] The intrinsic and extrinsic parameters of the stereo pair.
316  */
317  void VISION_IMPEXP projectMatchedFeature(
318  const CFeaturePtr & leftFeat,
319  const CFeaturePtr & rightFeat,
320  TPoint3D & p3D,
321  const TStereoSystemParams & params = TStereoSystemParams() );
322 
323  /** Project a list of matched features into the 3D space, using the provided parameters of the stereo system
324  * \param mfList [IN/OUT] The list of matched features. Features which yields a 3D point outside the area defined in TStereoSystemParams are removed from the lists.
325  * \param param [IN] The parameters of the stereo system.
326  * \param landmarks [OUT] A map containing the projected landmarks.
327  * \sa TStereoSystemParams, CLandmarksMap
328  */
329  void VISION_IMPEXP projectMatchedFeatures(
330  CMatchedFeatureList & mfList,
331  const TStereoSystemParams & param,
332  CLandmarksMap & landmarks );
333 
334  /** Project a pair of feature lists into the 3D space, using the provided options for the stereo system. The matches must be in order,
335  * i.e. leftList[0] corresponds to rightList[0] and so on. Features which yields a 3D point outside the area defined in TStereoSystemParams are removed from the lists.
336  * \param leftList [IN/OUT] The left list of matched features.
337  * \param rightList [IN/OUT] The right list of matched features.
338  * \param param [IN] The options of the stereo system.
339  * \param landmarks (OUT] A map containing the projected landmarks.
340  * \sa TStereoSystemParams, CLandmarksMap
341  */
342  void VISION_IMPEXP projectMatchedFeatures(
343  CFeatureList & leftList,
344  CFeatureList & rightList,
345  const TStereoSystemParams & param,
346  CLandmarksMap & landmarks );
347 
348  /** Converts a stereo images observation into a bearing and range observation.
349  \param inObs [IN] The input stereo images observation.
350  \param sg [IN] The sigma of the row, col, and disparity variables involved in the feature detection.
351  \param outObs [OUT] The output bearing and range observation (including covariances).
352  */
353  void VISION_IMPEXP StereoObs2BRObs(
354  const CObservationStereoImages & inObs,
355  const vector<double> & sg,
356  CObservationBearingRange & outObs );
357 
358  /** Converts a matched feature list into a bearing and range observation (some of the stereo camera system must be provided).
359  \param inMatches [IN] The input list of matched features.
360  \param intrinsicParams [IN] The intrisic params of the reference (left) camera of the stereo system.
361  \param baseline [IN] The distance among the X axis of the right camera wrt the reference (left) camera.
362  \param sg [IN] The sigma of the row, col, and disparity variables involved in the feature detection.
363  \param outObs [OUT] The output bearing and range observation (including covariances).
364  */
365  void VISION_IMPEXP StereoObs2BRObs(
366  const CMatchedFeatureList & inMatches,
367  const CMatrixDouble33 & intrinsicParams,
368  const double & baseline,
369  const CPose3D & sensorPose,
370  const vector<double> & sg,
371  CObservationBearingRange & outObs );
372 
373  /** Converts a CObservationVisualLandmarks into a bearing and range observation (without any covariances). Fields of view are not computed.
374  \param inObs [IN] The input observation.
375  \param sg [IN] The sigma of the row, col, and disparity variables involved in the feature detection.
376  \param outObs [OUT] The output bearing and range observation.
377  */
378  void VISION_IMPEXP StereoObs2BRObs(
379  const CObservationStereoImages & inObs,
380  const vector<double> & sg,
381  CObservationBearingRange & outObs );
382 
383  /** Converts a CObservationVisualLandmarks into a bearing and range observation (without any covariances). Fields of view are not computed.
384  \param inObs [IN] The input observation.
385  \param outObs [OUT] The output bearing and range observation.
386  */
387  void VISION_IMPEXP StereoObs2BRObs(
388  const CObservationVisualLandmarks & inObs,
389  CObservationBearingRange & outObs );
390 
391  /** Computes a pair of x-and-y maps for stereo rectification from a pair of cameras and the relative pose of the second one wrt the first one.
392  \param cam1, cam2 [IN] The pair of involved cameras
393  \param rightCameraPose [IN] The change in pose of the second camera wrt the first one
394  \param outMap1x,outMap1y [OUT] The x-and-y maps corresponding to cam1 (should be converted to *cv::Mat)
395  \param outMap2x,outMap2y [OUT] The x-and-y maps corresponding to cam2 (should be converted to *cv::Mat)
396  * \sa An easier to use class for stereo rectification mrpt::vision::CStereoRectifyMap
397  */
398  void VISION_IMPEXP computeStereoRectificationMaps(
399  const TCamera & cam1,
400  const TCamera & cam2,
401  const poses::CPose3D & rightCameraPose,
402  void *outMap1x,
403  void *outMap1y,
404  void *outMap2x,
405  void *outMap2y );
406 
407 
408  /** @} */ // end of grouping
409 
410  } // end-namespace-vision
411 } // end-namespace-mrpt
412 
413 
414 #endif


Page generated by Doxygen 1.8.3 for MRPT 0.9.6 SVN: at Fri Feb 15 22:05:02 EST 2013