ArUco Markers Explained and How to Create Them

By RWT Robotics Editorial Team Checked against 8 sources Published

An ArUco marker is a square black-and-white fiducial. Its inner grid of bits encodes an ID, and its four corners give a camera enough geometry to work out the marker’s full 3D position and orientation. Robots, drones, AR apps and calibration rigs use ArUco tags because one printed square and a calibrated camera give you a 6-DoF pose for almost no cost. This guide covers how to pick a dictionary, generate and print markers at a size you can trust, and detect them with the current OpenCV API.

Marker typeSquare binary fiducial
OriginUniversity of Cรณrdoba, 2014
Main libraryOpenCV objdetect
Latest OpenCV5.0.0
OutputID plus 6-DoF pose

Key takeaways

  • The marker ID is the code’s position in the dictionary list. It is not the number the bits spell out.
  • Use the smallest dictionary that covers your IDs. You get bigger cells, longer range and fewer ghost detections.
  • Print at 100% scale, measure the black square with calipers, and give solvePnP that exact size in metres.
  • Since OpenCV 4.7 the API is ArucoDetector plus solvePnP. estimatePoseSingleMarkers is deprecated.
  • Most wrong-distance bugs come from calibrating at one resolution and detecting at another.

Fact-checked

We checked these key facts against the sources named, on November 15, 2026:

  • DICT_ARUCO_ORIGINAL reproduces the first ArUco library’s 1024-code set (source: docs.opencv.org)
  • AprilTag 16h5 produced 49,321 false positives, ARToolKit 9,756, reacTIVision 348 and ArUco (a 16-bit, Hamming-distance-3 configuration) 146 (source: arxiv.org)
  • A curled sheet breaks the planar assumption behind solvePnP. :::tip Print and measure Print at 100% with “fit to page” off, then measure the black square’s outer edge with calipers (source: docs.opencv.org)

What an ArUco marker is, in 60 seconds

An ArUco marker is a square with a solid black border around an Nร—N grid of black and white cells. Each grid pattern belongs to a predefined list called a dictionary, and the marker’s ID is its index in that list. Once a detector finds the four corners and you know the printed size, you can recover the marker’s position and rotation relative to the camera.

The format comes from the ArUco library built by the AVA group at the University of Cรณrdoba. The reference paper is “Automatic generation and detection of highly reliable fiducial markers under occlusion” by Sergio Garrido-Jurado, Rafael Muรฑoz-Salinas, Francisco Josรฉ Madrid-Cuevas and Manuel Jesรบs Marรญn-Jimรฉnez, published in Pattern Recognition 47(6), pages 2280โ€“2292, in 2014. The paper’s main contribution was a way to generate dictionaries automatically, so the codes sit as far apart from each other as possible, plus a detector that stays reliable under partial occlusion.

Detected corners always come back in the same order, measured in the marker’s own orientation and regardless of how it is rotated in the image:

  1. Top-left
  2. Top-right
  3. Bottom-right
  4. Bottom-left

That clockwise order is what makes the pose unambiguous in rotation. Each code is checked against all four of its rotations, so the detector knows which corner is “top-left” even when the marker is upside down.

Why four corners are enough for pose

A square of known side length L, seen through a calibrated camera, constrains all six degrees of freedom. Four coplanar points with known 3D coordinates give eight image measurements (x and y for each corner), and a rigid pose has six unknowns: three for translation and three for rotation. That is why one marker is enough. It is also why the pose is only as good as the corner locations. A half-pixel corner error on a marker 30 pixels wide is a much bigger relative error than on one 300 pixels wide.

Marker ID vs binary value

The ID is a lookup index. When the detector reads the bit pattern, it searches the dictionary for the closest code, allowing a few flipped bits for error correction, and returns that code’s position. The OpenCV tutorial notes that turning the bits straight into a number is impractical for larger markers, which is why the dictionary lookup exists.

Did you know?

The OpenCV ArUco tutorial says a marker’s ID is just its index in the dictionary. Marker 7 in DICT_4X4_50 and marker 7 in DICT_6X6_250 look completely different, so a detector set to the wrong dictionary finds nothing.

Where ArUco lives today: OpenCV objdetect vs the original library

There are two lines of ArUco code, and tutorials mix them up all the time.

  • OpenCV’s objdetect module. Since OpenCV 4.7.0, ArUco detection has been part of the main repository in objdetect, with the cv::aruco::ArucoDetector class. Before that it lived in the opencv_contrib aruco module, which is where most old blog code comes from. OpenCV is under the Apache 2 license.
  • The original ArUco library from Cรณrdoba. It is still maintained separately. The latest release is aruco-3.1.12, which adds DCF-based tracking. Version 3.0.0 and later removed all deprecated 2.x functions. The library is GPLv3, and a commercial license is available on request. The same authors also publish Aruco Nano, a single-header detector. Version 5 was announced in August 2023, and an ArucoNano-v6 folder holds an aruco_nano.h dated 6 July 2025.

For most robot projects, OpenCV’s module is the default choice. It ships everywhere, its license suits commercial use, and the ROS 2 and Python tooling assumes it.

Choosing a dictionary

Pick the dictionary with the fewest bits and the fewest codes that still covers every ID you need. Fewer bits per marker means each cell is bigger at the same print size, so the marker reads from farther away. Fewer codes in the dictionary means the codes are spaced further apart in Hamming distance, so random patterns in the scene are less likely to decode as a valid ID.

Hamming distance is the number of bits you would have to flip to turn one code into another, counting all four rotations. A larger minimum distance gives the detector more room to correct bit errors and fewer chances to accept a false match.

Dictionary (OpenCV name) Inner bits Codes Min Hamming distance Best for
DICT_4X4_50 4ร—4 50 Highest of the 4ร—4 family Small robot cells, long range, few IDs
DICT_4X4_100 / _250 / _1000 4ร—4 100 / 250 / 1000 Falls as count rises Rarely worth it; switch to 5ร—5 instead
DICT_5X5_50 to _1000 5ร—5 50 to 1000 Higher than 4ร—4 at the same count General robotics, warehouse floor IDs
DICT_6X6_50 to _1000 6ร—6 50 to 1000 Higher again Many IDs, close to mid range, AR
DICT_7X7_50 to _1000 7ร—7 50 to 1000 Highest of the ArUco families Close range, large ID sets
DICT_ARUCO_ORIGINAL 5ร—5 1024 Low (includes a symmetric code) Legacy compatibility only
DICT_ARUCO_MIP_36h12 6ร—6 250 12 Robust 6ร—6 set; the original library’s recommended family
DICT_APRILTAG_16h5 4ร—4 30 5 Avoid: high false-positive rate
DICT_APRILTAG_25h9 5ร—5 35 9 Few IDs, small tags
DICT_APRILTAG_36h10 6ร—6 2320 10 Very large ID sets
DICT_APRILTAG_36h11 6ร—6 587 11 Interop with AprilTag-based robots and datasets

The 36h12 values come from the OpenCV 5.0 ArUco documentation. AprilTag family names encode their own figures: “36h11” means 36 data bits and a minimum Hamming distance of 11.

Engineer's note

Use the smallest dictionary that covers your IDs. If you need 30 markers, DICT_4X4_50 beats DICT_6X6_250 on range, cell size and false IDs. The larger dictionary only buys you IDs you will never print.

4x4_50 vs 6x6_250 vs 7x7_1000

The three common picks show the trade-off. Remember that the black border adds one module on each side, so the full marker is (bits + 2) modules across.

  • DICT_4X4_50: 6 modules across. At a given print size, each module is about 33% larger than on a 6ร—6 marker. Pick it for docking stations, small fleets and anything read from across a room.
  • DICT_6X6_250: 8 modules across. This is the default in many tutorials and a sensible choice for AR and mixed setups that need up to a few hundred IDs.
  • DICT_7X7_1000: 9 modules across. Use it only when you really need hundreds of unique IDs and the camera will be close. It is the hardest to read at distance.

ARUCO_ORIGINAL and the symmetry problem

DICT_ARUCO_ORIGINAL reproduces the first ArUco library’s 1024-code set. It contains a known weak spot: ID 1023 is rotationally symmetric, so its orientation is ambiguous and the pose can snap by 90ยฐ. Older ROS 1 detectors built around this dictionary often note the issue and leave it there. The modern fix is to drop ARUCO_ORIGINAL entirely and use a 5ร—5 OpenCV dictionary or ARUCO_MIP_36h12.

AprilTag dictionaries inside OpenCV

OpenCV can detect AprilTag families (16h5, 25h9, 36h10, 36h11) with the same ArucoDetector class. That is useful if your robot already uses AprilTag 36h11 tags, a common convention in many labs, and you want one detection pipeline. Keep in mind that detecting AprilTag codes through OpenCV’s ArUco pipeline is different from running the University of Michigan APRIL lab’s own AprilTag 3 detector. Thresholding, quad fitting and edge refinement all differ.

Generating and printing markers that actually measure correctly

Generate markers with OpenCV’s generateImageMarker or an online generator. Then print at exactly 100% scale and measure the result. The image file has no physical size. Your pose only becomes metric when you tell solvePnP the true edge length, so the printer is part of your measurement chain.

Generate in Python (OpenCV 4.7+ / 5.0)

This script writes ten DICT_4X4_50 markers. Each has exactly 100 pixels per module and a white quiet zone one module wide:

import cv2

dictionary = cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_50)

MODULES = 4 + 2          # 4x4 bits plus a 1-module black border on each side
PX_PER_MODULE = 100
side = MODULES * PX_PER_MODULE   # 600 px, an exact multiple: no resampling blur for marker_id in range(10):
    img = cv2.aruco.generateImageMarker(dictionary, marker_id, side, borderBits=1)
    # White quiet zone, one module wide
    img = cv2.copyMakeBorder(img, PX_PER_MODULE, PX_PER_MODULE,
                             PX_PER_MODULE, PX_PER_MODULE,
                             cv2.BORDER_CONSTANT, value=255)
    cv2.imwrite(f"aruco_4x4_50_id{marker_id:02d}.png", img)

Make the side length a whole multiple of the module count. If it isn’t, OpenCV resamples the grid and the cell edges blur by a pixel. In old code you will see drawMarker. It was renamed generateImageMarker in 4.7.

If you don’t want to script it, browser-based generators such as the one at chev.me let you choose the dictionary, ID and size in millimetres, then export SVG. Vector output in mm is the cleanest path to a correct print, because a PDF or SVG keeps its physical dimensions.

Print settings that won’t wreck your scale

Most pose errors that look like math bugs are really printing problems. Use this checklist:

  1. Export to PDF or SVG with the marker size set in millimetres.
  2. In the print dialog, turn off “fit to page”, “shrink to fit” and any borderless scaling. Choose “actual size” or 100%.
  3. Print on matte paper or card. Glossy stock and laminate cause specular glare that wipes out cells at some angles.
  4. Measure the outer edge of the black square (not the white margin) with calipers. Use the measured value, not the intended one.
  5. Keep a white quiet zone at least one module wide around the black border.
  6. Mount the marker flat on something rigid, such as foam board, aluminium composite or acrylic. A curled sheet breaks the planar assumption behind solvePnP.

Print and measure

Print at 100% with “fit to page” off, then measure the black square’s outer edge with calipers. A 50 mm marker that prints at 48.5 mm puts every distance off by 3%, and no amount of calibration fixes that.

For harsh or permanent setups, people laser-engrave anodised aluminium, etch markers onto PCBs, or paint them onto floors. Contrast and flatness matter more than the material.

Did you know?

For a 2021 class at MIT’s Center for Bits and Atoms, a student engraved an ArUco marker with 100 ยตm squares onto a penny and used it to track a motion stage at about 12.5 ยตm per pixel.

Marker size vs working distance

A marker’s size in the image is roughly f ร— L / Z pixels, where f is the focal length in pixels, L is the marker side and Z is the distance. Divide by the module count to get pixels per module. That one number predicts both whether the marker is detected and how steady the pose will be.

Take a 1280ร—720 camera with a 70ยฐ horizontal field of view. Its focal length is about 640 / tan(35ยฐ) โ‰ˆ 914 px. The numbers below follow directly from that geometry:

Marker side Distance Marker in image Px/module (4ร—4, 6 modules) Px/module (6ร—6, 8 modules) Expect
5 cm 1 m ~46 px ~7.6 ~5.7 Reliable detection, noticeable jitter
10 cm 1 m ~91 px ~15 ~11 Solid detection and usable pose
10 cm 2 m ~46 px ~7.6 ~5.7 Detects, rotation is noisy
10 cm 4 m ~23 px ~3.8 ~2.9 Marginal; 6ร—6 often fails
20 cm 4 m ~46 px ~7.6 ~5.7 Detects reliably
5 cm 3 m ~15 px ~2.5 ~1.9 Usually not detected

A practical rule: aim for at least 5 pixels per module for dependable detection, and at least 10 if you care about orientation accuracy. The OpenCV defaults set a hard floor too. minMarkerPerimeterRate = 0.03 rejects any candidate whose perimeter is under 3% of the image’s larger dimension, which is about 38 px of perimeter at 1280 px wide.

Motion blur, compression artefacts and lens defocus all raise those numbers. So a 10 cm marker at 4 m on a moving robot needs more margin than a static bench test suggests.

Detecting ArUco markers in OpenCV (current API)

In OpenCV 4.7 and later, including 5.0, you create a cv2.aruco.ArucoDetector from a dictionary and a DetectorParameters object, then call detectMarkers. It returns the corners, the IDs, and the rejected candidates that looked like squares but didn’t decode.

Behind that one call, the pipeline runs in five steps:

  1. Adaptive thresholding
  2. Contour extraction and filtering down to convex quadrilaterals
  3. Perspective removal of each candidate
  4. Bit extraction on a grid, with the border checked for black cells
  5. Dictionary lookup with error correction, then optional corner refinement

Minimal Python detector

import cv2

dictionary = cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_50)
params = cv2.aruco.DetectorParameters()
params.cornerRefinementMethod = cv2.aruco.CORNER_REFINE_SUBPIX

detector = cv2.aruco.ArucoDetector(dictionary, params)

frame = cv2.imread("scene.png")
gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)

corners, ids, rejected = detector.detectMarkers(gray)

if ids is not None:
    cv2.aruco.drawDetectedMarkers(frame, corners, ids)
    print("Found IDs:", ids.flatten().tolist())
else:
    print(f"No markers; {len(rejected)} rejected candidates")

cv2.imwrite("scene_detected.png", frame)

The same thing in C++:

\#include <opencv2/objdetect/aruco_detector.hpp>
\#include <opencv2/imgcodecs.hpp>

int main() {
    cv::aruco::Dictionary dict =
        cv::aruco::getPredefinedDictionary(cv::aruco::DICT_4X4_50);
    cv::aruco::DetectorParameters params;
    params.cornerRefinementMethod = cv::aruco::CORNER_REFINE_SUBPIX;
    cv::aruco::ArucoDetector detector(dict, params);

    cv::Mat img = cv::imread("scene.png");
    std::vector<int> ids;
    std::vector<std::vector<cv::Point2f>> corners, rejected;
    detector.detectMarkers(img, corners, ids, rejected);
    cv::aruco::drawDetectedMarkers(img, corners, ids);
    cv::imwrite("scene_detected.png", img);
}

When nothing is found, draw the rejected list on the frame. If you see red squares on your markers, they are being found as shapes but failing to decode. That almost always means the wrong dictionary, inverted colours or too few pixels per cell. If there are no candidates on the marker at all, look at thresholding, blur or the quiet zone.

Parameters worth tuning

Most of the dozens of DetectorParameters fields can stay at their defaults. These are the ones that matter in practice:

Parameter Default When to change it
adaptiveThreshWinSizeMin / Max / Step 3 / 23 / 10 Raise Max for large markers close to the camera; more steps cost CPU time
minMarkerPerimeterRate 0.03 Lower it to detect small, distant markers (expect more candidates)
maxMarkerPerimeterRate 4.0 Rarely; caps very large candidates
cornerRefinementMethod CORNER_REFINE_NONE Set SUBPIX for pose work; CONTOUR or APRILTAG are alternatives
perspectiveRemovePixelPerCell 4 Raise it for very large markers to sample bits more robustly
errorCorrectionRate 0.6 Lower it to cut false IDs, at the cost of fewer corrected reads
detectInvertedMarker false Set true for white-on-black markers

Corner refinement is off by default because it costs time, but every pose application should turn it on. OpenCV’s 2024 changelog lists a more accurate ArUco corner refinement that uses a dynamic window. That is one more reason to run a current release instead of a pinned 4.5 build.

RefineParameters sets how refineDetectedMarkers recovers markers it missed when you use a board with a known layout. Pass it as the third argument to ArucoDetector when you work with GridBoards.

Migrating from pre-4.7 code

If you get AttributeError: module 'cv2.aruco' has no attribute 'estimatePoseSingleMarkers' or 'Dictionary_get', you have old tutorial code running on a new OpenCV. The free functions moved into classes in 4.7:

Old call (contrib, โ‰ค4.6) Current call (4.7+, 5.0)
cv2.aruco.Dictionary_get(...) cv2.aruco.getPredefinedDictionary(...)
cv2.aruco.DetectorParameters_create() cv2.aruco.DetectorParameters()
cv2.aruco.detectMarkers(img, dict, parameters=p) cv2.aruco.ArucoDetector(dict, p).detectMarkers(img)
cv2.aruco.drawMarker(...) cv2.aruco.generateImageMarker(...)
cv2.aruco.estimatePoseSingleMarkers(...) cv2.solvePnP(...) with your own object points
cv2.aruco.CharucoBoard_create(...) cv2.aruco.CharucoBoard(...)

The OpenCV docs mark estimatePoseSingleMarkers as deprecated since 4.7.0 and point to cv::solvePnP, with Board::matchImagePoints for boards. Installing opencv-contrib-python brings some legacy names back, but porting is the better fix. Old shims won’t follow you to 5.0.

Reality check

OpenCV forum users reported that the pose coordinate system changed between 4.6 and 4.7. Old code can return a different axis convention after an upgrade without raising any error. Defining your own object points, as shown below, puts the convention in your code instead of in the library.

Estimating pose with solvePnP

To get a 6-DoF pose, you pass the four detected corners, the matching 3D corner coordinates for a square of side L, and your camera’s intrinsic matrix and distortion coefficients to cv2.solvePnP. SOLVEPNP_IPPE_SQUARE is the flag made for exactly this case. You get back a rotation vector and a translation vector in the camera frame, in whatever units you used for L.

Calibrate first

Without intrinsics, there is no metric pose. Calibrate at the exact resolution, focus and zoom you will detect with. Autofocus and digital zoom quietly change the focal length, so lock them if you can.

ChArUco boards are the recommended calibration target here. OpenCV’s 4.13 tutorial set includes aruco_calibration and charuco_detection for this. A ChArUco board still works when partly out of view, and its chessboard corners locate to subpixel accuracy.

A real failure from the OpenCV forum shows the stakes. A user’s ArUco distances were off by a factor of 2.37. The cause was a camera running with different settings during calibration than during detection. Once the settings matched, distance and pose came out right. Replies in the same thread point out that OpenCV’s capture often defaults to 640ร—480 whatever the sensor resolution, so check the frame size you actually get in both runs.

Match your settings

Calibrate at the same resolution, focus and zoom you detect with, and confirm the frame size in code with CAP_PROP_FRAME_WIDTH. A focal length from a 1920ร—1080 calibration applied to 640ร—480 frames scales every distance wrongly.

solvePnP for a single marker

import cv2
import numpy as np

MARKER_LENGTH = 0.0485   # metres: the measured outer black edge, not the intended size

calib = np.load("calib.npz")           # saved from your ChArUco calibration
K, dist = calib["K"], calib["dist"]

h = MARKER_LENGTH / 2

obj_pts = np.array([[-h,  h, 0],
                    [ h,  h, 0],
                    [ h, -h, 0],
                    [-h, -h, 0]], dtype=np.float32)

def marker_pose(corner, frame):
    img_pts = corner.reshape(4, 2).astype(np.float32)
    ok, rvec, tvec = cv2.solvePnP(obj_pts, img_pts, K, dist,
                                  flags=cv2.SOLVEPNP_IPPE_SQUARE)
    if not ok:
        return None
    proj, _ = cv2.projectPoints(obj_pts, rvec, tvec, K, dist)
    err = np.linalg.norm(proj.reshape(4, 2) - img_pts, axis=1).mean()
    cv2.drawFrameAxes(frame, K, dist, rvec, tvec, MARKER_LENGTH * 0.5)
    return rvec, tvec, err

Call marker_pose(c, frame) for each entry in corners from the detector. The origin sits at the marker centre. X points right and Y points up in the marker plane, and Z points out of the marker towards the camera. tvec[2] is the distance along the optical axis, not the straight-line range. For range, use np.linalg.norm(tvec).

Check the reprojection error on every frame. On a clean detection with refined corners, the mean error should be well under a pixel. When it suddenly climbs to several pixels, the corners are bad (blur, partial occlusion, glare) and you should throw that pose away rather than feed it to your controller.

On a mobile robot, marker poses work best as corrections fused with wheel or visual robot odometry in an EKF, not as the only source of truth.

Boards, ChArUco and Diamonds for better accuracy

A single marker gives you four points. A board gives you dozens, and that is the most effective fix for jitter and orientation flips.

  • GridBoard: a regular grid of markers with known spacing. Any visible subset gives a pose, and refineDetectedMarkers can recover missed markers from the layout.
  • ChArUco board: a chessboard with ArUco markers in the white squares. The markers identify each square, and the chessboard corners give subpixel accuracy. This is the go-to target for calibration and for high-accuracy fixed references, such as checking the axes of cartesian systems or gantries.
  • ArUco Diamond: a 3ร—3 chessboard holding four markers. Its ID is the set of four marker IDs, which multiplies the number of unique IDs and gives eight-plus points for pose.
import cv2 dictionary = cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_5X5_100)
board = cv2.aruco.CharucoBoard((5, 7), squareLength=0.04,
                               markerLength=0.03, dictionary=dictionary)
img = board.generateImage((1000, 1400), marginSize=40, borderBits=1)
cv2.imwrite("charuco_5x7.png", img)

What changed in OpenCV 4.13 and 5.0

If your code already uses the 4.7+ API, it carries over to both releases. The ArucoDetector, dictionaries, boards and ChArUco classes are the same. The bigger 5.0 changes are in build requirements and module layout, not in how ArUco detection works.

OpenCV 4.13 (January 2026)

OpenCV 4.13.0 reached PyPI as opencv-python 4.13.0.90 on 15 January 2026, and Fedora packaged it on 28 January 2026. Its ArUco tutorial set covers marker detection, board detection, calibration, an FAQ, ChArUco detection and Diamond detection. All of it targets OpenCV 4.7.0 or later. It is the last major 4.x line and a safe base if your toolchain can’t move to C++17 yet.

OpenCV 5.0

OpenCV 5.0.0 is the first release of the new major line. According to the project’s release material and its Wikipedia summary, it requires C++17 at minimum and builds Python 3 bindings only. The 3D stack gained multi-camera calibration, point cloud and mesh I/O, and dense RGB-D fusion. G-API and the classic ML module moved out to opencv_contrib. ArUco has its own page in the new 5.0 documentation under the objdetect module.

What this means for your upgrade:

  • Python: the cv2.aruco.ArucoDetector and cv2.solvePnP calls stay the same. Python 2 environments are finished.
  • C++: you need a C++17 compiler. The calibration and 3D functions have been reorganised, so check your includes and CMake link targets when solvePnP or the calibration functions fail to resolve.
  • Legacy contrib calls: anything that still relies on the deprecated estimatePoseSingleMarkers path should be ported now, not shimmed.
  • Multi-camera rigs: the new multi-camera calibration is worth a look if you calibrate stereo or surround-camera robots with ChArUco boards.

ArUco vs AprilTag: an honest comparison

Both are square binary fiducials. With families of similar Hamming distance, they perform about the same. The real differences are tooling, licensing, ecosystem conventions and which specific family you choose. Public benchmarks that put “ArUco” against “AprilTag” mostly compare two particular dictionaries, not the two systems.

Criterion ArUco (OpenCV) AprilTag (AprilTag 3 / OpenCV) Evidence
Origin University of Cรณrdoba, 2014 University of Michigan APRIL lab Original papers
Families 4ร—4 to 7ร—7, ARUCO_ORIGINAL, MIP_36h12 16h5, 25h9, 36h10, 36h11 and others OpenCV dictionary list
False positives Low with small dictionaries Very high with 16h5, low with 36h11 TopoTag benchmark; 2023 Hamming-distance study
Install Built into OpenCV Standalone library, or OpenCV dictionaries Package docs
Typical community default DICT_4X4_50, DICT_6X6_250 Tag36h11 Common lab and ROS usage
Corner refinement SUBPIX, CONTOUR, APRILTAG options Edge-based quad refinement OpenCV DetectorParameters
License Apache 2 in OpenCV; GPLv3 for original library Permissive (AprilTag 3) Project licenses

False positives and Hamming distance

The TopoTag paper (2019) benchmarked false positives on images with no markers in them. AprilTag 16h5 produced 49,321 false positives, ARToolKit 9,756, reacTIVision 348 and ArUco (a 16-bit, Hamming-distance-3 configuration) 146.

That headline looks like a verdict against AprilTag, but it isn’t one. 16h5 is a tiny family with a low minimum distance, so random texture matches it easily. A 2023 study found that false positives drop sharply as dictionary Hamming distance increases, for both AprilTag and ArUco. Compare families, not brand names.

Did you know?

In the TopoTag benchmark, AprilTag 16h5 returned 49,321 false positives against 146 for ArUco. The gap comes from the 16h5 family’s low Hamming distance. Larger families such as 36h11 behave very differently.

Speed, range and tooling

Range comes from module size, so a 4ร—4 code of either system beats a 6ร—6 code at the same print size. For tooling, ArUco’s advantage is that it is already inside OpenCV, with boards, ChArUco and calibration in the same module. AprilTag’s advantage is convention: many robotics datasets, simulators and ROS stacks assume Tag36h11. Other designs exist for specialist needs too. STag, for example, targets pose stability, and TopoTag uses topological encoding. Neither has a toolchain as broad as these two.

When to choose which

  • Indoor robot docking or a small fleet of IDs: ArUco DICT_4X4_50 or 5X5_50 with OpenCV.
  • Drone landing pads, including small platforms covered in our article on micro air vehicles: a large low-bit marker, or nested markers for close range, read from a downward camera with refinement on.
  • Interop with an existing AprilTag stack: Tag36h11. You can still detect it in OpenCV through DICT_APRILTAG_36h11.
  • Camera calibration: a ChArUco board. Neither plain tag beats it.
  • AR with many objects: DICT_6X6_250 or ARUCO_MIP_36h12.

The honest counter-argument: if your team already runs the AprilTag 3 detector and its ROS wrappers, switching to ArUco gains you little. Only switch for a concrete reason, such as wanting one OpenCV dependency or ChArUco calibration.

ArUco in ROS 2, MATLAB and other stacks

On ROS 2 Jazzy, aruco_opencv is the simplest maintained option. It wraps OpenCV’s module, ships under MIT, and installs from apt. aruco_ros wraps the original Cรณrdoba library instead. MATLAB users get readArucoMarker in the Computer Vision Toolbox, and browser projects can use js-aruco2.

Tool Latest version / release Backend License Stack
OpenCV 5.0.0 objdetect ArUco Apache 2 C++17, Python 3
OpenCV 4.x 4.13.0 (Jan 2026) objdetect ArUco Apache 2 C++, Python
ArUco library 3.1.12 Original Cรณrdoba code GPLv3 or commercial C++
aruco_opencv 6.1.1 (Jazzy) OpenCV aruco module MIT ROS 2, ament_cmake
aruco_ros Jazzy release Original ArUco library Inherits ArUco’s GPLv3 terms ROS 2
MATLAB readArucoMarker Since R2024a; docs at R2026b Computer Vision Toolbox Commercial MATLAB
js-aruco2 2.0.0 (npm) JavaScript port Open source Browser, Node.js

ROS 2: aruco_opencv vs aruco_ros

aruco_opencv is maintained by Fictionlab, and its Jazzy branch was last updated on 27 April 2026. Install and run it like this:

sudo apt install ros-${ROS_DISTRO}-aruco-opencv ros2 run aruco_opencv aruco_tracker_autostart --ros-args \
  -p cam_base_topic:=camera/image_raw \
  -p marker_size:=0.075 \
  -p image_is_rectified:=false

The node needs both an image topic and its matching camera_info. marker_size is the measured black edge in metres. Set image_is_rectified to true only if you feed it rectified images, otherwise distortion gets applied twice. Detector tuning sits under an aruco parameter namespace, which mirrors OpenCV’s DetectorParameters. A YAML file also sets marker_dict, publish_tf and output_frame.

When aruco_ros isn’t detecting a marker, the cause is usually a mismatch. Check that the dictionary and marker ID match what the node is configured for, that camera_info is actually being published, and that marker_size is in metres, not centimetres. Then view the debug image the node publishes. If the marker isn’t outlined there, the problem is in detection, not in TF. Simulating the whole chain in Gazebo first, with a textured marker model, is the same idea as using digital twins in robotics: perception bugs show up before they hit hardware.

MATLAB Computer Vision Toolbox

readArucoMarker has shipped since R2024a and is documented through R2026b. It returns IDs, corner locations and family names, and it can search several families at once, such as DICT_4X4_1000 and DICT_5X5_1000, when you don’t know which one was printed. You need a paid Computer Vision Toolbox license, so it suits teams already working in MATLAB more than hobby projects.

Licensing: GPLv3 ArUco library vs OpenCV

The original ArUco library is GPLv3 for research and education, and its authors ask for a commercial license for other uses. OpenCV’s module is Apache 2, and aruco_opencv is MIT. If you ship a closed-source product, the OpenCV route avoids a licensing conversation. Aruco Nano and ArUco 3.1.12 still have a place: compact embedded builds, or the DCF tracker, where you are willing to take on those license terms.

Troubleshooting: why markers aren’t detected or the pose is wrong

Nearly every ArUco problem falls into one of five symptoms. Each has a short list of causes, and the right check usually finds the cause within minutes.

Symptom Likely cause Fix
No detections at all Wrong dictionary, no quiet zone, inverted print Match the dictionary; add a white margin; set detectInvertedMarker
Candidates rejected Too few px/module, blur, glare Bigger marker or closer camera; faster shutter; matte stock
Distance off by a constant factor marker_size wrong or in wrong units; printer scaling Measure with calipers; pass metres
Distance off by ~2ร— or more Calibrated at a different resolution or zoom Recalibrate at the detection resolution
Pose jitters when still Small marker in pixels, no corner refinement CORNER_REFINE_SUBPIX; bigger marker; board; filtering
Axes flip at frontal views Planar pose ambiguity Boards; temporal consistency; solvePnPGeneric
Ghost IDs on random texture Large dictionary, low Hamming distance Smaller dictionary; ID whitelist; lower errorCorrectionRate
Different axes after upgrade 4.6 to 4.7 convention change Define object points explicitly

No detections

Start with the rejected candidates overlay. No candidates on the marker points to thresholding or blur. Candidates that fail to decode point to the wrong dictionary or too few pixels per module. Markers printed edge to edge, or stuck on a dark surface with no white margin, often fail because the detector can’t separate the black border from the background. A marker lit from the side under strong glare can lose cells completely. Claims that a detector “isn’t affected by lighting” don’t hold up against a glossy marker under a ceiling LED.

Distance is wrong

A constant percentage error means scale: the wrong marker_size, centimetres where metres were expected, or a printer that shrank the marker. A large factor, like the forum user’s 2.37ร—, almost always means the intrinsics don’t match the frames, because of a different resolution, zoom or crop. Also make sure you are comparing like with like. tvec[2] is depth along the optical axis, and a tape measure gives you range.

Jitter and flipping axes

A 2.5 cm marker that jitters badly is behaving as the geometry predicts. At a metre or two it covers only a few dozen pixels, and sub-pixel corner noise turns into degrees of rotation noise. In order of payoff, the fixes are: enable subpixel refinement, make the marker bigger or move the camera closer, use a GridBoard or ChArUco board, then add temporal filtering. A simple low-pass or a Kalman filter on the pose works, and fusing with odometry is better still.

The axes flipping when the marker faces the camera head-on is planar ambiguity. Near frontal views, two poses mirrored about the marker plane give almost the same reprojection error. cv2.solvePnPGeneric with SOLVEPNP_IPPE_SQUARE returns both solutions and their errors, so you can keep the one closest to the previous frame. A board with non-coplanar or widely spread points removes the ambiguity entirely.

Ghost IDs and false positives

False IDs on carpet, keyboards or shelving mean your dictionary is too permissive for the scene. Switch to the smallest dictionary that covers your IDs. Ignore any ID you didn’t deploy. Lower errorCorrectionRate if bit-corrected reads are getting through. And require a detection to persist for two or three frames before your robot acts on it. Anyone building an AI robot that reacts to markers should treat a single-frame ID as a hint, not a command.

FAQ

What is an ArUco marker used for?

ArUco markers give a camera a cheap, reliable reference it can identify and localise in 3D. Common uses are robot docking and localisation, drone landing pads, AR overlays, camera calibration with ChArUco boards, measuring motion stages, and labelling objects for pick-and-place.

How do I generate ArUco markers in Python with OpenCV?

Call cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_4X4_50), then cv2.aruco.generateImageMarker(dictionary, marker_id, side_pixels), and save the result with cv2.imwrite. Make the side length a multiple of the module count, and add a white border for the quiet zone.

What is the difference between ArUco and AprilTag?

Both are square binary fiducials from different research groups: ArUco from the University of Cรณrdoba, AprilTag from the University of Michigan. Reliability depends mostly on the family’s Hamming distance, not the brand. ArUco is built into OpenCV, while AprilTag 36h11 is a widespread robotics convention.

Which ArUco dictionary should I use?

Use the smallest one that covers your IDs. DICT_4X4_50 suits small robot setups and long range. DICT_5X5_100 is a good general default. DICT_6X6_250 or ARUCO_MIP_36h12 suit larger ID sets. Avoid ARUCO_ORIGINAL and AprilTag 16h5 for new work.

What size should I print an ArUco marker for a given distance?

Work out marker pixels โ‰ˆ focal_px ร— size / distance and aim for at least 5 pixels per module to detect, and 10 or more for a stable pose. On a 1280ร—720 camera with a 70ยฐ field of view, a 10 cm 4ร—4 marker gives about 15 px per module at 1 m and about 7.6 at 2 m.

Why was estimatePoseSingleMarkers removed and what replaces it?

OpenCV deprecated it in 4.7.0 when ArUco moved into objdetect, and the docs point to cv::solvePnP. Build the four 3D corners for your marker side length and call solvePnP with SOLVEPNP_IPPE_SQUARE. You also get full control over the coordinate convention.

Does OpenCV 5 still support ArUco?

Yes. OpenCV 5.0.0 keeps ArUco in objdetect with a dedicated documentation page. Code written for the 4.7+ API works. You need C++17 and Python 3, and C++ users should check includes for the reorganised 3D and calibration functions.

How do I detect ArUco markers in ROS 2?

On Jazzy, install ros-${ROS_DISTRO}-aruco-opencv and run the aruco_tracker node (or aruco_tracker_autostart). Set cam_base_topic, marker_size in metres and image_is_rectified, and make sure the camera publishes both the image and camera_info.

What is a ChArUco board and why use it for calibration?

A ChArUco board is a chessboard with ArUco markers in its white squares. The markers identify each corner, so the board works when it is partly out of view. The chessboard corners locate to subpixel accuracy, which makes it a stronger calibration target than a plain chessboard or a plain marker grid.

Can I detect ArUco markers online or on a phone?

Yes. js-aruco2 runs detection in the browser with JavaScript, and phone apps can use OpenCV’s Android and iOS builds. For metric pose on a phone, you still need intrinsics for that camera at the resolution you capture.

Where to start

Make one marker before you write any detection code. Generate a DICT_4X4_50 marker, print it at 100%, measure it with calipers, and calibrate your camera with a ChArUco board at your working resolution. Then run the detector and solvePnP script above and check that the reported distance matches a tape measure to within a centimetre. If it does, the rest of your perception stack has a reference it can trust. If it doesn’t, the troubleshooting table above tells you which part of the chain to check.

Credits and sources

By RWT Robotics Editorial Team

  • Facts were checked against the sources below before publication.
  • Published

Checking and sources

  • Researched from 8 sources, listed below.
  • Facts are checked against those sources; anything we cannot confirm is corrected, labelled or removed.
Sources (8)
  1. ArUco markers and boards detection for robust camera pose estimation (OpenCV 5.0) (docs.opencv.org)
  2. Detection of ArUco Markers (OpenCV 4.13.0) (docs.opencv.org)
  3. OpenCV Aruco Java docs (estimatePoseSingleMarkers deprecation) (docs.opencv.org)
  4. Aruco coordinate system changed in pose estimation for OpenCV 4.6/4.7 (forum.opencv.org)
  5. Aruco marker distance calculation off (forum.opencv.org)
  6. OpenCV Change Logs (github.com)
  7. OpenCV – Wikipedia (en.wikipedia.org)
  8. OpenCV 5 (opencv.org)