Main MRPT website > C++ reference for MRPT 1.5.6
List of all members | Public Member Functions | Private Member Functions | Private Attributes
mrpt::vision::CStereoRectifyMap Class Reference

Detailed Description

Use this class to rectify stereo images if the same distortion maps are reused over and over again.

The rectify maps are cached internally and only computed once for the camera parameters. The stereo camera calibration must be supplied in a mrpt::util::TStereoCamera structure (which provides method for loading from a plain text config file) or directly from the parameters of a mrpt::obs::CObservationStereoImages object.

Remember that the rectified images have a different set of intrinsic parameters than the original images, which can be retrieved with getRectifiedImageParams()

Works with grayscale or color images.

Refer to the program stereo-calib-gui for a tool that generates the required stereo camera parameters from a set of stereo images of a checkerboard.

Example of usage with mrpt::obs::CObservationStereoImages:

CStereoRectifyMap rectify_map;
// Set options as desired:
// rectify_map.setAlpha(...);
// rectify_map.enableBothCentersCoincide(...);
while (true) {
mrpt::obs::CObservationStereoImagesPtr obs_stereo = ... // Grab stereo observation from wherever
// Only once, construct the rectification maps:
if (!rectify_map.isSet())
rectify_map.setFromCamParams(*obs_stereo);
// Rectify in place:
unmap.rectify(*obs_stereo);
// Rectified images are now in: obs_stereo->imageLeft & obs_stereo->imageRight
}

Read also the tutorial page online: http://www.mrpt.org/Rectifying_stereo_images

See also
CUndistortMap, mrpt::obs::CObservationStereoImages, mrpt::utils::TCamera, the application camera-calib for calibrating a camera.
Note
This class provides a uniform wrap over different OpenCV versions. The "alpha" parameter is ignored if built against OpenCV 2.0.X

Definition at line 66 of file CStereoRectifyMap.h.

#include <mrpt/vision/CStereoRectifyMap.h>

Public Member Functions

 CStereoRectifyMap ()
 Default ctor. More...
 
Rectify map preparation and setting/getting of parameters
bool isSet () const
 Returns true if setFromCamParams() has been already called, false otherwise. More...
 
void setFromCamParams (const mrpt::utils::TStereoCamera &params)
 Prepares the mapping from the intrinsic, distortion and relative pose parameters of a stereo camera. More...
 
void setFromCamParams (const mrpt::obs::CObservationStereoImages &stereo_obs)
 A wrapper to setFromCamParams() which takes the parameters from an stereo observation object. More...
 
const mrpt::utils::TStereoCameragetCameraParams () const
 Returns the camera parameters which were used to generate the distortion map, as passed by the user to setFromCamParams. More...
 
const mrpt::utils::TStereoCameragetRectifiedImageParams () const
 After computing the rectification maps, this method retrieves the calibration parameters of the rectified images (which won't have any distortion). More...
 
const mrpt::utils::TCameragetRectifiedLeftImageParams () const
 Just like getRectifiedImageParams() but for the left camera only. More...
 
const mrpt::utils::TCameragetRectifiedRightImageParams () const
 Just like getRectifiedImageParams() but for the right camera only. More...
 
void setAlpha (double alpha)
 Sets the alpha parameter which controls the zoom in/out of the rectified images, such that: More...
 
double getAlpha () const
 Return the alpha parameter. More...
 
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. More...
 
bool isEnabledResizeOutput () const
 Returns whether resizing is enabled (default=false) More...
 
mrpt::utils::TImageSize getResizeOutputSize () const
 Only when isEnabledResizeOutput() returns true, this gets the target size. More...
 
void setInterpolationMethod (const mrpt::utils::TInterpolationMethod interp)
 Change remap interpolation method (default=Lineal). More...
 
mrpt::utils::TInterpolationMethod getInterpolationMethod () const
 Get the currently selected interpolation method. More...
 
void enableBothCentersCoincide (bool enable=true)
 If enabled (default=false), the principal points in both output images will coincide. More...
 
bool isEnabledBothCentersCoincide () const
 
const mrpt::poses::CPose3DQuatgetLeftCameraRot () const
 After computing the rectification maps, get the rotation applied to the left/right camera so their virtual image plane is the same after rectification. More...
 
const mrpt::poses::CPose3DQuatgetRightCameraRot () const
 See getLeftCameraRot() More...
 
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. More...
 
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. More...
 
Rectify methods
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() must have been set prior to calling this. More...
 
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 use_internal_mem_cache is set to true (recommended), will reuse over and over again the same auxiliary images (kept internally to this object) needed for in-place rectification. More...
 
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::CObservationStereoImages. More...
 
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 avoid header dependencies Output images CANNOT coincide with the input images. More...
 

Private Member Functions

void internal_invalidate ()
 

Private Attributes

double m_alpha
 
bool m_resize_output
 
bool m_enable_both_centers_coincide
 
mrpt::utils::TImageSize m_resize_output_value
 
mrpt::utils::TInterpolationMethod m_interpolation_method
 
mrpt::utils::CImage m_cache1
 
mrpt::utils::CImage m_cache2
 Memory caches for in-place rectification speed-up. More...
 
std::vector< int16_tm_dat_mapx_left
 
std::vector< int16_tm_dat_mapx_right
 
std::vector< uint16_tm_dat_mapy_left
 
std::vector< uint16_tm_dat_mapy_right
 
mrpt::utils::TStereoCamera m_camera_params
 A copy of the data provided by the user. More...
 
mrpt::utils::TStereoCamera m_rectified_image_params
 Resulting images params. More...
 
mrpt::poses::CPose3DQuat m_rot_left
 
mrpt::poses::CPose3DQuat m_rot_right
 The rotation applied to the left/right camera so their virtual image plane is the same after rectification. More...
 

Constructor & Destructor Documentation

◆ CStereoRectifyMap()

CStereoRectifyMap::CStereoRectifyMap ( )

Default ctor.

Definition at line 24 of file CStereoRectifyMap.cpp.

Member Function Documentation

◆ enableBothCentersCoincide()

void CStereoRectifyMap::enableBothCentersCoincide ( bool  enable = true)

If enabled (default=false), the principal points in both output images will coincide.

Note
Call this method before building the rectification maps, otherwise they'll be marked as invalid.

Definition at line 57 of file CStereoRectifyMap.cpp.

References internal_invalidate(), and m_enable_both_centers_coincide.

◆ enableResizeOutput()

void CStereoRectifyMap::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.

Note
Call this method before building the rectification maps, otherwise they'll be marked as invalid.

Definition at line 48 of file CStereoRectifyMap.cpp.

References internal_invalidate(), m_resize_output, m_resize_output_value, mrpt::utils::TPixelCoord::x, and mrpt::utils::TPixelCoord::y.

◆ getAlpha()

double mrpt::vision::CStereoRectifyMap::getAlpha ( ) const
inline

Return the alpha parameter.

See also
setAlpha

Definition at line 115 of file CStereoRectifyMap.h.

◆ getCameraParams()

const mrpt::utils::TStereoCamera& mrpt::vision::CStereoRectifyMap::getCameraParams ( ) const
inline

Returns the camera parameters which were used to generate the distortion map, as passed by the user to setFromCamParams.

Definition at line 94 of file CStereoRectifyMap.h.

◆ getInterpolationMethod()

mrpt::utils::TInterpolationMethod mrpt::vision::CStereoRectifyMap::getInterpolationMethod ( ) const
inline

Get the currently selected interpolation method.

See also
setInterpolationMethod

Definition at line 134 of file CStereoRectifyMap.h.

◆ getLeftCameraRot()

const mrpt::poses::CPose3DQuat& mrpt::vision::CStereoRectifyMap::getLeftCameraRot ( ) const
inline

After computing the rectification maps, get the rotation applied to the left/right camera so their virtual image plane is the same after rectification.

Definition at line 146 of file CStereoRectifyMap.h.

◆ getRectifiedImageParams()

const mrpt::utils::TStereoCamera & CStereoRectifyMap::getRectifiedImageParams ( ) const

After computing the rectification maps, this method retrieves the calibration parameters of the rectified images (which won't have any distortion).

Exceptions
std::exceptionIf the rectification maps have not been computed.

Definition at line 428 of file CStereoRectifyMap.cpp.

References isSet(), m_rectified_image_params, and THROW_EXCEPTION.

◆ getRectifiedLeftImageParams()

const mrpt::utils::TCamera & CStereoRectifyMap::getRectifiedLeftImageParams ( ) const

Just like getRectifiedImageParams() but for the left camera only.

Definition at line 434 of file CStereoRectifyMap.cpp.

References isSet(), mrpt::utils::TStereoCamera::leftCamera, m_rectified_image_params, and THROW_EXCEPTION.

◆ getRectifiedRightImageParams()

const mrpt::utils::TCamera & CStereoRectifyMap::getRectifiedRightImageParams ( ) const

Just like getRectifiedImageParams() but for the right camera only.

Definition at line 440 of file CStereoRectifyMap.cpp.

References isSet(), m_rectified_image_params, mrpt::utils::TStereoCamera::rightCamera, and THROW_EXCEPTION.

◆ getResizeOutputSize()

mrpt::utils::TImageSize mrpt::vision::CStereoRectifyMap::getResizeOutputSize ( ) const
inline

Only when isEnabledResizeOutput() returns true, this gets the target size.

See also
enableResizeOutput

Definition at line 126 of file CStereoRectifyMap.h.

◆ getRightCameraRot()

const mrpt::poses::CPose3DQuat& mrpt::vision::CStereoRectifyMap::getRightCameraRot ( ) const
inline

See getLeftCameraRot()

Definition at line 148 of file CStereoRectifyMap.h.

◆ internal_invalidate()

void CStereoRectifyMap::internal_invalidate ( )
private

◆ isEnabledBothCentersCoincide()

bool mrpt::vision::CStereoRectifyMap::isEnabledBothCentersCoincide ( ) const
inline
See also
enableBothCentersCoincide

Definition at line 142 of file CStereoRectifyMap.h.

◆ isEnabledResizeOutput()

bool mrpt::vision::CStereoRectifyMap::isEnabledResizeOutput ( ) const
inline

Returns whether resizing is enabled (default=false)

See also
enableResizeOutput

Definition at line 123 of file CStereoRectifyMap.h.

◆ isSet()

bool mrpt::vision::CStereoRectifyMap::isSet ( ) const
inline

Returns true if setFromCamParams() has been already called, false otherwise.

Can be used within loops to determine the first usage of the object and when it needs to be initialized.

Definition at line 76 of file CStereoRectifyMap.h.

Referenced by getRectifiedImageParams(), getRectifiedLeftImageParams(), getRectifiedRightImageParams(), and rectify_IPL().

◆ rectify() [1/3]

void CStereoRectifyMap::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() must have been set prior to calling this.

The previous contents of the output images are completely ignored, but if they are already of the correct size and type, allocation time will be saved. Recall that getRectifiedImageParams() provides you the new intrinsic parameters of these images.

Exceptions
std::exceptionIf the rectification maps have not been computed.
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)

Definition at line 265 of file CStereoRectifyMap.cpp.

References mrpt::utils::CImage::getAs(), mrpt::utils::CImage::isColor(), mrpt::utils::CImage::isOriginTopLeft(), mrpt::utils::TStereoCamera::leftCamera, m_camera_params, m_resize_output, m_resize_output_value, MRPT_END, MRPT_START, mrpt::utils::TCamera::ncols, mrpt::utils::TCamera::nrows, rectify_IPL(), mrpt::utils::CImage::resize(), mrpt::utils::TPixelCoord::x, and mrpt::utils::TPixelCoord::y.

Referenced by mrpt::hwdrivers::CDUO3DCamera::getObservations(), and rectify().

◆ rectify() [2/3]

void CStereoRectifyMap::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 use_internal_mem_cache is set to true (recommended), will reuse over and over again the same auxiliary images (kept internally to this object) needed for in-place rectification.

The only reason not to enable this cache is when multiple threads can invoke this method simultaneously.

Definition at line 299 of file CStereoRectifyMap.cpp.

References mrpt::utils::CImage::getAs(), mrpt::utils::CImage::isColor(), mrpt::utils::CImage::isOriginTopLeft(), mrpt::utils::TStereoCamera::leftCamera, m_cache1, m_cache2, m_camera_params, m_resize_output, m_resize_output_value, MRPT_END, MRPT_START, mrpt::utils::TCamera::ncols, mrpt::utils::TCamera::nrows, rectify_IPL(), mrpt::utils::CImage::resize(), mrpt::utils::CImage::setFromIplImage(), mrpt::utils::TPixelCoord::x, and mrpt::utils::TPixelCoord::y.

◆ rectify() [3/3]

void CStereoRectifyMap::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::CObservationStereoImages.

Upon return, the new camera intrinsic parameters will be already stored in the observation object. If use_internal_mem_cache is set to true (recommended), will reuse over and over again the same auxiliary images (kept internally to this object) needed for in-place rectification. The only reason not to enable this cache is when multiple threads can invoke this method simultaneously.

Note
This method uses the left & right camera rotations computed by the rectification map to update mrpt::obs::CObservationStereoImages::cameraPose (left camera wrt the robot frame) and mrpt::obs::CObservationStereoImages::rightCameraPose (right wrt left camera).

Upon return, the new camera intrinsic parameters will be already stored in the observation object.

Definition at line 361 of file CStereoRectifyMap.cpp.

References ASSERT_, mrpt::obs::CObservationStereoImages::cameraPose, mrpt::obs::CObservationStereoImages::hasImageRight, mrpt::obs::CObservationStereoImages::imageLeft, mrpt::obs::CObservationStereoImages::imageRight, mrpt::poses::CPose3DQuat::m_coords, m_rectified_image_params, m_rot_left, MRPT_END, MRPT_START, rectify(), mrpt::obs::CObservationStereoImages::rightCameraPose, and mrpt::obs::CObservationStereoImages::setStereoCameraParams().

◆ rectify_IPL()

void CStereoRectifyMap::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 avoid header dependencies Output images CANNOT coincide with the input images.

Just like rectify() but directly works with OpenCV's "IplImage*", which must be passed as "void*" to avoid header dependencies.

Definition at line 386 of file CStereoRectifyMap.cpp.

References ASSERT_, isSet(), mrpt::utils::TStereoCamera::leftCamera, m_camera_params, m_dat_mapx_left, m_dat_mapx_right, m_dat_mapy_left, m_dat_mapy_right, m_interpolation_method, m_resize_output, m_resize_output_value, MRPT_END, MRPT_START, mrpt::utils::TCamera::ncols, mrpt::utils::TCamera::nrows, THROW_EXCEPTION, mrpt::utils::TPixelCoord::x, and mrpt::utils::TPixelCoord::y.

Referenced by rectify().

◆ setAlpha()

void CStereoRectifyMap::setAlpha ( double  alpha)

Sets the alpha parameter which controls the zoom in/out of the rectified images, such that:

  • alpha=0 => rectified images are zoom in so that only valid pixels are visible
  • alpha=1 => rectified images will contain large "black areas" but no pixel from the original image will be lost. Intermediary values leads to intermediary results. Its default value (-1) means auto guess by the OpenCV's algorithm.
    Note
    Call this method before building the rectification maps, otherwise they'll be marked as invalid.

Definition at line 41 of file CStereoRectifyMap.cpp.

References internal_invalidate(), and m_alpha.

◆ setFromCamParams() [1/2]

void CStereoRectifyMap::setFromCamParams ( const mrpt::utils::TStereoCamera params)

Prepares the mapping from the intrinsic, distortion and relative pose parameters of a stereo camera.

Prepares the mapping from the distortion parameters of a camera.

Must be called before invoking rectify(). The alpha parameter can be changed with setAlpha() before invoking this method; otherwise, the current rectification maps will be marked as invalid and should be prepared again.

See also
setAlpha()

Must be called before invoking undistort().

Definition at line 69 of file CStereoRectifyMap.cpp.

References ASSERT_, mrpt::utils::TCamera::dist, mrpt::utils::TCamera::focalLengthMeters, mrpt::utils::TCamera::intrinsicParams, mrpt::utils::TStereoCamera::leftCamera, m_alpha, m_camera_params, m_dat_mapx_left, m_dat_mapx_right, m_dat_mapy_left, m_dat_mapy_right, m_enable_both_centers_coincide, m_rectified_image_params, m_resize_output, m_resize_output_value, m_rot_left, m_rot_right, MRPT_END, MRPT_START, mrpt::utils::TCamera::ncols, mrpt::utils::TCamera::nrows, R, mrpt::utils::TStereoCamera::rightCamera, mrpt::utils::TStereoCamera::rightCameraPose, mrpt::poses::CPose3D::setRotationMatrix(), THROW_EXCEPTION, mrpt::utils::TPixelCoord::x, and mrpt::utils::TPixelCoord::y.

Referenced by mrpt::hwdrivers::CDUO3DCamera::open().

◆ setFromCamParams() [2/2]

void mrpt::vision::CStereoRectifyMap::setFromCamParams ( const mrpt::obs::CObservationStereoImages stereo_obs)
inline

A wrapper to setFromCamParams() which takes the parameters from an stereo observation object.

Definition at line 86 of file CStereoRectifyMap.h.

References mrpt::obs::CObservationStereoImages::getStereoCameraParams().

◆ setInterpolationMethod()

void mrpt::vision::CStereoRectifyMap::setInterpolationMethod ( const mrpt::utils::TInterpolationMethod  interp)
inline

Change remap interpolation method (default=Lineal).

This parameter can be safely changed at any instant without consequences.

Definition at line 129 of file CStereoRectifyMap.h.

◆ setRectifyMaps()

void CStereoRectifyMap::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.

Definition at line 446 of file CStereoRectifyMap.cpp.

References m_dat_mapx_left, m_dat_mapx_right, m_dat_mapy_left, and m_dat_mapy_right.

◆ setRectifyMapsFast()

void CStereoRectifyMap::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.

This method swaps the vectors so the inputs are no longer available.

Definition at line 461 of file CStereoRectifyMap.cpp.

References m_dat_mapx_left, m_dat_mapx_right, m_dat_mapy_left, and m_dat_mapy_right.

Member Data Documentation

◆ m_alpha

double mrpt::vision::CStereoRectifyMap::m_alpha
private

Definition at line 209 of file CStereoRectifyMap.h.

Referenced by setAlpha(), and setFromCamParams().

◆ m_cache1

mrpt::utils::CImage mrpt::vision::CStereoRectifyMap::m_cache1
mutableprivate

Definition at line 215 of file CStereoRectifyMap.h.

Referenced by rectify().

◆ m_cache2

mrpt::utils::CImage mrpt::vision::CStereoRectifyMap::m_cache2
mutableprivate

Memory caches for in-place rectification speed-up.

Definition at line 215 of file CStereoRectifyMap.h.

Referenced by rectify().

◆ m_camera_params

mrpt::utils::TStereoCamera mrpt::vision::CStereoRectifyMap::m_camera_params
private

A copy of the data provided by the user.

Definition at line 220 of file CStereoRectifyMap.h.

Referenced by rectify(), rectify_IPL(), and setFromCamParams().

◆ m_dat_mapx_left

std::vector<int16_t> mrpt::vision::CStereoRectifyMap::m_dat_mapx_left
private

◆ m_dat_mapx_right

std::vector<int16_t> mrpt::vision::CStereoRectifyMap::m_dat_mapx_right
private

◆ m_dat_mapy_left

std::vector<uint16_t> mrpt::vision::CStereoRectifyMap::m_dat_mapy_left
private

◆ m_dat_mapy_right

std::vector<uint16_t> mrpt::vision::CStereoRectifyMap::m_dat_mapy_right
private

◆ m_enable_both_centers_coincide

bool mrpt::vision::CStereoRectifyMap::m_enable_both_centers_coincide
private

Definition at line 211 of file CStereoRectifyMap.h.

Referenced by enableBothCentersCoincide(), and setFromCamParams().

◆ m_interpolation_method

mrpt::utils::TInterpolationMethod mrpt::vision::CStereoRectifyMap::m_interpolation_method
private

Definition at line 213 of file CStereoRectifyMap.h.

Referenced by rectify_IPL().

◆ m_rectified_image_params

mrpt::utils::TStereoCamera mrpt::vision::CStereoRectifyMap::m_rectified_image_params
private

◆ m_resize_output

bool mrpt::vision::CStereoRectifyMap::m_resize_output
private

Definition at line 210 of file CStereoRectifyMap.h.

Referenced by enableResizeOutput(), rectify(), rectify_IPL(), and setFromCamParams().

◆ m_resize_output_value

mrpt::utils::TImageSize mrpt::vision::CStereoRectifyMap::m_resize_output_value
private

Definition at line 212 of file CStereoRectifyMap.h.

Referenced by enableResizeOutput(), rectify(), rectify_IPL(), and setFromCamParams().

◆ m_rot_left

mrpt::poses::CPose3DQuat mrpt::vision::CStereoRectifyMap::m_rot_left
private

Definition at line 223 of file CStereoRectifyMap.h.

Referenced by rectify(), and setFromCamParams().

◆ m_rot_right

mrpt::poses::CPose3DQuat mrpt::vision::CStereoRectifyMap::m_rot_right
private

The rotation applied to the left/right camera so their virtual image plane is the same after rectification.

Definition at line 223 of file CStereoRectifyMap.h.

Referenced by setFromCamParams().




Page generated by Doxygen 1.8.14 for MRPT 1.5.6 Git: 4c65e8431 Tue Apr 24 08:18:17 2018 +0200 at lun oct 28 01:35:26 CET 2019