Function opencv::calib3d::stereo_rectify_camera

pub fn stereo_rectify_camera(
    camera_matrix1: &dyn ToInputArray, 
    dist_coeffs1: &dyn ToInputArray, 
    camera_matrix2: &dyn ToInputArray, 
    dist_coeffs2: &dyn ToInputArray, 
    image_size: Size, 
    r: &dyn ToInputArray, 
    t: &dyn ToInputArray, 
    r1: &mut dyn ToOutputArray, 
    r2: &mut dyn ToOutputArray, 
    p1: &mut dyn ToOutputArray, 
    p2: &mut dyn ToOutputArray, 
    q: &mut dyn ToOutputArray, 
    flags: i32, 
    alpha: f64, 
    new_image_size: Size, 
    valid_pix_roi1: &mut Rect, 
    valid_pix_roi2: &mut Rect
) -> Result<()>

Computes rectification transforms for each head of a calibrated stereo camera.

Parameters

• cameraMatrix1: First camera matrix.
• distCoeffs1: First camera distortion parameters.
• cameraMatrix2: Second camera matrix.
• distCoeffs2: Second camera distortion parameters.
• imageSize: Size of the image used for stereo calibration.
• R: Rotation matrix between the coordinate systems of the first and the second cameras.
• T: Translation vector between coordinate systems of the cameras.
• R1: Output 3x3 rectification transform (rotation matrix) for the first camera.
• R2: Output 3x3 rectification transform (rotation matrix) for the second camera.
• P1: Output 3x4 projection matrix in the new (rectified) coordinate systems for the first camera.
• P2: Output 3x4 projection matrix in the new (rectified) coordinate systems for the second camera.
• Q: Output disparity-to-depth mapping matrix (see reprojectImageTo3D ).
• flags: Operation flags that may be zero or CALIB_ZERO_DISPARITY . If the flag is set, the function makes the principal points of each camera have the same pixel coordinates in the rectified views. And if the flag is not set, the function may still shift the images in the horizontal or vertical direction (depending on the orientation of epipolar lines) to maximize the useful image area.
• alpha: Free scaling parameter. If it is -1 or absent, the function performs the default scaling. Otherwise, the parameter should be between 0 and 1. alpha=0 means that the rectified images are zoomed and shifted so that only valid pixels are visible (no black areas after rectification). alpha=1 means that the rectified image is decimated and shifted so that all the pixels from the original images from the cameras are retained in the rectified images (no source image pixels are lost). Obviously, any intermediate value yields an intermediate result between those two extreme cases.
• newImageSize: New image resolution after rectification. The same size should be passed to initUndistortRectifyMap (see the stereo_calib.cpp sample in OpenCV samples directory). When (0,0) is passed (default), it is set to the original imageSize . Setting it to larger value can help you preserve details in the original image, especially when there is a big radial distortion.
• validPixROI1: Optional output rectangles inside the rectified images where all the pixels are valid. If alpha=0 , the ROIs cover the whole images. Otherwise, they are likely to be smaller (see the picture below).
• validPixROI2: Optional output rectangles inside the rectified images where all the pixels are valid. If alpha=0 , the ROIs cover the whole images. Otherwise, they are likely to be smaller (see the picture below).

The function computes the rotation matrices for each camera that (virtually) make both camera image planes the same plane. Consequently, this makes all the epipolar lines parallel and thus simplifies the dense stereo correspondence problem. The function takes the matrices computed by stereoCalibrate as input. As output, it provides two rotation matrices and also two projection matrices in the new coordinates. The function distinguishes the following two cases:

• Horizontal stereo: the first and the second camera views are shifted relative to each other mainly along the x axis (with possible small vertical shift). In the rectified images, the corresponding epipolar lines in the left and right cameras are horizontal and have the same y-coordinate. P1 and P2 look like:

where is a horizontal shift between the cameras and if CALIB_ZERO_DISPARITY is set.

• Vertical stereo: the first and the second camera views are shifted relative to each other mainly in vertical direction (and probably a bit in the horizontal direction too). The epipolar lines in the rectified images are vertical and have the same x-coordinate. P1 and P2 look like:

where is a vertical shift between the cameras and if CALIB_ZERO_DISPARITY is set.

As you can see, the first three columns of P1 and P2 will effectively be the new "rectified" camera matrices. The matrices, together with R1 and R2 , can then be passed to initUndistortRectifyMap to initialize the rectification map for each camera.

See below the screenshot from the stereo_calib.cpp sample. Some red horizontal lines pass through the corresponding image regions. This means that the images are well rectified, which is what most stereo correspondence algorithms rely on. The green rectangles are roi1 and roi2 . You see that their interiors are all valid pixels.

C++ default parameters

• flags: CALIB_ZERO_DISPARITY
• alpha: -1
• new_image_size: Size()
• valid_pix_roi1: 0
• valid_pix_roi2: 0