Main Content

readAprilTag

Detect and estimate pose for AprilTag in image

Since R2020b

Description

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

example

[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

collapse all

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)

Figure contains an axes object. The hidden axes object contains an object of type image.

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

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

Figure contains an axes object. The hidden axes object contains an object of type image.

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)

Figure contains an axes object. The hidden axes object contains an object of type image.

Input Arguments

collapse all

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

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

Camera intrinsic parameters, specified as a cameraIntrinsics object.

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.

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.

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

Tag IDs, returned as a vector of positive integers.

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.

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.

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

Version History

Introduced in R2020b

expand all