readAprilTag

Detect and estimate pose for AprilTag in image

Since R2020b

Syntax

[id,loc] = readAprilTag(I)

[id,loc] = readAprilTag(I,tagFamily)

[___,pose] = readAprilTag(___,intrinsics,tagSize)

[___,detectedFamily] = readAprilTag(___)

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

Description

[id,loc] = readAprilTag(I) detects AprilTags in the input image I and returns the locations and IDs associated with the tags.

[id,loc] = readAprilTag(I,tagFamily) detects AprilTags of only the specified families, tagFamily.

[___,pose] = readAprilTag(___,intrinsics,tagSize) returns the poses of the tags with respect to the specified camera intrinsic parameters, intrinsics and size of the tags tagSize in addition to any combination of arguments in previous syntaxes.

[___,detectedFamily] = readAprilTag(___) returns the recognized AprilTag families, detectedFamily.

[___] = readAprilTag(___,Name=Value) specifies options using one or more name-value arguments. For example, GaussianSigma=2, sets the standard deviation to 2 for the 2-D Gaussian smoothing kernel.

Examples

Detect AprilTags in Image

Read an image into the workspace.

I = imread("aprilTagsMulti.jpg");

Specify the AprilTag formats to search in the image.

tagFamily = ["tag36h11","tagCircle21h7","tagCircle49h12","tagCustom48h12","tagStandard41h12"];

Detect tags and tag locations in the image, and read the tag IDs.

[id,loc,detectedFamily] = readAprilTag(I,tagFamily);

for idx = 1:length(id)
        % Display the ID and tag family
        disp("Detected Tag ID, Family: " + id(idx) + ", " ...
            + detectedFamily(idx));
 
        % Insert markers to indicate the locations
        markerRadius = 8;
        numCorners = size(loc,1);
        markerPosition = [loc(:,:,idx),repmat(markerRadius,numCorners,1)];
        I = insertShape(I,"FilledCircle",markerPosition,ShapeColor="red",Opacity=1);
end

Detected Tag ID, Family: 30, tag36h11
Detected Tag ID, Family: 32, tagCircle21h7
Detected Tag ID, Family: 98, tagStandard41h12
Detected Tag ID, Family: 195, tagCustom48h12
Detected Tag ID, Family: 884, tagCircle49h12

Display the image with markers to indicate the corner locations of the detected tags.

imshow(I)

Estimate AprilTag Poses in Image

Read an image that contains AprilTags into the workspace. Display the image.

I = imread("aprilTag36h11.jpg");
imshow(I)

Load the camera intrinsic parameters.

data = load("camIntrinsicsAprilTag.mat");
intrinsics = data.intrinsics;  

Specify the tag size in meters.

tagSize = 0.04;

Undistort the input image using the camera intrinsic parameters.

I = undistortImage(I,intrinsics,OutputView="same");

Detect a specific family of AprilTags and estimate the tag poses.

[id,loc,pose] = readAprilTag(I,"tag36h11",intrinsics,tagSize);

Set the origin for the axes vectors and for the tag frames.

worldPoints = [0 0 0; tagSize/2 0 0; 0 tagSize/2 0; 0 0 tagSize/2];

Add the tag frames and IDs to the image.

for i = 1:length(pose)
    % Get image coordinates for axes.
    imagePoints = world2img(worldPoints,pose(i),intrinsics);

    % Draw colored axes.
    I = insertShape(I,Line=[imagePoints(1,:) imagePoints(2,:); ...
        imagePoints(1,:) imagePoints(3,:); imagePoints(1,:) imagePoints(4,:)], ...
        ShapeColor=["red","green","blue"],LineWidth=7);

    I = insertText(I,loc(1,:,i),id(i),BoxOpacity=1,FontSize=25);
end

Display the annotated image.

imshow(I)

Input Arguments

I — Input image

M-by-N-by-3 truecolor image | M-by-N grayscale image

Input image, specified as an M-by-N-by-3 truecolor image or an M-by-N grayscale image.

tagFamily — AprilTag families

one or more valid AprilTag families

AprilTag families, specified as one or more of the valid AprilTag families listed in this table. Specifying a family can reduce the run time of the function by restricting the search.

AprilTag Family
"tag16h5"
"tag25h9"
"tag36h11"
"tagCircle21h7"
"tagCircle49h12"
"tagCustom48h12"
"tagStandard41h12"
"tagStandard52h13"

Data Types: char | string | cell

intrinsics — Camera intrinsic parameters

cameraIntrinsics object

Camera intrinsic parameters, specified as a cameraIntrinsics object.

tagSize — Size of tag

positive scalar

Size of the tags in world units (such as millimeters), specified as a positive scalar. The function defines the size of the tags as the length between two adjacent corner outer black edges.

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.

Example: readAprilTag(I,GaussianSigma=2) sets the standard deviation to 2 for the 2-D Gaussian smoothing kernel.

GaussianSigma — Standard deviation for 2-D Gaussian smoothing kernel

0 (default) | non-negative scalar

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

DecimationFactor — Decimation factor

2 (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

id — Tag IDs

vector of positive integers

Tag IDs, returned as a vector of positive integers.

loc — Locations of tags in image

4-by-2-by-N array

Locations of tags in image, returned as a 4-by-2-by-N array. The array contains the (x,y) locations for each of the four corners for N tags.

pose — Poses of tags

array of rigidtform3d objects

Poses of tags with respect to the camera, returned as an array of rigidtform3d objects. Each object encapsulates the 3-D rigid transformation of a tag in the same world units as the tagSize input argument. The origin of each tag frame is located at the center of the corresponding tag. The X-Y plane of the tag frame is defined by the planar surface on which the AprilTag sits with the Z-axis pointing into the tag.

detectedFamily — Detected tag families

vector of strings

Detected tag families, returned as a vector of strings.

Tips

• For applications that require real-time performance, while also minimizing false-positive detections, consider using the "tag36h11" family tag.

• For applications that require a faster detection time as opposed to the number of supported IDs, use the "tagStandard41h12" family tag.

• For pregenerated tags for all supported tag families, see Pregenerated AprilTag Images on GitHub.

• The readAprilTag function cannot read AprilTags containing 2 border bits.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

• Generates code only on host platforms.

• You must specify the input argument tagFamily as a character vector or an array of character vectors. String inputs are not supported.

Version History

Introduced in R2020b

R2022b: Returns poses as rigidtform3d objects

Starting in R2022b, most Computer Vision Toolbox™ functions create and perform geometric transformations using the premultiply convention. Accordingly, the readAprilTag function now returns pose as an array of rigidtform3d objects, which use the premultiply convention. Before, the function returned pose as an array of rigid3d objects, which use the postmultiply convention. For more information, see Migrate Geometric Transformations to Premultiply Convention.