detectCheckerboardPoints

Detect checkerboard pattern in image

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

Single Image Checkerboard Detection

[imagePoints,boardSize] = detectCheckerboardPoints(I) detects the keypoints of a checkerboard calibration pattern in a single image, a set of images, or stereo image pairs. The function returns the detected points imagePoints, and dimensions of the checkerboard boardSize.

[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.

Stereo Pair Checkerboard Detection

[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.

Optional Arguments

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

Examples

Detect Checkerboard in Images with High Distortion

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', 'MarkerColor', 'red', 'Size', 10);

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

Detect Checkerboard in Image

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','MarkerColor','red','Size',5);
imshow(J);
title(sprintf('Detected a %d x %d Checkerboard',boardSize));

Detect Checkerboard in a Set of Image Files

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

Detect Checkerboard in Stereo Images

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')

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')

Input Arguments

I — Input image

M-by-N-by-3 truecolor image | M-by-N 2-D grayscale image

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

imageFileNames — Image file names

N-element cell array of character vectors | N-element array of strings

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

imageFileNames1 — File names for camera 1 images

N-element cell array of character vectors | N-element array of strings

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.

imageFileNames2 — File names for camera 2 images

N-element cell array of character vectors | N-element array of strings

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 — Images

height-by-width-by-color channel-by-number of frames array

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.

images1 — Stereo pair images from camera 1

height-by-width-by-color channel-by-number of frames array

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.

images2 — Stereo pair images from camera 2

height-by-width-by-color channel-by-number of frames array

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'

MinCornerMetric — Minimum corner metric threshold

0.15 | 0.12 | nonnegative scalar

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.

HighDistortion — High distortion

false (default) | true

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.

PartialDetections — Partial detections

true (default) | false

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

imagePoints — Detected checkerboard corner coordinates

M-by-2 matrix | M-by-2-by- number of images array | M-by-2-by-number of pairs of images-by-number of cameras array

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 and the size of this board is returned in boardSize.

boardSize — Checkerboard dimensions

2-element [height, width] vector

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].

imagesUsed — Pattern detection flag

N-by-1 logical vector

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.

pairsUsed — Stereo pair pattern detection flag

N-by-1 logical vector

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

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Code generation will not support specifying images as file names or cell arrays of file names. It supports only checkerboard detection in a single image or stereo pair of images. For example, these syntaxes are supported:

  • detectCheckerboardPoints(I1)

  • detectCheckerboardPoints(I1,I2)

  I1 and I2 are single grayscale or RGB images.

• Images must be compile-time constants.

Version History

Introduced in R2014a