Main Content

detectAprilGridPoints

Detect keypoints of AprilGrid pattern in images

Since R2024b

Description

Single Image AprilGrid Detection

imagePoints = detectAprilGridPoints(I,patternDims,tagFamily) detects keypoints of an AprilGrid pattern in a 2-D trucolor or grayscale image I. patternDims specifies the number of tags in the pattern, and tagFamily specifies the AprilTag family.

example

[imagePoints,imagesUsed,tagFamily] = detectAprilGridPoints(imageFileNames,patternDims) detects an AprilGrid pattern in the image files specified by imageFileNames, and additionally returns the list of images in which the pattern is detected imagesUsed.

[___] = detectAprilGridPoints(images,patternDims) detects a AprilGrid in the specified images images.

Stereo Pair AprilGrid Detection

[imagePoints,pairsUsed,tagFamily] = detectAprilGridPoints(imageFileNames1,imageFileNames2,patternDims) detects an AprilGrid pattern in the stereo pairs of image files specified by imageFileNames1 and imageFileNames2. The function additionally returns a list of the pairs in which the pattern is detected pairsUsed.

[___] = detectAprilGridPoints(images1,images2,patternDims) detects an AprilGrid pattern in the stereo pairs of image files specified by images1 and images2.

Optional Arguments

[___] = detectAprilGridPoints(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, NumBorderBits=1 sets the number of tag border bits to generate an AprilTag to 1.

Examples

collapse all

Load the calibration image containing an AprilGrid into the workspace.

I = imread("aprilgrid.jpg");

Define the AprilGrid properties.

tagFamily = "tag36h11";
patternDims = [6 6];

Detect AprilGrid in the image.

imagePoints = detectAprilGridPoints(I,patternDims,tagFamily);

Display the detected keypoints of AprilGrid in the image.

imshow(I); 
hold on;
plot(imagePoints(:,1),imagePoints(:,2),"yo");

Figure contains an axes object. The hidden axes object contains 2 objects of type image, line. One or more of the lines displays its values using only markers

Load a stereo image pair containing an AprilGrid pattern into the workspace.

I1 = imread("leftAprilGrid.jpg");
I2 = imread("rightAprilGrid.jpg");

Define the AprilGrid properties.

tagFamily = "tag36h11";
patternDims = [6 6];

Detect the AprilGrid keypoints.

imagePoints = detectAprilGridPoints(I1,I2,patternDims,tagFamily);

Display the detected points on the image.

figure(1)
imshow(I1) 
hold on
plot(imagePoints(:,1,1,1),imagePoints(:,2,1,1),"go");
title("Left camera")

Figure contains an axes object. The hidden axes object with title Left camera contains 2 objects of type image, line. One or more of the lines displays its values using only markers

figure(2)
imshow(I2)
hold on
plot(imagePoints(:,1,1,2),imagePoints(:,2,1,2),"go");
title("Right camera")

Figure contains an axes object. The hidden axes object with title Right camera contains 2 objects of type image, line. One or more of the lines displays its values using only markers

Input Arguments

collapse all

Pattern dimensions, specified as a two-element vector that represents the number of tags in the x and y dimensions of the AprilGrid image, respectively. For more details on AprilTag patterns, see AprilGrid Pattern

AprilTag marker family used in the AprilGrid pattern, specified as "tag36h11", "tag25h9", or "tag16h5".

Image, specified as a 2-D truecolor image or grayscale image.

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

Images, specified as an H-by-W-by-numColorChannels-by-numImages array, where H and W describe the height and width of each image, respectively. numColorChannels is the number of color channels in each image, and numImages is the number of images.

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

Stereo pair images from camera one, specified as an H-by-W-by-numColorChannels-by-numImages array, where H and W describe the height and width of each image, respectively. numColorChannels is the number of color channels in each image, and numImages is the number of images.

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

Stereo pair images from camera two, specified as an H-by-W-by-numColorChannels-by-numImages array, where H and W describe the height and width of each image, respectively. numColorChannels is the number of color channels in each image, and numImages is the number of images.

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

Image filenames, specified as a cell array of character vectors or an array of strings.

Stereo image filenames for camera one, specified as a cell array of character vectors or an array of strings.

Stereo image filenames for camera two, specified as a cell array of character vectors or an array of strings.

Name-Value Arguments

Example: detectAprilGridPoints(I,patternDims,NumBorderBits=1) sets the number of tag border bits to generate an AprilTag to 1.

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.

Number of tag border bits, specified as 1 or 2. The tag border bits are used to generate the AprilTags. The border bits relate to each generated tag image, but not to a tag family. Refer to the manufacturer manual for your AprilTag pattern, to set this value.

If the function does not detect a fully visible tag, check that the tagFamily is correct. Otherwise, the specified NumborderBits might be incorrect.

Lowest value tag ID in the AprilGrid pattern, specified as a nonnegative integer. The tags in the pattern must have sequential IDs with an increment of 1.

Standard deviation for 2-D Gaussian smoothing kernel, specified as a nonnegative scalar. The Gaussian kernel smooths the input image to decrease white Gaussian noise. Increase this value to increase the processing speed, but at the cost of reduced precision.

Decimation factor, specified as a positive integer. The decimation factor controls the scale of the downsampling. Increase this value to increase the detection rate, while decreasing detection distance.

Output Arguments

collapse all

Corner coordinates of the detected AprilGrid pattern, returned as an M-by-2 matrix, M-by-2-by-numImages array, or an M-by-2-by-numPairs-by-2 array. M is the number of AprilGrid patterns detected, calculated as the product of the number of Aprilgrid patterns detected in each dimension. Each row of the matrix or array specifies the xy- coordinates of the center an AprilGrid.

  • For single image — This argument is an M-by-2 matrix.

  • For mutliple images — This argument is an M-by-2-numImages array.

  • For stereo pairs — This argument is an M-by-2-by-numPairs-by-2 array, where numPairs is the number of image pairs in which the function detects an AprilGrid. imagePoints(:,:,:,1) returns the points from the first set of images, and imagePoints(:,:,:,2) returns the points from the second set.

Pattern detection flag, returned as a logical vector. A value of true in the imagesUsed vector indicates that the pattern has been detected in the corresponding image.

Stereo pair pattern detection flag, returned as a logical vector. A value of true in the pairsUsed vector indicates that the pattern has been detected in the corresponding image pair.

Version History

Introduced in R2024b