class mrpt::vision::CStereoRectifyMap

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::CObservationStereoImages::Ptr 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: https://www.mrpt.org/Rectifying_stereo_images

This class provides a uniform wrap over different OpenCV versions. The “alpha” parameter is ignored if built against OpenCV 2.0.X

See also:

CUndistortMap, mrpt::obs::CObservationStereoImages, mrpt::img::TCamera, the application camera-calib for calibrating a camera.

#include <mrpt/vision/CStereoRectifyMap.h>

class CStereoRectifyMap
{
public:
    // construction

    CStereoRectifyMap();

    //
methods

    bool isSet() const;
    void setFromCamParams(const mrpt::img::TStereoCamera& params);
    void setFromCamParams(const mrpt::obs::CObservationStereoImages& stereo_obs);
    const mrpt::img::TStereoCamera& getCameraParams() const;
    const mrpt::img::TStereoCamera& getRectifiedImageParams() const;
    const mrpt::img::TCamera& getRectifiedLeftImageParams() const;
    const mrpt::img::TCamera& getRectifiedRightImageParams() const;
    void setAlpha(double alpha);
    double getAlpha() const;

    void enableResizeOutput(
        bool enable,
        unsigned int target_width = 0,
        unsigned int target_height = 0
        );

    bool isEnabledResizeOutput() const;
    mrpt::img::TImageSize getResizeOutputSize() const;
    void setInterpolationMethod(const mrpt::img::TInterpolationMethod interp);
    mrpt::img::TInterpolationMethod getInterpolationMethod() const;
    void enableBothCentersCoincide(bool enable = true);
    bool isEnabledBothCentersCoincide() const;
    const mrpt::poses::CPose3DQuat& getLeftCameraRot() const;
    const mrpt::poses::CPose3DQuat& getRightCameraRot() const;

    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
        );

    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
        );

    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;

    void rectify(mrpt::obs::CObservationStereoImages& stereo_image_observation, const bool use_internal_mem_cache = true) const;
};

Methods

bool isSet() const

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.

void setFromCamParams(const mrpt::img::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. Must be called before invoking undistort().

See also:

setAlpha()

void setFromCamParams(const mrpt::obs::CObservationStereoImages& stereo_obs)

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

const mrpt::img::TStereoCamera& getCameraParams() const

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

const mrpt::img::TStereoCamera& getRectifiedImageParams() const

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

Parameters:

std::exception

If the rectification maps have not been computed.

 
const mrpt::img::TCamera& getRectifiedLeftImageParams() const

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

const mrpt::img::TCamera& getRectifiedRightImageParams() const

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

void 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. Call this method before building the rectification maps, otherwise they’ll be marked as invalid.

double getAlpha() const

Return the alpha parameter.

See also:

setAlpha

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.

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

bool isEnabledResizeOutput() const

Returns whether resizing is enabled (default=false)

See also:

enableResizeOutput

mrpt::img::TImageSize getResizeOutputSize() const

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

See also:

enableResizeOutput

void setInterpolationMethod(const mrpt::img::TInterpolationMethod interp)

Change remap interpolation method (default=Lineal).

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

mrpt::img::TInterpolationMethod getInterpolationMethod() const

Get the currently selected interpolation method.

See also:

setInterpolationMethod

void enableBothCentersCoincide(bool enable = true)

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

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

bool isEnabledBothCentersCoincide() const

See also:

enableBothCentersCoincide

const mrpt::poses::CPose3DQuat& getLeftCameraRot() 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.

const mrpt::poses::CPose3DQuat& getRightCameraRot() const

See getLeftCameraRot()

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.

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.

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

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() 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. 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)

Parameters:

std::exception

If the rectification maps have not been computed.

 
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.

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. 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).