Main MRPT website > C++ reference for MRPT 1.5.7
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-2017, 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...
GLclampf GLclampf GLclampf alpha
Definition: glext.h:3510
A class for storing images as grayscale or RGB bitmaps.
Definition: CImage.h:101
bool isEnabledResizeOutput() const
Returns whether resizing is enabled (default=false)
A pair (x,y) of pixel coordinates (integer resolution).
Definition: TPixelCoord.h:37
const mrpt::utils::TStereoCamera & getCameraParams() const
Returns the camera parameters which were used to generate the distortion map, as passed by the user t...
mrpt::utils::TStereoCamera m_rectified_image_params
Resulting images params.
mrpt::utils::TStereoCamera m_camera_params
A copy of the data provided by the user.
Structure to hold the parameters of a pinhole stereo camera model.
Definition: TStereoCamera.h:25
mrpt::utils::TInterpolationMethod m_interpolation_method
bool isSet() const
Returns true if setFromCamParams() has been already called, false otherwise.
mrpt::utils::TImageSize m_resize_output_value
mrpt::utils::TInterpolationMethod getInterpolationMethod() const
Get the currently selected interpolation method.
mrpt::utils::TImageSize getResizeOutputSize() const
Only when isEnabledResizeOutput() returns true, this gets the target size.
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.
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< int16_t > m_dat_mapx_right
GLuint interp
Definition: glext.h:6197
double getAlpha() const
Return the alpha parameter.
const mrpt::poses::CPose3DQuat & getRightCameraRot() const
See getLeftCameraRot()
GLenum const GLfloat * params
Definition: glext.h:3514
mrpt::poses::CPose3DQuat m_rot_right
The rotation applied to the left/right camera so their virtual image plane is the same after rectific...
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.14 for MRPT 1.5.7 Git: 5902e14cc Wed Apr 24 15:04:01 2019 +0200 at lun oct 28 01:39:17 CET 2019