Function opencv::calib3d::stereo_calibrate

pub fn stereo_calibrate(
    object_points: &dyn ToInputArray, 
    image_points1: &dyn ToInputArray, 
    image_points2: &dyn ToInputArray, 
    camera_matrix1: &mut dyn ToInputOutputArray, 
    dist_coeffs1: &mut dyn ToInputOutputArray, 
    camera_matrix2: &mut dyn ToInputOutputArray, 
    dist_coeffs2: &mut dyn ToInputOutputArray, 
    image_size: Size, 
    r: &mut dyn ToOutputArray, 
    t: &mut dyn ToOutputArray, 
    e: &mut dyn ToOutputArray, 
    f: &mut dyn ToOutputArray, 
    flags: i32, 
    criteria: TermCriteria
) -> Result<f64>

Calibrates a stereo camera set up. This function finds the intrinsic parameters for each of the two cameras and the extrinsic parameters between the two cameras.

Parameters

• objectPoints: Vector of vectors of the calibration pattern points. The same structure as in @ref calibrateCamera. For each pattern view, both cameras need to see the same object points. Therefore, objectPoints.size(), imagePoints1.size(), and imagePoints2.size() need to be equal as well as objectPoints[i].size(), imagePoints1[i].size(), and imagePoints2[i].size() need to be equal for each i.
• imagePoints1: Vector of vectors of the projections of the calibration pattern points, observed by the first camera. The same structure as in @ref calibrateCamera.
• imagePoints2: Vector of vectors of the projections of the calibration pattern points, observed by the second camera. The same structure as in @ref calibrateCamera.
• cameraMatrix1: Input/output camera intrinsic matrix for the first camera, the same as in @ref calibrateCamera. Furthermore, for the stereo case, additional flags may be used, see below.
• distCoeffs1: Input/output vector of distortion coefficients, the same as in @ref calibrateCamera.
• cameraMatrix2: Input/output second camera intrinsic matrix for the second camera. See description for cameraMatrix1.
• distCoeffs2: Input/output lens distortion coefficients for the second camera. See description for distCoeffs1.
• imageSize: Size of the image used only to initialize the camera intrinsic matrices.
• R: Output rotation matrix. Together with the translation vector T, this matrix brings points given in the first camera's coordinate system to points in the second camera's coordinate system. In more technical terms, the tuple of R and T performs a change of basis from the first camera's coordinate system to the second camera's coordinate system. Due to its duality, this tuple is equivalent to the position of the first camera with respect to the second camera coordinate system.
• T: Output translation vector, see description above.
• E: Output essential matrix.
• F: Output fundamental matrix.
• perViewErrors: Output vector of the RMS re-projection error estimated for each pattern view.
• flags: Different flags that may be zero or a combination of the following values:
• @ref CALIB_FIX_INTRINSIC Fix cameraMatrix? and distCoeffs? so that only R, T, E, and F matrices are estimated.
• @ref CALIB_USE_INTRINSIC_GUESS Optimize some or all of the intrinsic parameters according to the specified flags. Initial values are provided by the user.
• @ref CALIB_USE_EXTRINSIC_GUESS R and T contain valid initial values that are optimized further. Otherwise R and T are initialized to the median value of the pattern views (each dimension separately).
• @ref CALIB_FIX_PRINCIPAL_POINT Fix the principal points during the optimization.
• @ref CALIB_FIX_FOCAL_LENGTH Fix and .
• @ref CALIB_FIX_ASPECT_RATIO Optimize . Fix the ratio .
• @ref CALIB_SAME_FOCAL_LENGTH Enforce and .
• @ref CALIB_ZERO_TANGENT_DIST Set tangential distortion coefficients for each camera to zeros and fix there.
• @ref CALIB_FIX_K1,..., @ref CALIB_FIX_K6 Do not change the corresponding radial distortion coefficient during the optimization. If @ref CALIB_USE_INTRINSIC_GUESS is set, the coefficient from the supplied distCoeffs matrix is used. Otherwise, it is set to 0.
• @ref CALIB_RATIONAL_MODEL Enable coefficients k4, k5, and k6. To provide the backward compatibility, this extra flag should be explicitly specified to make the calibration function use the rational model and return 8 coefficients. If the flag is not set, the function computes and returns only 5 distortion coefficients.
• @ref CALIB_THIN_PRISM_MODEL Coefficients s1, s2, s3 and s4 are enabled. To provide the backward compatibility, this extra flag should be explicitly specified to make the calibration function use the thin prism model and return 12 coefficients. If the flag is not set, the function computes and returns only 5 distortion coefficients.
• @ref CALIB_FIX_S1_S2_S3_S4 The thin prism distortion coefficients are not changed during the optimization. If @ref CALIB_USE_INTRINSIC_GUESS is set, the coefficient from the supplied distCoeffs matrix is used. Otherwise, it is set to 0.
• @ref CALIB_TILTED_MODEL Coefficients tauX and tauY are enabled. To provide the backward compatibility, this extra flag should be explicitly specified to make the calibration function use the tilted sensor model and return 14 coefficients. If the flag is not set, the function computes and returns only 5 distortion coefficients.
• @ref CALIB_FIX_TAUX_TAUY The coefficients of the tilted sensor model are not changed during the optimization. If @ref CALIB_USE_INTRINSIC_GUESS is set, the coefficient from the supplied distCoeffs matrix is used. Otherwise, it is set to 0.
• criteria: Termination criteria for the iterative optimization algorithm.

The function estimates the transformation between two cameras making a stereo pair. If one computes the poses of an object relative to the first camera and to the second camera, ( , ) and (,), respectively, for a stereo camera where the relative position and orientation between the two cameras are fixed, then those poses definitely relate to each other. This means, if the relative position and orientation (,) of the two cameras is known, it is possible to compute (,) when (,) is given. This is what the described function does. It computes (,) such that:

Therefore, one can compute the coordinate representation of a 3D point for the second camera's coordinate system when given the point's coordinate representation in the first camera's coordinate system:

Optionally, it computes the essential matrix E:

where are components of the translation vector : . And the function can also compute the fundamental matrix F:

Besides the stereo-related information, the function can also perform a full calibration of each of the two cameras. However, due to the high dimensionality of the parameter space and noise in the input data, the function can diverge from the correct solution. If the intrinsic parameters can be estimated with high accuracy for each of the cameras individually (for example, using calibrateCamera ), you are recommended to do so and then pass @ref CALIB_FIX_INTRINSIC flag to the function along with the computed intrinsic parameters. Otherwise, if all the parameters are estimated at once, it makes sense to restrict some parameters, for example, pass @ref CALIB_SAME_FOCAL_LENGTH and @ref CALIB_ZERO_TANGENT_DIST flags, which is usually a reasonable assumption.

Similarly to calibrateCamera, the function minimizes the total re-projection error for all the points in all the available views from both cameras. The function returns the final value of the re-projection error.

Overloaded parameters

C++ default parameters

• flags: CALIB_FIX_INTRINSIC
• criteria: TermCriteria(TermCriteria::COUNT+TermCriteria::EPS,30,1e-6)