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



Page generated by Doxygen 1.8.11 for MRPT 1.4.0 SVN: at Mon Aug 15 11:50:21 UTC 2016