Main Content

detectCharucoBoardPoints

Detect ChArUco board pattern in images

Since R2024b

collapse all in page

Syntax

imagePoints = detectCharucoBoardPoints(I,patternDims,markerFamily,checkerSize,markerSize)
imagePoints = detectCharucoBoardPoints(___,intrinsics)
[imagePoints,imagesUsed] = detectCharucoBoardPoints(imageFileNames,___)
[___] = detectCharucoBoardPoints(images,___)
[imagePoints] = detectCharucoBoardPoints(I1,I2,patternDims,markerFamily,checkerSize,markerSize)
[imagePoints] = detectCharucoBoardPoints(I1,I2,patternDims,markerFamily,checkerSize,markerSize,intrinsics)
[imagePoints,pairsUsed] = detectCharucoBoardPoints(imageFileNames1,imageFileNames2,patternDims,markerFamily,checkerSize,markerSize)
[___] = detectCharucoBoardPoints(I1,I2,intrinsics)
[___] = detectCharucoBoardPoints(___,Name=Value)

Description

Single Image ChArUco Board Detection

imagePoints = detectCharucoBoardPoints(I,patternDims,markerFamily,checkerSize,markerSize) detects a ChArUco board in a 2-D truecolor or grayscale image. The function uses local homography to detect ChArUco corners.

example

imagePoints = detectCharucoBoardPoints(___,intrinsics) detects ChArUco corners using approximated pose estimation. The approximation is based on the estimated extrinsic properties, given the camera intrinsics.

[imagePoints,imagesUsed] = detectCharucoBoardPoints(imageFileNames,___) detects a ChArUco board in the image files specified by imageFileNames, and additionally returns the list of images in which the board is detected imagesUsed.

[___] = detectCharucoBoardPoints(images,___) detects a ChArUco board in the specified images images.

Stereo Pair ChArUco Board Detection

[imagePoints] = detectCharucoBoardPoints(I1,I2,patternDims,markerFamily,checkerSize,markerSize) detects a ChArUco board in a set of 2-D truecolor or grayscale image.

[imagePoints] = detectCharucoBoardPoints(I1,I2,patternDims,markerFamily,checkerSize,markerSize,intrinsics) detects ChArUco corners in a set of 2-D truecolor or grayscale using approximated pose estimation. The approximation is based on the estimated extrinsic properties, given the camera intrinsics.

[imagePoints,pairsUsed] = detectCharucoBoardPoints(imageFileNames1,imageFileNames2,patternDims,markerFamily,checkerSize,markerSize) detects an ChArUco 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 board is detected pairsUsed.

[___] = detectCharucoBoardPoints(I1,I2,intrinsics) detects an ChArUco pattern in the stereo pairs of image files specified by images1 and images2.

Optional Arguments

[___] = detectCharucoBoardPoints(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, NumBorderBits=2 sets the number of border bits to detect a marker to 2.

Examples

collapse all

Open Live Script

Specify your calibration images.

imds = imageDatastore("charuco");
images = imds.Files;

Define the ChArUco board properties. Checker board and marker size are in millimeters.

markerFamily = "DICT_4X4_1000";
patternDims = [7 10];
checkerSize = 29;
markerSize = 21;

Detect the board in the image.

imagePoints = detectCharucoBoardPoints(images,patternDims,markerFamily,checkerSize,markerSize);

Display the points from the first four images.

tiledlayout(2,2,TileSpacing="compact",Padding="compact");
for i = 1:4
  nexttile
  imshow(images{i}) 
  hold on
  plot(imagePoints(:,1,i,1),imagePoints(:,2,i,1),"gx");    
end

Figure contains 4 axes objects. Hidden axes object 1 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Hidden axes object 2 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Hidden axes object 3 contains 2 objects of type image, line. One or more of the lines displays its values using only markers Hidden axes object 4 contains 2 objects of type image, line. One or more of the lines displays its values using only markers

Open Live Script

Load a stereo image pair containing a ChArUco board into the workspace.

I1 = imread("leftChArUco.jpg");
I2 = imread("rightChArUco.jpg");

Define the ChArUco board properties. The checker board and marker size are specified in millimeters.

markerFamily = "DICT_4X4_1000";
patternDims = [7 10];
checkerSize = 29;
markerSize = 21;

Detect the ChArUco board in the images.

imagePoints = detectCharucoBoardPoints(I1,I2,patternDims,markerFamily,checkerSize,markerSize);

Display the detected points in the left and right images.

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 checker boxes in the dim1 and dim2 dimensions of the ChArUco board, respectively. For more details on ChArUco board patterns, see Calibration Patterns.

ArUco marker family used in ChArUco board, specified as "DICT_ARUCO_ORIGINAL", "DICT_4X4_1000", or "DICT_5X5_1000", "DICT_6X6_1000", or "DICT_7X7_1000".

ChArUco board checker box side length, specified as a scalar in world units, such as millimeters or inches. The checkerSize and markerSize must be specified in the same world units and checkerSize must be a larger value than markerSize.

ArUco marker side length, specified as a scalar in world units, such as millimeters or inches. The checkerSize and markerSize must be specified in the same world units and checkerSize must be a larger value than markerSize.

Camera intrinsics, specified as a scalar cameraIntrinsics object for a single camera, a two-element vector for a stereo camera, cameraParameters object, or a stereoParameters object.

To specify a fisheyeIntrinsics object, first undistort the image using the undistortFisheyeImage function. Use the undistorted image for the detectChArUcoBoardPoints image input and the cameraIntrinsics object that the undistortFisheyeImage function returns for the intrinsics argument.

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 file names, specified as a cell array of character vectors or an array of strings.

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

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

Name-Value Arguments

Example: detectCharucoBoardPoints(___,NumBorderBits=2) sets the number of marker border bits to detect a marker to 2.

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.

Descriptive Properties

collapse all

Lowest value marker ID in the pattern, specified as a non-negative integer. The markers in the pattern must correspond to sequential IDs, each incremented by 1.

Color of the checker box located in the top-left corner of ChArUco board origin, specified as "black" or "white". The board origin is the keypoint closest to the ArUco marker with the lowest ID. This value must not be set to "white" when the board contains an odd number of boxes in the x dimension, specified in patternDims(1).

Adaptive Thresholding Arguments

collapse all

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.

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

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.

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

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 check the ChArUco manufacturer manual to get the correct value for the number of border bits to use.

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.

Subpixel Corner Refinement Arguments

collapse all

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.

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.

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.

Termination tolerance, specified as a positive scalar.

Output Arguments

collapse all

Corner coordinates of detected ChArUco board, 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 ChArUco boards detected. Each row of the matrix or array specifies the x-y coordinates of the corner of a ChArUco pattern.

  • For single images — This argument is an M-by-2 matrix or an M-by-2-by- numImages array, when detecting ChArUco board pattern in single images. numImages is the number of images.

  • For stereo pairs — This argument is an M-by-2-by-numPairs-by-2 array when detecting ChArUco board patterns in stereo pairs of images. numPairs is the number of image pairs in which an ChArUco board patterns is detected. imagePoints(:,:,:,1) returns the points from the first set of images, and imagePoints(:,:,:,2) are the points from the second set.

When no ArUco marker was detected in the board image, the function returns imagePoints with NaN for its surrounding ChArUco corner locations.

ChArUco board 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 ChArUco board pattern detection flag, returned as a logical vector. A value of true in the pairsUsed vector indicates that the ChArUco board pattern has been detected in the corresponding image pair.

Tips

  • When no ArUco marker was detected in the board image, the function returns imagePoints with NaN for its surrounding ChArUco corner locations.

  • To debug any missed detections of ArUco markers, you can use the readArucoMarker function.

  • To specify a fisheyeIntrinsics object, first undistort the image using the undistortFisheyeImage function. Use the undistorted image for the detectChArUcoBoardPoints image input and the cameraIntrinsics object that the undistortFisheyeImage function returns for the intrinsics argument.

  • To detect multiple ChArUco boards in the same image, use this function with a unique for MinMarkerID, for each board.

  • To use this function, the markers in the pattern must correspond to sequential IDs, each incremented by 1.

Version History

Introduced in R2024b

See Also

Apps

Functions

Objects

Topics