Main Content


Refine 3-D points using structure-only bundle adjustment



xyzRefinedPoints = bundleAdjustmentStructure(xyzPoints,pointTracks,cameraPoses,intrinsics) returns the refined 3-D points that minimize reprojection errors.

The structure-only refinement procedure is a special case of bundle adjustment with camera poses fixed during optimization. The 3-D points and the camera poses are placed in the same world coordinate system.

[xyzRefinedPoints,reprojectionErrors] = bundleAdjustmentStructure(___) additionally returns an N-element vector containing the mean reprojection error for each 3-D world point using the arguments from the previous syntax.

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


collapse all

Load data for initialization.

data = load('sfmGlobe');

Refine the 3-D world points.

xyzRefinedPoints = bundleAdjustmentStructure(data.xyzPoints,data.pointTracks,data.cameraPoses,data.intrinsics);

Display the refined 3-D world points.


Display the cameras.

hold on
hold off
grid on

Figure contains an axes object. The axes object contains 51 objects of type line, text, patch, scatter.

Input Arguments

collapse all

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

Data Types: single | double

Matched points across multiple images, specified as an N-element array of pointTracks objects.

Camera poses, specified as a table containing two columns for 'ViewId' and 'AbsolutePose'. You can get the cameraPoses table using the imageviewset poses object function.

Camera intrinsics, specified as a scalar or an N-element array of cameraIntrinsics objects, where N is the height of the cameraPoses table. Use a scalar when images are captured using the same camera. Use the N-element array when images are captured using different cameras.

Name-Value 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.

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

Reprojection errors, returned as an M-elment 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. Volume 36, Issue 1. March 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: Theory and Practice. Pages 298 — 372. Springer-Verlag. 1999.

Introduced in R2020a