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