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>
16
18
19namespace 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 */
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 */
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 */
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 */
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 */
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. */
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
226
227 }; // end class
228
229 } // end namespace
230} // end namespace
231#endif
Observation class for either a pair of left+right or left+disparity images from a stereo camera.
void getStereoCameraParams(mrpt::utils::TStereoCamera &out_params) const
Populates a TStereoCamera structure with the parameters in leftCamera, rightCamera and rightCameraPos...
A class used to store a 3D pose as a translation (x,y,z) and a quaternion (qr,qx,qy,...
Definition: CPose3DQuat.h:42
A class for storing images as grayscale or RGB bitmaps.
Definition: CImage.h:102
Structure to hold the parameters of a pinhole camera model.
Definition: TCamera.h:32
Structure to hold the parameters of a pinhole stereo camera model.
Definition: TStereoCamera.h:26
Use this class to rectify stereo images if the same distortion maps are reused over and over again.
const mrpt::utils::TStereoCamera & getRectifiedImageParams() const
After computing the rectification maps, this method retrieves the calibration parameters of the recti...
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.
void rectify(mrpt::obs::CObservationStereoImages &stereo_image_observation, const bool use_internal_mem_cache=true) const
Overloaded version for in-place rectification of image pairs stored in a mrpt::obs::CObservationStere...
bool isEnabledResizeOutput() const
Returns whether resizing is enabled (default=false)
void rectify(const mrpt::utils::CImage &in_left_image, const mrpt::utils::CImage &in_right_image, mrpt::utils::CImage &out_left_image, mrpt::utils::CImage &out_right_image) const
Rectify the input image pair and save the result in a different output images - setFromCamParams() mu...
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.
const mrpt::utils::TCamera & getRectifiedRightImageParams() const
Just like getRectifiedImageParams() but for the right camera only.
const mrpt::utils::TCamera & getRectifiedLeftImageParams() const
Just like getRectifiedImageParams() but for the left camera only.
const mrpt::poses::CPose3DQuat & getRightCameraRot() const
See getLeftCameraRot()
std::vector< int16_t > m_dat_mapx_left
void enableBothCentersCoincide(bool enable=true)
If enabled (default=false), the principal points in both output images will coincide.
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's "IplImage*", which must be passed as "void*" to ...
mrpt::utils::TImageSize m_resize_output_value
mrpt::utils::TInterpolationMethod getInterpolationMethod() const
Get the currently selected interpolation method.
std::vector< uint16_t > m_dat_mapy_left
void setInterpolationMethod(const mrpt::utils::TInterpolationMethod interp)
Change remap interpolation method (default=Lineal).
void rectify(mrpt::utils::CImage &left_image, mrpt::utils::CImage &right_image, const bool use_internal_mem_cache=true) const
Overloaded version for in-place rectification: replace input images with their rectified versions If ...
void setFromCamParams(const mrpt::utils::TStereoCamera &params)
Prepares the mapping from the intrinsic, distortion and relative pose parameters of a stereo camera.
mrpt::utils::TInterpolationMethod m_interpolation_method
const mrpt::poses::CPose3DQuat & getLeftCameraRot() const
After computing the rectification maps, get the rotation applied to the left/right camera so their vi...
mrpt::poses::CPose3DQuat m_rot_left
mrpt::utils::TStereoCamera m_camera_params
A copy of the data provided by the user.
const mrpt::utils::TStereoCamera & getCameraParams() const
Returns the camera parameters which were used to generate the distortion map, as passed by the user t...
void setFromCamParams(const mrpt::obs::CObservationStereoImages &stereo_obs)
A wrapper to setFromCamParams() which takes the parameters from an stereo observation object.
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.
mrpt::utils::TStereoCamera m_rectified_image_params
Resulting images params.
bool isSet() const
Returns true if setFromCamParams() has been already called, false otherwise.
double getAlpha() const
Return the alpha parameter.
mrpt::utils::TImageSize getResizeOutputSize() const
Only when isEnabledResizeOutput() returns true, this gets the target size.
void setAlpha(double alpha)
Sets the alpha parameter which controls the zoom in/out of the rectified images, such that:
TInterpolationMethod
Interpolation methods for images.
Definition: CImage.h:32
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
A pair (x,y) of pixel coordinates (integer resolution).
Definition: TPixelCoord.h:38



Page generated by Doxygen 1.9.5 for MRPT 1.4.0 SVN: at Tue Dec 27 00:54:45 UTC 2022