showExtrinsics

Visualize extrinsic camera parameters

Syntax

showExtrinsics(cameraParams)

showExtrinsics(cameraParams,viewStyle)

showExtrinsics(___,Name=Value)

ax = showExtrinsics(___)

Description

showExtrinsics(cameraParams) renders a 3-D visualization of extrinsic parameters of a single calibrated camera, a calibrated stereo pair, or multiple calibrated cameras. The function plots a 3-D view of the calibration patterns with respect to the camera. The cameraParams input contains one of:

• cameraParameters or stereoParameters object which the estimateCameraParameters function returns.

• fisheyeParameters or object which the estimateFisheyeParameters function returns.

• multiCameraParameters object which the estimateMultiCameraParameters function returns.

The showExtrinsics function shows the 3-D view of the calibration pattern as a convex polygon containing all the detected keypoints of the pattern in the original calibration image.

showExtrinsics(cameraParams,viewStyle) displays visualization of the camera extrinsic parameters using the style specified by the viewStyle input.

showExtrinsics(___,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.

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

Examples

Visualize Single Camera Extrinsic Parameters

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.

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

Calibrate the camera.

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

Visualize pattern locations.

figure
showExtrinsics(cameraParams);

Visualize camera locations.

figure
showExtrinsics(cameraParams,'patternCentric');

Visualize Stereo Pair of Camera Extrinsic Parameters

Specify calibration images.

imageDir = fullfile(toolboxdir('vision'),'visiondata',...
        'calibration','circleGrid','stereo');
leftImages = imageDatastore(fullfile(imageDir,'left'));
rightImages = imageDatastore(fullfile(imageDir,'right'));
leftImageFileNames = leftImages.Files(2:2:10);
rightImageFileNames = rightImages.Files(2:2:10);

Define the circle grid pattern dimensions, and detect the pattern in the images.

patternDims = [4 11];
imagePoints = detectCircleGridPoints(leftImageFileNames,...
        rightImageFileNames,patternDims);

Specify the world coordinates for the circle grid keypoints. Center distance is in millimeters.

centerDistance = 36.5;
worldPoints = patternWorldPoints('circle-grid-asymmetric',patternDims,centerDistance);

Calibrate the stereo camera system. Both cameras have the same resolution.

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

Visualize pattern locations.

figure
showExtrinsics(cameraParams)

Visualize camera locations.

figure
showExtrinsics(cameraParams,'patternCentric')

Calibrate Multi-Camera System

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)

Visualize the camera extrinsic parameters.

figure
showExtrinsics(params)
view(2)

Input Arguments

cameraParams — Object containing parameters of single camera or stereo pair

cameraParameters object | fisheyeParameters object | stereoParameters object | multiCameraParameters object

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:

• estimateCameraParameters function to return a cameraParameters or stereoParameters object.

• estimateFisheyeParameters function to return a fisheyeParameters object.

• estimateMultiCameraParameters function to return a multiCameraParameters object.

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.

viewStyle — Camera- or pattern-centric view

"CameraCentric" | "PatternCentric"

Camera or pattern-centric view, specified as "CameraCentric" or "PatternCentric". The viewStyle input sets the visualization for the camera extrinsic parameters. If you keep your camera stationary while moving the calibration pattern, set viewStyle to "CameraCentric". If the pattern is stationary while you move your camera, set it to "PatternCentric".

Name-Value Arguments

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: showExtrinsics(cameraParams,HighlightIndex = [1,4]), sets the highlight selection index to patterns 1 and 4.

HighlightIndex — Highlight selection index

[] (default) | vector | scalar

Highlight selection index, specified as a scalar or a vector of integers. When you specify this index, the opacity of that particular pattern is increased, making it stand out in contrast to the other patterns.

CameraIndex — Camera selection index

[] (default) | vector | scalar

Camera selection index, specified as a scalar or a vector of integers. This argument applies only when the cameraParams is a multiCameraParameters object. When CameraIndex is empty, all cameras are displayed.

Parent — Output axes

current axes (default)

Output axes, specified as an axes. You can obtain the current axes handle by returning the function to an output variable:

ax = showExtrinsics(cameraParams)

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

Output Arguments

ax — Current axes handle

scalar value

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

Example: ax = showExtrinsics(cameraParams)

Version History

Introduced in R2014a