Main Content

detectCheckerboardPoints

Detect checkerboard pattern in image

collapse all in page

Syntax

[imagePoints,boardSize] = detectCheckerboardPoints(I)
[imagePoints,boardSize,imagesUsed] = detectCheckerboardPoints(imageFileNames)
[imagePoints,boardSize,imagesUsed] = detectCheckerboardPoints(images)
[imagePoints,boardSize,pairsUsed] = detectCheckerboardPoints(imageFileNames1,imageFileNames2)
[imagePoints,boardSize,pairsUsed] = detectCheckerboardPoints(images1,images2)
[imagePoints,boardSize,pairsUsed] = detectCheckerboardPoints(___,Name,Value)

Description

example

[imagePoints,boardSize] = detectCheckerboardPoints(I) detects a black and white checkerboard of size greater than 4-by-4 squares in a 2-D truecolor or grayscale image. The function returns the detected points and dimensions of the checkerboard.

[imagePoints,boardSize,imagesUsed] = detectCheckerboardPoints(imageFileNames) detects a checkerboard pattern in a set of input images, provided as an array of file names.

[imagePoints,boardSize,imagesUsed] = detectCheckerboardPoints(images) detects a checkerboard pattern in a set of input images, provided as an array of grayscale or truecolor images.

[imagePoints,boardSize,pairsUsed] = detectCheckerboardPoints(imageFileNames1,imageFileNames2) detects a checkerboard pattern in stereo pairs of images, provided as cell arrays of file names.

[imagePoints,boardSize,pairsUsed] = detectCheckerboardPoints(images1,images2) detects a checkerboard pattern in stereo pairs of images, provided as arrays of grayscale or truecolor images.

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

Examples

collapse all

Open Live Script

Create an imageDatastore containing calibration images from a GoPro camera.

imds = imageDatastore(fullfile(toolboxdir('vision'),'visiondata','calibration','gopro'));

Detect calibration pattern using the 'HighDistortion' option, which is good to use with fisheye lens images.

[imagePoints,boardSize,imagesUsed] = detectCheckerboardPoints(imds.Files(1:4),'HighDistortion',true);

Display detected points.

for i = 1:4
  % Read image
  I = readimage(imds, i);

  % Insert markers at detected point locations
  I = insertMarker(I, imagePoints(:,:,i), 'o', 'Color', 'red', 'Size', 10);

  % Display image
  subplot(2, 2, i);
  imshow(I);
end

Figure contains 4 axes objects. Axes object 1 contains an object of type image. Axes object 2 contains an object of type image. Axes object 3 contains an object of type image. Axes object 4 contains an object of type image.

Open Live Script

Load an image containing a checkerboard pattern.

imageFileName = fullfile(toolboxdir('vision'),'visiondata','calibration','webcam','image4.tif');
I = imread(imageFileName);

Detect the checkerboard points.

[imagePoints,boardSize] = detectCheckerboardPoints(I);

Display detected points.

J = insertText(I,imagePoints,1:size(imagePoints,1));
J = insertMarker(J,imagePoints,'o','Color','red','Size',5);
imshow(J);
title(sprintf('Detected a %d x %d Checkerboard',boardSize));

Figure contains an axes object. The axes object with title Detected a 7 x 10 Checkerboard contains an object of type image.

Open Live Script

Create a cell array of file names of calibration images.

for i = 1:5
  imageFileName = sprintf('image%d.tif', i);
  imageFileNames{i} = fullfile(matlabroot,'toolbox','vision',...
       'visiondata','calibration','webcam',imageFileName);
end

Detect calibration pattern in the images.

[imagePoints,boardSize,imagesUsed] = detectCheckerboardPoints(imageFileNames, 'PartialDetections', false);

Display the detected points.

imageFileNames = imageFileNames(imagesUsed);
for i = 1:numel(imageFileNames)
  I = imread(imageFileNames{i});
  subplot(2, 2, i);
  imshow(I);
  hold on;
  plot(imagePoints(:,1,i),imagePoints(:,2,i),'ro');
end

Open Live Script

Read in stereo images.

numImages = 4;
images1 = cell(1, numImages);
images2 = cell(1, numImages);
for i = 1:numImages
    images1{i} = fullfile(matlabroot,'toolbox','vision',...
        'visiondata','calibration','stereo','left',sprintf('left%02d.png',i));
    images2{i} = fullfile(matlabroot,'toolbox','vision',...
        'visiondata','calibration','stereo','right',sprintf('right%02d.png',i));
end

Detect the checkerboards in the images.

[imagePoints,boardSize,pairsUsed] = ...
    detectCheckerboardPoints(images1,images2);

Display points from images1.

images1 = images1(pairsUsed);
figure;
for i = 1:numel(images1)
      I = imread(images1{i});
      subplot(2,2,i);
      imshow(I); 
      hold on; 
      plot(imagePoints(:,1,i,1),imagePoints(:,2,i,1),'ro');
end 
annotation('textbox',[0 0.9 1 0.1],'String','Camera 1',...
    'EdgeColor','none','HorizontalAlignment','center')

Figure contains 4 axes objects. Axes object 1 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Axes object 2 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Axes object 3 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Axes object 4 contains 2 objects of type image, line. One or more of the lines displays its values using only markers

Display points from images2.

images2 = images2(pairsUsed);
figure;
for i = 1:numel(images2)
      I = imread(images2{i});
      subplot(2, 2, i);
      imshow(I);
      hold on; 
      plot(imagePoints(:,1,i,2),imagePoints(:,2,i,2),'ro');
end 
annotation('textbox',[0 0.9 1 0.1],'String','Camera 2',...
    'EdgeColor','none','HorizontalAlignment','center')

Figure contains 4 axes objects. Axes object 1 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Axes object 2 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Axes object 3 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Axes object 4 contains 2 objects of type image, line. One or more of the lines displays its values using only markers

Input Arguments

collapse all

Input image, specified as either an M-by-N-by-3 truecolor or M-by-N 2-D grayscale. The input image must be real and nonsparse. The function can detect checkerboards with a minimum size of 4-by-4 squares.

Data Types: single | double | int16 | uint8 | uint16 | logical

Image file names, specified as an N-element cell array of N file names.

File names for camera 1 images, specified as an N-element cell array of N file names. The images contained in this array must be in the same order as images contained in imageFileNames2, forming stereo pairs.

File names for camera 2 images, specified as an N-element cell array of N file names. The images contained in this array must be in the same order as images contained in imageFileNames1, forming stereo pairs.

Images, specified as an H-by-W-by-B-by-F array containing a set of grayscale or truecolor images. The input dimensions are:

H represents the image height.
W represents the image width.
B represents the color channel. A value of 1 indicates a grayscale image, and a value of 3 indicates a truecolor image.
F represents the number of image frames.

Stereo pair images from camera 1, specified as an H-by-W-by-B-by-F array containing a set of grayscale or truecolor images. The input dimensions are:

H represents the image height.
W represents the image width.
B represents the color channel. A value of 1 indicates a grayscale image, and a value of 3 indicates a truecolor image.
F represents the number of image frames.

Stereo pair images from camera 2, specified as an H-by-W-by-B-by-F array containing a set of grayscale or truecolor images. The input dimensions are:

H represents the image height.
W represents the image width.
B represents the color channel. A value of 1 indicates a grayscale image, and a value of 3 indicates a truecolor image.
F represents the number of image frames.

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'MinCornerMetric', '0.15'

Minimum corner metric threshold, specified as a nonnegative scalar. When the image is noisy or highly textured, increase this value to reduce the number of false corner detections. When you set the 'HighDistortion' property to false the function sets the default value to 0.15. When you set the 'HighDistortion' property to true the function sets the default value to 0.12. Decreasing the value results in an increase of corner detections.

High distortion, specified as false or true. Set 'HighDistortion' to true when the images contain a high level of distortion, which is typical of a wide field of view camera, such as a fisheye camera. Set 'HighDistortion' to false when the images do not contain a high level of distortion. Setting 'HighDistortion' to true can increase the resiliency to image distortion but decreases the processing speed.

Partial detections, specified as true or false. Set 'PartialDetections' to true to return partially detected checkerboards. The function fills missing keypoint detections with [NaN,NaN] coordinates. Set 'PartialDetections' to false to discard partially detected checkerboards. This property is ignored for stereo image pairs.

Output Arguments

collapse all

Detected checkerboard corner coordinates, returned as an M-by-2 matrix for one image. For multiple images, points are returned as an M-by-2-by-number of images array, and for stereo pairs of images, the function returns points as an M-by-2-by-number of pairs-by-number of cameras array.

For stereo pairs, imagePoints(:,:,:,1) are the points from the first set of images, and imagePoints(:,:,:,2) are the points from the second set of images. The output contains M number of [x y] coordinates. Each coordinate represents a point where square corners are detected on the checkerboard. The number of points the function returns depends on the value of boardSize, which indicates the number of squares detected. The function detects the points with sub-pixel accuracy.

The function calculates the number of points, M, as follows:

M = prod(boardSize-1).

If the checkerboard cannot be detected:
imagePoints = []
boardSize = [0,0]

When you specify the imageFileNames input, the function can return imagePoints as an M-by-2-by-N array. In this array, N represents the number of images in which a checkerboard is detected. If a checkerboard cannot be detected, the function sets imagePoints to [].

For single camera images only:

  • If the complete checkerboard cannot be detected, the function returns a partially detected checkerboard with [NaN,NaN] as the x-y coordinates for missing corners in imagePoints. This default behavior can be modified using the 'PartialDetections' name-value argument.

  • When possible, the function orients the partially detected checkerboard such that the location of the origin and the arrangement of the corners is consistent with the completely visible checkerboard. If the function cannot detect a complete checkerboard in any of the input images, the largest detected checkerboard is used as the reference checkerboard.

Checkerboard dimensions, returned as a 2-element [height, width] vector. The dimensions of the checkerboard are expressed in terms of the number of squares.

If a checkerboard cannot be detected, the function sets boardSize to [0,0].

Pattern detection flag, returned as an N-by-1 logical vector of N logicals. The function outputs the same number of logicals as there are input images. A true value indicates that the pattern was detected in the corresponding image. A false value indicates that the function did not detect a pattern.

Stereo pair pattern detection flag, returned as an N-by-1 logical vector of N logicals. The function outputs the same number of logicals as there are input images. A true value indicates that the pattern is detected in the corresponding stereo image pair. A false value indicates that the function does not detect a pattern.

For stereo pair pattern detection, the checkerboard needs to be fully visible in both images for it to be detected. Unlike single camera calibration, partially detected checkerboards are rejected for stereo image pairs.

References

[1] Geiger, A., F. Moosmann, O. Car, and B. Schuster. "Automatic Camera and Range Sensor Calibration using a Single Shot," International Conference on Robotics and Automation (ICRA), St. Paul, USA, May 2012.

Extended Capabilities

Version History

Introduced in R2014a

See Also

| | | |

Topics