OpenCV  4.0.0-beta
Open Source Computer Vision
Classes | Enumerations | Functions
ArUco Marker Detection

Classes

class  cv::aruco::Board
 Board of markers. More...
 
class  cv::aruco::CharucoBoard
 ChArUco board Specific class for ChArUco boards. A ChArUco board is a planar board where the markers are placed inside the white squares of a chessboard. The benefits of ChArUco boards is that they provide both, ArUco markers versatility and chessboard corner precision, which is important for calibration and pose estimation. This class also allows the easy creation and drawing of ChArUco boards. More...
 
struct  cv::aruco::DetectorParameters
 Parameters for the detectMarker process: More...
 
class  cv::aruco::Dictionary
 Dictionary/Set of markers. It contains the inner codification. More...
 
class  cv::aruco::GridBoard
 Planar board with grid arrangement of markers More common type of board. All markers are placed in the same plane in a grid arrangment. The board can be drawn using drawPlanarBoard() function (. More...
 

Enumerations

enum  cv::aruco::CornerRefineMethod {
  cv::aruco::CORNER_REFINE_NONE,
  cv::aruco::CORNER_REFINE_SUBPIX,
  cv::aruco::CORNER_REFINE_CONTOUR,
  cv::aruco::CORNER_REFINE_APRILTAG
}
 
enum  cv::aruco::PREDEFINED_DICTIONARY_NAME {
  cv::aruco::DICT_4X4_50 = 0,
  cv::aruco::DICT_4X4_100,
  cv::aruco::DICT_4X4_250,
  cv::aruco::DICT_4X4_1000,
  cv::aruco::DICT_5X5_50,
  cv::aruco::DICT_5X5_100,
  cv::aruco::DICT_5X5_250,
  cv::aruco::DICT_5X5_1000,
  cv::aruco::DICT_6X6_50,
  cv::aruco::DICT_6X6_100,
  cv::aruco::DICT_6X6_250,
  cv::aruco::DICT_6X6_1000,
  cv::aruco::DICT_7X7_50,
  cv::aruco::DICT_7X7_100,
  cv::aruco::DICT_7X7_250,
  cv::aruco::DICT_7X7_1000,
  cv::aruco::DICT_ARUCO_ORIGINAL,
  cv::aruco::DICT_APRILTAG_16h5,
  cv::aruco::DICT_APRILTAG_25h9,
  cv::aruco::DICT_APRILTAG_36h10,
  cv::aruco::DICT_APRILTAG_36h11
}
 Predefined markers dictionaries/sets Each dictionary indicates the number of bits and the number of markers contained. More...
 

Functions

void cv::aruco::_drawPlanarBoardImpl (Board *board, Size outSize, OutputArray img, int marginSize=0, int borderBits=1)
 Implementation of drawPlanarBoard that accepts a raw Board pointer. More...
 
double cv::aruco::calibrateCameraAruco (InputArrayOfArrays corners, InputArray ids, InputArray counter, const Ptr< Board > &board, Size imageSize, InputOutputArray cameraMatrix, InputOutputArray distCoeffs, OutputArrayOfArrays rvecs, OutputArrayOfArrays tvecs, OutputArray stdDeviationsIntrinsics, OutputArray stdDeviationsExtrinsics, OutputArray perViewErrors, int flags=0, TermCriteria criteria=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 30, DBL_EPSILON))
 Calibrate a camera using aruco markers. More...
 
double cv::aruco::calibrateCameraAruco (InputArrayOfArrays corners, InputArray ids, InputArray counter, const Ptr< Board > &board, Size imageSize, InputOutputArray cameraMatrix, InputOutputArray distCoeffs, OutputArrayOfArrays rvecs=noArray(), OutputArrayOfArrays tvecs=noArray(), int flags=0, TermCriteria criteria=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 30, DBL_EPSILON))
 It's the same function as calibrateCameraAruco but without calibration error estimation. More...
 
double cv::aruco::calibrateCameraCharuco (InputArrayOfArrays charucoCorners, InputArrayOfArrays charucoIds, const Ptr< CharucoBoard > &board, Size imageSize, InputOutputArray cameraMatrix, InputOutputArray distCoeffs, OutputArrayOfArrays rvecs, OutputArrayOfArrays tvecs, OutputArray stdDeviationsIntrinsics, OutputArray stdDeviationsExtrinsics, OutputArray perViewErrors, int flags=0, TermCriteria criteria=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 30, DBL_EPSILON))
 Calibrate a camera using Charuco corners. More...
 
double cv::aruco::calibrateCameraCharuco (InputArrayOfArrays charucoCorners, InputArrayOfArrays charucoIds, const Ptr< CharucoBoard > &board, Size imageSize, InputOutputArray cameraMatrix, InputOutputArray distCoeffs, OutputArrayOfArrays rvecs=noArray(), OutputArrayOfArrays tvecs=noArray(), int flags=0, TermCriteria criteria=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 30, DBL_EPSILON))
 It's the same function as calibrateCameraCharuco but without calibration error estimation. More...
 
void cv::aruco::detectCharucoDiamond (InputArray image, InputArrayOfArrays markerCorners, InputArray markerIds, float squareMarkerLengthRate, OutputArrayOfArrays diamondCorners, OutputArray diamondIds, InputArray cameraMatrix=noArray(), InputArray distCoeffs=noArray())
 Detect ChArUco Diamond markers. More...
 
void cv::aruco::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. More...
 
void cv::aruco::drawAxis (InputOutputArray image, InputArray cameraMatrix, InputArray distCoeffs, InputArray rvec, InputArray tvec, float length)
 Draw coordinate system axis from pose estimation. More...
 
void cv::aruco::drawCharucoDiamond (const Ptr< Dictionary > &dictionary, Vec4i ids, int squareLength, int markerLength, OutputArray img, int marginSize=0, int borderBits=1)
 Draw a ChArUco Diamond marker. More...
 
void cv::aruco::drawDetectedCornersCharuco (InputOutputArray image, InputArray charucoCorners, InputArray charucoIds=noArray(), Scalar cornerColor=Scalar(255, 0, 0))
 Draws a set of Charuco corners. More...
 
void cv::aruco::drawDetectedDiamonds (InputOutputArray image, InputArrayOfArrays diamondCorners, InputArray diamondIds=noArray(), Scalar borderColor=Scalar(0, 0, 255))
 Draw a set of detected ChArUco Diamond markers. More...
 
void cv::aruco::drawDetectedMarkers (InputOutputArray image, InputArrayOfArrays corners, InputArray ids=noArray(), Scalar borderColor=Scalar(0, 255, 0))
 Draw detected markers in image. More...
 
void cv::aruco::drawMarker (const Ptr< Dictionary > &dictionary, int id, int sidePixels, OutputArray img, int borderBits=1)
 Draw a canonical marker image. More...
 
void cv::aruco::drawPlanarBoard (const Ptr< Board > &board, Size outSize, OutputArray img, int marginSize=0, int borderBits=1)
 Draw a planar board. More...
 
int cv::aruco::estimatePoseBoard (InputArrayOfArrays corners, InputArray ids, const Ptr< Board > &board, InputArray cameraMatrix, InputArray distCoeffs, OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess=false)
 Pose estimation for a board of markers. More...
 
bool cv::aruco::estimatePoseCharucoBoard (InputArray charucoCorners, InputArray charucoIds, const Ptr< CharucoBoard > &board, InputArray cameraMatrix, InputArray distCoeffs, OutputArray rvec, OutputArray tvec, bool useExtrinsicGuess=false)
 Pose estimation for a ChArUco board given some of their corners. More...
 
void cv::aruco::estimatePoseSingleMarkers (InputArrayOfArrays corners, float markerLength, InputArray cameraMatrix, InputArray distCoeffs, OutputArray rvecs, OutputArray tvecs, OutputArray _objPoints=noArray())
 Pose estimation for single markers. More...
 
Ptr< Dictionarycv::aruco::generateCustomDictionary (int nMarkers, int markerSize, int randomSeed=0)
 
Ptr< Dictionarycv::aruco::generateCustomDictionary (int nMarkers, int markerSize, const Ptr< Dictionary > &baseDictionary, int randomSeed=0)
 Generates a new customizable marker dictionary. More...
 
void cv::aruco::getBoardObjectAndImagePoints (const Ptr< Board > &board, InputArrayOfArrays detectedCorners, InputArray detectedIds, OutputArray objPoints, OutputArray imgPoints)
 Given a board configuration and a set of detected markers, returns the corresponding image points and object points to call solvePnP. More...
 
Ptr< Dictionarycv::aruco::getPredefinedDictionary (PREDEFINED_DICTIONARY_NAME name)
 Returns one of the predefined dictionaries defined in PREDEFINED_DICTIONARY_NAME. More...
 
Ptr< Dictionarycv::aruco::getPredefinedDictionary (int dict)
 Returns one of the predefined dictionaries referenced by DICT_*. More...
 
int cv::aruco::interpolateCornersCharuco (InputArrayOfArrays markerCorners, InputArray markerIds, InputArray image, const Ptr< CharucoBoard > &board, OutputArray charucoCorners, OutputArray charucoIds, InputArray cameraMatrix=noArray(), InputArray distCoeffs=noArray(), int minMarkers=2)
 Interpolate position of ChArUco board corners. More...
 
void cv::aruco::refineDetectedMarkers (InputArray image, const Ptr< Board > &board, InputOutputArrayOfArrays detectedCorners, InputOutputArray detectedIds, InputOutputArrayOfArrays rejectedCorners, InputArray cameraMatrix=noArray(), InputArray distCoeffs=noArray(), float minRepDistance=10.f, float errorCorrectionRate=3.f, bool checkAllOrders=true, OutputArray recoveredIdxs=noArray(), const Ptr< DetectorParameters > &parameters=DetectorParameters::create())
 Refind not detected markers based on the already detected and the board layout. More...
 

Detailed Description

This module is dedicated to square fiducial markers (also known as Augmented Reality Markers) These markers are useful for easy, fast and robust camera pose estimation.ç

The main functionalities are:

The implementation is based on the ArUco Library by R. Muñoz-Salinas and S. Garrido-Jurado [69].

Markers can also be detected based on the AprilTag 2 [211] fiducial detection method.

See also
S. Garrido-Jurado, R. Muñoz-Salinas, F. J. Madrid-Cuevas, and M. J. Marín-Jiménez. 2014. "Automatic generation and detection of highly reliable fiducial markers under occlusion". Pattern Recogn. 47, 6 (June 2014), 2280-2292. DOI=10.1016/j.patcog.2014.01.005
http://www.uco.es/investiga/grupos/ava/node/26

This module has been originally developed by Sergio Garrido-Jurado as a project for Google Summer of Code 2015 (GSoC 15).

Enumeration Type Documentation

§ CornerRefineMethod

Enumerator
CORNER_REFINE_NONE 
Python: cv.aruco.CORNER_REFINE_NONE

Tag and corners detection based on the ArUco approach.

CORNER_REFINE_SUBPIX 
Python: cv.aruco.CORNER_REFINE_SUBPIX

ArUco approach and refine the corners locations using corner subpixel accuracy.

CORNER_REFINE_CONTOUR 
Python: cv.aruco.CORNER_REFINE_CONTOUR

ArUco approach and refine the corners locations using the contour-points line fitting.

CORNER_REFINE_APRILTAG 
Python: cv.aruco.CORNER_REFINE_APRILTAG

Tag and corners detection based on the AprilTag 2 approach [211].

§ PREDEFINED_DICTIONARY_NAME

Predefined markers dictionaries/sets Each dictionary indicates the number of bits and the number of markers contained.

  • DICT_ARUCO_ORIGINAL: standard ArUco Library Markers. 1024 markers, 5x5 bits, 0 minimum distance
Enumerator
DICT_4X4_50 
Python: cv.aruco.DICT_4X4_50
DICT_4X4_100 
Python: cv.aruco.DICT_4X4_100
DICT_4X4_250 
Python: cv.aruco.DICT_4X4_250
DICT_4X4_1000 
Python: cv.aruco.DICT_4X4_1000
DICT_5X5_50 
Python: cv.aruco.DICT_5X5_50
DICT_5X5_100 
Python: cv.aruco.DICT_5X5_100
DICT_5X5_250 
Python: cv.aruco.DICT_5X5_250
DICT_5X5_1000 
Python: cv.aruco.DICT_5X5_1000
DICT_6X6_50 
Python: cv.aruco.DICT_6X6_50
DICT_6X6_100 
Python: cv.aruco.DICT_6X6_100
DICT_6X6_250 
Python: cv.aruco.DICT_6X6_250
DICT_6X6_1000 
Python: cv.aruco.DICT_6X6_1000
DICT_7X7_50 
Python: cv.aruco.DICT_7X7_50
DICT_7X7_100 
Python: cv.aruco.DICT_7X7_100
DICT_7X7_250 
Python: cv.aruco.DICT_7X7_250
DICT_7X7_1000 
Python: cv.aruco.DICT_7X7_1000
DICT_ARUCO_ORIGINAL 
Python: cv.aruco.DICT_ARUCO_ORIGINAL
DICT_APRILTAG_16h5 
Python: cv.aruco.DICT_APRILTAG_16h5

4x4 bits, minimum hamming distance between any two codes = 5, 30 codes

DICT_APRILTAG_25h9 
Python: cv.aruco.DICT_APRILTAG_25h9

5x5 bits, minimum hamming distance between any two codes = 9, 35 codes

DICT_APRILTAG_36h10 
Python: cv.aruco.DICT_APRILTAG_36h10

6x6 bits, minimum hamming distance between any two codes = 10, 2320 codes

DICT_APRILTAG_36h11 
Python: cv.aruco.DICT_APRILTAG_36h11

6x6 bits, minimum hamming distance between any two codes = 11, 587 codes

Function Documentation

§ _drawPlanarBoardImpl()

void cv::aruco::_drawPlanarBoardImpl ( Board board,
Size  outSize,
OutputArray  img,
int  marginSize = 0,
int  borderBits = 1 
)

Implementation of drawPlanarBoard that accepts a raw Board pointer.

§ calibrateCameraAruco() [1/2]

double cv::aruco::calibrateCameraAruco ( InputArrayOfArrays  corners,
InputArray  ids,
InputArray  counter,
const Ptr< Board > &  board,
Size  imageSize,
InputOutputArray  cameraMatrix,
InputOutputArray  distCoeffs,
OutputArrayOfArrays  rvecs,
OutputArrayOfArrays  tvecs,
OutputArray  stdDeviationsIntrinsics,
OutputArray  stdDeviationsExtrinsics,
OutputArray  perViewErrors,
int  flags = 0,
TermCriteria  criteria = TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 30, DBL_EPSILON) 
)
Python:
retval, cameraMatrix, distCoeffs, rvecs, tvecs=cv.aruco.calibrateCameraAruco(corners, ids, counter, board, imageSize, cameraMatrix, distCoeffs[, rvecs[, tvecs[, flags[, criteria]]]])
retval, cameraMatrix, distCoeffs, rvecs, tvecs, stdDeviationsIntrinsics, stdDeviationsExtrinsics, perViewErrors=cv.aruco.calibrateCameraArucoExtended(corners, ids, counter, board, imageSize, cameraMatrix, distCoeffs[, rvecs[, tvecs[, stdDeviationsIntrinsics[, stdDeviationsExtrinsics[, perViewErrors[, flags[, criteria]]]]]]])

Calibrate a camera using aruco markers.

Parameters
cornersvector of detected marker corners in all frames. The corners should have the same format returned by detectMarkers (see detectMarkers).
idslist of identifiers for each marker in corners
counternumber of markers in each frame so that corners and ids can be split
boardMarker Board layout
imageSizeSize of the image used only to initialize the intrinsic camera matrix.
cameraMatrixOutput 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\) . If CV_CALIB_USE_INTRINSIC_GUESS and/or CV_CALIB_FIX_ASPECT_RATIO are specified, some or all of fx, fy, cx, cy must be initialized before calling the function.
distCoeffsOutput vector of distortion coefficients \((k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])\) of 4, 5, 8 or 12 elements
rvecsOutput vector of rotation vectors (see Rodrigues ) estimated for each board view (e.g. std::vector<cv::Mat>>). That is, each k-th rotation vector together with the corresponding k-th translation vector (see the next output parameter description) brings the board pattern from the model coordinate space (in which object points are specified) to the world coordinate space, that is, a real position of the board pattern in the k-th pattern view (k=0.. M -1).
tvecsOutput vector of translation vectors estimated for each pattern view.
stdDeviationsIntrinsicsOutput vector of standard deviations estimated for intrinsic parameters. Order of deviations values: \((f_x, f_y, c_x, c_y, k_1, k_2, p_1, p_2, k_3, k_4, k_5, k_6 , s_1, s_2, s_3, s_4, \tau_x, \tau_y)\) If one of parameters is not estimated, it's deviation is equals to zero.
stdDeviationsExtrinsicsOutput vector of standard deviations estimated for extrinsic parameters. Order of deviations values: \((R_1, T_1, \dotsc , R_M, T_M)\) where M is number of pattern views, \(R_i, T_i\) are concatenated 1x3 vectors.
perViewErrorsOutput vector of average re-projection errors estimated for each pattern view.
flagsflags Different flags for the calibration process (see calibrateCamera for details).
criteriaTermination criteria for the iterative optimization algorithm.

This function calibrates a camera using an Aruco Board. The function receives a list of detected markers from several views of the Board. The process is similar to the chessboard calibration in calibrateCamera(). The function returns the final re-projection error.

§ calibrateCameraAruco() [2/2]

double cv::aruco::calibrateCameraAruco ( InputArrayOfArrays  corners,
InputArray  ids,
InputArray  counter,
const Ptr< Board > &  board,
Size  imageSize,
InputOutputArray  cameraMatrix,
InputOutputArray  distCoeffs,
OutputArrayOfArrays  rvecs = noArray(),
OutputArrayOfArrays  tvecs = noArray(),
int  flags = 0,
TermCriteria  criteria = TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 30, DBL_EPSILON) 
)
Python:
retval, cameraMatrix, distCoeffs, rvecs, tvecs=cv.aruco.calibrateCameraAruco(corners, ids, counter, board, imageSize, cameraMatrix, distCoeffs[, rvecs[, tvecs[, flags[, criteria]]]])
retval, cameraMatrix, distCoeffs, rvecs, tvecs, stdDeviationsIntrinsics, stdDeviationsExtrinsics, perViewErrors=cv.aruco.calibrateCameraArucoExtended(corners, ids, counter, board, imageSize, cameraMatrix, distCoeffs[, rvecs[, tvecs[, stdDeviationsIntrinsics[, stdDeviationsExtrinsics[, perViewErrors[, flags[, criteria]]]]]]])

It's the same function as calibrateCameraAruco but without calibration error estimation.

§ calibrateCameraCharuco() [1/2]

double cv::aruco::calibrateCameraCharuco ( InputArrayOfArrays  charucoCorners,
InputArrayOfArrays  charucoIds,
const Ptr< CharucoBoard > &  board,
Size  imageSize,
InputOutputArray  cameraMatrix,
InputOutputArray  distCoeffs,
OutputArrayOfArrays  rvecs,
OutputArrayOfArrays  tvecs,
OutputArray  stdDeviationsIntrinsics,
OutputArray  stdDeviationsExtrinsics,
OutputArray  perViewErrors,
int  flags = 0,
TermCriteria  criteria = TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 30, DBL_EPSILON) 
)
Python:
retval, cameraMatrix, distCoeffs, rvecs, tvecs=cv.aruco.calibrateCameraCharuco(charucoCorners, charucoIds, board, imageSize, cameraMatrix, distCoeffs[, rvecs[, tvecs[, flags[, criteria]]]])
retval, cameraMatrix, distCoeffs, rvecs, tvecs, stdDeviationsIntrinsics, stdDeviationsExtrinsics, perViewErrors=cv.aruco.calibrateCameraCharucoExtended(charucoCorners, charucoIds, board, imageSize, cameraMatrix, distCoeffs[, rvecs[, tvecs[, stdDeviationsIntrinsics[, stdDeviationsExtrinsics[, perViewErrors[, flags[, criteria]]]]]]])

Calibrate a camera using Charuco corners.

Parameters
charucoCornersvector of detected charuco corners per frame
charucoIdslist of identifiers for each corner in charucoCorners per frame
boardMarker Board layout
imageSizeinput image size
cameraMatrixOutput 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\) . If CV_CALIB_USE_INTRINSIC_GUESS and/or CV_CALIB_FIX_ASPECT_RATIO are specified, some or all of fx, fy, cx, cy must be initialized before calling the function.
distCoeffsOutput vector of distortion coefficients \((k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])\) of 4, 5, 8 or 12 elements
rvecsOutput vector of rotation vectors (see Rodrigues ) estimated for each board view (e.g. std::vector<cv::Mat>>). That is, each k-th rotation vector together with the corresponding k-th translation vector (see the next output parameter description) brings the board pattern from the model coordinate space (in which object points are specified) to the world coordinate space, that is, a real position of the board pattern in the k-th pattern view (k=0.. M -1).
tvecsOutput vector of translation vectors estimated for each pattern view.
stdDeviationsIntrinsicsOutput vector of standard deviations estimated for intrinsic parameters. Order of deviations values: \((f_x, f_y, c_x, c_y, k_1, k_2, p_1, p_2, k_3, k_4, k_5, k_6 , s_1, s_2, s_3, s_4, \tau_x, \tau_y)\) If one of parameters is not estimated, it's deviation is equals to zero.
stdDeviationsExtrinsicsOutput vector of standard deviations estimated for extrinsic parameters. Order of deviations values: \((R_1, T_1, \dotsc , R_M, T_M)\) where M is number of pattern views, \(R_i, T_i\) are concatenated 1x3 vectors.
perViewErrorsOutput vector of average re-projection errors estimated for each pattern view.
flagsflags Different flags for the calibration process (see calibrateCamera for details).
criteriaTermination criteria for the iterative optimization algorithm.

This function calibrates a camera using a set of corners of a Charuco Board. The function receives a list of detected corners and its identifiers from several views of the Board. The function returns the final re-projection error.

§ calibrateCameraCharuco() [2/2]

double cv::aruco::calibrateCameraCharuco ( InputArrayOfArrays  charucoCorners,
InputArrayOfArrays  charucoIds,
const Ptr< CharucoBoard > &  board,
Size  imageSize,
InputOutputArray  cameraMatrix,
InputOutputArray  distCoeffs,
OutputArrayOfArrays  rvecs = noArray(),
OutputArrayOfArrays  tvecs = noArray(),
int  flags = 0,
TermCriteria  criteria = TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, 30, DBL_EPSILON) 
)
Python:
retval, cameraMatrix, distCoeffs, rvecs, tvecs=cv.aruco.calibrateCameraCharuco(charucoCorners, charucoIds, board, imageSize, cameraMatrix, distCoeffs[, rvecs[, tvecs[, flags[, criteria]]]])
retval, cameraMatrix, distCoeffs, rvecs, tvecs, stdDeviationsIntrinsics, stdDeviationsExtrinsics, perViewErrors=cv.aruco.calibrateCameraCharucoExtended(charucoCorners, charucoIds, board, imageSize, cameraMatrix, distCoeffs[, rvecs[, tvecs[, stdDeviationsIntrinsics[, stdDeviationsExtrinsics[, perViewErrors[, flags[, criteria]]]]]]])

It's the same function as calibrateCameraCharuco but without calibration error estimation.

§ detectCharucoDiamond()

void cv::aruco::detectCharucoDiamond ( InputArray  image,
InputArrayOfArrays  markerCorners,
InputArray  markerIds,
float  squareMarkerLengthRate,
OutputArrayOfArrays  diamondCorners,
OutputArray  diamondIds,
InputArray  cameraMatrix = noArray(),
InputArray  distCoeffs = noArray() 
)
Python:
diamondCorners, diamondIds=cv.aruco.detectCharucoDiamond(image, markerCorners, markerIds, squareMarkerLengthRate[, diamondCorners[, diamondIds[, cameraMatrix[, distCoeffs]]]])

Detect ChArUco Diamond markers.

Parameters
imageinput image necessary for corner subpixel.
markerCornerslist of detected marker corners from detectMarkers function.
markerIdslist of marker ids in markerCorners.
squareMarkerLengthRaterate between square and marker length: squareMarkerLengthRate = squareLength/markerLength. The real units are not necessary.
diamondCornersoutput list of detected diamond corners (4 corners per diamond). The order is the same than in marker corners: top left, top right, bottom right and bottom left. Similar format than the corners returned by detectMarkers (e.g std::vector<std::vector<cv::Point2f> > ).
diamondIdsids of the diamonds in diamondCorners. The id of each diamond is in fact of type Vec4i, so each diamond has 4 ids, which are the ids of the aruco markers composing the diamond.
cameraMatrixOptional camera calibration matrix.
distCoeffsOptional camera distortion coefficients.

This function detects Diamond markers from the previous detected ArUco markers. The diamonds are returned in the diamondCorners and diamondIds parameters. If camera calibration parameters are provided, the diamond search is based on reprojection. If not, diamond search is based on homography. Homography is faster than reprojection but can slightly reduce the detection rate.

§ detectMarkers()

void cv::aruco::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() 
)
Python:
corners, ids, rejectedImgPoints=cv.aruco.detectMarkers(image, dictionary[, corners[, ids[, parameters[, rejectedImgPoints[, cameraMatrix[, distCoeff]]]]]])

Basic marker detection.

Parameters
imageinput image
dictionaryindicates the type of markers that will be searched
cornersvector of detected marker corners. For each marker, its four corners are provided, (e.g std::vector<std::vector<cv::Point2f> > ). For N detected markers, the dimensions of this array is Nx4. The order of the corners is clockwise.
idsvector of identifiers of the detected markers. The identifier is of type int (e.g. std::vector<int>). For N detected markers, the size of ids is also N. The identifiers have the same order than the markers in the imgPoints array.
parametersmarker detection parameters
rejectedImgPointscontains the imgPoints of those squares whose inner code has not a correct codification. Useful for debugging purposes.
cameraMatrixoptional input 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeffoptional vector of distortion coefficients \((k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])\) of 4, 5, 8 or 12 elements

Performs marker detection in the input image. Only markers included in the specific dictionary are searched. For each detected marker, it returns the 2D position of its corner in the image and its corresponding identifier. Note that this function does not perform pose estimation.

See also
estimatePoseSingleMarkers, estimatePoseBoard

§ drawAxis()

void cv::aruco::drawAxis ( InputOutputArray  image,
InputArray  cameraMatrix,
InputArray  distCoeffs,
InputArray  rvec,
InputArray  tvec,
float  length 
)
Python:
image=cv.aruco.drawAxis(image, cameraMatrix, distCoeffs, rvec, tvec, length)

Draw coordinate system axis from pose estimation.

Parameters
imageinput/output image. It must have 1 or 3 channels. The number of channels is not altered.
cameraMatrixinput 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeffsvector of distortion coefficients \((k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])\) of 4, 5, 8 or 12 elements
rvecrotation vector of the coordinate system that will be drawn. (
See also
Rodrigues).
Parameters
tvectranslation vector of the coordinate system that will be drawn.
lengthlength of the painted axis in the same unit than tvec (usually in meters)

Given the pose estimation of a marker or board, this function draws the axis of the world coordinate system, i.e. the system centered on the marker/board. Useful for debugging purposes.

Examples:
samples/cpp/tutorial_code/features2D/Homography/homography_from_camera_displacement.cpp, samples/cpp/tutorial_code/features2D/Homography/pose_from_homography.cpp, and samples/cpp/tutorial_code/ml/introduction_to_pca/introduction_to_pca.cpp.

§ drawCharucoDiamond()

void cv::aruco::drawCharucoDiamond ( const Ptr< Dictionary > &  dictionary,
Vec4i  ids,
int  squareLength,
int  markerLength,
OutputArray  img,
int  marginSize = 0,
int  borderBits = 1 
)

Draw a ChArUco Diamond marker.

Parameters
dictionarydictionary of markers indicating the type of markers.
idslist of 4 ids for each ArUco marker in the ChArUco marker.
squareLengthsize of the chessboard squares in pixels.
markerLengthsize of the markers in pixels.
imgoutput image with the marker. The size of this image will be 3*squareLength + 2*marginSize,.
marginSizeminimum margins (in pixels) of the marker in the output image
borderBitswidth of the marker borders.

This function return the image of a ChArUco marker, ready to be printed.

§ drawDetectedCornersCharuco()

void cv::aruco::drawDetectedCornersCharuco ( InputOutputArray  image,
InputArray  charucoCorners,
InputArray  charucoIds = noArray(),
Scalar  cornerColor = Scalar(255, 0, 0) 
)
Python:
image=cv.aruco.drawDetectedCornersCharuco(image, charucoCorners[, charucoIds[, cornerColor]])

Draws a set of Charuco corners.

Parameters
imageinput/output image. It must have 1 or 3 channels. The number of channels is not altered.
charucoCornersvector of detected charuco corners
charucoIdslist of identifiers for each corner in charucoCorners
cornerColorcolor of the square surrounding each corner

This function draws a set of detected Charuco corners. If identifiers vector is provided, it also draws the id of each corner.

§ drawDetectedDiamonds()

void cv::aruco::drawDetectedDiamonds ( InputOutputArray  image,
InputArrayOfArrays  diamondCorners,
InputArray  diamondIds = noArray(),
Scalar  borderColor = Scalar(0, 0, 255) 
)
Python:
image=cv.aruco.drawDetectedDiamonds(image, diamondCorners[, diamondIds[, borderColor]])

Draw a set of detected ChArUco Diamond markers.

Parameters
imageinput/output image. It must have 1 or 3 channels. The number of channels is not altered.
diamondCornerspositions of diamond corners in the same format returned by detectCharucoDiamond(). (e.g std::vector<std::vector<cv::Point2f> > ). For N detected markers, the dimensions of this array should be Nx4. The order of the corners should be clockwise.
diamondIdsvector of identifiers for diamonds in diamondCorners, in the same format returned by detectCharucoDiamond() (e.g. std::vector<Vec4i>). Optional, if not provided, ids are not painted.
borderColorcolor of marker borders. Rest of colors (text color and first corner color) are calculated based on this one.

Given an array of detected diamonds, this functions draws them in the image. The marker borders are painted and the markers identifiers if provided. Useful for debugging purposes.

§ drawDetectedMarkers()

void cv::aruco::drawDetectedMarkers ( InputOutputArray  image,
InputArrayOfArrays  corners,
InputArray  ids = noArray(),
Scalar  borderColor = Scalar(0, 255, 0) 
)
Python:
image=cv.aruco.drawDetectedMarkers(image, corners[, ids[, borderColor]])

Draw detected markers in image.

Parameters
imageinput/output image. It must have 1 or 3 channels. The number of channels is not altered.
cornerspositions of marker corners on input image. (e.g std::vector<std::vector<cv::Point2f> > ). For N detected markers, the dimensions of this array should be Nx4. The order of the corners should be clockwise.
idsvector of identifiers for markers in markersCorners . Optional, if not provided, ids are not painted.
borderColorcolor of marker borders. Rest of colors (text color and first corner color) are calculated based on this one to improve visualization.

Given an array of detected marker corners and its corresponding ids, this functions draws the markers in the image. The marker borders are painted and the markers identifiers if provided. Useful for debugging purposes.

§ drawMarker()

void cv::aruco::drawMarker ( const Ptr< Dictionary > &  dictionary,
int  id,
int  sidePixels,
OutputArray  img,
int  borderBits = 1 
)
Python:
img=cv.aruco.drawMarker(dictionary, id, sidePixels[, img[, borderBits]])

Draw a canonical marker image.

Parameters
dictionarydictionary of markers indicating the type of markers
ididentifier of the marker that will be returned. It has to be a valid id in the specified dictionary.
sidePixelssize of the image in pixels
imgoutput image with the marker
borderBitswidth of the marker border.

This function returns a marker image in its canonical form (i.e. ready to be printed)

§ drawPlanarBoard()

void cv::aruco::drawPlanarBoard ( const Ptr< Board > &  board,
Size  outSize,
OutputArray  img,
int  marginSize = 0,
int  borderBits = 1 
)
Python:
img=cv.aruco.drawPlanarBoard(board, outSize[, img[, marginSize[, borderBits]]])

Draw a planar board.

See also
_drawPlanarBoardImpl
Parameters
boardlayout of the board that will be drawn. The board should be planar, z coordinate is ignored
outSizesize of the output image in pixels.
imgoutput image with the board. The size of this image will be outSize and the board will be on the center, keeping the board proportions.
marginSizeminimum margins (in pixels) of the board in the output image
borderBitswidth of the marker borders.

This function return the image of a planar board, ready to be printed. It assumes the Board layout specified is planar by ignoring the z coordinates of the object points.

§ estimatePoseBoard()

int cv::aruco::estimatePoseBoard ( InputArrayOfArrays  corners,
InputArray  ids,
const Ptr< Board > &  board,
InputArray  cameraMatrix,
InputArray  distCoeffs,
OutputArray  rvec,
OutputArray  tvec,
bool  useExtrinsicGuess = false 
)
Python:
retval, rvec, tvec=cv.aruco.estimatePoseBoard(corners, ids, board, cameraMatrix, distCoeffs[, rvec[, tvec[, useExtrinsicGuess]]])

Pose estimation for a board of markers.

Parameters
cornersvector of already detected markers corners. For each marker, its four corners are provided, (e.g std::vector<std::vector<cv::Point2f> > ). For N detected markers, the dimensions of this array should be Nx4. The order of the corners should be clockwise.
idslist of identifiers for each marker in corners
boardlayout of markers in the board. The layout is composed by the marker identifiers and the positions of each marker corner in the board reference system.
cameraMatrixinput 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeffsvector of distortion coefficients \((k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])\) of 4, 5, 8 or 12 elements
rvecOutput vector (e.g. cv::Mat) corresponding to the rotation vector of the board (see cv::Rodrigues). Used as initial guess if not empty.
tvecOutput vector (e.g. cv::Mat) corresponding to the translation vector of the board.
useExtrinsicGuessdefines whether initial guess for rvec and tvec will be used or not. Used as initial guess if not empty.

This function receives the detected markers and returns the pose of a marker board composed by those markers. A Board of marker has a single world coordinate system which is defined by the board layout. The returned transformation is the one that transforms points from the board coordinate system to the camera coordinate system. Input markers that are not included in the board layout are ignored. The function returns the number of markers from the input employed for the board pose estimation. Note that returning a 0 means the pose has not been estimated.

§ estimatePoseCharucoBoard()

bool cv::aruco::estimatePoseCharucoBoard ( InputArray  charucoCorners,
InputArray  charucoIds,
const Ptr< CharucoBoard > &  board,
InputArray  cameraMatrix,
InputArray  distCoeffs,
OutputArray  rvec,
OutputArray  tvec,
bool  useExtrinsicGuess = false 
)
Python:
retval, rvec, tvec=cv.aruco.estimatePoseCharucoBoard(charucoCorners, charucoIds, board, cameraMatrix, distCoeffs[, rvec[, tvec[, useExtrinsicGuess]]])

Pose estimation for a ChArUco board given some of their corners.

Parameters
charucoCornersvector of detected charuco corners
charucoIdslist of identifiers for each corner in charucoCorners
boardlayout of ChArUco board.
cameraMatrixinput 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeffsvector of distortion coefficients \((k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])\) of 4, 5, 8 or 12 elements
rvecOutput vector (e.g. cv::Mat) corresponding to the rotation vector of the board (see cv::Rodrigues).
tvecOutput vector (e.g. cv::Mat) corresponding to the translation vector of the board.
useExtrinsicGuessdefines whether initial guess for rvec and tvec will be used or not.

This function estimates a Charuco board pose from some detected corners. The function checks if the input corners are enough and valid to perform pose estimation. If pose estimation is valid, returns true, else returns false.

§ estimatePoseSingleMarkers()

void cv::aruco::estimatePoseSingleMarkers ( InputArrayOfArrays  corners,
float  markerLength,
InputArray  cameraMatrix,
InputArray  distCoeffs,
OutputArray  rvecs,
OutputArray  tvecs,
OutputArray  _objPoints = noArray() 
)
Python:
rvecs, tvecs, _objPoints=cv.aruco.estimatePoseSingleMarkers(corners, markerLength, cameraMatrix, distCoeffs[, rvecs[, tvecs[, _objPoints]]])

Pose estimation for single markers.

Parameters
cornersvector of already detected markers corners. For each marker, its four corners are provided, (e.g std::vector<std::vector<cv::Point2f> > ). For N detected markers, the dimensions of this array should be Nx4. The order of the corners should be clockwise.
See also
detectMarkers
Parameters
markerLengththe length of the markers' side. The returning translation vectors will be in the same unit. Normally, unit is meters.
cameraMatrixinput 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeffsvector of distortion coefficients \((k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])\) of 4, 5, 8 or 12 elements
rvecsarray of output rotation vectors (
See also
Rodrigues) (e.g. std::vector<cv::Vec3d>). Each element in rvecs corresponds to the specific marker in imgPoints.
Parameters
tvecsarray of output translation vectors (e.g. std::vector<cv::Vec3d>). Each element in tvecs corresponds to the specific marker in imgPoints.
_objPointsarray of object points of all the marker corners

This function receives the detected markers and returns their pose estimation respect to the camera individually. So for each marker, one rotation and translation vector is returned. The returned transformation is the one that transforms points from each marker coordinate system to the camera coordinate system. The marker corrdinate system is centered on the middle of the marker, with the Z axis perpendicular to the marker plane. The coordinates of the four corners of the marker in its own coordinate system are: (-markerLength/2, markerLength/2, 0), (markerLength/2, markerLength/2, 0), (markerLength/2, -markerLength/2, 0), (-markerLength/2, -markerLength/2, 0)

§ generateCustomDictionary() [1/2]

Ptr<Dictionary> cv::aruco::generateCustomDictionary ( int  nMarkers,
int  markerSize,
int  randomSeed = 0 
)
Python:
retval=cv.aruco.custom_dictionary(nMarkers, markerSize[, randomSeed])
retval=cv.aruco.custom_dictionary_from(nMarkers, markerSize, baseDictionary[, randomSeed])

§ generateCustomDictionary() [2/2]

Ptr<Dictionary> cv::aruco::generateCustomDictionary ( int  nMarkers,
int  markerSize,
const Ptr< Dictionary > &  baseDictionary,
int  randomSeed = 0 
)
Python:
retval=cv.aruco.custom_dictionary(nMarkers, markerSize[, randomSeed])
retval=cv.aruco.custom_dictionary_from(nMarkers, markerSize, baseDictionary[, randomSeed])

Generates a new customizable marker dictionary.

Parameters
nMarkersnumber of markers in the dictionary
markerSizenumber of bits per dimension of each markers
baseDictionaryInclude the markers in this dictionary at the beginning (optional)
randomSeeda user supplied seed for theRNG()

This function creates a new dictionary composed by nMarkers markers and each markers composed by markerSize x markerSize bits. If baseDictionary is provided, its markers are directly included and the rest are generated based on them. If the size of baseDictionary is higher than nMarkers, only the first nMarkers in baseDictionary are taken and no new marker is added.

§ getBoardObjectAndImagePoints()

void cv::aruco::getBoardObjectAndImagePoints ( const Ptr< Board > &  board,
InputArrayOfArrays  detectedCorners,
InputArray  detectedIds,
OutputArray  objPoints,
OutputArray  imgPoints 
)
Python:
objPoints, imgPoints=cv.aruco.getBoardObjectAndImagePoints(board, detectedCorners, detectedIds[, objPoints[, imgPoints]])

Given a board configuration and a set of detected markers, returns the corresponding image points and object points to call solvePnP.

Parameters
boardMarker board layout.
detectedCornersList of detected marker corners of the board.
detectedIdsList of identifiers for each marker.
objPointsVector of vectors of board marker points in the board coordinate space.
imgPointsVector of vectors of the projections of board marker corner points.

§ getPredefinedDictionary() [1/2]

Ptr<Dictionary> cv::aruco::getPredefinedDictionary ( PREDEFINED_DICTIONARY_NAME  name)
Python:
retval=cv.aruco.getPredefinedDictionary(dict)

Returns one of the predefined dictionaries defined in PREDEFINED_DICTIONARY_NAME.

§ getPredefinedDictionary() [2/2]

Ptr<Dictionary> cv::aruco::getPredefinedDictionary ( int  dict)
Python:
retval=cv.aruco.getPredefinedDictionary(dict)

Returns one of the predefined dictionaries referenced by DICT_*.

§ interpolateCornersCharuco()

int cv::aruco::interpolateCornersCharuco ( InputArrayOfArrays  markerCorners,
InputArray  markerIds,
InputArray  image,
const Ptr< CharucoBoard > &  board,
OutputArray  charucoCorners,
OutputArray  charucoIds,
InputArray  cameraMatrix = noArray(),
InputArray  distCoeffs = noArray(),
int  minMarkers = 2 
)
Python:
retval, charucoCorners, charucoIds=cv.aruco.interpolateCornersCharuco(markerCorners, markerIds, image, board[, charucoCorners[, charucoIds[, cameraMatrix[, distCoeffs[, minMarkers]]]]])

Interpolate position of ChArUco board corners.

Parameters
markerCornersvector of already detected markers corners. For each marker, its four corners are provided, (e.g std::vector<std::vector<cv::Point2f> > ). For N detected markers, the dimensions of this array should be Nx4. The order of the corners should be clockwise.
markerIdslist of identifiers for each marker in corners
imageinput image necesary for corner refinement. Note that markers are not detected and should be sent in corners and ids parameters.
boardlayout of ChArUco board.
charucoCornersinterpolated chessboard corners
charucoIdsinterpolated chessboard corners identifiers
cameraMatrixoptional 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeffsoptional vector of distortion coefficients \((k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])\) of 4, 5, 8 or 12 elements
minMarkersnumber of adjacent markers that must be detected to return a charuco corner

This function receives the detected markers and returns the 2D position of the chessboard corners from a ChArUco board using the detected Aruco markers. If camera parameters are provided, the process is based in an approximated pose estimation, else it is based on local homography. Only visible corners are returned. For each corner, its corresponding identifier is also returned in charucoIds. The function returns the number of interpolated corners.

§ refineDetectedMarkers()

void cv::aruco::refineDetectedMarkers ( InputArray  image,
const Ptr< Board > &  board,
InputOutputArrayOfArrays  detectedCorners,
InputOutputArray  detectedIds,
InputOutputArrayOfArrays  rejectedCorners,
InputArray  cameraMatrix = noArray(),
InputArray  distCoeffs = noArray(),
float  minRepDistance = 10.f,
float  errorCorrectionRate = 3.f,
bool  checkAllOrders = true,
OutputArray  recoveredIdxs = noArray(),
const Ptr< DetectorParameters > &  parameters = DetectorParameters::create() 
)
Python:
detectedCorners, detectedIds, rejectedCorners, recoveredIdxs=cv.aruco.refineDetectedMarkers(image, board, detectedCorners, detectedIds, rejectedCorners[, cameraMatrix[, distCoeffs[, minRepDistance[, errorCorrectionRate[, checkAllOrders[, recoveredIdxs[, parameters]]]]]]])

Refind not detected markers based on the already detected and the board layout.

Parameters
imageinput image
boardlayout of markers in the board.
detectedCornersvector of already detected marker corners.
detectedIdsvector of already detected marker identifiers.
rejectedCornersvector of rejected candidates during the marker detection process.
cameraMatrixoptional input 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeffsoptional vector of distortion coefficients \((k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6],[s_1, s_2, s_3, s_4]])\) of 4, 5, 8 or 12 elements
minRepDistanceminimum distance between the corners of the rejected candidate and the reprojected marker in order to consider it as a correspondence.
errorCorrectionRaterate of allowed erroneous bits respect to the error correction capability of the used dictionary. -1 ignores the error correction step.
checkAllOrdersConsider the four posible corner orders in the rejectedCorners array. If it set to false, only the provided corner order is considered (default true).
recoveredIdxsOptional array to returns the indexes of the recovered candidates in the original rejectedCorners array.
parametersmarker detection parameters

This function tries to find markers that were not detected in the basic detecMarkers function. First, based on the current detected marker and the board layout, the function interpolates the position of the missing markers. Then it tries to find correspondence between the reprojected markers and the rejected candidates based on the minRepDistance and errorCorrectionRate parameters. If camera parameters and distortion coefficients are provided, missing markers are reprojected using projectPoint function. If not, missing marker projections are interpolated using global homography, and all the marker corners in the board must have the same Z coordinate.