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 }
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 }
	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< Dictionary >	cv::aruco::generateCustomDictionary (int nMarkers, int markerSize)
Ptr< Dictionary >	cv::aruco::generateCustomDictionary (int nMarkers, int markerSize, const Ptr< Dictionary > &baseDictionary)
	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< Dictionary >	cv::aruco::getPredefinedDictionary (PREDEFINED_DICTIONARY_NAME name)
	Returns one of the predefined dictionaries defined in PREDEFINED_DICTIONARY_NAME. More...
Ptr< Dictionary >	cv::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:

• Detection of markers in a image
• Pose estimation from a single marker or from a board/set of markers
• Detection of ChArUco board for high subpixel accuracy
• Camera calibration from both, ArUco boards and ChArUco boards.
• Detection of ChArUco diamond markers The samples directory includes easy examples of how to use the module.

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

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

enum cv::aruco::CornerRefineMethod

Enumerator
CORNER_REFINE_NONE  Python: cv.aruco.CORNER_REFINE_NONE
CORNER_REFINE_SUBPIX  Python: cv.aruco.CORNER_REFINE_SUBPIX
CORNER_REFINE_CONTOUR  Python: cv.aruco.CORNER_REFINE_CONTOUR

PREDEFINED_DICTIONARY_NAME

enum cv::aruco::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

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

corners	vector of detected marker corners in all frames. The corners should have the same format returned by detectMarkers (see detectMarkers).
ids	list of identifiers for each marker in corners
counter	number of markers in each frame so that corners and ids can be split
board	Marker Board layout
imageSize	Size of the image used only to initialize the intrinsic camera matrix.
cameraMatrix	Output 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.
distCoeffs	Output 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
rvecs	Output 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).
tvecs	Output vector of translation vectors estimated for each pattern view.
stdDeviationsIntrinsics	Output 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.
stdDeviationsExtrinsics	Output 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.
perViewErrors	Output vector of average re-projection errors estimated for each pattern view.
flags	flags Different flags for the calibration process (see calibrateCamera for details).
criteria	Termination 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

charucoCorners	vector of detected charuco corners per frame
charucoIds	list of identifiers for each corner in charucoCorners per frame
board	Marker Board layout
imageSize	input image size
cameraMatrix	Output 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.
distCoeffs	Output 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
rvecs	Output 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).
tvecs	Output vector of translation vectors estimated for each pattern view.
stdDeviationsIntrinsics	Output 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.
stdDeviationsExtrinsics	Output 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.
perViewErrors	Output vector of average re-projection errors estimated for each pattern view.
flags	flags Different flags for the calibration process (see calibrateCamera for details).
criteria	Termination 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

image	input image necessary for corner subpixel.
markerCorners	list of detected marker corners from detectMarkers function.
markerIds	list of marker ids in markerCorners.
squareMarkerLengthRate	rate between square and marker length: squareMarkerLengthRate = squareLength/markerLength. The real units are not necessary.
diamondCorners	output 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> > ).
diamondIds	ids 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.
cameraMatrix	Optional camera calibration matrix.
distCoeffs	Optional 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

image	input image
dictionary	indicates the type of markers that will be searched
corners	vector 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.
ids	vector 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.
parameters	marker detection parameters
rejectedImgPoints	contains the imgPoints of those squares whose inner code has not a correct codification. Useful for debugging purposes.
cameraMatrix	optional input 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeff	optional 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

image	input/output image. It must have 1 or 3 channels. The number of channels is not altered.
cameraMatrix	input 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeffs	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
rvec	rotation vector of the coordinate system that will be drawn. (

See also

Rodrigues).

Parameters

tvec	translation vector of the coordinate system that will be drawn.
length	length 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:

homography_from_camera_displacement.cpp, and pose_from_homography.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

dictionary	dictionary of markers indicating the type of markers.
ids	list of 4 ids for each ArUco marker in the ChArUco marker.
squareLength	size of the chessboard squares in pixels.
markerLength	size of the markers in pixels.
img	output image with the marker. The size of this image will be 3*squareLength + 2*marginSize,.
marginSize	minimum margins (in pixels) of the marker in the output image
borderBits	width 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

image	input/output image. It must have 1 or 3 channels. The number of channels is not altered.
charucoCorners	vector of detected charuco corners
charucoIds	list of identifiers for each corner in charucoCorners
cornerColor	color 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

image	input/output image. It must have 1 or 3 channels. The number of channels is not altered.
diamondCorners	positions 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.
diamondIds	vector 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.
borderColor	color 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

image	input/output image. It must have 1 or 3 channels. The number of channels is not altered.
corners	positions 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.
ids	vector of identifiers for markers in markersCorners . Optional, if not provided, ids are not painted.
borderColor	color 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

dictionary	dictionary of markers indicating the type of markers
id	identifier of the marker that will be returned. It has to be a valid id in the specified dictionary.
sidePixels	size of the image in pixels
img	output image with the marker
borderBits	width 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

board	layout of the board that will be drawn. The board should be planar, z coordinate is ignored
outSize	size of the output image in pixels.
img	output image with the board. The size of this image will be outSize and the board will be on the center, keeping the board proportions.
marginSize	minimum margins (in pixels) of the board in the output image
borderBits	width 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

corners	vector 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.
ids	list of identifiers for each marker in corners
board	layout 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.
cameraMatrix	input 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeffs	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
rvec	Output vector (e.g. cv::Mat) corresponding to the rotation vector of the board (see cv::Rodrigues). Used as initial guess if not empty.
tvec	Output vector (e.g. cv::Mat) corresponding to the translation vector of the board.
useExtrinsicGuess	defines 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

charucoCorners	vector of detected charuco corners
charucoIds	list of identifiers for each corner in charucoCorners
board	layout of ChArUco board.
cameraMatrix	input 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeffs	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
rvec	Output vector (e.g. cv::Mat) corresponding to the rotation vector of the board (see cv::Rodrigues).
tvec	Output vector (e.g. cv::Mat) corresponding to the translation vector of the board.
useExtrinsicGuess	defines 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

corners

vector 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

markerLength	the length of the markers' side. The returning translation vectors will be in the same unit. Normally, unit is meters.
cameraMatrix	input 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeffs	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
rvecs	array 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

tvecs	array of output translation vectors (e.g. std::vector<cv::Vec3d>). Each element in tvecs corresponds to the specific marker in imgPoints.
_objPoints	array 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
	)

Python:
	retval	=	cv.aruco.custom_dictionary(	nMarkers, markerSize	)
	retval	=	cv.aruco.custom_dictionary_from(	nMarkers, markerSize, baseDictionary	)

See also

generateCustomDictionary

generateCustomDictionary() [2/2]

Ptr<Dictionary> cv::aruco::generateCustomDictionary	(	int	nMarkers,
		int	markerSize,
		const Ptr< Dictionary > &	baseDictionary
	)

Python:
	retval	=	cv.aruco.custom_dictionary(	nMarkers, markerSize	)
	retval	=	cv.aruco.custom_dictionary_from(	nMarkers, markerSize, baseDictionary	)

Generates a new customizable marker dictionary.

Parameters

nMarkers	number of markers in the dictionary
markerSize	number of bits per dimension of each markers
baseDictionary	Include the markers in this dictionary at the beginning (optional)

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

board	Marker board layout.
detectedCorners	List of detected marker corners of the board.
detectedIds	List of identifiers for each marker.
objPoints	Vector of vectors of board marker points in the board coordinate space.
imgPoints	Vector 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

markerCorners	vector 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.
markerIds	list of identifiers for each marker in corners
image	input image necesary for corner refinement. Note that markers are not detected and should be sent in corners and ids parameters.
board	layout of ChArUco board.
charucoCorners	interpolated chessboard corners
charucoIds	interpolated chessboard corners identifiers
cameraMatrix	optional 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeffs	optional 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
minMarkers	number 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

image	input image
board	layout of markers in the board.
detectedCorners	vector of already detected marker corners.
detectedIds	vector of already detected marker identifiers.
rejectedCorners	vector of rejected candidates during the marker detection process.
cameraMatrix	optional input 3x3 floating-point camera matrix \(A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\)
distCoeffs	optional 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
minRepDistance	minimum distance between the corners of the rejected candidate and the reprojected marker in order to consider it as a correspondence.
errorCorrectionRate	rate of allowed erroneous bits respect to the error correction capability of the used dictionary. -1 ignores the error correction step.
checkAllOrders	Consider the four posible corner orders in the rejectedCorners array. If it set to false, only the provided corner order is considered (default true).
recoveredIdxs	Optional array to returns the indexes of the recovered candidates in the original rejectedCorners array.
parameters	marker 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.