OpenCV  4.5.3
Open Source Computer Vision
Detection of Diamond Markers

A ChArUco diamond marker (or simply diamond marker) is a chessboard composed by 3x3 squares and 4 ArUco markers inside the white squares. It is similar to a ChArUco board in appearance, however they are conceptually different.

In both, ChArUco board and Diamond markers, their detection is based on the previous detected ArUco markers. In the ChArUco case, the used markers are selected by directly looking their identifiers. This means that if a marker (included in the board) is found on a image, it will be automatically assumed to belong to the board. Furthermore, if a marker board is found more than once in the image, it will produce an ambiguity since the system wont be able to know which one should be used for the Board.

On the other hand, the detection of Diamond marker is not based on the identifiers. Instead, their detection is based on the relative position of the markers. As a consequence, marker identifiers can be repeated in the same diamond or among different diamonds, and they can be detected simultaneously without ambiguity. However, due to the complexity of finding marker based on their relative position, the diamond markers are limited to a size of 3x3 squares and 4 markers.

As in a single ArUco marker, each Diamond marker is composed by 4 corners and a identifier. The four corners correspond to the 4 chessboard corners in the marker and the identifier is actually an array of 4 numbers, which are the identifiers of the four ArUco markers inside the diamond.

Diamond markers are useful in those scenarios where repeated markers should be allowed. For instance:

  • To increase the number of identifiers of single markers by using diamond marker for labeling. They would allow up to N^4 different ids, being N the number of markers in the used dictionary.
  • Give to each of the four markers a conceptual meaning. For instance, one of the four marker ids could be used to indicate the scale of the marker (i.e. the size of the square), so that the same diamond can be found in the environment with different sizes just by changing one of the four markers and the user does not need to manually indicate the scale of each of them. This case is included in the diamond_detector.cpp file inside the samples folder of the module.

Furthermore, as its corners are chessboard corners, they can be used for accurate pose estimation.

The diamond functionalities are included in <opencv2/aruco/charuco.hpp>

ChArUco Diamond Creation

The image of a diamond marker can be easily created using the drawCharucoDiamond() function. For instance:

cv::Mat diamondImage;
cv::aruco::drawCharucoDiamond(dictionary, cv::Vec4i(45,68,28,74), 200, 120, markerImage);
n-dimensional dense array class
Definition: mat.hpp:802
Template class for short numerical vectors, a partial case of Matx.
Definition: matx.hpp:342
Ptr< Dictionary > getPredefinedDictionary(PREDEFINED_DICTIONARY_NAME name)
Returns one of the predefined dictionaries defined in PREDEFINED_DICTIONARY_NAME.
void drawCharucoDiamond(const Ptr< Dictionary > &dictionary, Vec4i ids, int squareLength, int markerLength, OutputArray img, int marginSize=0, int borderBits=1)
Draw a ChArUco Diamond marker.
@ DICT_6X6_250
Definition: dictionary.hpp:152
std::shared_ptr< _Tp > Ptr
Definition: cvstd_wrapper.hpp:23

This will create a diamond marker image with a square size of 200 pixels and a marker size of 120 pixels. The marker ids are given in the second parameter as a Vec4i object. The order of the marker ids in the diamond layout are the same as in a standard ChArUco board, i.e. top, left, right and bottom.

The image produced will be:

A full working example is included in the create_diamond.cpp inside the module samples folder.

Note: The samples now take input via commandline via the OpenCV Commandline Parser. For this file the example parameters will look like

"_path_/mydiamond.png" -sl=200 -ml=120 -d=10 -ids=45,68,28,74

ChArUco Diamond Detection

As in most cases, the detection of diamond markers requires a previous detection of ArUco markers. After detecting markers, diamond are detected using the detectCharucoDiamond() function:

cv::Mat inputImage;
float squareLength = 0.40;
float markerLength = 0.25;
...
std::vector<int> markerIds;
std::vector<std::vector< cv::Point2f>> markerCorners;
// detect ArUco markers
cv::aruco::detectMarkers(inputImage, dictionary, markerCorners, markerIds);
std::vector<cv::Vec4i> diamondIds;
std::vector<std::vector<cv::Point2f>> diamondCorners;
// detect diamon diamonds
cv::aruco::detectCharucoDiamond(inputImage, markerCorners, markerIds, squareLength / markerLength, diamondCorners, diamondIds);
void detectCharucoDiamond(InputArray image, InputArrayOfArrays markerCorners, InputArray markerIds, float squareMarkerLengthRate, OutputArrayOfArrays diamondCorners, OutputArray diamondIds, InputArray cameraMatrix=noArray(), InputArray distCoeffs=noArray())
Detect ChArUco Diamond markers.
void detectMarkers(InputArray image, const Ptr< Dictionary > &dictionary, OutputArrayOfArrays corners, OutputArray ids, const Ptr< DetectorParameters > &parameters=DetectorParameters::create(), OutputArrayOfArrays rejectedImgPoints=noArray(), InputArray cameraMatrix=noArray(), InputArray distCoeff=noArray())
Basic marker detection.

The detectCharucoDiamond() function receives the original image and the previous detected marker corners and ids. The input image is necessary to perform subpixel refinement in the ChArUco corners. It also receives the rate between the square size and the marker sizes which is required for both, detecting the diamond from the relative positions of the markers and interpolating the ChArUco corners.

The function returns the detected diamonds in two parameters. The first parameter, diamondCorners, is an array containing all the four corners of each detected diamond. Its format is similar to the detected corners by the detectMarkers() function and, for each diamond, the corners are represented in the same order than in the ArUco markers, i.e. clockwise order starting with the top-left corner. The second returned parameter, diamondIds, contains all the ids of the returned diamond corners in diamondCorners. Each id is actually an array of 4 integers that can be represented with Vec4i.

The detected diamond can be visualized using the function drawDetectedDiamonds() which simply receives the image and the diamond corners and ids:

...
std::vector<cv::Vec4i> diamondIds;
std::vector<std::vector<cv::Point2f>> diamondCorners;
cv::aruco::detectCharucoDiamond(inputImage, markerCorners, markerIds, squareLength / markerLength, diamondCorners, diamondIds);
cv::aruco::drawDetectedDiamonds(inputImage, diamondCorners, diamondIds);
void drawDetectedDiamonds(InputOutputArray image, InputArrayOfArrays diamondCorners, InputArray diamondIds=noArray(), Scalar borderColor=Scalar(0, 0, 255))
Draw a set of detected ChArUco Diamond markers.

The result is the same that the one produced by drawDetectedMarkers(), but printing the four ids of the diamond:

A full working example is included in the detect_diamonds.cpp inside the module samples folder.

Note: The samples now take input via commandline via the OpenCV Commandline Parser. For this file the example parameters will look like

-c="_path_/calib.txt" -dp="_path_/detector_params.yml" -sl=0.04 -ml=0.02 -d=10

ChArUco Diamond Pose Estimation

Since a ChArUco diamond is represented by its four corners, its pose can be estimated in the same way than in a single ArUco marker, i.e. using the estimatePoseSingleMarkers() function. For instance:

...
std::vector<cv::Vec4i> diamondIds;
std::vector<std::vector<cv::Point2f>> diamondCorners;
// detect diamon diamonds
cv::aruco::detectCharucoDiamond(inputImage, markerCorners, markerIds, squareLength / markerLength, diamondCorners, diamondIds);
// estimate poses
std::vector<cv::Vec3d> rvecs, tvecs;
cv::aruco::estimatePoseSingleMarkers(diamondCorners, squareLength, camMatrix, distCoeffs, rvecs, tvecs);
// draw axis
for(unsigned int i=0; i<rvecs.size(); i++)
cv::aruco::drawAxis(inputImage, camMatrix, distCoeffs, rvecs[i], tvecs[i], axisLength);
void drawAxis(InputOutputArray image, InputArray cameraMatrix, InputArray distCoeffs, InputArray rvec, InputArray tvec, float length)
Draw coordinate system axis from pose estimation.
void estimatePoseSingleMarkers(InputArrayOfArrays corners, float markerLength, InputArray cameraMatrix, InputArray distCoeffs, OutputArray rvecs, OutputArray tvecs, OutputArray _objPoints=noArray())
Pose estimation for single markers.

The function will obtain the rotation and translation vector for each of the diamond marker and store them in rvecs and tvecs. Note that the diamond corners are a chessboard square corners and thus, the square length has to be provided for pose estimation, and not the marker length. Camera calibration parameters are also required.

Finally, an axis can be drawn to check the estimated pose is correct using drawAxis():

The coordinate system of the diamond pose will be in the center of the marker with the Z axis pointing out, as in a simple ArUco marker pose estimation.

Sample video:

A full working example is included in the detect_diamonds.cpp inside the module samples folder.

Note: The samples now take input via commandline via the OpenCV Commandline Parser. For this file the example parameters will look like

-c="_output path_/calib.txt" -dp="_path_/detector_params.yml" -sl=0.04 -ml=0.02 -d=10