Main MRPT website > C++ reference for MRPT 1.9.9
CStereoRectifyMap.h
Go to the documentation of this file.
1 /* +------------------------------------------------------------------------+
2  | Mobile Robot Programming Toolkit (MRPT) |
3  | http://www.mrpt.org/ |
4  | |
5  | Copyright (c) 2005-2018, Individual contributors, see AUTHORS file |
6  | See: http://www.mrpt.org/Authors - All rights reserved. |
7  | Released under BSD License. See details in http://www.mrpt.org/License |
8  +------------------------------------------------------------------------+ */
9 #ifndef mrpt_CStereoRectifyMap_H
10 #define mrpt_CStereoRectifyMap_H
11 
12 #include <mrpt/img/TStereoCamera.h>
13 #include <mrpt/img/CImage.h>
15 #include <mrpt/poses/CPose3DQuat.h>
16 
17 namespace mrpt
18 {
19 namespace vision
20 {
21 /** Use this class to rectify stereo images if the same distortion maps are
22  * reused over and over again.
23  * The rectify maps are cached internally and only computed once for the
24  * camera parameters.
25  * The stereo camera calibration must be supplied in a
26  * mrpt::util::TStereoCamera structure
27  * (which provides method for loading from a plain text config file) or
28  * directly from the
29  * parameters of a mrpt::obs::CObservationStereoImages object.
30  *
31  * Remember that the rectified images have a different set of intrinsic
32  * parameters than the
33  * original images, which can be retrieved with \a getRectifiedImageParams()
34  *
35  * Works with grayscale or color images.
36  *
37  * Refer to the program stereo-calib-gui for a tool that generates the
38  * required stereo camera parameters
39  * from a set of stereo images of a checkerboard.
40  *
41  * Example of usage with mrpt::obs::CObservationStereoImages:
42  *
43  * \code
44  * CStereoRectifyMap rectify_map;
45  * // Set options as desired:
46  * // rectify_map.setAlpha(...);
47  * // rectify_map.enableBothCentersCoincide(...);
48  *
49  * while (true) {
50  * mrpt::obs::CObservationStereoImages::Ptr obs_stereo = ... // Grab stereo
51  * observation from wherever
52  *
53  * // Only once, construct the rectification maps:
54  * if (!rectify_map.isSet())
55  * rectify_map.setFromCamParams(*obs_stereo);
56  *
57  * // Rectify in place:
58  * unmap.rectify(*obs_stereo);
59  * // Rectified images are now in: obs_stereo->imageLeft &
60  * obs_stereo->imageRight
61  * }
62  * \endcode
63  *
64  * Read also the tutorial page online:
65  * http://www.mrpt.org/Rectifying_stereo_images
66  *
67  * \sa CUndistortMap, mrpt::obs::CObservationStereoImages,
68  * mrpt::img::TCamera, the application <a
69  * href="http://www.mrpt.org/Application:camera-calib" >camera-calib</a> for
70  * calibrating a camera.
71  *
72  * \note This class provides a uniform wrap over different OpenCV versions. The
73  * "alpha" parameter is ignored if built against OpenCV 2.0.X
74  *
75  * \ingroup mrpt_vision_grp
76  */
78 {
79  public:
80  /** Default ctor */
82 
83  /** @name Rectify map preparation and setting/getting of parameters
84  @{ */
85  /** Returns true if \a setFromCamParams() has been already called, false
86  * otherwise.
87  * Can be used within loops to determine the first usage of the object and
88  * when it needs to be initialized.
89  */
90  inline bool isSet() const { return !m_dat_mapx_left.empty(); }
91  /** Prepares the mapping from the intrinsic, distortion and relative pose
92  * parameters of a stereo camera.
93  * Must be called before invoking \a rectify().
94  * The \a alpha parameter can be changed with \a setAlpha() before invoking
95  * this method; otherwise, the current rectification maps will be marked as
96  * invalid and should be prepared again.
97  * \sa setAlpha()
98  */
100 
101  /** A wrapper to \a setFromCamParams() which takes the parameters from an
102  * stereo observation object */
104  {
106  stereo_obs.getStereoCameraParams(params);
108  }
109 
110  /** Returns the camera parameters which were used to generate the distortion
111  * map, as passed by the user to \a setFromCamParams */
113  {
114  return m_camera_params;
115  }
116 
117  /** After computing the rectification maps, this method retrieves the
118  * calibration parameters of the rectified images
119  * (which won't have any distortion).
120  * \exception std::exception If the rectification maps have not been
121  * computed.
122  */
124 
125  /** Just like \a getRectifiedImageParams() but for the left camera only */
127  /** Just like \a getRectifiedImageParams() but for the right camera only */
129 
130  /** Sets the \a alpha parameter which controls the zoom in/out of the
131  * rectified images, such that:
132  * - alpha=0 => rectified images are zoom in so that only valid pixels are
133  * visible
134  * - alpha=1 => rectified images will contain large "black areas" but no
135  * pixel from the original image will be lost.
136  * Intermediary values leads to intermediary results.
137  * Its default value (-1) means auto guess by the OpenCV's algorithm.
138  * \note Call this method before building the rectification maps, otherwise
139  * they'll be marked as invalid.
140  */
141  void setAlpha(double alpha);
142 
143  /** Return the \a alpha parameter \sa setAlpha */
144  inline double getAlpha() const { return m_alpha; }
145  /** If enabled, the computed maps will rectify images to a size different
146  * than their original size.
147  * \note Call this method before building the rectification maps, otherwise
148  * they'll be marked as invalid.
149  */
150  void enableResizeOutput(
151  bool enable, unsigned int target_width = 0,
152  unsigned int target_height = 0);
153 
154  /** Returns whether resizing is enabled (default=false) \sa
155  * enableResizeOutput */
156  bool isEnabledResizeOutput() const { return m_resize_output; }
157  /** Only when \a isEnabledResizeOutput() returns true, this gets the target
158  * size \sa enableResizeOutput */
160  {
161  return m_resize_output_value;
162  }
163 
164  /** Change remap interpolation method (default=Lineal). This parameter can
165  * be safely changed at any instant without consequences. */
167  {
169  }
170 
171  /** Get the currently selected interpolation method \sa
172  * setInterpolationMethod */
174  {
175  return m_interpolation_method;
176  }
177 
178  /** If enabled (default=false), the principal points in both output images
179  * will coincide.
180  * \note Call this method before building the rectification maps, otherwise
181  * they'll be marked as invalid.
182  */
183  void enableBothCentersCoincide(bool enable = true);
184 
185  /** \sa enableBothCentersCoincide */
187  {
189  }
190 
191  /** After computing the rectification maps, get the rotation applied to the
192  * left/right camera so their virtual image plane is the same after
193  * rectification */
195  {
196  return m_rot_left;
197  }
198  /** See \a getLeftCameraRot() */
200  {
201  return m_rot_right;
202  }
203  /** Direct input access to rectify maps */
204  void setRectifyMaps(
205  const std::vector<int16_t>& left_x, const std::vector<uint16_t>& left_y,
206  const std::vector<int16_t>& right_x,
207  const std::vector<uint16_t>& right_y);
208 
209  /** Direct input access to rectify maps. This method swaps the vectors so
210  * the inputs are no longer available.*/
211  void setRectifyMapsFast(
212  std::vector<int16_t>& left_x, std::vector<uint16_t>& left_y,
213  std::vector<int16_t>& right_x, std::vector<uint16_t>& right_y);
214 
215  /** @} */
216 
217  /** @name Rectify methods
218  @{ */
219 
220  /** Rectify the input image pair and save the result in a different output
221  * images - \a setFromCamParams() must have been set prior to calling this.
222  * The previous contents of the output images are completely ignored, but
223  * if they are already of the
224  * correct size and type, allocation time will be saved.
225  * Recall that \a getRectifiedImageParams() provides you the new intrinsic
226  * parameters of these images.
227  * \exception std::exception If the rectification maps have not been
228  * computed.
229  * \note The same image CANNOT be at the same time input and output, in
230  * which case an exception will be raised (but see the overloaded version
231  * for in-place rectification)
232  */
233  void rectify(
234  const mrpt::img::CImage& in_left_image,
235  const mrpt::img::CImage& in_right_image,
236  mrpt::img::CImage& out_left_image,
237  mrpt::img::CImage& out_right_image) const;
238 
239  /** Overloaded version for in-place rectification: replace input images with
240  * their rectified versions
241  * If \a use_internal_mem_cache is set to \a true (recommended), will reuse
242  * over and over again the same
243  * auxiliary images (kept internally to this object) needed for in-place
244  * rectification.
245  * The only reason not to enable this cache is when multiple threads can
246  * invoke this method simultaneously.
247  */
248  void rectify(
249  mrpt::img::CImage& left_image, mrpt::img::CImage& right_image,
250  const bool use_internal_mem_cache = true) const;
251 
252  /** Overloaded version for in-place rectification of image pairs stored in a
253  * mrpt::obs::CObservationStereoImages.
254  * Upon return, the new camera intrinsic parameters will be already stored
255  * in the observation object.
256  * If \a use_internal_mem_cache is set to \a true (recommended), will reuse
257  * over and over again the same
258  * auxiliary images (kept internally to this object) needed for in-place
259  * rectification.
260  * The only reason not to enable this cache is when multiple threads can
261  * invoke this method simultaneously.
262  * \note This method uses the left & right camera rotations computed by the
263  * rectification map to update
264  * mrpt::obs::CObservationStereoImages::cameraPose (left camera wrt
265  * the robot frame) and
266  * mrpt::obs::CObservationStereoImages::rightCameraPose (right wrt
267  * left camera).
268  */
269  void rectify(
270  mrpt::obs::CObservationStereoImages& stereo_image_observation,
271  const bool use_internal_mem_cache = true) const;
272 
273  /** Just like rectify() but directly works with OpenCV's "IplImage*", which
274  * must be passed as "void*" to avoid header dependencies
275  * Output images CANNOT coincide with the input images. */
276  void rectify_IPL(
277  const void* in_left_image, const void* in_right_image,
278  void* out_left_image, void* out_right_image) const;
279 
280  /** @} */
281 
282  private:
283  double m_alpha;
288 
289  /** Memory caches for in-place rectification speed-up. */
291 
292  std::vector<int16_t> m_dat_mapx_left, m_dat_mapx_right;
293  std::vector<uint16_t> m_dat_mapy_left, m_dat_mapy_right;
294 
295  /** A copy of the data provided by the user */
297  /** Resulting images params */
299 
300  /** The rotation applied to the left/right camera so their virtual image
301  * plane is the same after rectification. */
303 
304  void internal_invalidate();
305 
306 }; // end class
307 
308 } // end namespace
309 } // end namespace
310 #endif
mrpt::img::CImage m_cache1
Memory caches for in-place rectification speed-up.
void setFromCamParams(const mrpt::obs::CObservationStereoImages &stereo_obs)
A wrapper to setFromCamParams() which takes the parameters from an stereo observation object...
GLclampf GLclampf GLclampf alpha
Definition: glext.h:3525
mrpt::img::TStereoCamera m_camera_params
A copy of the data provided by the user.
const mrpt::img::TStereoCamera & getRectifiedImageParams() const
After computing the rectification maps, this method retrieves the calibration parameters of the recti...
mrpt::img::TInterpolationMethod getInterpolationMethod() const
Get the currently selected interpolation method.
mrpt::img::TStereoCamera m_rectified_image_params
Resulting images params.
bool isEnabledResizeOutput() const
Returns whether resizing is enabled (default=false)
void setInterpolationMethod(const mrpt::img::TInterpolationMethod interp)
Change remap interpolation method (default=Lineal).
void setRectifyMaps(const std::vector< int16_t > &left_x, const std::vector< uint16_t > &left_y, const std::vector< int16_t > &right_x, const std::vector< uint16_t > &right_y)
Direct input access to rectify maps.
void setFromCamParams(const mrpt::img::TStereoCamera &params)
Prepares the mapping from the intrinsic, distortion and relative pose parameters of a stereo camera...
void getStereoCameraParams(mrpt::img::TStereoCamera &out_params) const
Populates a TStereoCamera structure with the parameters in leftCamera, rightCamera and rightCameraPos...
bool isSet() const
Returns true if setFromCamParams() has been already called, false otherwise.
mrpt::img::TInterpolationMethod m_interpolation_method
void rectify_IPL(const void *in_left_image, const void *in_right_image, void *out_left_image, void *out_right_image) const
Just like rectify() but directly works with OpenCV&#39;s "IplImage*", which must be passed as "void*" to ...
void rectify(const mrpt::img::CImage &in_left_image, const mrpt::img::CImage &in_right_image, mrpt::img::CImage &out_left_image, mrpt::img::CImage &out_right_image) const
Rectify the input image pair and save the result in a different output images - setFromCamParams() mu...
void setAlpha(double alpha)
Sets the alpha parameter which controls the zoom in/out of the rectified images, such that: ...
const mrpt::img::TCamera & getRectifiedLeftImageParams() const
Just like getRectifiedImageParams() but for the left camera only.
TInterpolationMethod
Interpolation methods for images.
Definition: img/CImage.h:34
Observation class for either a pair of left+right or left+disparity images from a stereo camera...
Use this class to rectify stereo images if the same distortion maps are reused over and over again...
Structure to hold the parameters of a pinhole camera model.
Definition: TCamera.h:29
mrpt::img::TImageSize getResizeOutputSize() const
Only when isEnabledResizeOutput() returns true, this gets the target size.
A class used to store a 3D pose as a translation (x,y,z) and a quaternion (qr,qx,qy,qz).
Definition: CPose3DQuat.h:48
void enableBothCentersCoincide(bool enable=true)
If enabled (default=false), the principal points in both output images will coincide.
std::vector< int16_t > m_dat_mapx_left
const mrpt::img::TStereoCamera & getCameraParams() const
Returns the camera parameters which were used to generate the distortion map, as passed by the user t...
mrpt::poses::CPose3DQuat m_rot_left
The rotation applied to the left/right camera so their virtual image plane is the same after rectific...
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
const mrpt::poses::CPose3DQuat & getLeftCameraRot() const
After computing the rectification maps, get the rotation applied to the left/right camera so their vi...
mrpt::img::TImageSize m_resize_output_value
const mrpt::img::TCamera & getRectifiedRightImageParams() const
Just like getRectifiedImageParams() but for the right camera only.
TPixelCoord TImageSize
A type for image sizes.
Definition: TPixelCoord.h:53
std::vector< int16_t > m_dat_mapx_right
GLuint interp
Definition: glext.h:7133
std::vector< uint16_t > m_dat_mapy_left
void enableResizeOutput(bool enable, unsigned int target_width=0, unsigned int target_height=0)
If enabled, the computed maps will rectify images to a size different than their original size...
double getAlpha() const
Return the alpha parameter.
const mrpt::poses::CPose3DQuat & getRightCameraRot() const
See getLeftCameraRot()
GLenum const GLfloat * params
Definition: glext.h:3534
mrpt::poses::CPose3DQuat m_rot_right
Structure to hold the parameters of a pinhole stereo camera model.
Definition: TStereoCamera.h:25
std::vector< uint16_t > m_dat_mapy_right
A class for storing images as grayscale or RGB bitmaps.
Definition: img/CImage.h:130
void setRectifyMapsFast(std::vector< int16_t > &left_x, std::vector< uint16_t > &left_y, std::vector< int16_t > &right_x, std::vector< uint16_t > &right_y)
Direct input access to rectify maps.



Page generated by Doxygen 1.8.14 for MRPT 1.9.9 Git: ad3a9d8ae Tue May 1 23:10:22 2018 -0700 at lun oct 28 00:14:14 CET 2019