Refine camera poses and 3-D points


[xyzRefinedPoints,refinedPoses] = bundleAdjustment(xyzPoints,pointTracks,cameraPoses,cameraParams)
[___,reprojectionErrors] = bundleAdjustment(___)
[___] = bundleAdjustment(___,Name,Value)



[xyzRefinedPoints,refinedPoses] = bundleAdjustment(xyzPoints,pointTracks,cameraPoses,cameraParams) returns the refined 3-D points and camera poses that minimize reprojection errors. The refinement procedure is a variant of the Levenberg-Marquardt algorithm.

[___,reprojectionErrors] = bundleAdjustment(___) additionally returns reprojection errors for each 3-D world point using the arguments from the previous syntax.

[___] = bundleAdjustment(___,Name,Value) uses additional options specified by one or more Name,Value pair arguments. Unspecified properties have default values.

Code Generation Support:
Supports Code Generation: No
Supports MATLAB Function block: No
Code Generation Support, Usage Notes, and Limitations


collapse all

Load data for initialization.


Refine the camera poses and points.

[xyzRefinedPoints,refinedPoses] = ...

Display the refined camera poses and 3-D world points.

cameraSize = 0.1;
for j = 1:height(refinedPoses)
    id = refinedPoses.ViewId(j);
    loc = refinedPoses.Location{j};
    orient = refinedPoses.Orientation{j};
    hold on
grid on

Input Arguments

collapse all

Unrefined 3-D points, specified as an M-by-3 matrix of [x,y,z] locations.

Matching points across multiple images, specified as an N-element array of pointTrack objects. Each element contains two or more matching points across multiple images.

Camera pose ViewId, Orientation, and Location information, specified as a three-column table. The view IDs relate to the IDs in the pointTracks object. The orientations are specified as 3-by-3 rotation matrices. The locations are specified as a three-element vectors.

Camera parameters, specified as a cameraParameters or cameraIntrinsics object. You can return the cameraParameters object using the estimateCameraParameters function. The cameraParameters object contains the intrinsic, extrinsic, and lens distortion parameters of a camera.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'MaxIterations', '50'

Maximum number of iterations before the Levenberg-Marquardt algorithm stops, specified as the comma-separated pair consisting of 'MaxIterations' and a positive integer.

Absolute termination tolerance of the mean squared reprojection error in pixels, specified as the comma-separated pair consisting of 'AbsoluteTolerance' and a positive scalar.

Relative termination tolerance of the reduction in reprojection error between iterations, specified as the comma-separated pair consisting of 'RelativeTolerance' and a positive scalar.

Flag to indicate lens distortion, specified as the comma-separated pair consisting of 'PointsUndistorted' and either false or true. When you set PointsUndistorted to false, the 2-D points in pointTracks must be from images with lens distortion. To use undistorted points, use the undistortImage function first, then set PointsUndistorted to true.

View IDs for fixed camera pose, specified as the comma-separated pair consisting of 'FixedViewIDs' and a vector of nonnegative integers. Each ID corresponds to the ViewId of a fixed camera pose in cameraPoses. An empty value for FixedViewIDs means that all camera poses are optimized.

Display progress information, specified as the comma-separated pair consisting of 'Verbose' and either false or true.

Output Arguments

collapse all

3-D locations of refined world points, returned as an M-by-3 matrix of [x,y, z] locations.

Data Types: single | double

Refined camera poses, returned as a table. The table contains three columns for 'ViewId', 'Orientation', and 'Location'.

Reprojection errors, returned as an M-by-1 vector. The function projects each world point back into each camera. Then in each image, the function calculates the reprojection error as the distance between the detected and the reprojected point. The reprojectionErrors vector contains the average reprojection error for each world point.


[1] Lourakis, M.I.A., and A.A. Argyros. "SBA: A Software Package for Generic Sparse Bundle Adjustment." ACM Transactions on Mathematical Software. 2009.

[2] Hartley, R., and A. Zisserman. Multiple View Geometry in Computer Vision. Cambridge University Press, 2003.

[3] Triggs, B., P. McLauchlan, R. Hartley, and A. Fitzgibbon. "Bundle Adjustment: A Modern Synthesis." Proceedings of the International Workshop on Vision Algorithms. Springer-Verlag. 1999, pp. 298-372.

Introduced in R2016a