detectCheckerboardPoints

Detect checkerboard pattern in image

Syntax

[imagePoints,patternDims] = detectCheckerboardPoints(I)

[imagePoints,patternDims,imagesUsed] = detectCheckerboardPoints(imageFileNames)

[imagePoints,patternDims,imagesUsed] = detectCheckerboardPoints(images)

[imagePoints,patternDims,pairsUsed] = detectCheckerboardPoints(imageFileNames1,imageFileNames2)

[imagePoints,patternDims,pairsUsed] = detectCheckerboardPoints(images1,images2)

[imagePoints,patternDims,pairsUsed] = detectCheckerboardPoints(___,Name,Value)

Description

Single Image Checkerboard Detection

[imagePoints,patternDims] = 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 patternDims.

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

[imagePoints,patternDims,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,patternDims,pairsUsed] = detectCheckerboardPoints(imageFileNames1,imageFileNames2) detects a checkerboard pattern in stereo pairs of images, provided as cell arrays of file names.

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

Optional Arguments

[imagePoints,patternDims,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,patternDims,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","dslr","image01.jpg");
I = imread(imageFileName);

Detect the checkerboard points.

[imagePoints,patternDims] = 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",patternDims));

Detect Checkerboard in a Set of Image Files

Create a cell array of file names of calibration images.

images = imageDatastore(fullfile(toolboxdir("vision"),"visiondata",...
    "calibration","dslr"));
imageFileNames = images.Files;

Detect calibration pattern in the images.

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

Display the detected points.

imageFileNames = imageFileNames(imagesUsed);
for i = 1:4
  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,patternDims,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 patternDims, 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(patternDims-1).

If the checkerboard cannot be detected:

imagePoints = []

patternDims = [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 dimensions of this board is returned in patternDims.

patternDims — Pattern dimensions

2-element [height, width] vector

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

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

imagesUsed — Pattern detection

N-by-1 logical vector

Pattern detection, returned as an N-by-1 logical vector, where N is the number of images. The function returns 1 (true) if corners are successfully detected in an image, and 0 (false) if no corners are detected.

The function estimates the checkerboard corners based on a successful detection of the keypoints. If any step in the detection process fails, the function does not return corners for that image, and the corresponding value in the logical vector is false.

pairsUsed — Stereo pair pattern detection

N-by-1 logical vector

Stereo pair pattern detection, returned as an N-by-1 logical vector, where N is the number of images. The function returns 1 (true) if corners are successfully detected in a stereo image pair, and 0 (false) if no corners are detected.

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.

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

The detectCheckerboardPoints function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2014a