Main MRPT website > C++ reference
MRPT logo
CStereoRectifyMap.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 #ifndef mrpt_CStereoRectifyMap_H
29 #define mrpt_CStereoRectifyMap_H
30 
31 #include <mrpt/utils/TStereoCamera.h>
32 #include <mrpt/utils/CImage.h>
33 #include <mrpt/slam/CObservationStereoImages.h>
34 
35 #include <mrpt/vision/link_pragmas.h>
36 
37 namespace mrpt
38 {
39  namespace vision
40  {
41  /** Use this class to rectify stereo images if the same distortion maps are reused over and over again.
42  * The rectify maps are cached internally and only computed once for the camera parameters.
43  * The stereo camera calibration must be supplied in a mrpt::util::TStereoCamera structure
44  * (which provides method for loading from a plain text config file) or directly from the
45  * parameters of a mrpt::slam::CObservationStereoImages object.
46  *
47  * Remember that the rectified images have a different set of intrinsic parameters than the
48  * original images, which can be retrieved with \a getRectifiedImageParams()
49  *
50  * Works with grayscale or color images.
51  *
52  * Refer to the program stereo-calib-gui for a tool that generates the required stereo camera parameters
53  * from a set of stereo images of a checkerboard.
54  *
55  * Example of usage with mrpt::slam::CObservationStereoImages:
56  *
57  * \code
58  * CStereoRectifyMap rectify_map;
59  * // Set options as desired:
60  * // rectify_map.setAlpha(...);
61  * // rectify_map.enableBothCentersCoincide(...);
62  *
63  * while (true) {
64  * mrpt::slam::CObservationStereoImagesPtr obs_stereo = ... // Grab stereo observation from wherever
65  *
66  * // Only once, construct the rectification maps:
67  * if (!rectify_map.isSet())
68  * rectify_map.setFromCamParams(*obs_stereo);
69  *
70  * // Rectify in place:
71  * unmap.rectify(*obs_stereo);
72  * // Rectified images are now in: obs_stereo->imageLeft & obs_stereo->imageRight
73  * }
74  * \endcode
75  *
76  * Read also the tutorial page online: http://www.mrpt.org/Rectifying_stereo_images
77  *
78  * \sa CUndistortMap, mrpt::slam::CObservationStereoImages, mrpt::utils::TCamera, the application <a href="http://www.mrpt.org/Application:camera-calib" >camera-calib</a> for calibrating a camera.
79  *
80  * \note This class provides a uniform wrap over different OpenCV versions. The "alpha" parameter is ignored if built against OpenCV 2.0.X
81  *
82  * \ingroup mrpt_vision_grp
83  */
84  class VISION_IMPEXP CStereoRectifyMap
85  {
86  public:
87  CStereoRectifyMap(); //!< Default ctor
88 
89  /** @name Rectify map preparation and setting/getting of parameters
90  @{ */
91  /** Returns true if \a setFromCamParams() has been already called, false otherwise.
92  * Can be used within loops to determine the first usage of the object and when it needs to be initialized.
93  */
94  inline bool isSet() const { return !m_dat_mapx_left.empty(); }
95 
96  /** Prepares the mapping from the intrinsic, distortion and relative pose parameters of a stereo camera.
97  * Must be called before invoking \a rectify().
98  * The \a alpha parameter can be changed with \a setAlpha() before invoking this method; otherwise, the current rectification maps will be marked as invalid and should be prepared again.
99  * \sa setAlpha()
100  */
101  void setFromCamParams(const mrpt::utils::TStereoCamera &params);
102 
103  /** A wrapper to \a setFromCamParams() which takes the parameters from an stereo observation object */
104  void setFromCamParams(const mrpt::slam::CObservationStereoImages &stereo_obs)
105  {
106  mrpt::utils::TStereoCamera params;
107  stereo_obs.getStereoCameraParams(params);
108  setFromCamParams(params);
109  }
110 
111  /** Returns the camera parameters which were used to generate the distortion map, as passed by the user to \a setFromCamParams */
112  inline const mrpt::utils::TStereoCamera & getCameraParams() const { return m_camera_params; }
113 
114  /** After computing the rectification maps, this method retrieves the calibration parameters of the rectified images
115  * (which won't have any distortion).
116  * \exception std::exception If the rectification maps have not been computed.
117  */
118  const mrpt::utils::TStereoCamera & getRectifiedImageParams() const;
119 
120  const mrpt::utils::TCamera & getRectifiedLeftImageParams() const; //!< Just like \a getRectifiedImageParams() but for the left camera only
121  const mrpt::utils::TCamera & getRectifiedRightImageParams() const; //!< Just like \a getRectifiedImageParams() but for the right camera only
122 
123  /** Sets the \a alpha parameter which controls the zoom in/out of the rectified images, such that:
124  * - alpha=0 => rectified images are zoom in so that only valid pixels are visible
125  * - alpha=1 => rectified images will contain large "black areas" but no pixel from the original image will be lost.
126  * Intermediary values leads to intermediary results.
127  * Its default value (-1) means auto guess by the OpenCV's algorithm.
128  * \note Call this method before building the rectification maps, otherwise they'll be marked as invalid.
129  */
130  void setAlpha(double alpha);
131 
132  /** Return the \a alpha parameter \sa setAlpha */
133  inline double getAlpha() const { return m_alpha; }
134 
135  /** If enabled, the computed maps will rectify images to a size different than their original size.
136  * \note Call this method before building the rectification maps, otherwise they'll be marked as invalid.
137  */
138  void enableResizeOutput(bool enable, unsigned int target_width=0, unsigned int target_height=0);
139 
140  /** Returns whether resizing is enabled (default=false) \sa enableResizeOutput */
141  bool isEnabledResizeOutput() const { return m_resize_output; }
142 
143  /** Only when \a isEnabledResizeOutput() returns true, this gets the target size \sa enableResizeOutput */
144  mrpt::utils::TImageSize getResizeOutputSize() const { return m_resize_output_value; }
145 
146  /** Change remap interpolation method (default=Lineal). This parameter can be safely changed at any instant without consequences. */
147  void setInterpolationMethod(const mrpt::utils::TInterpolationMethod interp) { m_interpolation_method = m_interpolation_method; }
148 
149  /** Get the currently selected interpolation method \sa setInterpolationMethod */
150  mrpt::utils::TInterpolationMethod getInterpolationMethod() const { return m_interpolation_method; }
151 
152  /** If enabled (default=false), the principal points in both output images will coincide.
153  * \note Call this method before building the rectification maps, otherwise they'll be marked as invalid.
154  */
155  void enableBothCentersCoincide(bool enable=true);
156 
157  /** \sa enableBothCentersCoincide */
158  bool isEnabledBothCentersCoincide() const { return m_enable_both_centers_coincide; }
159 
160 
161  /** @} */
162 
163  /** @name Rectify methods
164  @{ */
165 
166  /** Rectify the input image pair and save the result in a different output images - \a setFromCamParams() must have been set prior to calling this.
167  * The previous contents of the output images are completely ignored, but if they are already of the
168  * correct size and type, allocation time will be saved.
169  * Recall that \a getRectifiedImageParams() provides you the new intrinsic parameters of these images.
170  * \exception std::exception If the rectification maps have not been computed.
171  * \note The same image CANNOT be at the same time input and output, in which case an exception will be raised (but see the overloaded version for in-place rectification)
172  */
173  void rectify(
174  const mrpt::utils::CImage &in_left_image,
175  const mrpt::utils::CImage &in_right_image,
176  mrpt::utils::CImage &out_left_image,
177  mrpt::utils::CImage &out_right_image) const;
178 
179  /** Overloaded version for in-place rectification: replace input images with their rectified versions
180  * If \a use_internal_mem_cache is set to \a true (recommended), will reuse over and over again the same
181  * auxiliary images (kept internally to this object) needed for in-place rectification.
182  * The only reason not to enable this cache is when multiple threads can invoke this method simultaneously.
183  */
184  void rectify(
185  mrpt::utils::CImage &left_image,
186  mrpt::utils::CImage &right_image,
187  const bool use_internal_mem_cache = true ) const;
188 
189  /** Overloaded version for in-place rectification of image pairs stored in a mrpt::slam::CObservationStereoImages.
190  * Upon return, the new camera intrinsic parameters will be already stored in the observation object.
191  * If \a use_internal_mem_cache is set to \a true (recommended), will reuse over and over again the same
192  * auxiliary images (kept internally to this object) needed for in-place rectification.
193  * The only reason not to enable this cache is when multiple threads can invoke this method simultaneously.
194  */
195  void rectify(
196  mrpt::slam::CObservationStereoImages & stereo_image_observation,
197  const bool use_internal_mem_cache = true ) const;
198 
199  /** Just like rectify() but directly works with OpenCV's "IplImage*", which must be passed as "void*" to avoid header dependencies
200  * Output images CANNOT coincide with the input images. */
201  void rectify_IPL(
202  const void* in_left_image,
203  const void* in_right_image,
204  void* out_left_image,
205  void* out_right_image) const;
206 
207  /** @} */
208 
209  private:
210  double m_alpha;
211  bool m_resize_output;
212  bool m_enable_both_centers_coincide;
213  mrpt::utils::TImageSize m_resize_output_value;
214  mrpt::utils::TInterpolationMethod m_interpolation_method;
215 
216  mutable mrpt::utils::CImage m_cache1, m_cache2; //!< Memory caches for in-place rectification speed-up.
217 
218  std::vector<int16_t> m_dat_mapx_left,m_dat_mapx_right;
219  std::vector<uint16_t> m_dat_mapy_left,m_dat_mapy_right;
220 
221  mrpt::utils::TStereoCamera m_camera_params; //!< A copy of the data provided by the user
222  mrpt::utils::TStereoCamera m_rectified_image_params; //!< Resulting images params
223 
224  void internal_invalidate();
225 
226  }; // end class
227 
228  } // end namespace
229 } // end namespace
230 #endif


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