showReprojectionErrors

Visualize calibration errors

collapse all in page

Syntax

showReprojectionErrors(cameraParams)
showReprojectionErrors(cameraParams,viewStyle)
showReprojectionErrors(___,Name=Value)
ax = showReprojectionErrors(___)

Description

showReprojectionErrors(cameraParams) displays a bar graph that represents the calibration accuracy for a single camera, a stereo pair, a fisheye camera, or a multi-camera system. For non-multi-camera systems, the bar graph shows the mean reprojection error for each image. For multi-camera systems, the graph is divided into three sub-plots, displaying the mean reprojection error per image, per view, and per camera. A view represents a specific position where the calibration pattern is observed by the cameras. The cameraParams object contains one of:

example

showReprojectionErrors(cameraParams,viewStyle) displays the reprojection errors using the visualization style specified by the viewStyle input. The viewStyle argument is not supported for a multi-camera system.

example

showReprojectionErrors(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, HighlightIndex = [1,4] sets the highlight patterns to 1 and 4.

example

ax = showReprojectionErrors(___) returns the plot axis, using any of the preceding syntaxes.

example

Examples

collapse all

Open Live Script

Create a set of calibration images.

images = imageDatastore(fullfile(toolboxdir('vision'),'visiondata', ...
  'calibration','webcam'));
imageFileNames = images.Files(1:5);

Detect calibration pattern.

[imagePoints, boardSize] = detectCheckerboardPoints(imageFileNames);

Generate world coordinates of the corners of the squares. The square size is in millimeters.

squareSize = 25;
worldPoints = patternWorldPoints('checkerboard',boardSize,squareSize);

Calibrate the camera.

I = readimage(images,1); 
imageSize = [size(I, 1), size(I, 2)];
params = estimateCameraParameters(imagePoints,worldPoints, ...
                                  'ImageSize',imageSize);

Visualize the errors as a bar graph.

subplot(1,2,1);
showReprojectionErrors(params);

Figure contains an axes object. The axes object with title Mean Reprojection Error per Image, xlabel Images, ylabel Mean Error in Pixels contains 3 objects of type bar, line. This object represents Overall Mean Error: 0.25 pixels.

Visualize the errors as a scatter plot.

subplot(1,2,2);
showReprojectionErrors(params,'ScatterPlot');

Figure contains 2 axes objects. Axes object 1 with title Mean Reprojection Error per Image, xlabel Images, ylabel Mean Error in Pixels contains 3 objects of type bar, line. This object represents Overall Mean Error: 0.25 pixels. Axes object 2 with title Reprojection Errors in Pixels, xlabel X, ylabel Y contains 5 objects of type line. One or more of the lines displays its values using only markers These objects represent 1, 2, 3, 4, 5.

Open Live Script

Specify calibration images

imageDir = fullfile(toolboxdir('vision'),'visiondata', ...
    'calibration','stereo');
leftImages = imageDatastore(fullfile(imageDir,'left'));
rightImages = imageDatastore(fullfile(imageDir,'right'));

Detect the checkerboards.

[imagePoints, boardSize] = detectCheckerboardPoints(...
     leftImages.Files,rightImages.Files);

Specify world coordinates of checkerboard keypoints. The square size is in millimeters.

squareSize = 108; 
worldPoints = patternWorldPoints('checkerboard',boardSize,squareSize);

Calibrate the stereo camera system. Here both cameras have the same resolution.

I = readimage(leftImages,1); 
imageSize = [size(I, 1), size(I, 2)];
params = estimateCameraParameters(imagePoints,worldPoints, ...
                                  'ImageSize',imageSize);

Visualize calibration accuracy.

showReprojectionErrors(params);

Figure contains an axes object. The axes object with title Mean Reprojection Error per Image, xlabel Image Pairs, ylabel Mean Error in Pixels contains 5 objects of type bar, line. These objects represent Camera 1, Camera 2, Overall Mean Error: 0.06 pixels.

Open Live Script

Estimate the relative position and orientation of six cameras with overlapping fields of view by using calibration images that contain a single ChArUco board.

Download the calibration images.

calibImagesURL = "https://www.mathworks.com/supportfiles/vision/data/overlapping-cameras-charuco.zip";
calibImagesDir = fullfile(pwd,"overlapping-cameras-charuco");
calibImagesZip = fullfile(pwd,"overlapping-cameras-charuco.zip");
if ~exist(calibImagesZip,"file")
    disp("Downloading calibration images (52 MB)...")
    websave(calibImagesZip,calibImagesURL);
end
if ~exist(calibImagesDir,"dir")
    unzip(calibImagesZip,pwd)
end

Specify calibration image filenames for each camera.

numCameras = 6;
camDirPrefix = "Cam00";
imageFiles = cell(1,numCameras);
for i = 1:numCameras
    camDir = fullfile(calibImagesDir,camDirPrefix+i);
    imds = imageDatastore(camDir);
    imageFiles{i} = imds.Files;
end
imageFiles = [imageFiles{:}];

Define the ChArUco board properties. Specify checker size and marker size in centimeters.

markerFamily = "DICT_6X6_1000";
patternDims = [5 5];
markerSize = 6.8;   % in cm
checkerSize = 9.15; % in cm
numKeyPoints = prod(patternDims - 1);

Create a function handle for detectCharucoBoardPoints that specifies the non-zero minimum marker ID of the board.

minMarkerId = 144;
funcHandle = @(image) detectCharucoBoardPoints(image,patternDims, ...
    markerFamily,checkerSize,markerSize,MinMarkerID=minMarkerId);

Detect the key points of the ChArUco board in the calibration images.

imagePoints = detectPatternPoints(imageFiles,funcHandle,numKeyPoints);
[==================================================] 100%
Elapsed time: 00:00:04
Estimated time remaining: 00:00:00

Generate the world points for the pattern.

worldPoints = patternWorldPoints("charuco-board",patternDims,checkerSize);

Load the intrinsic parameters of the six cameras. These parameters have been estimated using the Using the Single Camera Calibrator App.

ld = load("sixCameraIntrinsics.mat");

Perform multi-camera calibration.

params = estimateMultiCameraParameters(imagePoints,worldPoints,ld.intrinsics,WorldUnits="cm");

Visualize the calibration accuracy.

figure(Position=[100,100,1000,400])
showReprojectionErrors(params)

Figure contains 3 axes objects. Axes object 1 with title Mean Reprojection Error per Image, xlabel View, ylabel Camera contains an object of type patch. Axes object 2 with title Mean Reprojection Error per View, xlabel View, ylabel Mean Error in Pixels contains 2 objects of type bar, line. This object represents Overall Mean Error: 0.37 pixels. Axes object 3 with title Mean Reprojection Error per Camera, xlabel Camera, ylabel Mean Error in Pixels contains 2 objects of type bar, line.

Visualize the camera extrinsic parameters.

figure
showExtrinsics(params)
view(2)

Figure contains an axes object. The axes object with title Extrinsic Parameters Visualization, xlabel X (cm), ylabel Z (cm) contains 56 objects of type patch, text, line.

Input Arguments

collapse all

Object containing parameters for a single, fisheye, stereo pair, or multi-camera system, specified as either a cameraParameters, fisheyeParameters, stereoParameters, multiCameraParameters object. You can create these objects using the:

You can also use the Camera Calibrator app to create the cameraParameters input object, or use Stereo Camera Calibrator app to create the stereoParameters input object. See Using the Single Camera Calibrator App and Using the Stereo Camera Calibrator App.

Plot view, specified as either "BarGraph" or "ScatterPlot". The viewStyle input sets the visualization for the camera extrinsic parameters. Set viewStyle to "BarGraph" to display the mean error per image as a bar graph. Set viewStyle to "ScatterPlot" to display the error for each point as a scatter plot. The "ScatterPlot" option applies only to the single camera case. This argument is not supported for a multi-camera system.

Name-Value Arguments

collapse all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: showReprojectionErrors(cameraParams,HighlightIndex = [1,4]), sets the highlight selection index to patterns 1 and 4.

Highlight selection index, specified as a scalar or a vector of integers. When you set the viewStyle to "BarGraph", the function highlights the bars corresponding to the selected images. When you set the viewStyle to "ScatterPlot", the function highlights the points corresponding to the selected images with circle markers. This argument is not supported for a multi-camera system.

Output axes, specified as the comma-separated pair consisting of 'Parent' and a scalar value. Specify output axes to display the visualization. You can obtain the current axes handle by returning the function to an output variable:

ax = showReprojectionErrors(cameraParams)

You can also use the gca function to get the current axes handle.

Example: showReprojectionErrors(cameraParams,'Parent',ax)

Output Arguments

collapse all

Current axes handle, returned as a scalar value. The function returns the handle to the current axes for the current figure.

Example: ax = showReprojectionErrors(cameraParams)

Version History

Introduced in R2014a

See Also

Apps

Functions

Objects

Topics