Finds the centers in the grid of circles

centers = cv.findCirclesGrid(im, patternSize)
[centers,patternFound] = cv.findCirclesGrid(im, patternSize)
[...] = cv.findCirclesGrid(..., 'OptionName', optionValue, ...)

Input

• im Grid view of input circles. It must be an 8-bit grayscale or color image.
• patternSize Number of circles per row and column (patternSize = [points_per_row, points_per_colum]).

Output

• centers Cell array of detected centers {[x,y], ...}.
• patternFound logical return value, see below.

Options

• SymmetricGrid Use symmetric or asymmetric pattern of circles. In an asymmetric grid, the circles in each row are staggered transverse to the row (important to remember how rows and columns are counted in this case). default true.
• Clustering Use a special algorithm for grid detection. It is more robust to perspective distortions but much more sensitive to background clutter. This is a good choice when you are trying to calibrate a camera with an unusually wide field of view. default false.
• BlobDetector feature detector that finds blobs like dark circles on light background. It can be specified as a string containing the type of feature detector, such as 'SimpleBlobDetector'. It can also be specified as a cell-array of the form {fdetector, 'key',val, ...}, where the first element is the type, and the remaining elements are optional parameters used to construct the specified feature detector. See cv.FeatureDetector for possible types. default is to use cv.SimpleBlobDetector with its default parameters.
• FinderParameters Parameters for finding circles in a grid pattern. You can specify the parameters as a cell-array that starts with the grid type followed by pairs of key-value options {'Symmetric', 'key',val, ...}, or as a structure where the fields are the options struct('GridType','Symmetric', 'key',val, ...).
  • GridType one of 'Symmetric' (default) or 'Asymmetric'
  • DensityNeighborhoodSize default [16,16]
  • MinDensity default 10.0
  • KmeansAttempts default 100
  • MinDistanceToAddKeypoint default 20
  • KeypointScale default 1
  • MinGraphConfidence default 9.0
  • VertexGain default 1.0
  • VertexPenalty default -0.6
  • ExistingVertexGain default 10000.0
  • EdgeGain default 1.0
  • EdgePenalty default -0.6
  • ConvexHullFactor default 1.1
  • MinRNGEdgeSwitchDist default 5.0
  • SquareSize Distance between two adjacent points. Used by 'Clustering' algorithm. default 1.0
  • MaxRectifiedDistance Max deviation from predicion. Used by 'Clustering' algorithm. default SquareSize/2

The function attempts to determine whether the input image contains a grid of circles. If it is, the function locates centers of the circles. The function returns true if all of the centers have been found and they have been 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 false.

Example

Sample usage of detecting and drawing the centers of circles:

patternSize = [7,7];   % number of centers
gray = imread('...');  % source 8-bit image
[centers,patternfound] = cv.findCirclesGrid(gray, patternSize);
img = cv.drawChessboardCorners(img, patternSize, cat(1,centers{:}), ...
    'PatternWasFound',patternfound);
imshow(img)

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.