detectAprilGridPoints

Detect keypoints of AprilGrid pattern in images

Since R2024b

Syntax

imagePoints = detectAprilGridPoints(I,patternDims,tagFamily)

[imagePoints,imagesUsed] = detectAprilGridPoints(imageFileNames,___)

[___] = detectAprilGridPoints(images,___)

imagePoints = detectAprilGridPoints(images1,images2,patternDims,tagFamily)

[imagePoints,pairsUsed] = detectAprilGridPoints(imageFileNames1,imageFileNames2,___)

[___] = detectAprilGridPoints(images1,images2,___)

[___] = detectAprilGridPoints(___,Name=Value)

Description

Single Image AprilGrid Detection

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

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

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

Stereo Pair AprilGrid Detection

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

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

[___] = detectAprilGridPoints(images1,images2,___) detects an AprilGrid pattern in the stereo pairs of images 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

Detect AprilGrid in Image

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");

Detect AprilGrid in Stereo Image Pair

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(2)
imshow(I2)
hold on
plot(imagePoints(:,1,1,2),imagePoints(:,2,1,2),"go");
title("Right camera")

Input Arguments

patternDims — Pattern dimensions

two-element vector

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 Calibration Patterns.

tagFamily — AprilTag marker family used in AprilGrid pattern

"tag36h11" | "tag25h9" | "tag16h5"

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

I — Image

2-D truecolor image | grayscale image

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

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

images — Images

H-by-W-by-numColorChannels-by-numImages array

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

images1 — Stereo pair images from camera one

H-by-W-by-numColorChannels-by-numImages array

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

images2 — Stereo pair images from camera two

H-by-W-by-numColorChannels-by-numImages array

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

imageFileNames — Image filenames

cell array of character vectors | array of strings

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

imageFileNames1 — Stereo image filenames for camera one

cell array of character vectors | array of strings

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

imageFileNames2 — Stereo image filenames for camera two

cell array of character vectors | 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.

NumBorderBits — Number of tag border bits

2 (default) | 1

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.

MinTagID — Lowest value tag ID in pattern

0 (default) | nonnegative integer

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.

GaussianSigma — Standard deviation for 2-D Gaussian smoothing kernel

0 (default) | nonnegative scalar

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.

DecimationFactor — Decimation factor

1 (default) | positive integer

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

imagePoints — Corner coordinates of detected AprilGrid pattern

M-by-2 matrix | M-by-2-by- numImages array | M-by-2-by-numPairs-by-2 array

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.

imagesUsed — Pattern detection flag

logical vector

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.

pairsUsed — Stereo pair pattern detection flag

logical vector

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