readArucoMarker

Detect and estimate pose for ArUco marker in image

Since R2024a

collapse all in page

Syntax

[id,loc] = readArucoMarker(I)

[id,loc] = readArucoMarker(I,markerFamily)

[id,loc,pose] = readArucoMarker(___,intrinsics,markerSize)

[___,detectedFamily,rejections] = readArucoMarker(___)

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

Description

[id,loc] = readArucoMarker(I) detects ArUco markers in the input image I, and returns the locations and IDs associated with the markers.

example

[id,loc] = readArucoMarker(I,markerFamily) detects ArUco markers of only the specified families, markerFamily.

[id,loc,pose] = readArucoMarker(___,intrinsics,markerSize) returns the poses of the markers with respect to the specified camera intrinsic parameters, intrinsics, and size of the markers, markerSize, in addition to any combination of input arguments from previous syntaxes.

[___,detectedFamily,rejections] = readArucoMarker(___) returns the recognized ArUco marker families, detectedFamily, and the xy-locations of rejected ArUco marker candidates, rejections, in addition to any combination of arguments from previous syntaxes.

example

[___] = readArucoMarker(___,Name=Value) specifies options using one or more name-value arguments. For example, WindowSizeStep=12 sets the number of pixels by which to increment the window size during adaptive thresholding to 12.

Examples

collapse all

Read ArUco Markers in Image

Open Live Script

Read an image into the workspace.

I = imread("ArUcoMarkersMulti.jpg");

Read the ArUco markers in the image to get their IDs, pixel locations, and marker families.

[ids,locs,detectedFamily] = readArucoMarker(I);

Overlay the marker edges, corners, and IDs on the image for visualization.

numMarkers = length(ids);
for i = 1:numMarkers
  loc = locs(:,:,i);
   
  % Display the marker ID and family
  disp("Detected marker ID, Family: " + ids(i) + ", " + detectedFamily(i))  
 
  % Insert marker edges
  I = insertShape(I,"polygon",{loc},Opacity=1,ShapeColor="green",LineWidth=4);
 
  % Insert marker corners
  markerRadius = 6;
  numCorners = size(loc,1);
  markerPosition = [loc,repmat(markerRadius,numCorners,1)];
  I = insertShape(I,"FilledCircle",markerPosition,ShapeColor="red",Opacity=1);
   
  % Insert marker IDs
  center = mean(loc);
  I = insertText(I,center,ids(i),FontSize=30,BoxOpacity=1);
end

Detected marker ID, Family: 3, DICT_4X4_1000
Detected marker ID, Family: 34, DICT_5X5_1000
Detected marker ID, Family: 84, DICT_6X6_1000
Detected marker ID, Family: 264, DICT_7X7_1000
Detected marker ID, Family: 879, DICT_ARUCO_ORIGINAL

Display the results.

imshow(I)

Estimate ArUco Poses in Image

Open Live Script

Read an image that contains ArUco markers into the workspace.

I = imread("ArUcoBoard.jpg");

Load intrinsics of the camera that captured the image.

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

Undistort the image and display it.

[I,camIntrinsics] = undistortFisheyeImage(I,intrinsics);
imshow(I)

Measure the marker size in millimeters.

markerSizeInMM = 25.4;

Specify the marker family for faster performance of readArucoMarker function.

markerFamily = "DICT_6X6_250";

Estimate marker poses.

[ids,locs,poses] = readArucoMarker(I,markerFamily,camIntrinsics,markerSizeInMM);

Overlay estimated poses on the image for visualization.

% Origin and axes vectors for the object coordinate system
worldPoints = [0 0 0; markerSizeInMM/2 0 0; 0 markerSizeInMM/2 0; 0 0 markerSizeInMM/2];

for i = 1:length(poses)
  % Get image coordinates for axes
  imagePoints = world2img(worldPoints,poses(i),camIntrinsics);
 
  axesPoints = [imagePoints(1,:) imagePoints(2,:);
                imagePoints(1,:) imagePoints(3,:);
                imagePoints(1,:) imagePoints(4,:)];
  % Draw colored axes
  I = insertShape(I, "Line", axesPoints, ...
      Color = ["red","green","blue"], LineWidth=10);
end

Display the results.

imshow(I)

Input Arguments

collapse all

`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. The input image must be undistorted.

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

`markerFamily` — ArUco marker families
character vector | string scalar | vector of strings | cell array of character vectors

ArUco marker families, specified as a character vector, string scalar, vector of strings, or cell array of character vectors. Each element must be one of the valid ArUco marker families listed in the table. Specifying a family can reduce the run time of the function by restricting its search. Use this argument to improve the execution time when you know the marker family in the image. Be default, the function searches for:

[ "DICT_ARUCO_ORIGINAL","DICT_4X4_1000","DICT_5X5_1000","DICT_6X6_1000", "DICT_7X7_1000"].

Family	Marker Size (bits)	Number of Markers in Family	Minimum Hamming Distance Between Markers (bits)
`"DICT_ARUCO_ORIGINAL"`	5-by-5	1024	3
`"DICT_4X4_50"`	4-by-4	50	4
`"DICT_4X4_100"`		100	3
`"DICT_4X4_250"`		250	2
`"DICT_4X4_1000"`		1000	2
`"DICT_5X5_50"`	5-by-5	50	8
`"DICT_5X5_100"`		100	7
`"DICT_5X5_250"`		250	6
`"DICT_5X5_1000"`		1000	5
`"DICT_6X6_50"`	6-by-6	50	13
`"DICT_6X6_100"`		100	12
`"DICT_6X6_250"`		250	11
`"DICT_6X6_1000"`		1000	9
`"DICT_7X7_50"`	7-by-7	50	19
`"DICT_7X7_100"`		250	18
`"DICT_7X7_250"`		250	17
`"DICT_7X7_1000"`		1000	14

Data Types: char | string | cell

`intrinsics` — Camera intrinsic parameters
`cameraIntrinsics` object

Camera intrinsic parameters, specified as a cameraIntrinsics object.

`markerSize` — Size of marker
positive scalar

Size of the marker in world units (such as millimeters), specified as a positive scalar. The function defines the size of the markers as the length of one side of the square marker.

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: readArucoMarker(I,WindowSizeStep=12) sets the number of pixels by which to increment the window size during adaptive thresholding to 12.

Adaptive Thresholding Arguments

collapse all

`WindowSizeRange` — Window size range
`[3 23]` (default) | two-element vector

Window size range, in pixels, specified as a two-element vector of the form [min max]. The elements set the minimum and maximum size, respectively, for the windows used for adaptive thresholding. Each value n in the range represents an n-by-n square window. Each element of this argument must be a positive integer greater than or equal to 3. The function determines the local window threshold by calculating the average pixel value obtained from the sum of its surrounding pixels. Increase the max value when using ArUco markers that are larger than 400-by-400 pixels.

`WindowSizeStep` — Window step size
`10` (default) | positive integer

Window step size, in pixels, specified as a positive integer. The function uses the window step size for adaptive thresholding, but stays within the range set by the WindowSizeRange argument. The function starts at the minimum size of the range, and then increments the window size by the value of WindowSizeStep, until it reaches the maximum range value. If the window size is too small and a marker is large, the function might not detect that marker. This can occur when the window overlaps with the marker border. If the window size is large and a marker is small, the function might detect the marker, but the difference in size can negatively impact processing speed.

Contour Filtering Arguments

collapse all

`MarkerSizeRange` — Range for marker boundary perimeter length
`[0.0075 1]` (default) | two-element vector

Range for marker boundary perimeter length, specified as a two-element vector of the form [min max]. The elements set the minimum and maximum size for the perimeter length of detected markers. Specify each element as a value normalized to the maximum dimension of the image. Reduce the range if a rejected marker completely encloses a valid marker.

`SquarenessTolerance` — Maximum polygonal approximation error
`0.03` (default) | positive scalar

Maximum polygonal approximation error, specified as a positive scalar. The function utilizes the Douglas-Peucker algorithm to apply a polygonal approximation to each marker candidate, accepting only those that closely resemble a square shape. The value of the SquarenessTolerance is relative to the candidate marker length (in pixels). Decrease this value to filter false corner detections in occluded markers. Increase this value to detect marker candidates in highly distorted images.

Bit Extraction Arguments

collapse all

`NumBorderBits` — Number of border bits in marker
`1` (default) | positive integer

Number of border bits in the marker, specified as a positive integer. By default, the marker boundary contains one bit. If the function does not detect a marker candidate, first ensure that you have correctly set the markerFamily, then follow one of these two steps:

If you used the generateArucoMarker function to generate the marker image, then ensure this name-value argument value is set to the same value as NumBorderBits of the generateArucoMarker function.
If you did not use the generateArucoMarker function, then check the ArUco marker manufacturer manual to get the correct value for the number of border bits to use.

`ResolutionPerBit` — Resolution of the decoder
`4` (default) | positive integer

Resolution of the decoder to use in the bit extraction step, in pixels, specified as a positive integer. This value sets the number of pixels, per bit, to use in the obtained image after correcting perspective distortion. Increase this value to improve the accuracy with which the function reads marker IDs at the expense of runtime speed. The maximum value for argument is 1000.

Subpixel Corner Refinement Arguments

collapse all

`RefineCorners` — Subpixel refinement process
`false` or `0` (default) | `true` or `1`

Subpixel refinement process, specified as a logical 1(true) or 0(false). Set this value to true to enable the subpixel refinement process for the detected marker corner locations. This step is computationally expensive. Enable this process only if the corner locations must be accurate for pose estimation or for camera calibration applications.

`RefinementWindowSize` — Window size of subpixel refinement process
`5` (default) | positive integer

Window size of the subpixel refinement process, in pixels, specified as a positive integer. Increasing this value can cause the window area to include a corner of the image. As a result of this proximity, marker corners might move to an incorrect locations.

`RefinementMaxIterations` — Maximum number of iterations for subpixel refinement process
`30` (default) | positive integer

Maximum number of iterations the subpixel refinement process, specified as a positive integer. The process stops after the specified number of iterations even if it has not achieved the termination tolerance RefinementTolerance.

`RefinementTolerance` — Termination tolerance
`0.1` (default) | positive scalar

Termination tolerance, specified as a positive scalar.

Output Arguments

collapse all

`id` — Marker IDs
N-element vector

Marker IDs, returned as an N-element vector of positive integers.

`loc` — Locations of detected markers in image
4-by-2-by-N array

Locations of the detected markers in the image, returned as a 4-by-2-by-N array. The array contains the xy-locations of the four corners for each detected marker. N is the number of detected markers.

`pose` — Poses of markers
array of `rigidtform3d` objects

Poses of markers with respect to the camera, returned as an array of rigidtform3d objects. Each object encapsulates the 3-D rigid transformation of a marker in the same world units as the markerSize input argument. The origin of each marker frame is located at the center of the corresponding marker. The planar surface on which the ArUco marker sits defines the XY-plane of the marker frame with the Z-axis pointing out of the marker.

`detectedFamily` — Detected ArUco marker families
vector of strings

Detected ArUco marker families, returned as a vector of strings.

`rejections` — Locations of rejected ArUco marker candidates
4-by-2-by-P array

Locations of the rejected ArUco marker candidates, returned as a 4-by-2-by-P array. The array contains the xy-locations for the four corners of each rejected marker candidate. P is the number of rejected marker candidates.

Tips

This function does not account for lens distortion during pose estimation. To estimate poses, the input image must be undistorted. To estimate poses with a camera that has been calibrated using the Scaramuzza model, you can use the virtual pinhole model returned by the undistortFisheyeImage function.
Consider the number of markers your application requires, marker length, and Hamming distance when choosing a marker family. The minimum Hamming distance between markers in the same family determines how capable the function is of detecting them and correcting errors. Smaller marker families, in terms of the number of markers in the family, and marker families with more bits have a larger minimum Hamming distance, but the additional bits to extract can make marker detection more difficult. For example, if your application only requires 10 markers, you can use a family of 10 markers for increased error robustness over a family of 1000 markers. In summary:
- The fewer bits used to encode the ID in the ArUco marker, the greater the distance from the camera that you can detect the marker. The marker family name specifies the number of bits (for example, DICT_4X4_50 has a marker size of 4-by-4, totaling 16 bits).
- Refer to the full list of ArUco family markers, specified in the markerFamily argument description.
Use one or more of these debugging tips:
- Include a white border (also called a quiet zone) around ArUco markers for proper identification and decoding.
- The function does not detect markers if the images have been flipped vertically or horizontally.
- The function does not detect markers if their square shape has been altered as a result of lens distortion. You can undistort images to improve marker detection.
- If the function does not detect a marker image, and does not return it as a rejected marker candidate, you might need to modify the adaptive thresholding steps. You can do this by adjusting the WindowSizeRange and WindowSizeStep values.
- If the function does not detect a marker image, but returns it as a rejected candidate, verify or adjust the markerFamily and NumBorderBits values. Also, verify that the image has not been flipped vertically or horizontally.
- If a detected or rejected marker incorrectly encompasses any surrounding black borders, adjust the MarkerSizeRange value.
- If the function returns an incorrect marker ID, or if it detects the same marker using two different marker families, increase the ResolutionPerBit value.

Algorithms

When the detection process starts, the function binarizes the input image using adaptive thresholding at different neighborhood window sizes. The function extracts marker rejections on each of the binarized images.

The marker detection algorithm uses these steps:

Perform adaptive thresholding to binarize the image.
Extract and filter contours to detect square-shaped marker candidates.
Remove perspective distortion and extract marker bits to analyze the inner codification of the marker bits.
Perform error correction to identify valid markers.
Optionally, perform subpixel refinement of corner positions.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

During code generation, detectedFamily output argument is returned as cell array unlike vector of strings in simulation.

Version History

Introduced in R2024a

readArucoMarker

Syntax

Description

Examples

Read ArUco Markers in Image

Estimate ArUco Poses in Image

Input Arguments

`I` — Input image
M-by-N-by-3 truecolor image | M-by-N grayscale image

`markerFamily` — ArUco marker families
character vector | string scalar | vector of strings | cell array of character vectors

`intrinsics` — Camera intrinsic parameters
`cameraIntrinsics` object

`markerSize` — Size of marker
positive scalar

Name-Value Arguments

`WindowSizeRange` — Window size range
`[3 23]` (default) | two-element vector

`WindowSizeStep` — Window step size
`10` (default) | positive integer

`MarkerSizeRange` — Range for marker boundary perimeter length
`[0.0075 1]` (default) | two-element vector

`SquarenessTolerance` — Maximum polygonal approximation error
`0.03` (default) | positive scalar

`NumBorderBits` — Number of border bits in marker
`1` (default) | positive integer

`ResolutionPerBit` — Resolution of the decoder
`4` (default) | positive integer

`RefineCorners` — Subpixel refinement process
`false` or `0` (default) | `true` or `1`

`RefinementWindowSize` — Window size of subpixel refinement process
`5` (default) | positive integer

`RefinementMaxIterations` — Maximum number of iterations for subpixel refinement process
`30` (default) | positive integer

`RefinementTolerance` — Termination tolerance
`0.1` (default) | positive scalar

Output Arguments

`id` — Marker IDs
N-element vector

`loc` — Locations of detected markers in image
4-by-2-by-N array

`pose` — Poses of markers
array of `rigidtform3d` objects

`detectedFamily` — Detected ArUco marker families
vector of strings

`rejections` — Locations of rejected ArUco marker candidates
4-by-2-by-P array

Tips

Algorithms

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

See Also

Functions

Topics

readArucoMarker

Syntax

Description

Examples

Read ArUco Markers in Image

Estimate ArUco Poses in Image

Input Arguments

I — Input image M-by-N-by-3 truecolor image | M-by-N grayscale image

markerFamily — ArUco marker families character vector | string scalar | vector of strings | cell array of character vectors

intrinsics — Camera intrinsic parameters cameraIntrinsics object

markerSize — Size of marker positive scalar

Name-Value Arguments

WindowSizeRange — Window size range [3 23] (default) | two-element vector

WindowSizeStep — Window step size 10 (default) | positive integer

MarkerSizeRange — Range for marker boundary perimeter length [0.0075 1] (default) | two-element vector

SquarenessTolerance — Maximum polygonal approximation error 0.03 (default) | positive scalar

NumBorderBits — Number of border bits in marker 1 (default) | positive integer

ResolutionPerBit — Resolution of the decoder 4 (default) | positive integer

RefineCorners — Subpixel refinement process false or 0 (default) | true or 1

RefinementWindowSize — Window size of subpixel refinement process 5 (default) | positive integer

RefinementMaxIterations — Maximum number of iterations for subpixel refinement process 30 (default) | positive integer

RefinementTolerance — Termination tolerance 0.1 (default) | positive scalar

Output Arguments

id — Marker IDs N-element vector

loc — Locations of detected markers in image 4-by-2-by-N array

pose — Poses of markers array of rigidtform3d objects

detectedFamily — Detected ArUco marker families vector of strings

rejections — Locations of rejected ArUco marker candidates 4-by-2-by-P array

Tips

Algorithms

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

Version History

See Also

Functions

Topics

`I` — Input image
M-by-N-by-3 truecolor image | M-by-N grayscale image

`markerFamily` — ArUco marker families
character vector | string scalar | vector of strings | cell array of character vectors

`intrinsics` — Camera intrinsic parameters
`cameraIntrinsics` object

`markerSize` — Size of marker
positive scalar

`WindowSizeRange` — Window size range
`[3 23]` (default) | two-element vector

`WindowSizeStep` — Window step size
`10` (default) | positive integer

`MarkerSizeRange` — Range for marker boundary perimeter length
`[0.0075 1]` (default) | two-element vector

`SquarenessTolerance` — Maximum polygonal approximation error
`0.03` (default) | positive scalar

`NumBorderBits` — Number of border bits in marker
`1` (default) | positive integer

`ResolutionPerBit` — Resolution of the decoder
`4` (default) | positive integer

`RefineCorners` — Subpixel refinement process
`false` or `0` (default) | `true` or `1`

`RefinementWindowSize` — Window size of subpixel refinement process
`5` (default) | positive integer

`RefinementMaxIterations` — Maximum number of iterations for subpixel refinement process
`30` (default) | positive integer

`RefinementTolerance` — Termination tolerance
`0.1` (default) | positive scalar

`id` — Marker IDs
N-element vector

`loc` — Locations of detected markers in image
4-by-2-by-N array

`pose` — Poses of markers
array of `rigidtform3d` objects

`detectedFamily` — Detected ArUco marker families
vector of strings

`rejections` — Locations of rejected ArUco marker candidates
4-by-2-by-P array

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.