Finds the positions of internal corners of the chessboard

[corners,ok] = cv.findChessboardCorners(im, patternSize)
[...] = cv.findChessboardCorners(..., 'OptionName', optionValue, ...)

Input

• im Source chessboard view. It must be an 8-bit grayscale or color image.
• patternSize Number of inner corners per a chessboard row and column (patternSize = [points_per_row,points_per_colum] = [columns,rows]).

Output

• corners Output array of detected corners. Cell array of 2-element vectors {[x,y], ...}. Returns an empty cell if it fails to find all the corners.
• ok returns true if all of the corners are found and they are placed in a certain order. Otherwise, if the function fails to find all the corners or reorder them, it returns false.

Options

• AdaptiveThresh Use adaptive thresholding to convert the image to black and white, rather than a fixed threshold level (computed from the average image brightness). default true.
• NormalizeImage Normalize the image gamma with cv.equalizeHist before applying fixed or adaptive thresholding. default true.
• FilterQuads Use additional criteria (like contour area, perimeter, square-like shape) to filter out false quads extracted at the contour retrieval stage. default false.
• FastCheck Run a fast check on the image that looks for chessboard corners, and shortcut the call if none is found. This can drastically speed up the call in the degenerate condition when no chessboard is observed. default false.

The function attempts to determine whether the input image is a view of the chessboard pattern and locate the internal chessboard corners. The function returns a non-zero value if all of the corners are found and they are placed in a certain order (row by row, left to right in every row). Otherwise, if the function fails to find all the corners or reorder them, it returns an empty cell array. For example, a regular chessboard has 8x8 squares and 7x7 internal corners, that is, points where the black squares touch each other. The detected coordinates are approximate, and to determine their positions more accurately, the function calls cv.cornerSubPix. You also may use the function cv.cornerSubPix with different parameters if returned coordinates are not accurate enough.

In practice, it is more convenient to use a chessboard grid that is asymmetric, for example 5x6. Using such even-odd asymmetry yields a chessboard that has only one symmetry axis, so the board orientation can always be defined uniquely.

Example

Sample usage of detecting and drawing chessboard corners:

patternsize = [9,6];         % interior number of corners
gray = imread(fullfile(mexopencv.root(),'test','left01.jpg'));
% 'FastCheck' saves a lot of time on images
% that do not contain any chessboard corners
[corners,patternfound] = cv.findChessboardCorners(gray, patternsize, ...
    'AdaptiveThresh',true, 'NormalizeImage',true, 'FastCheck',true);
if patternfound
    corners = cv.cornerSubPix(gray, corners, 'Criteria',...
        struct('type','Count+EPS', 'maxCount',30, 'epsilon',0.1));
end
img = cv.drawChessboardCorners(repmat(gray,[1 1 3]), patternsize, ...
    cat(1,corners{:}), 'PatternWasFound',patternfound);

Note

The function requires white space (like a square-thick border, the wider the better) around the board to make the detection more robust in various environments. Otherwise, if there is no border and the background is dark, the outer black squares cannot be segmented properly and so the square grouping and ordering algorithm fails.