ArUco Marker Detection

API reference for ArUco marker detection, CharUco board detection, and dictionary management

ArUco Marker Detection

API reference for detecting ArUco markers and CharUco boards for robust camera pose estimation.

ArucoDetector

Main class for detecting ArUco markers in images.

Constructor

cv::aruco::ArucoDetector::ArucoDetector(
    const Dictionary& dictionary = getPredefinedDictionary(cv::aruco::DICT_4X4_50),
    const DetectorParameters& detectorParams = DetectorParameters(),
    const RefineParameters& refineParams = RefineParameters()
)

dictionary · Dictionary

Dictionary indicating the type of markers that will be searched

detectorParams · DetectorParameters

Marker detection parameters

refineParams · RefineParameters

Marker refine detection parameters

Multi-Dictionary Constructor

cv::aruco::ArucoDetector::ArucoDetector(
    const std::vector<Dictionary>& dictionaries,
    const DetectorParameters& detectorParams = DetectorParameters(),
    const RefineParameters& refineParams = RefineParameters()
)

dictionaries · std::vector<Dictionary>

Multiple dictionaries for marker detection. Cannot be empty.

Methods

detectMarkers

Basic marker detection in an image.

void detectMarkers(
    InputArray image,
    OutputArrayOfArrays corners,
    OutputArray ids,
    OutputArrayOfArrays rejectedImgPoints = noArray()
) const

image · InputArray

Input image where markers will be detected

corners · OutputArrayOfArrays

Vector of detected marker corners. For each marker, its four corners are provided (clockwise order). For N detected markers, dimensions are Nx4.

ids · OutputArray

Vector of identifiers of the detected markers. For N detected markers, the size is N.

rejectedImgPoints · OutputArrayOfArrays

Contains the corners of squares whose inner code has incorrect codification. Useful for debugging.

The function does not correct lens distortion. It’s recommended to undistort the input image if camera parameters are known.

detectMarkersWithConfidence

Marker detection with confidence computation.

void detectMarkersWithConfidence(
    InputArray image,
    OutputArrayOfArrays corners,
    OutputArray ids,
    OutputArray markersConfidence,
    OutputArrayOfArrays rejectedImgPoints = noArray()
) const

markersConfidence · OutputArray

Contains the normalized confidence [0;1] of the markers’ detection, defined as 1 minus the normalized uncertainty (percentage of incorrect pixel detections).

refineDetectedMarkers

Refine undetected markers based on already detected markers and board layout.

void refineDetectedMarkers(
    InputArray image,
    const Board& board,
    InputOutputArrayOfArrays detectedCorners,
    InputOutputArray detectedIds,
    InputOutputArrayOfArrays rejectedCorners,
    InputArray cameraMatrix = noArray(),
    InputArray distCoeffs = noArray(),
    OutputArray recoveredIdxs = noArray()
) const

image · InputArray

Input image

board · Board

Layout of markers in the board

detectedCorners · InputOutputArrayOfArrays

Vector of already detected marker corners

detectedIds · InputOutputArray

Vector of already detected marker identifiers

rejectedCorners · InputOutputArrayOfArrays

Vector of rejected candidates during the marker detection process

cameraMatrix · InputArray

Optional 3x3 floating-point camera matrix

distCoeffs · InputArray

Optional vector of distortion coefficients

recoveredIdxs · OutputArray

Optional array to return the indexes of recovered candidates in the original rejectedCorners array

getDictionary / setDictionary

const Dictionary& getDictionary() const
void setDictionary(const Dictionary& dictionary)

Gets or sets the first dictionary used for marker detection.

getDetectorParameters / setDetectorParameters

const DetectorParameters& getDetectorParameters() const
void setDetectorParameters(const DetectorParameters& detectorParameters)

Gets or sets the detector parameters.

getRefineParameters / setRefineParameters

const RefineParameters& getRefineParameters() const
void setRefineParameters(const RefineParameters& refineParameters)

Gets or sets the refine parameters.

Example Usage

C++

#include <opencv2/objdetect/aruco_detector.hpp>
#include <opencv2/imgproc.hpp>

// Create ArUco detector with 6x6 dictionary
cv::aruco::Dictionary dictionary = 
    cv::aruco::getPredefinedDictionary(cv::aruco::DICT_6X6_250);
cv::aruco::DetectorParameters detectorParams = 
    cv::aruco::DetectorParameters();
cv::aruco::ArucoDetector detector(dictionary, detectorParams);

// Detect markers
std::vector<std::vector<cv::Point2f>> corners;
std::vector<int> ids;
std::vector<std::vector<cv::Point2f>> rejected;

detector.detectMarkers(image, corners, ids, rejected);

// Draw detected markers
if (!ids.empty()) {
    cv::aruco::drawDetectedMarkers(image, corners, ids);
}

std::cout << "Detected " << ids.size() << " markers" << std::endl;

Python

import cv2
import numpy as np

# Create ArUco detector with 6x6 dictionary
dictionary = cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_6X6_250)
parameters = cv2.aruco.DetectorParameters()
detector = cv2.aruco.ArucoDetector(dictionary, parameters)

# Detect markers
corners, ids, rejected = detector.detectMarkers(image)

# Draw detected markers
if ids is not None:
    cv2.aruco.drawDetectedMarkers(image, corners, ids)

print(f"Detected {len(ids) if ids is not None else 0} markers")

---

Dictionary

A dictionary is a set of unique ArUco markers of the same size.

Constructor

cv::aruco::Dictionary::Dictionary()

cv::aruco::Dictionary::Dictionary(
    const Mat& bytesList,
    int markerSize,
    int maxCorrectionBits = 0
)

bytesList · Mat

Bits for all ArUco markers in dictionary (CV_8UC4 type)

markerSize · int

ArUco marker size in units (number of bits per dimension)

maxCorrectionBits · int · default: "0"

Maximum number of bits that can be corrected

Properties

• bytesList (Mat): Marker code information stored as 2D matrix with 4 channels
• markerSize (int): Number of bits per dimension
• maxCorrectionBits (int): Maximum number of bits that can be corrected

Methods

identify

Given a matrix of bits, returns whether the marker is identified.

bool identify(
    const Mat& onlyBits,
    int& idx,
    int& rotation,
    double maxCorrectionRate
) const

onlyBits · Mat

Input matrix of bits

idx · int&

Output marker ID in the dictionary (if any)

rotation · int&

Output marker rotation (0-3)

maxCorrectionRate · double

Maximum error correction rate

Returns: true if marker is identified

generateImageMarker

Generates a canonical marker image.

void generateImageMarker(
    int id,
    int sidePixels,
    OutputArray img,
    int borderBits = 1
) const

id · int

Marker ID to generate

sidePixels · int

Size of the output image in pixels

img · OutputArray

Output marker image

borderBits · int · default: "1"

Width of the marker border

Predefined Dictionaries

getPredefinedDictionary

Dictionary getPredefinedDictionary(PredefinedDictionaryType name)
Dictionary getPredefinedDictionary(int dict)

Available predefined dictionaries:

• DICT_4X4_50 - 4x4 bits, 50 markers, hamming distance 4
• DICT_4X4_100 - 4x4 bits, 100 markers, hamming distance 3
• DICT_4X4_250 - 4x4 bits, 250 markers, hamming distance 3
• DICT_4X4_1000 - 4x4 bits, 1000 markers, hamming distance 2
• DICT_5X5_50 - 5x5 bits, 50 markers, hamming distance 8
• DICT_5X5_100 - 5x5 bits, 100 markers, hamming distance 7
• DICT_5X5_250 - 5x5 bits, 250 markers, hamming distance 6
• DICT_5X5_1000 - 5x5 bits, 1000 markers, hamming distance 5
• DICT_6X6_50 - 6x6 bits, 50 markers, hamming distance 13
• DICT_6X6_100 - 6x6 bits, 100 markers, hamming distance 12
• DICT_6X6_250 - 6x6 bits, 250 markers, hamming distance 11
• DICT_6X6_1000 - 6x6 bits, 1000 markers, hamming distance 9
• DICT_7X7_50 - 7x7 bits, 50 markers, hamming distance 19
• DICT_7X7_100 - 7x7 bits, 100 markers, hamming distance 18
• DICT_7X7_250 - 7x7 bits, 250 markers, hamming distance 17
• DICT_7X7_1000 - 7x7 bits, 1000 markers, hamming distance 14
• DICT_ARUCO_ORIGINAL - 6x6 bits, 1024 markers (standard ArUco Library)
• DICT_APRILTAG_16h5 - 4x4 bits, 30 markers, hamming distance 5
• DICT_APRILTAG_25h9 - 5x5 bits, 35 markers, hamming distance 9
• DICT_APRILTAG_36h10 - 6x6 bits, 2320 markers, hamming distance 10
• DICT_APRILTAG_36h11 - 6x6 bits, 587 markers, hamming distance 11
• DICT_ARUCO_MIP_36h12 - 6x6 bits, 250 markers, hamming distance 12

---

CharucoDetector

Detector for ChArUco boards (chessboard + ArUco markers).

Constructor

cv::aruco::CharucoDetector::CharucoDetector(
    const CharucoBoard& board,
    const CharucoParameters& charucoParams = CharucoParameters(),
    const DetectorParameters& detectorParams = DetectorParameters(),
    const RefineParameters& refineParams = RefineParameters()
)

board · CharucoBoard

ChArUco board configuration

charucoParams · CharucoParameters

ChArUco detection parameters

detectorParams · DetectorParameters

Marker detection parameters

refineParams · RefineParameters

Marker refine detection parameters

Methods

detectBoard

Detects ArUco markers and interpolates ChArUco board corners.

void detectBoard(
    InputArray image,
    OutputArray charucoCorners,
    OutputArray charucoIds,
    InputOutputArrayOfArrays markerCorners = noArray(),
    InputOutputArray markerIds = noArray()
) const

image · InputArray

Input image necessary for corner refinement

charucoCorners · OutputArray

Interpolated chessboard corners

charucoIds · OutputArray

Interpolated chessboard corner identifiers

markerCorners · InputOutputArrayOfArrays

Vector of already detected marker corners. If empty, the function will detect markers.

markerIds · InputOutputArray

List of identifiers for each marker in corners. If empty, the function will detect markers.

After OpenCV 4.6.0, there was an incompatible change in the ChArUco pattern generation algorithm for even row counts. Use CharucoBoard::setLegacyPattern() to ensure compatibility with patterns created before 4.6.0.

detectDiamonds

Detects ChArUco Diamond markers.

void detectDiamonds(
    InputArray image,
    OutputArrayOfArrays diamondCorners,
    OutputArray diamondIds,
    InputOutputArrayOfArrays markerCorners = noArray(),
    InputOutputArray markerIds = noArray()
) const

image · InputArray

Input image necessary for corner subpixel accuracy

diamondCorners · OutputArrayOfArrays

Output list of detected diamond corners (4 corners per diamond) in clockwise order

diamondIds · OutputArray

IDs of the diamonds. Each diamond has 4 IDs corresponding to the ArUco markers composing it.

markerCorners · InputOutputArrayOfArrays

List of detected marker corners. If empty, the function will detect markers.

markerIds · InputOutputArray

List of marker IDs. If empty, the function will detect markers.

Example Usage

C++

#include <opencv2/objdetect/charuco_detector.hpp>
#include <opencv2/objdetect/aruco_board.hpp>

// Create ChArUco board
cv::aruco::Dictionary dictionary = 
    cv::aruco::getPredefinedDictionary(cv::aruco::DICT_6X6_250);
cv::aruco::CharucoBoard board(cv::Size(5, 7), 0.04f, 0.02f, dictionary);

// Create detector
cv::aruco::CharucoDetector detector(board);

// Detect ChArUco corners
std::vector<cv::Point2f> charucoCorners;
std::vector<int> charucoIds;
std::vector<std::vector<cv::Point2f>> markerCorners;
std::vector<int> markerIds;

detector.detectBoard(image, charucoCorners, charucoIds, 
                     markerCorners, markerIds);

// Draw detected corners
if (!charucoIds.empty()) {
    cv::aruco::drawDetectedCornersCharuco(image, charucoCorners, 
                                          charucoIds, cv::Scalar(255, 0, 0));
}

Python

import cv2
import numpy as np

# Create ChArUco board
dictionary = cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_6X6_250)
board = cv2.aruco.CharucoBoard((5, 7), 0.04, 0.02, dictionary)

# Create detector
detector = cv2.aruco.CharucoDetector(board)

# Detect ChArUco corners
charuco_corners, charuco_ids, marker_corners, marker_ids = \
    detector.detectBoard(image)

# Draw detected corners
if charuco_ids is not None and len(charuco_ids) > 0:
    cv2.aruco.drawDetectedCornersCharuco(image, charuco_corners, 
                                         charuco_ids, (255, 0, 0))

DetectorParameters

Parameters for ArUco marker detection.

Key Parameters

struct DetectorParameters {
    int adaptiveThreshWinSizeMin;      // default: 3
    int adaptiveThreshWinSizeMax;      // default: 23
    int adaptiveThreshWinSizeStep;     // default: 10
    double adaptiveThreshConstant;     // default: 7
    double minMarkerPerimeterRate;     // default: 0.03
    double maxMarkerPerimeterRate;     // default: 4.0
    double polygonalApproxAccuracyRate; // default: 0.03
    double minCornerDistanceRate;      // default: 0.05
    int minDistanceToBorder;           // default: 3
    double minMarkerDistanceRate;      // default: 0.125
    int cornerRefinementMethod;        // default: CORNER_REFINE_NONE
    int cornerRefinementWinSize;       // default: 5
    int cornerRefinementMaxIterations; // default: 30
    double cornerRefinementMinAccuracy; // default: 0.1
    int markerBorderBits;              // default: 1
    int perspectiveRemovePixelPerCell; // default: 4
    double errorCorrectionRate;        // default: 0.6
    bool detectInvertedMarker;         // default: false
    bool useAruco3Detection;           // default: false
}

cornerRefinementMethod · int

Corner refinement method:

• CORNER_REFINE_NONE - No refinement
• CORNER_REFINE_SUBPIX - Subpixel corner refinement
• CORNER_REFINE_CONTOUR - Contour-based refinement
• CORNER_REFINE_APRILTAG - AprilTag approach

useAruco3Detection · bool

Enable the new and faster ArUco 3 detection strategy (from Romero-Ramirez et al. 2018)

Utility Functions

drawDetectedMarkers

Draws detected markers in an image.

void drawDetectedMarkers(
    InputOutputArray image,
    InputArrayOfArrays corners,
    InputArray ids = noArray(),
    Scalar borderColor = Scalar(0, 255, 0)
)

generateImageMarker

Generates a canonical marker image.

void generateImageMarker(
    const Dictionary& dictionary,
    int id,
    int sidePixels,
    OutputArray img,
    int borderBits = 1
)

See Also

• Cascade Classifier
• Face Detection
• QR Code Detection